Index of Lua Library Functions for the Rbq Application
608 total function(s)
last updated Tue Dec 14 16:06:06 2004
Function Categories
descrip
Appends text lines to an annotation billboard shown in the graphics window.
params
table tLines
[string sBillboardName = "default"]
returns
number bRet = 1
or
nil if error
notes
The param named billboard must already exist or the call will fail.
seealso
AnnUtil.setBillboardText()
include
AnnUtil.lua
descrip
Adds a line label annotation that is shown in the graphics window.
params
string sLineLabelName
string sText
table ptLineBeg = { x, y, z }
table ptLineEnd = { x, y, z }
[table vColor = { r, g, b }]
returns
number bRet = 1
or
nil if error
notes
A line label is an annotation that consists of a text string, drawn at a point in 3D space
in the graphics window, and an associated line segment. It can be used to point out and describe
particular features of objects in the graphics window.
The text is drawn at ptLineBeg. The line segment begins at ptLineBeg and ends at ptLineEnd.
seealso
AnnUtil.removeLineLabel()
include
AnnUtil.lua
descrip
Deletes named annotation.
params
string sAnnName
[number bEchoCmd = (nil, 0) or 1]
returns
number bRet = 1 or nil
notes
Script objects are annotations, so this function is used to delete script objects.
seealso
deleteAnnotations(), deleteScriptObject(), scheduleDeleteScriptObject()
groups
Ann, Script
include
AnnUtil.lua
descrip
Deletes all annotations.
params
[number bEchoCmd = 1 or nil]
returns
number bRet = 1 or nil
notes
Script objects are annotations, so this function is used to delete script objects.
seealso
deleteAnnotation(), deleteScriptObject(), scheduleDeleteScriptObject()
groups
Ann, Script
include
AnnUtil.lua
descrip
Deletes all line label annotations.
params
returns
number bRet = 1 or nil
notes
seealso
groups
include
AnnUtil.lua
descrip
Draws a bitmap string with param text, 3D pos and color.
params
string sText
table ptPos
table vColor
returns
number bRet = 1
or
nil
notes
The param position is a coordinate in 3D space which defines the location
of the text. To define text located in 2D screen coordinates, use
drawOrthoText().
seealso
drawOrthoText()
include
AnnUtil.lua
descrip
Draws a block arrow with param points.
params
table tPoints = { [1] = ptBegin, [2] = ptEnd }
table vColor = { r, g, b }
[number fThick = nil]
returns
number bRet = 1 or nil
notes
If thickness is nil, it will be auto-calculated from the length.
include
AnnUtil.lua
descrip
Draws a box with param size.
params
table vSize = { w, h, d }
returns
number bRet = 1 or nil
notes
The box position and color are determined by the state of the
current model matrix and color setting.
seealso
drawBoxLc(), drawSphere(), drawCylinder()
include
AnnUtil.lua
descrip
Draws a box with param location, size and color
params
table tHMatrix = { m00, ..., m15 }
table vSize = { w, h, d }
table vColor = { r, g, b }
returns
number bRet = 1 or nil
notes
seealso
drawBox()
include
AnnUtil.lua
descrip
Draws the appearance of a covalent bond.
params
table vPosI = position of atom i
number iEl = element of atom i
table vPosJ = position of atom j
number jEl = element of atom j
number fSize = radius of bond
[table vColor] = color of bond
returns
number bRet = 1 or nil
notes
seealso
include
AnnUtil.lua
descrip
Draws a cylinder with param size.
params
number fRadius
number fHeight
returns
number bRet = 1 or nil
notes
Location and color of cylinder are defined by previous calls to
setDrawMatrix() and setDrawColor().
seealso
drawCylinderLc(), drawBox(), drawSphere()
include
AnnUtil.lua
descrip
Draws a cylinder with param location, size and color
params
table tHMatrix = { m00, ..., m15 }
number fRadius
number fHeight
table vColor = { r, g, b }
returns
number bRet = 1 or nil
notes
seealso
drawCylinder()
include
AnnUtil.lua
descrip
Draws a line with param endpoints and color.
params
table ptBeg
table ptEnd
table vColor
returns
number bRet = 1
or
nil
include
AnnUtil.lua
descrip
Draws a polygon in orthographic projection.
params
table tVerts = { ptTopLeft, ptBotLeft, ptBotRight, ptTopRight }
table vColor
[number fTrans = 0]
returns
number bRet = 1
or
nil
notes
This function can be used to draw a semi-transparent polygon that can serve
as a background for orthographic text.
The coordinates { x, y, z } that define a vertex of the quadrilateral are window
pixel coordinates, where the upper-left corner begins at (0, 0). The positive x and y
directions increase to the right and down. The z coordinate must be in the range (-2, -1].
If fTrans = 0, the quad is completely opaque. If fTrans = 1, the quad is completely transparent.
seealso
drawOrthoText(), textAreaToPixels()
include
AnnUtil.lua
descrip
Draws a bitmap string with param text, 2D pos and color, in orthographic projection.
params
string sText
table ptPos = { iCol, Row }
table vColor = { r, g, b }
returns
number bRet = 1
or
nil
notes
The param position is a coordinate in 2D space which defines the location
of the text. To define text located in 3D screen coordinates, use
drawBitmapText().
ptPos[1] = screen column
ptPos[2] = screen row
col 0, row 0 is located in the upper-left corner of the screen. The
number of columns and rows is determined by the current size of the
graphics window and can be determined by calling getTextArea().
A background polygon can be drawn behind the text by calling drawOrthoQuad().
seealso
drawBitmapText(), drawOrthoQuad(), getTextArea()
include
AnnUtil.lua
descrip
Draws a quadrilateral polygon with param vertices and color.
params
table tVerts = { pt0, pt1, pt2, ... }
table vColor = { r, g, b }
returns
number bRet = 1
or
nil
notes
seealso
include
AnnUtil.lua
descrip
Draws a sphere with param radius.
params
number fRadius
returns
number bRet = 1 or nil
notes
The sphere position and color are determined by the state of the
current model matrix and color setting.
seealso
drawSphereLc(), drawBox(), drawCylinder()
include
AnnUtil.lua
descrip
Draws a sphere with param location, radius and color.
params
table ptCen = { x, y, z }
number fRadius
table vColor = { r, g, b }
returns
number bRet = 1 or nil
notes
seealso
drawSphere()
include
AnnUtil.lua
descrip
Draws a wireframe arc segement with param location, orientation, radius and arc endpoints.
params
number fDegBeg = beginning angle of arc, in degrees
number fDegEnd = ending angle of arc, in degrees
number fRadius = radius of arc
table ptCen = { x, y, z } center point of arc
table vX = { x, y, z } vector defining +x direction in arc plane
table vY = { x, y, z } vector defining +y direction in arc plane
returns
number bRet = 1 or nil
notes
The color of the arc is set by a prior call to setDrawColor().
seealso
drawWireQuad(), setDrawColor()
include
AnnUtil.lua
descrip
Draws a wireframe quadrilateral with param vertices and color.
params
table tVerts = { pt1, pt2, pt3, pt4 }
table tColor
returns
number bRet = 1 or nil
notes
seealso
drawWireArc()
include
AnnUtil.lua
descrip
Returns true if named annotation exists.
params
string sAnnName
returns
number iRet = 1 or nil
notes
seealso
include
AnnUtil.lua
descrip
Enables single-stepping of currently-loaded sim, if any.
params
number bEnable = 1 or nil
returns
number bRet = 1 or nil
notes
seealso
include
AnnUtil.lua
descrip
Returns height of a bitmap character, in pixels.
params
returns
number iHeight
notes
seealso
getBitmapCharWidth()
include
AnnUtil.lua
descrip
Returns width of a bitmap character, in pixels.
params
returns
number iWidth
notes
seealso
getBitmapCharHeight()
include
AnnUtil.lua
descrip
Returns width of a bitmap character, in pixels.
params
returns
number iWidth
notes
seealso
getBitmapCharWidth(), getBitmapCharHeight()
include
AnnUtil.lua
descrip
Returns a factor to slowdown the interpolations in schematic simulations.
params
returns
number fSlowdown
notes
This factor is used by scripts that do interpolation. The script
uses this slowdown factor to adjust the interpolation rate so that it
runs at a uniform speed on a particular host machine.
This value is permanently stored in the 'LocalEnv.set' file in the application
base directory and read at startup by the 'SetLocalEnv.lua' script.
seealso
setInterpSlowdownFactor()
include
AnnUtil.lua
descrip
Returns the number of columns and rows of text that will fit the current graphics rectangle.
params
returns
number iCols, iRows
notes
seealso
drawOrthoText()
groups
Ann, Graphics
include
AnnUtil.lua
descrip
Returns a reference to the currently loaded sim object, if any.
params
returns
table tSimObject
or
nil if no current sim object
notes
seealso
include
AnnUtil.lua
descrip
Performs operations defined in all steps up to but not including param step, for the currently loaded sim, if any.
params
number iGotoStep
returns
number bRet = 1 or nil
notes
iStep must be in the range [1, iTotalSteps]
seealso
include
AnnUtil.lua
descrip
Inserts a bitmap text string as an annotation.
params
string sAnnName
table ptPos
table vColor
string sText
returns
number bRet = 1 or nil
notes
seealso
include
AnnUtil.lua
descrip
Inserts a graphical line as an annotation.
params
string sAnnName
table ptBeg
table ptEnd
table vColor
returns
number bRet = 1 or nil
notes
seealso
include
AnnUtil.lua
descrip
Inserts a graphical mesh object as an annotation.
params
string sFile
[string sAnnName]
[number iEchoCmd = 0] or 1
returns
number iRet = 1 or nil
notes
seealso
include
AnnUtil.lua
descrip
Inserts a graphical smooth mesh object as an annotation.
params
string sFile
[string sAnnName]
[number iEchoCmd = 0] or 1
returns
number iRet = 1 or nil
A smooth mesh can be created using the msurf program.
notes
seealso
include
AnnUtil.lua
descrip
Inserts a graphical smooth color mesh object as an annotation.
params
string sFile
[string sAnnName]
[number iEchoCmd = 0] or 1
returns
number iRet = 1 or nil
notes
A smooth color mesh can be created using the msurf program.
seealso
include
AnnUtil.lua
descrip
Inserts a graphical sphere as an annotation.
params
string sAnnName
number fRadius
table ptCen
table vColor
[number bEchoCmd = 0] or 1
returns
number bRet = 1 or nil
notes
seealso
include
AnnUtil.lua
descrip
Lists all the steps for the currently defined simulation object, if any.
params
returns
number bRet = 1 or nil
notes
seealso
include
AnnUtil.lua
descrip
Loads a schematic simulation, but does not run it.
params
table simObject
[number iBegStep = 1]
returns
number bRet = 1
or
nil if error
notes
seealso
AnnUtil.runSim()
include
AnnUtil.lua
descrip
Restores current drawing matrix from stack.
params
returns
notes
seealso
pushDrawMatrix(), translateDrawMatrix(), rotateDrawMatrix()
include
AnnUtil.lua
descrip
Saves current drawing matrix on stack.
params
returns
notes
seealso
popDrawMatrix(), translateDrawMatrix(), rotateDrawMatrix()
include
AnnUtil.lua
descrip
Removes a line label annotation that is shown in the graphics window.
params
string sLineLabelName
returns
number bRet = 1
or
nil if error
notes
seealso
AnnUtil.addLineLabel()
include
AnnUtil.lua
descrip
Rotates current draw matrix by param degrees about param vector.
params
number fDeg
table vRot
returns
number bRet = 1 or nil
notes
seealso
translateDrawMatrix(), pushDrawMatrix(), popDrawMatrix()
include
AnnUtil.lua
descrip
Loads and runs a schematic simulation.
params
table simObject
returns
number bRet = 1
or
nil if error
notes
seealso
AnnUtil.loadSim()
include
AnnUtil.lua
descrip
Sets position of an annotation billboard shown in the graphics window.
params
table tPos = { iCol, iRow }
[string sBillboardName = "default"]
returns
number bRet = 1
or
nil if error
notes
This function will create a new billboard with the param name, if the
billboard does not exist. The associated Billboard script object is also created
as needed.
seealso
AnnUtil.setBillboardText()
include
AnnUtil.lua
descrip
Sets text on an annotation billboard shown in the graphics window.
params
table tLines
[string sBillboardName = "default"]
returns
number bRet = 1
or
nil if error
notes
This function will create a new billboard with the param name, if the
billboard does not exist. The associated Billboard script object is also created
as needed.
seealso
AnnUtil.setBillboardPos(), AnnUtil.addBillboardText()
include
AnnUtil.lua
descrip
Sets current drawing color.
params
table vColor = { r, g, b }
returns
number bRet = 1
or
nil if error
notes
seealso
setDrawColor()
include
AnnUtil.lua
descrip
Sets param matrix as current drawing model matrix.
params
table hm = 16 float homogeneous matrix
returns
notes
seealso
translateDrawMatrix(), rotateDrawMatrix(), setDrawColor()
include
AnnUtil.lua
descrip
Sets a factor to slowdown the interpolations in schematic simulations.
params
number fSlowdown
returns
notes
This factor is used by scripts that do interpolation. The script
uses this slowdown factor to adjust the interpolation rate so that it
runs at a uniform speed on a particular host machine.
This value is permanently stored in the 'LocalEnv.set' file in the application
base directory on application exit and read at startup by the 'SetLocalEnv.lua'
script.
seealso
getInterpSlowdownFactor()
include
AnnUtil.lua
descrip
Sets the run state of the currently loaded sim, if any.
params
number bRun = 1 or nil
returns
number bRet = 1
or
nil if error
notes
If no sim is loaded, the function will return nil.
seealso
AnnUtil.loadSim(), AnnUtil.runSim()
include
AnnUtil.lua
descrip
Shows/hides annotation with param name
params
string sAnnName
number iShow = 1 or 0
number iEchoCmd = 1 or 0
returns
number iRet = 1 or nil
include
AnnUtil.lua
descrip
Translates current draw matrix by param vector.
params
table vTrans
returns
number bRet = 1 or nil
notes
seealso
rotateDrawMatrix(), pushDrawMatrix(), popDrawMatrix()
groups
Ann, Graphics
include
AnnUtil.lua
descrip
Returns pixel coordinates of a text area, as a table of 4 vertices. The table can be passed as a parameter to drawOrthoQuad().
params
table tTextArea = { iColBeg, iRowBeg, iColEnd, iRowEnd }
[number fZDepth = -1.5]
returns
table tPixRect = { vTopLeft, vBotLeft, vBotRight, vTopRight }
notes
Beginning point is the upper-left of corner area, end point in lower-right corner.
This function can be used to determine the coordinates of a background polygon
drawn behind a rectangle of orthographic text.
seealso
drawOrthoQuad(), drawOrthoText(), getBitmapTextMetric(), getGraphicsWinSize()
groups
Ann, Graphics
include
AnnUtil.lua
descrip
Draws a graphical representation of a camera object at param location.
params
table tFrame = { ptOrg, tMat }
[number bActive = nil] (turns red light on)
[number fScale = 1]
returns
number bRet = 1 or nil
notes
In the identity frame, the camera is looking towards the +z axis with
with top of camera pointed towards the +y axis.
seealso
getIdentityFrame(), translateFrame(), rotateFrame()
include
CamUtil.lua
descrip
Sets color of current selection to default cpk color.
params
returns
number bRet = 1 or nil
notes
CPK colors are defined for atom element type and are shown for atom
spheres and bonds. For chain backbones, this command will reset the
backbone color to the 'default', which is blue for nucleic acid chains
and grey for proteins.
seealso
colorRgb(), colorName(), getResidueColor(), getElementColor()
include
ChemDrawUtil.lua
descrip
Sets color of current selection with param color.
params
string sColor, number bEcho
returns
number bRet = 1 or nil
notes
seealso
colorCpk(), colorRgb(), getResidueColor()
include
ChemDrawUtil.lua
descrip
Sets color of current selection with param rgb color.
params
numbers r, g, b
[number bEcho = nil]
returns
number bRet = 1 or nil
notes
The color values r, g, b represent red, green and blue and should be in the range [0, 1].
seealso
colorCpk(), colorName(), colorRgbV(), getResidueColor()
include
ChemDrawUtil.lua
descrip
Sets color of current selection with param rgb color vector.
params
table vColor = { r, g, b }
[number bEcho]
returns
number bRet = 1 or nil
notes
The color values r, g, b represent red, green and blue and should be in the range [0, 1].
seealso
colorCpk(), colorName(), colorRgb(), getResidueColor()
include
ChemDrawUtil.lua
descrip
Creates surfaces for the currently selected pdb chains.
params
[number fResolution]
[number iEchoCmd = 0]
returns
number bRet = 1 or nil
notes
fResolution is resolution of the surface mesh, in Angstroms.
seealso
createPdbSurf(), drawSurface()
include
ChemDrawUtil.lua
descrip
Creates a new pdb surface for the currently selected pdb objects.
params
[number fResolution]
[number iEchoCmd = 0]
returns
number bRet = 1 or nil
notes
fResolution is resolution of the surface mesh, in Angstroms.
seealso
createChainSurf(), drawSurface()
include
ChemDrawUtil.lua
descrip
Sets display of backbone segment for current selection.
params
number bSet
[number iEchoCmd = 0]
returns
number bRet = 1 or nil
include
ChemDrawUtil.lua
descrip
Sets size of backbone segment for current selection.
params
number fBackboneRadiusFactor
returns
include
ChemDrawUtil.lua
descrip
Sets display of ball and stick for current selection.
params
number bSet, number bEcho
returns
include
ChemDrawUtil.lua
descrip
Sets display of covalent bonds for current selection.
params
number bDrawCovalentBonds
returns
number bRet = 1 or nil
include
ChemDrawUtil.lua
descrip
Sets size of covalent bonds for current selection.
params
number fCovalentRadiusFactor
returns
number bRet = 1 or nil
include
ChemDrawUtil.lua
descrip
Sets display of spacefill atoms for current selection.
params
number bDrawSpacefill
returns
number bRet = 1 or nil
include
ChemDrawUtil.lua
descrip
Sets size of spacefill atoms for current selection.
params
number fSpacefillRadiusFactor
returns
include
ChemDrawUtil.lua
descrip
Sets display of surface mesh for current selection.
params
number bShow = 1 or nil
[number bEchoCmd = nil or 1]
returns
number bRet = 1 or nil
notes
Prior to the show operation, a default surface will be automatically created
if no prior surface exists, for each selected pdb model.
If a surface is automatically created prior to a show operation, the default creation
type is for the entire pdb and the default resolution is 4 A.
To explicitly create surfaces prior to specifying a show operation,
use the 'createChainSurf()' or 'createPdbSurf()' functions. These functions
allow for specification of surface type and resolution.
seealso
createChainSurf(), createPdbSurf(), drawSurfTrans()
include
ChemDrawUtil.lua
descrip
Sets transparency for surface meshes of current selection.
params
number fTrans ( range: [0 - 1], 0 = no transparency, 1 = full transparency )
[number bEchoCmd = nil or 1]
returns
number bRet = 1 or nil
notes
The surface must already have been created.
seealso
drawSurface()
include
ChemDrawUtil.lua
descrip
Enables/disables drawing in the graphics window.
params
number iEnable = 1 or [ 0 | nil]
returns
notes
seealso
redraw()
include
ChemDrawUtil.lua
descrip
Returns cpk color of param element.
params
number iElement
returns
table vRgbColor
notes
seealso
colorCpk()
include
ChemDrawUtil.lua
descrip
Returns color of param residue.
params
table tResIndex = { iPdb, iChain, iRes }
returns
table vRgbColor = { r, g, b }
notes
The color of a residue is either the default color, which is the
initial color at time of creation, or a 'user color', which has been
set by the user with one of the color commands.
For backbone segments and surfaces, the default color is blue for nucleic
acids and grey for proteins. For atoms and bonds, the default color is
the CPK color.
When a 'user color' has been set for a residue, then the backbone segment,
surface, atoms and bonds are all drawn with this same color.
The 'colorCpk()' function will remove the 'user color' setting and restore
the residue color to the default one.
seealso
colorCpk(), colorName(), colorRgb(), setResidueColor()
include
ChemDrawUtil.lua
descrip
Returns true if param chain has a visible element.
params
table tChainIndex = { number iPdbInDoc, iChainInPdb }
returns
number bVisible = 1 or nil
include
ChemDrawUtil.lua
descrip
Returns true if log scaling of force display arrows is set.
params
returns
number bSet = 1 or nil
include
ChemDrawUtil.lua
descrip
Returns true if param force object covalent drawing is set.
params
table tForceObjIndex = { iPdb, iDynSeg, iRes }
returns
number bVisible = 1 or nil
include
ChemDrawUtil.lua
descrip
Posts a request for the graphics window to be redrawn.
params
returns
notes
seealso
enableDrawing()
groups
ChemDraw, Ann, Script
include
ChemDrawUtil.lua
descrip
Sets background color to param color.
params
numbers r, g, b
returns
number bRet = 1 or nil
notes
The color values should be in the range [0, 1].
seealso
setBgColorV()
groups
Win, ChemDraw, Graphics
include
ChemDrawUtil.lua
descrip
Sets background color to param color vector.
params
table vColor = { r, g, b }
returns
number bRet = 1 or nil
notes
The color values should be in the range [0, 1].
seealso
setBgColor()
groups
Win, ChemDraw, Graphics
include
ChemDrawUtil.lua
descrip
Sets mode that enables a temporary flashing of selected color.
params
number iSet = 1 or 0
returns
number bRet = 1 or nil
notes
seealso
groups
ChemDraw, Graphics, Select
include
ChemDrawUtil.lua
descrip
Sets param residue to the param color.
params
table tResIndex = { iPdb, iChain, iRes }
table vRgbColor = { r, g, b }
returns
number bRet = 1
or
nil if error
notes
seealso
getResidueColor()
include
ChemDrawUtil.lua
descrip
Returns the smallest difference angle between param angles (fAngleEnd - fAngleBeg), with proper sign. This is done by projecting first angle ahead 360, as needed, if that produces the smaller difference.
params
number fAngleBeg
number fAngleEnd
returns
number fAngleDiff
include
DihedralUtil.lua
descrip
Returns position of atom with param name and owner force object.
params
table tForceObj = index of owner force object
string sAtomName = pdb name of atom, with spaces trimmed
returns
table tPos
or
nil if atom not found
notes
include
DihedralUtil.lua
descrip
Returns position of atoms of param force object, which names in param table.
params
table tForceObj = index of owner force object
table tAtomNames = pdb names of atoms
returns
table tAtomsPos
or
nil if any atom not found
notes
include
DihedralUtil.lua
descrip
Returns angle of param backbone dihedral index of param dynamic nucleic acid residue. Calculates and returns the dihedral angle between the param plane and the previous plane in the nucleic acid backbone, as defined by the atoms in the global table above, for param force object.
params
table tObj = index of force object
number iNbbDihedral = index of nucleic acid backbone dihedral angle (0 - 5) (alpha - zeta)
[number bExtraInfo = nil] = flag to return additional geometrical data associated with angle
returns
number fDhAng = dihedral angle
[table tExtraInfo =
{
table ptA = position of A atom,
table ptB = position of B atom,
table vba = normalized vector BA,
table vbc = normalized vector BC
table ptC = position of C atom,
table ptD = position of D atom,
}]
or
nil if angle not available or error
notes
The number angles correspond to the following:
0 alpha
1 beta
2 gamma
3 delta
4 epsilon
5 zeta
If the angle is for the first bond in the backbone (0), there must be a previous force object
to calculate the angle, else nil will be returned.
If the angle is for the final 2 bonds in the backbone (4,5), there must be a next force object
to calculate the angle, else nil will be returned.
The dihedral angle is the angle between the normal of the plane defined by atoms B, C, D
and the normal of the plane defined by atoms A, B, C, where atom A, B, C, D are successive
atoms along the phosphate backbone in the 5' to 3' direction.
The angle will be in the range of [0, 360). When looking down the vBC vector, with A and
D eclipsed and D just clockwise from A will give a dihedral angle of just > 180 degrees.
seealso
getFoTorsionAngle(), getResDihedralAngle()
include
DihedralUtil.lua
descrip
Returns the positions of the atoms for param torsion plane of param force object.
params
table tObj = index of force object
number iPlane
returns
table tAtomsPos = { ptAtom0, ptAtom1, ... }
or
nil if atom position info is not available for param plane
notes
include
DihedralUtil.lua
descrip
Returns the ribose pucker phase for the param dynamic nucleic acid residue.
params
table tDynRes = index of dynamic nucleic acid residue
returns
number iThreeEndo = 1 if 3' endo, else 0
or
nil if failed doing pucker calc.
include
DihedralUtil.lua
descrip
Returns torsion angle of param backbone torsion index of param dynamic nucleic acid residue.
params
table tObj = index of force object
number iTor = index of nucleic acid backbone torsion bond (0 - 5) (alpha - zeta)
[number bExtraInfo = nil] = flag to return additional geometrical data associated with angle
returns
number fTorAngle = torsion angle
[table tExtraInfo =
{
table ptA = position of A atom,
table ptB = position of B atom,
table vba = normalized vector BA,
table vbc = normalized vector BC
table ptC = position of C atom,
table ptD = position of D atom,
}]
or
nil if angle not available or error
notes
The number angles correspond to the following:
0 alpha
1 beta
2 gamma
3 delta
4 epsilon
5 zeta
If the angle is for the first bond in the backbone (0), there must be a previous force object
to calculate the angle, else nil will be returned.
If the angle is for the final 2 bonds in the backbone (4,5), there must be a next force object
to calculate the angle, else nil will be returned.
The angle will be in the range of [-180, 180). When looking down the vBC vector, with A and
D eclipsed and D just clockwise from A will give a dihedral angle of just > 0 degrees.
seealso
getFoDihedralAngle(), getResTorsionAngle()
include
DihedralUtil.lua
descrip
Returns all backbone torsion angles of param dynamic nucleic acid residue.
params
table tObj = index of force object
returns
table tTorAngles = { a, b, c, d, e, z }
or
nil if any angle not available or error
notes
seealso
getFoTorsionAngle()
include
DihedralUtil.lua
descrip
Returns table which defines a plane in the nucleic acid phosphate backbone.
params
number iPlane = { 1 - 7 }
returns
table tPlaneDef = { { tAtomNames }, { tOwnerRes }, sAngleName }
or
nil if invalid plane number
notes
This is just a helper function for calculating dihedral angles.
seealso
getTotalNabPlaneDefs()
include
DihedralUtil.lua
descrip
Returns total number of atom planes in table which defines the nucleic acid phosphate backbone.
params
returns
number iTotalPlanes
notes
This is just a helper function for calculating dihedral angles.
seealso
getNabPlaneDef()
include
DihedralUtil.lua
descrip
Returns table of atom names used to define a plane in the nucleic acid phosphate backbone.
params
number iPlane = { 1 - 7 }
returns
table tNames = { nameAtomA, nameAtomB, nameAtomC }
or
nil if invalid plane number
notes
This is just a helper function for calculating dihedral angles.
include
DihedralUtil.lua
descrip
Returns position of atom with param name and owner residue.
params
table tRes = index of owner residue
string sAtomName = pdb name of atom, with spaces trimmed
returns
table tPos
or
nil if atom not found
include
DihedralUtil.lua
descrip
Returns positions of atoms with param names and owner residue.
params
table tRes = index of owner residue
table tAtomNames = pdb names of atoms, with spaces trimmed
returns
table tAtomsPos
or
nil if any atom pos not found
include
DihedralUtil.lua
descrip
Returns the positions of the atoms for param torsion plane of param residue.
params
table tRes = index of residue
number iPlane
returns
table tAtomsPos = { ptAtom0, ptAtom1, ... }
or
nil if atom position info is not available for param plane
notes
include
DihedralUtil.lua
descrip
Returns dihedral angle of param backbone dihedral index of param static nucleic acid residue.
params
table tRes = index of residue
number iDh = index of nucleic acid backbone dihedral angle (0 - 5) (alpha - zeta)
[number bExtraInfo = nil] = flag to return additional geometrical data associated with angle
returns
number fDhAng = dihedral angle
[table tExtraInfo =
{
table ptA = position of A atom,
table ptB = position of B atom,
table vba = normalized vector BA,
table vbc = normalized vector BC
}]
or
nil if angle not available or error
notes
The number angles correspond to the following:
0 alpha
1 beta
2 gamma
3 delta
4 epsilon
5 zeta
If the angle is for the first bond in the backbone (0), there must be a previous force object
to calculate the angle, else nil will be returned.
If the angle is for the final 2 bonds in the backbone (4,5), there must be a next force object
to calculate the angle, else nil will be returned.
The dihedral angle is the angle between the normal of the plane defined by atoms B, C, D
and the normal of the plane defined by atoms A, B, C, where atom A, B, C, D are successive
atoms along the phosphate backbone in the 5' to 3' direction.
seealso
getFoDihedralAngle(), getResTorsionAngle()
include
DihedralUtil.lua
descrip
Returns the ribose pucker phase for the param static nucleic acid residue.
params
table tRes = index of static nucleic acid residue
returns
number iThreeEndo = 1 if 3' endo, else 0
or
nil if failed doing pucker calc.
include
DihedralUtil.lua
descrip
Returns torsion angle of param backbone dihedral index of param static nucleic acid residue.
params
table tRes = index of residue
number iTorIdx = index of nucleic acid backbone dihedral angle (0 - 5) (alpha - zeta)
[number bExtraInfo = nil] = flag to return additional geometrical data associated with angle
returns
number fTorAng = torsion angle
[table tExtraInfo =
{
table ptA = position of A atom,
table ptB = position of B atom,
table vba = normalized vector BA,
table vbc = normalized vector BC
}]
or
nil if angle not available or error
notes
The number angles correspond to the following:
0 alpha
1 beta
2 gamma
3 delta
4 epsilon
5 zeta
If the angle is for the first bond in the backbone (0), there must be a previous force object
to calculate the angle, else nil will be returned.
If the angle is for the final 2 bonds in the backbone (4,5), there must be a next force object
to calculate the angle, else nil will be returned.
The dihedral angle is the angle between the normal of the plane defined by atoms B, C, D
and the normal of the plane defined by atoms A, B, C, where atom A, B, C, D are successive
atoms along the phosphate backbone in the 5' to 3' direction.
seealso
getResDihedralAngle(), getFoTorsionAngle()
include
DihedralUtil.lua
descrip
Returns list of atom names for param nucleic acid backbone torsion bond.
params
number iTorIdx = index of dihedral or torsion angle ( 0 - 5 )
returns
table tAtomNames = { sAtomA, sAtomB, sAtomC, sAtomD }
or
nil otherwise
notes
Example: for iTorIdx0, the atom names for the alpha torsion bond would be returned:
{ "O3*", "P", "O5*", "C5*" }
seealso
getTorsionIndexFromAtomName()
include
DihedralUtil.lua
descrip
Returns index of nab torsion bond associated with atom of param name.
params
string sTorsionLabel = ( "A" || "B" || "C" || "D" )
string sAtomName
returns
number iTorIdx = index of dihedral or torsion angle ( 0 - 5 )
or
nil otherwise
notes
Example: for torsion label "A" and atom name "O3*", the torsion index 0
would be returned.
seealso
getTorsionBondAtomNames()
include
DihedralUtil.lua
descrip
Returns true if param number is a valid index for a nucleic acid backbone torsion angle.
params
number iTorIdx = index of dihedral or torsion angle ( 0 - 5 )
returns
number bRet = 1 if index is [0 - 5]
or
nil otherwise
notes
seealso
include
DihedralUtil.lua
descrip
Writes the nucleic acid backbone dihedral or torsion angles for the param dynamic residue to the param file handle. Also writes the ribose pucker phase (3'endo state).
params
number fout = open file handle to output file
table tForceObj = index of dynamic residue
[number bTorsion] = output torsion angle instead of dihedral angle
returns
number iTotalAnglesOutput
include
DihedralUtil.lua
descrip
Writes the nucleic acid backbone dihedral or torsion angles for the param static residue to the param file handle. Also writes the ribose pucker phase (3'endo state).
params
number fout = open file handle to output file
table tRes = index of static residue
[number bTorsion] = output torsion angle instead of dihedral angle
returns
number iTotalAnglesOutput
include
DihedralUtil.lua
descrip
Outputs dihedral or torsion angle data to a file for selected dynamic nucleic acid residues.
params
string sFile = name of file to output data
number bShowProgress = flag to show progress during output
[number bTorsion] = output torsion angle instead of dihedral angle
returns
number iTotalAnglesOutput
or
-1 if progress cancelled
or
nil if error
include
DihedralUtil.lua
descrip
Outputs dihedral angle data to a file for selected static residues.
params
string sFile = Name of file to output data
number bShowProgress = Flag to show progress during output
[number bTorsion] = output torsion angle instead of dihedral angle
returns
number iTotalAnglesOutput
or
-1 if progress cancelled
or
nil if error
include
DihedralUtil.lua
descrip
Sets param dihedral of param force object to param angle.
params
table tForceObj = index of force object { iPdb, iDynSeg, iForceObjInSeg }
number iDh = index of dihedral angle ( 0 - 5 )
number fTargetAngle = angle to which plane will be set
[number fTol] = [error tolerance value = 0.2]
returns
number bRet = 1
or
nil if angle not available or error
notes
If the difference between the param new angle and the actual resulting angle
is greater than the param tolerance value, an error message will be reported to errout.
seealso
setFoTorsionAngle()
groups
ForceObject, Geom
include
DihedralUtil.lua
descrip
Sets param torsion of param force object to param angle.
params
table tForceObj = index of force object { iPdb, iDynSeg, iForceObjInSeg }
number iTor = index of torsion angle ( 0 - 5 )
number fAngle = angle to which plane will be set
[number fTol] = [error tolerance value = 0.2]
returns
number bRet = 1
or
nil if angle not available or error
notes
seealso
setFoDihedralAngle()
groups
ForceObject, Geom
include
DihedralUtil.lua
descrip
Append param string to param file.
params
string sFile = name of file
string sText = string to be appended to file
returns
number bRet = 1 if success, else nil
notes
If failed opening file for append, an error msg will be output to app errOut.
seealso
readRecordsFromFile()
include
FileUtil.lua
descrip
Outputs an xml start tag with param name, followed by a newline.
params
number fh File handle to receive output data.
string sTagName
returns
string sBeginTag = "<sTagName>"
notes
seealso
endTag()
include
FileUtil.lua
descrip
Closes the current document.
params
[number bSkipSaveDlg = nil or 1]
returns
number bRet = 1 or nil
notes
The optional parameter enables bypassing a 'save current document' dialog,
which will be displayed if a current document exists in an unsaved state.
If shown, script execution will halt until the user manually responds to the
dialog window.
If this function is called during a script object event, it will fail because
closing a document would also result in the deletion of the currently-executing
script object. An alternative might be to delete all pdb objects in the current
document.
seealso
newDocument(), deleteAllPdbObjects()
include
FileUtil.lua
descrip
Returns true if the param files are identical.
params
string sFile1
string sFile2
returns
number bEqual = 1 or 0
string sDifference
or
number bRet = nil if error
string sError
notes
seealso
include
FileUtil.lua
descrip
Displays a dialog to confirm overwriting a file if it exists.
params
string sFilename
returns
number bConfirmed = 1 or nil
notes
seealso
include
FileUtil.lua
descrip
Copies param input file to param output file.
params
string sInFilename
string sOutFilename
returns
number bRet = 1 or nil
notes
The file is copied line by line, reading and writing in text mode.
seealso
isFileHere()
include
FileUtil.lua
descrip
Copies param input file to param output file, outputs info to errOut if failed.
params
string sSrcFile
string sDstFile
returns
number bRet = 1 or nil
notes
The file is copied line by line, reading and writing in text mode.
seealso
isFileHere()
include
FileUtil.lua
descrip
Deletes param file if any.
params
string sFileName
returns
number bRet = 1 or nil
notes
seealso
isFileHere()
include
FileUtil.lua
descrip
Outputs an xml end tag with param name, followed by a newline.
params
number fh File handle to receive output data.
string sTagName
returns
string sEndTag = "</sTagName>"
notes
seealso
begTag()
include
FileUtil.lua
descrip
Returns true if param directory exists.
params
string sDir = name of directory
returns
number bRet = 1 or nil
notes
This is just a wrapper for isFileHere().
seealso
isFileHere(), mkdir()
include
FileUtil.lua
descrip
Exports current selection to a pdb file.
params
string sFile = name of PDB file to be created.
returns
number bRet = 1
or
nil if error
notes
seealso
groups
File, Select
include
FileUtil.lua
descrip
Outputs message to stdErr which describes 'failed opening file for append'.
params
string sFile
[string sMoreInfo]
returns
nil
notes
seealso
foffi(), foffo()
include
FileUtil.lua
descrip
Outputs message to stdErr which describes 'failed opening file for input'.
params
string sFile
[string sMoreInfo]
returns
nil
notes
seealso
foffo(), foffa()
include
FileUtil.lua
descrip
Outputs message to stdErr which describes 'failed opening file for output'.
params
string sFile
[string sMoreInfo]
returns
nil
notes
seealso
foffi(), foffa()
include
FileUtil.lua
descrip
Returns the name of the application logfile.
params
returns
string sLogfile
notes
The application logfile receives a copy of all messages that are output
to the application status window.
The name is qualified with a relative path to the application log
subdirectory.
seealso
include
FileUtil.lua
descrip
Returns ith filename specified by a filespec.
params
string sFileSpec = file spec (may contain a wild-card specifier)
number iFile = ith file found by filespec
[number bExcludeDirs = 1 | 0]
returns
string sFileName
or
nil
notes
iFile index is 0-based.
seealso
getFiles(), getTotalFiles()
include
FileUtil.lua
descrip
Returns list of filenames matching a file spec.
params
string sFileSpec = file spec (may contain a wild-card specifier)
[number bExcludeDirs = 1 | 0]
returns
table tFileNames
notes
If no files are found matching the spec, an empty table will be returned.
seealso
getFile(), getTotalFiles()
include
FileUtil.lua
descrip
Returns the base portion of a filename (directories stripped).
params
string sFilename
returns
string sBaseName
include
FileUtil.lua
descrip
Returns path to tmp subdir.
params
returns
string sTmpDir
notes
This directory is located beneath the application base directory and
can be used to store temporary files.
seealso
getPdbDir()
include
FileUtil.lua
descrip
Returns total number of files specified by a filespec.
params
string sFileSpec
returns
number iTotalFilesMatchingSpec
[number bExcludeDirs = 1 | 0]
notes
seealso
getFile()
include
FileUtil.lua
descrip
Returns true if param line has length 0 or begins with '#' char.
params
string sLine
returns
number bRet = 1 or nil
include
FileUtil.lua
descrip
Returns true if file with param name exists.
params
string sFile = name of file
returns
number bRet = 1 or nil
notes
File is considered to exist if file information for the param name was
obtained in a call to the C runtime function _stat().
seealso
existDir()
include
FileUtil.lua
descrip
Creates a full path from the param base path and filename.
params
<string sBasePath> || <table tParentDirList>
string sFile
returns
string sPath
notes
table tParentDirList is a table of strings which are directories
in a path hierarchy. Example: makePath( { "exp", "dev", "report" }, "out.txt" ) will
return "exp/dev/report/out.txt" on unix platforms.
seealso
splitPath(), getPathSeparator()
groups
File, Script
include
FileUtil.lua
descrip
Creates a directory with param name.
params
string sDir
returns
number bRet = 1 or nil
notes
seealso
existDir(), errFailedCreateDir()
include
FileUtil.lua
descrip
Creates a new, empty ribosome builder document.
params
[number bSkipSaveDlg = nil or 1]
returns
number bRet = 1 or nil
notes
The optional parameter enables bypassing a 'save current document' dialog,
which will be displayed if a current document exists in the unsaved state.
If shown, script execution will halt until the user manually responds to the
dialog window.
seealso
include
FileUtil.lua
descrip
Writes param string to a file.
params
string sFile = name of file to be created
returns
string sBuf = contents read from file
or
number bRet = nil
string sStatus = error message
notes
The file is read in text mode.
seealso
writeFile()
groups
File
include
FileUtil.lua
descrip
Reads lines from param file into a table, skipping comment and empty lines.
params
local sInFile = name of input file
returns
table tRecords = { sLine1, sLine2, ... }
or
nil if error
notes
If an error occurs in trying to open the file, a message will be reported to errOut
and nil will be returned. If the file is successfully opened, but no records are
found, an empty table will be returned. Comment lines begin with '#'.
seealso
writeRecordsToFile(), appendString()
include
FileUtil.lua
descrip
Returns the components of the param full path name. These are simply the tokens between the path separator. The base filename and possible extension are NOT split.
params
string sPath
returns
table tPathComponents
or
nil if param sPath is nil
notes
If the param sPath is an empty string, an empty table will be returned.
seealso
makePath(), getPathSeparator()
groups
File, Script
include
FileUtil.lua
descrip
Writes param string to a file.
params
string sFile = name of file to be created
string sBuf = contents to write to file
returns
number bRet = 1 if success
or
nil if error
notes
The file is written in text mode.
An error message is printed to errOut() on error.
seealso
readFile()
groups
File
include
FileUtil.lua
descrip
Writes items from param table to a new file, appending a newline after each item.
params
table tRecords = { sItem1, sItem2, ... }
local sOutFile = name of output file
returns
number bRet = 1 if success
or
nil if error
string sErr
notes
If an error occurs in trying to open the file, a message will be reported to errOut
and nil will be returned.
seealso
readRecordsFromFile(), appendString()
include
FileUtil.lua
descrip
Resets forcefield interaction counts.
params
returns
notes
seealso
getFfCumInteractionCount()
include
ForceFieldUtil.lua
descrip
Closes a stream for detailed reporting of forcefield interactions.
params
returns
number bRet = 1 or nil
notes
seealso
openFfReportStream(), setFfReportCondition().
include
ForceFieldUtil.lua
descrip
Adds a force group to a custom force container.
params
number bMoveGroup - enables movement of the objects as a group
number bIntraGroupForceCalc - enables force calculations between objects in group
returns
number iGroup = index of newly-created group
or
nil if error
notes
A custom force container provides for user-defined interaction of force objects
that are organized in groups. This is typically done for simulations where
a portion of the force objects might be defined as unmoveable 'substrate' and
other portions as 'dockable' ligands. For example, a tRNA docking into the
A-site of the 30S subunit.
After the group is created, the objects contained within it are added by
calling addForceObjectsToGroup().
If bIntraGroupForceCalc is true, then individual movement of the objects in the group
will also be enabled.
seealso
addForceObjectToGroup(), enableCustomForceContainer()
include
ForceFieldUtil.lua
descrip
Enables interactions of force objects in a custom force container. When enabled, interactions occur between residues of force groups that have been previously defined by the user. When disabled, interactions occur between every pair of dynamic residues in the forcefield.
params
number bEnable = 1 or (nil, 0)
returns
notes
seealso
addForceObjectToGroup(), createForceGroup()
include
ForceFieldUtil.lua
descrip
Enables timestep movement in forcefield.
params
number bEnable = 1 or (nil, 0)
returns
notes
include
ForceFieldUtil.lua
descrip
Enables energy calculation in addition to force calculation.
params
number bEnable = 1 or (nil, 0)
returns
notes
include
ForceFieldUtil.lua
descrip
Returns name of energy of param id.
params
number iId
returns
string sName
or
nil
notes
seealso
getTotalEnergy(), getTotalEnergyTypes()
include
ForceFieldUtil.lua
descrip
Returns total number of interactions of param energy type that occurred since cumulative counts were reset.
params
int iType = { 0, ..., iTotalEnergyTypes - 1 }
returns
number iCount
or
nil if error
notes
seealso
getTotalEnergyTypes(), getEnergyName(), getTimestepInteractionCount(), clearFfCumInteractionCounts()
include
ForceFieldUtil.lua
descrip
Returns true if forcefield run state is enabled.
params
returns
number bRet = 1 or nil
notes
isForcefieldRunning() is a duplicate of this function.
seealso
setFfRunState(), isForcefieldRunning()
include
ForceFieldUtil.lua
descrip
Returns a text description of forcefield settings. Format: '<name> <value>\n' ...
params
returns
string sRet = text description of forcefield settings
notes
seealso
outputFfParams(), setFfParamDefaults()
include
ForceFieldUtil.lua
descrip
Returns current timestep count.
params
returns
number iTotalTimesteps
notes
seealso
resetTimestepCount()
include
ForceFieldUtil.lua
descrip
Returns total number of interactions of param energy type that occurred in most recent timestep.
params
int iType = { 0, ..., iTotalEnergyTypes - 1 }
returns
number iCount
or
nil if error
notes
seealso
getTotalEnergyTypes(), getEnergyName()
include
ForceFieldUtil.lua
descrip
Returns total energy [of param type] in most recent timestep.
params
[string sType = { "steric", "covalent", "electro", "hbond", "ringStack" }]
returns
number fTotalEnergy
or
nil
notes
If no type is specified, the collective total of all types is returned.
seealso
getEnergyName(), getTotalEnergyTypes()
include
ForceFieldUtil.lua
descrip
Returns total number of energy types, as used in energy reporting.
params
returns
number iTotalEnergyTypes
notes
seealso
getEnergyName(), getTotalEnergy()
include
ForceFieldUtil.lua
descrip
Returns true if movement is enabled in the forcefield.
params
returns
number bEnabled = 1 or nil
notes
include
ForceFieldUtil.lua
descrip
Returns true if forcefield is running.
params
returns
number bRunning = 1 or nil
notes
getFfRunState() is a duplicate of this function.
seealso
getFfRunState(), setFfRunState()
include
ForceFieldUtil.lua
descrip
Opens a stream for detailed reporting of forcefield interactions.
params
string sFile
returns
number bRet = 1 or nil
notes
Data will only be output for the single force interaction and force object pair,
as specified by the current reporting condition, will be output.
seealso
closeFfReportStream(), setFfReportCondition().
include
ForceFieldUtil.lua
descrip
Writes current forcefield settings to file.
params
string sOutfile
returns
number bRet = 1 or nil
notes
This is equivalent to the console command 'ff paramsWrite'.
seealso
getFfParams()
include
ForceFieldUtil.lua
descrip
Resets the forcefield context to an initial state.
params
returns
number bRet = 1 or nil
notes
This resets the timestep count and accumulated statistics and report conditions
of the forcefield to an initialized state.
This function is equivalent to the console command 'ff reset'.
This function does not reset the forcefield parameters, which
can be done using the function setFfParamDefaults().
seealso
resetTimestepCount(), setFfParamDefaults()
include
ForceFieldUtil.lua
descrip
Resets timestep counter to zero.
params
returns
number bRet = 1 or nil
notes
seealso
getTimestepCount(), resetForcefield()
include
ForceFieldUtil.lua
descrip
Sets all timestep parameters to their initial default value.
params
returns
number bRet = 1 or nil
notes
This is equivalent to the command 'ff setFfParamDefaults'.
After calling this function, the state of the forcefield parameters should be
the same as at program startup, except for any additional changes
done by automatic execution of the 'FfInit.lua' script located in the
application base directory. This is an optional script which can be used to
customize the forcefield settings.
seealso
resetForcefield()
include
ForceFieldUtil.lua
descrip
Sets a condition in the forcefield for detail reporting.
params
string sInteractionType = { "steric" }
table tForceObjI = Index of 1st force object { iPdb, iDynSeg, iForceObjInSeg }
table tForceObjJ = Index of 2nd force object { jPdb, jDynSeg, jForceObjInSeg }
returns
number bRet = 1 or nil
notes
This method is used to generate data for detailed interactions involving
specific force objects. For example, to produce a file which lists the
steric forces between all pairs of atoms within a particular residue,
the following steps are done:
- Movement of all objects is disabled through a call to enableForcefieldMovement().
- Force calculation for all objects but those being analyzed is disabled through calls
to setForceObj_EnableInternalCalc() and setForceObj_EnableExternalCalc() (optional optimization to speed
up the calculation for large models).
- The report filename is specified in a call to openFfReportStream().
- The report condition is specified in a call to this function:
setFfReportCondition( "steric", tObj, tObj ) where tObjs hold the index
of the force object to be reported.
- The forcefield is single-stepped by a call to stepForcefield().
- The report stream is closed by a call to closeFfReportStream().
The script 'StericReport.lua' has an example of forcefield reporting for selected objects.
seealso
enableForceMovement(), setForceObj_EnableInternalCalc(), setForceObj_EnableExternalCalc()
openFfReportStream(), stepForcefield(), closeFfReportStream().
include
ForceFieldUtil.lua
descrip
Starts or stops the running of the forcefield.
params
number bEnable = 1 to enable or (0 | nil) to disable
returns
number bRet = 1 or nil
notes
seealso
getFfRunState()
include
ForceFieldUtil.lua
descrip
Does an immediate timestep of the forcefield.
params
returns
number bRet = 1 or nil
notes
seealso
setFfReportCondition()
include
ForceFieldUtil.lua
descrip
Adds a new atom type to the list of atom types used in the forcefield.
params
number iElement = element
number fVdwRadius = van der waals radius
number fCharge = electrical charge on atom
string sName = name of the new atom type
returns
number iNewAtomType = number of new atom type
or
nil if error
notes
seealso
setForceObj_AtomType()
include
ForceObjectUtil.lua
descrip
Adds a force object to a force group.
params
number iGroup
table tObj = index of force object
returns
number bAdded = 1
or
nil if error
notes
The group must have been previously created by a call to
createForceGroup().
seealso
createForceGroup(), enableCustomForceContainer()
include
ForceObjectUtil.lua
descrip
Applies a force at a specified position to a node of a force object.
params
table tObj = index of force object
number iNode = index of node in force object
table tPos = Position at which force will be applied
table tForce = { x, y, z } components of force
returns
number bRet = 1
or
nil if error
notes
Typically used by script objects that have defined an fiTick() event.
This allows for external input of forces to objects in the forcefield.
The force is applied after all object forces have been calculated, but
before any timestep movement has occurred.
seealso
addNodeTorque(), createScriptObject(), getForceObj_IndexFromName(), getForceObj_TotalNodes()
include
ForceObjectUtil.lua
descrip
Applies a torque to a node of a force object.
params
table tObj = index of force object
number iNode = index of node in force object
table tTorque = { x, y, z } components of torque
returns
number bRet = 1
or
nil if error
notes
Typically used by script objects that have defined an fiTick() event.
This allows for external input of forces to objects in the forcefield.
The torque is applied after all object forces have been calculated, but
before any timestep movement has occurred. The torque is applied at the
center of mass of the node.
seealso
addNodeForce(), createScriptObject(), getForceObj_IndexFromName(), getForceObj_TotalNodes()
include
ForceObjectUtil.lua
descrip
Creates dynamic segments from the current selection.
params
[string sFlags = '[-v] [-xh<sFullAtomName>.<N>]'
returns
number bRet = 1 or nil
notes
The current selection must consist of static pdb residues. The resulting
dynamic segements will consist of dynamic residues that correspond to
contiguous pdb residues of a static pdb chain.
Flags:
-v = verbose reporting of creation details
-xh<sFullAtomName>.<N> = exclude hydro addition for bond vector <N> on atom <sFullAtomName>
seealso
isCreateSingleAtomNodeSet(), setCreateSingleAtomNode()
include
ForceObjectUtil.lua
descrip
Enables movement for selected force objects.
params
number bEnable = 1 or [nil | 0]
returns
number bRet = 1 or nil
notes
seealso
setForceObj_EnableNodeMove()
groups
ForceObject, Select
include
ForceObjectUtil.lua
descrip
Returns index of node containing param atom in param force object.
params
table tForceObj
number iAtomInForceObj
returns
number iNode
or
nil
notes
seealso
groups
ForceObject
include
ForceObjectUtil.lua
descrip
Returns numerical id of atom type with param name.
params
string sAtomType = name of atom type
returns
number iAtomType
or
nil if error
notes
seealso
getAtomTypeName(), getFirstAtomTypeId(), getTotalAtomTypes()
groups
ForceObject
include
ForceObjectUtil.lua
descrip
Returns name of atom type with param numerical id.
params
number iAtomType = numerical id of atom type (starts at first atom type id, not 0)
returns
string sAtomType = name of atom type
or
nil if error
notes
seealso
getFirstAtomTypeId(), getTotalAtomTypes()
groups
ForceObject
include
ForceObjectUtil.lua
descrip
Returns vdw radius of param atom type.
params
string sAtomType = name of atom type
returns
number fRadius
or
nil if error
notes
seealso
setAtomTypeVdwRadius(), getElementVdwRadius()
getAtomTypeName(), getFirstAtomTypeId(), getTotalAtomTypes()
groups
ForceObject
include
ForceObjectUtil.lua
descrip
Returns the index of the dynamic object with the param name.
params
string sObjName
returns
table tIdx = { iPdb [, iSeg [, iRes [, iAtom]] }
or
nil if dynamic object not found from name
notes
seealso
getObjectIndexFromName()
groups
ForceObject
include
ForceObjectUtil.lua
descrip
Returns number of element from param name.
params
string sName
returns
number iElement
notes
If a valid name is not specified, the number 0 is returned.
include
ForceObjectUtil.lua
descrip
Returns vanderwaals radius of param element.
params
number iElement
returns
number fRadius
notes
seealso
getAtomTypeVdwRadius()
include
ForceObjectUtil.lua
descrip
Returns numerical id of first atom type.
params
returns
number iFirstAtomType
notes
This can be used to enumerate the atom types.
seealso
getAtomTypeName(), getTotalAtomTypes()
groups
ForceObject
include
ForceObjectUtil.lua
descrip
Returns index of force object with param name
params
string sName = (format = 'sPdb.chainId$sResN' where sPdb = pdb name, chainId = chain id, sRes = residue name, N = residue sequence num)
returns
table tForceObj = (index of force object { iPdb, iDynSeg, iDynRes })
or
nil
notes
seealso
getForceObj_Name()
include
ForceObjectUtil.lua
descrip
Returns element of param atom of param force object.
params
table tForceObj = Index of force object { iPdb, iDynSeg, iDynRes }
number iAtom = Index of atom in force object
returns
number iElement
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns index of atom of param force object which has param atom name.
params
table tForceObj
string sName
returns
number iAtomInForceObject
or
nil if not found.
notes
The param name is the atom name in the pdb ATOM record, with spaces trimmed off.
getForceObj_AtomName() will return the name WITH spaces, so those spaces
should be trimmed before being passed into this function.
seealso
getForceObj_AtomName()
include
ForceObjectUtil.lua
descrip
Returns pdb name of param atom of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iAtom = index of atom in force object
returns
string sName
or
nil
notes
The name from the PDB atom record will have typically have spaces in it.
This function should probably be renamed 'getForceObj_AtomRecordName()'
and there should be a new function 'getForceObj_AtomName()' that
automatically returns the trimmed name. Until then, the user must
trim the name before it is to be used in a call to getForceObj_AtomIndexFromName().
If the atom is not a PDB atom, such as hydrogens which have been
added after model loading, then they may not have a proper name and
a proxy name equal to the element symbol will be returned.
seealso
getForceObj_AtomIndexFromName()
include
ForceObjectUtil.lua
descrip
Returns position of param atom of param node of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iAtom = index of atom in force object
returns
table ptAtom
or
nil
notes
For static atoms, the corresponding function is getAtomPos().
seealso
getAtomPos()
include
ForceObjectUtil.lua
descrip
Returns index of node containing param atom in param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iAtom = index of atom in force object
returns
number iNode
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns atom type of param atom of param force object.
params
table tForceObj = Index of force object { iPdb, iDynSeg, iDynRes }
number iAtom = Index of atom in force object
returns
number iElement
or
nil
notes
seealso
setForceObj_AtomType()
include
ForceObjectUtil.lua
descrip
Returns aa bounding box center of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
returns
table ptCenter
or
nil
notes
seealso
getForceObj_MassCenter()
include
ForceObjectUtil.lua
descrip
Returns pdb name of atom of param hydrogen bond acceptor of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iAccept = index of hydrogen bond acceptor
returns
string sAtomName
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns position of atom of param hydrogen bond acceptor of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iAccept = index of hydrogen bond acceptor
returns
table tAtomPos
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns position of hydrogen atom of param hydrogen bond acceptor of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iAccept = index of hydrogen bond acceptor
returns
table tElectronPos
or
nil
notes
This is the normalized position of the electron. The actual position of the
electron is determined by the van der Waals radius and the forcefield
parameter 'nbeProject'.
include
ForceObjectUtil.lua
descrip
Returns max potential of param hydrogen bond acceptor of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iAccept = index of hydrogen bond acceptor
returns
number fMaxPot
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns ptr of max hb donor of param hydrogen bond acceptor of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iAccept = index of hydrogen bond acceptor
returns
string sDonorPtr
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns ptr of param hydrogen bond acceptor of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iAccept = index of hydrogen bond acceptor
returns
string sAcceptPtr
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns pdb name of atom of param hydrogen bond donor of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iDonor = index of hydrogen bond donor
returns
string sAtomName
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns position of atom of param hydrogen bond donor of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iDonor = index of hydrogen bond donor
returns
table tAtomPos
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns position of hydrogen atom of param hydrogen bond donor of param force object.
params
table tForceObj = index of force object { iPdb, iTotalChains + iDynSeg, iDynRes }
number iDonor = index of hydrogen bond donor
returns
table tHydroAtomPos
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns ptr of param hydrogen bond acceptor of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iDonor = index of hydrogen bond acceptor
returns
string sDonorPtr
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns mass center of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
returns
table ptCenter
or
nil
notes
seealso
getForceObj_BoxCenter()
include
ForceObjectUtil.lua
descrip
Returns table of pairs of atom indices of intra-residue bonds of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
returns
table tBonds = { { iAtom0, jAtom0 }, { iAtom1, jAtom1 }, ... }
or
nil if invalid index
notes
iAtom0 is the index of the first atom of the first intra-residue bond, jAtom0
is the index of the second atom of the first intra-residue bond.
seealso
getForceObj_PrevResBond()
include
ForceObjectUtil.lua
descrip
Returns name of force object with param index.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
returns
string sName
or
nil if invalid index
notes
Currently, a force object name is equivalent to the full name of a dynamic residue
(e.g: '1tra.a$.G1').
seealso
getForceObj_IndexFromName()
include
ForceObjectUtil.lua
descrip
Returns indices of child nodes of param node of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iNode
returns
table tDescendantNodeIdxs
or
nil if error
notes
If the param node has no children, the returned table will be empty.
seealso
getForceObj_NodeParent(), getForceObj_NodeDescendants()
include
ForceObjectUtil.lua
descrip
Returns center-of-mass position of param node.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iNode
returns
table ptCom
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns indices of descendant nodes of param node of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iNode
returns
table tDescendantNodeIdxs
or
nil if error
notes
If the param node has no descendants, the returned table will be empty.
seealso
getForceObj_NodeChildren(), getForceObj_NodeParent()
include
ForceObjectUtil.lua
descrip
Returns total force on param node.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iNode
returns
table vForce
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns homogeneous transform matrix for param node of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iNode
returns
table hmFrame = { hm00, ..., hm15 }
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns index of parent node of param node of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iNode
returns
number tParentNodeIdx
or
nil if error
notes
If the param node has no parent, the value -1 will be returned.
seealso
getForceObj_NodeChildren(), getForceObj_NodeDescendants()
include
ForceObjectUtil.lua
descrip
Returns total torque on param node.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iNode
returns
table vTorque
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns velocity of param node.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iNode
returns
table vVel
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns angular velocity of param node.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iNode
returns
table vAngVel
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns selected state of param force object node.
params
table tForceObj = Index of force object { iPdb, iDynSeg, iDynRes }
number iNode = Index of node in force object
returns
number bSelected = 1 or 0
or
nil if error
notes
If force object has been created with 'single-atom-per-node' option, this
will be equivalent to the selected atom state.
seealso
isForceObjectNodeSelected(), selectNode()
groups
ForceObject, Select
include
ForceObjectUtil.lua
descrip
Returns table of pairs of atom indices of intra-residue bonds of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
returns
table tBond = { iAtom, jAtom }
or
nil if invalid index
notes
iAtom is the index of the atom in the param residue and jAtom is
is the index of the atom in the previous residue.
seealso
getForceObj_IntraResBonds()
include
ForceObjectUtil.lua
descrip
Returns selected state of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
returns
number bSelected = 1 or 0
or
nil if error
notes
seealso
isForceObjectSelected()
groups
ForceObject, Select
include
ForceObjectUtil.lua
descrip
Returns total number of atoms in param force object.
params
table tForceObj = Index of force object { iPdb, iDynSeg, iDynRes }
returns
number iTotalAtomsInForceObject
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns total number of atoms in param node in param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iNode
returns
number iTotalAtoms
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns total force vector on param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
returns
table tTotalForce = { fx, fy, fz }
or
nil if error
notes
The total force on a force object is defined as the sum of the total
forces on all the nodes of the force object.
include
ForceObjectUtil.lua
descrip
Returns total number of hbond acceptors in param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
returns
number iTotal
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns total number of hbond donors in param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
returns
number iTotal
or
nil
notes
include
ForceObjectUtil.lua
descrip
Returns total number of nodes in param force object.
params
table tForceObj = Index of force object { iPdb, iDynSeg, iDynRes }
returns
number iTotal
or
nil
notes
Nodes are the basic units to which force is applied in the forcefield.
In the current implementation, a node is equivalent to a single atom.
A set of atoms within a dynamic residue are connected as nodes in a
graph, as determined by the covalent bonds between the atoms. Together,
the set of nodes comprise a force object.
include
ForceObjectUtil.lua
descrip
Returns a homogeneous matrix of most recent rotation of param node of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iNode = index of node
returns
table tMatrix = { hmf00, ... hmf15 }
or
nil if error
notes
Recording must first be enabled by setForceObj_EnableRecordNodeMove().
seealso
getForceObjectRecordedNodeTranslation(), setForceObj_EnableRecordNodeMove()
include
ForceObjectUtil.lua
descrip
Returns a homogeneous matrix of most recent translation of param node of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iNode = index of node
returns
table tMatrix = { hmf00, ... hmf15 }
or
nil if error
notes
Recording must first be enabled by setForceObj_EnableRecordNodeMove().
seealso
getForceObjectRecordedNodeRotation(), setForceObj_EnableRecordNodeMove()
include
ForceObjectUtil.lua
descrip
Returns a list of indices of all force objects.
params
returns
table tObjs = { tObj0, tObj1, ..., tObjN }
notes
The content of each 'tObjN' is { iPdb, iDynSeg, iRes }
For large models, the stack size of the lua script context may need to be increased before
calling this function.
seealso
getSelectedForceObjects()
groups
ForceObject
include
ForceObjectUtil.lua
descrip
Returns index of previous force object in segment, if any.
params
table tForceObj = index of force object
returns
table tPrevForceObj
or
nil if no previous force object in segment exists
or the force object index is not valid.
notes
seealso
getNextForceObjectInSeg()
include
ForceObjectUtil.lua
descrip
Returns index of next force object in segment, if any.
params
table tForceObj = index of force object
returns
table tNextForceObj
or
nil if no next force object in segment exists or the param index is
not valid.
notes
seealso
getPrevForceObjectInSeg()
include
ForceObjectUtil.lua
descrip
Returns index of param selected dynamic atom.
params
number iSelAtom = ith selected dynamic atom when iterating all dynamic atoms
returns
table tAtom = { iPdb, iDynSeg, iRes, iAtom }
or
nil
notes
seealso
getTotalSelectedDynamicAtoms(), isDynamicAtomSelected()
groups
ForceObject, Select
include
ForceObjectUtil.lua
descrip
Returns index of param selected force object (dynamic residue).
params
[number iSelObj = 0]
returns
table tObj = { iPdb, iDynSeg, iRes }
or
nil
notes
seealso
getTotalSelectedForceObjects(), getSelectedForceObjects()
groups
ForceObject, Select
include
ForceObjectUtil.lua
descrip
Returns a list of indices of all selected force objects (dynamic residues).
params
returns
table tSel = { tObj0, tObj1, ..., tObjN }
notes
The content of each 'tObjN' is { iPdb, iDynSeg, iRes }
seealso
getTotalSelectedForceObjects(), getSelectedForceObject()
groups
ForceObject, Select
include
ForceObjectUtil.lua
descrip
Returns total number of atom types.
params
returns
number iTotalAtomTypes
or
nil
notes
seealso
getFirstAtomTypeId(), getAtomTypeName()
include
ForceObjectUtil.lua
descrip
Returns total number of dynamic segments in param pdb model.
params
number iPdb = index of pdb model in document
returns
number iTotalDynSegsInPdb
notes
include
ForceObjectUtil.lua
descrip
Returns total number of force objects in forcefield.
params
returns
number iTotal
notes
seealso
groups
ForceObject
include
ForceObjectUtil.lua
descrip
Returns total number of force objects in param dynamic segment.
params
number iPdb = index of pdb model in document
number iSeg = index of dynamic segment in pdb
returns
number iTotalForceObjs
notes
This function, in conjunction with getTotalDynamicSegmentsInPdb() and
getTotalPdbs(), can be used to enumerate all the force objects in the document.
seealso
getTotalDynamicSegmentsInPdb(), getTotalPdbs()
include
ForceObjectUtil.lua
descrip
Returns total number of selected dynamic atoms.
params
returns
number iTotalSelDynAtoms
notes
seealso
getSelectedDynamicAtom(), isDynamicAtomSelected()
groups
ForceObject, Select
include
ForceObjectUtil.lua
descrip
Returns total number of selected force objects (dynamic residues) in the document.
params
returns
number iTotalSelectedForceObjects
notes
For static residues, use getTotalSelectedResidues() instead.
seealso
getSelectedForceObject(), getSelectedForceObjects(), getTotalSelectedResidues()
groups
ForceObject, Select
include
ForceObjectUtil.lua
descrip
Returns true if single-atom node creation is enabled for dynamic models.
params
returns
number bSet = 1 or nil
notes
seealso
setCreateSingleAtomNode()
include
ForceObjectUtil.lua
descrip
Returns selected state of param force object node.
params
table tForceObj = Index of force object { iPdb, iDynSeg, iDynRes }
number iAtom = index of dynamic atom
returns
number bSelected = 1 or nil
notes
If the param index is invalid, no error is returned.
seealso
getSelectedDynamiAtom()
groups
ForceObject, Select
include
ForceObjectUtil.lua
descrip
Returns selected state of param force object node.
params
table tForceObj = Index of force object { iPdb, iDynSeg, iDynRes }
number iNode = index of force object node
returns
number bSelected = 1 or nil
notes
If the param index is invalid, no error is returned.
seealso
getForceObj_NodeSelectedState(), selectNode()
groups
ForceObject, Select
include
ForceObjectUtil.lua
descrip
Returns selected state of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
returns
number bSelected = 1 or nil
notes
If the param index is invalid, no error is returned.
seealso
getForceObj_SelectedState()
groups
ForceObject, Select
include
ForceObjectUtil.lua
descrip
Returns true if param index is a valid dynamic segment index.
params
number iPdb
number iSeg
returns
number bValid = 1 or nil
notes
seealso
isValidForceObjectIndex()
groups
ForceObject
include
ForceObjectUtil.lua
descrip
Returns true if param table is a valid force object index.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
returns
number bValid = 1 or nil
notes
seealso
isValidDynSegIndex()
groups
ForceObject
include
ForceObjectUtil.lua
descrip
Resets the transforms for all selected force objects.
params
returns
number bRet = 1 or nil
notes
seealso
transformForceObject()
groups
ForceObject, Geom, Select
include
ForceObjectUtil.lua
descrip
Rotates force object about param vector around param point by param degrees.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number fDeg = degrees to rotate
table vRot = vector about which to rotate, in world frame
table ptCenter = point around which to rotate, in world frame
returns
number bRet = 1 or nil
notes
seealso
translateForceObject(), transformForceObject(), rotateForceObjectNode()
groups
ForceObject, Geom
include
ForceObjectUtil.lua
descrip
Rotates a chain of force object nodes about a bond axis associated with the param node, by param degrees.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iNode = Node on force object about which to rotate
number fDeg = degrees to rotate
number bFwdNodes = 1 : rotate descendent nodes, else rotate ancestor nodes
returns
number bRet = 1 or nil
notes
The subsequent nodes in the residue, and subsequent residues in the segment
will be automatically rotated about the node bond axis as well. The bond
axis is determined by the between between the first atom in the node and the
bond partner atom in the parent node.
To do rotation of the node about an arbitrary axis, transformForceObjectNode() can
be used instead.
seealso
transformForceObjectNode()
groups
ForceObject, Geom, Dihedral
include
ForceObjectUtil.lua
descrip
Selects all force objects.
params
returns
number bRet = 1 or nil
notes
seealso
groups
ForceObject, Select
include
ForceObjectUtil.lua
descrip
Sets param atom type vdw radius to param value.
params
string sAtomType = '<C|N|O|P><sp2|sp3|1P|2P>'
number fRadius
returns
number bRet = 1
or
nil if error
notes
When force objects are created, the types of their component atoms
will be set to a particular value, based upon the atom name and type of
residue that it is in. For example, 'A1.C2', which refers to the C2
atom of an adenosine resiude, would be set to type 'Carbon_Sp2', to indicate
that it is in a planar base with valence sp2. Additionally, 'A1.C2*'
would be set to 'Carbon_Sp3' to indicate its sp3 valence. Each atom
type can have an individual set of forcefield parameters, the first of
which is a van der waals radius. This type will be used during force
and energy calculations, such as is done in the rbq classes CTorsionBodyIteFcon,
CTorsionBodyTgaFcon and CTorsionBodyTgaxFcon. If no atom type is set,
the atom has a default type corresponding to its element, with parameters
such as a 'generic' van der waals radius assigned by the element properties
class CElement.
seealso
getAtomTypeVdwRadius(), getElementVdwRadius()
getAtomTypeName(), getFirstAtomTypeId(), getTotalAtomTypes()
groups
ForceObject
include
ForceObjectUtil.lua
descrip
Sets 'single atom node' creation mode for force objects.
params
number bSet = 1 or nil
returns
number bRet = 1 if success or nil if error
notes
When force objects are created, atoms within rings can be consolidated into
a common node when the 'create single atom per node' mode is off. This
means that all these atoms will move together as a rigid body. For large
models, this mode can reduce the memory size and processing time that is
needed for simulating the dynamic model.
When the mode is on, each node created in the force object will consist of a single atom.
For force objects saved in rbd documents, the current state of the mode will be saved
with the model, and used to recreate the dynamic model when reloaded. However, if
the user creates a dynamic model, simulates it and records a movie of the simulation
and then manually recreates the dynamic model in in a subsequent session, the mode in
the subsequent session must be the same as when the movie was recorded or the movie
playback will be incorrect.
seealso
isCreateSingleAtomNodeSet()
groups
ForceObject
include
ForceObjectUtil.lua
descrip
Sets angular velocity of all nodes in param force object to param velocity.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
table tVel = {vx, vy, vz}
returns
number bRet = 1 on success
or
nil if error
notes
seealso
setForceObj_Velocity()
include
ForceObjectUtil.lua
descrip
Sets atom type of param atom of param force object.
params
table tForceObj = Index of force object { iPdb, iDynSeg, iDynRes }
number iAtom = Index of atom in force object
number iAtomType = number of atom type
returns
number bRet = 1 if success
or
nil if error
notes
seealso
getForceObj_AtomType(), addCustomAtomType()
include
ForceObjectUtil.lua
descrip
Enables movement of param node of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iNode = index of node in force object
number iEnable = 1 or 0
returns
number bRet = 1 on success
or
nil if error
notes
seealso
getForceObj_TotalNodes(), enableSelForceObjectsMove()
include
ForceObjectUtil.lua
descrip
Enables external force calculations for the param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iEnable = 1 or [0, or nil]
returns
number bRet = 1 on success
or
nil if error
notes
External force calculations consist of inter-residue (atom, atom) steric
interactions, hydrogen bond forces, electrostatic forces and aromatic
ring-stacking interactions.
seealso
setForceObj_EnableForceCalc(), setForceObj_EnableInternalCalc()
include
ForceObjectUtil.lua
descrip
Enables/disables all force calculations for the param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iEnable = 1 or [0 or nil]
returns
number bRet = 1 on success
or
nil if error
notes
Enables/disables internal and external force calculations. If disabled,
all interactions with other dynamic residues are skipped for this object
and all internal interactions are skipped as well.
seealso
setForceObj_EnableInternalCalc(), setForceObj_EnableExternalCalc()
include
ForceObjectUtil.lua
descrip
Enables internal force calculations for the param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iEnable = 1 or [0 or nil]
returns
number bRet = 1 on success
or
nil if error
notes
Internal force calculations consist of intra-residue (atom, atom) steric
interactions, intra-residue covalent bond forces, and covalent bond force
to subsequent residue in segment, if any.
In the current implementation, these internal force calculations also
include covalent and torsion interactions with the previous force object
in the segment, if any.
seealso
setForceObj_EnableForceCalc(), setForceObj_EnableExternalCalc()
include
ForceObjectUtil.lua
descrip
Enables recording of movement of param node of param force object.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iNode = index of node in force object
number iEnable = 1 or 0
returns
number bRet = 1 on success
or
nil if error
notes
seealso
getForceObjectRecordedNodeRotation(), getForceObjectRecordedNodeTranslation()
include
ForceObjectUtil.lua
descrip
Sets velocity of all nodes in param force object to param velocity.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
table tVel = {vx, vy, vz}
returns
number bRet = 1 on success
or
nil if error
notes
seealso
setForceObj_AngVelocity()
include
ForceObjectUtil.lua
descrip
Transforms force object by param matrix.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
table tMat = { hmf00, ..., hmf15 }
returns
number bRet = 1 or nil
notes
This funtion can be used in conjunction with getForceObjectRecordedNodeRotation()
and getForceObjectRecordedNodeTranslation() to synchronize the movement of inactive
force objects to adjacent active ones.
seealso
rotateForceObject(), translateForceObject(),
getForceObjectRecordedNodeRotation(), getForceObjectRecordedNodeTranslation()
transformForceObjectNode()
groups
ForceObject, Geom
include
ForceObjectUtil.lua
descrip
Transforms param node of param force object by param matrix.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
number iNode = node to be transformed
table tMat = { hmf00, ..., hmf15 }
returns
number bRet = 1 or nil
notes
The node matrix is premultiplied by the param homogeneous transform matrix.
The caller must subsequently call updateForceObjectAtomPositions() for the
new transform to be applied.
seealso
rotateForceObject(), translateForceObject(),
getForceObjectRecordedNodeRotation(), getForceObjectRecordedNodeTranslation()
transformForceObject(), updateForceObjectAtomPositions(), rotateForceObjectNode()
getRotatedHMatrix(), getTranslatedHMatrix()
groups
ForceObject, Geom
include
ForceObjectUtil.lua
descrip
Translates force object by param vector.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
table vTrans = (translation, world frame)
returns
number bRet = 1 or nil
notes
seealso
rotateForceObject(), transformForceObject()
groups
ForceObject, Geom
include
ForceObjectUtil.lua
descrip
Updates all atoms in param force object with positions defined by the force object node frames.
params
table tForceObj = index of force object { iPdb, iDynSeg, iDynRes }
returns
number bRet = 1 or nil
notes
This function is typically called after one or more calls to transformForceObjectNode().
seealso
transformForceObjectNode()
groups
ForceObject, Geom
include
ForceObjectUtil.lua
descrip
Aligns one pdb model to another using 2 param helices. The pdb model of the second chain (sPdbChainJ) is aligned to the pdb model of the first chain (sPdbChainI). The first helices of the chains (sHelixNum1) are exactly aligned and then the model is rotated about the first helix axis until the second helices (sHelixNum2 ) are most closely aligned.
params
string sPdbChainI
string sPdbChainJ
string sHelixNum1
string sHelixNum2
returns
number bRet = 1 or nil
notes
include
GeomUtil.lua
descrip
Calculates the RMS difference between backbone atoms of 2 pdb chains.
params
string sPdbChainI
string sPdbChainJ
returns
number fRms = RMS difference or -1 if error
string sStatus
notes
A sequence map file for the param chains is required for RMS calculation.
seealso
groups
Geom, Seq
include
GeomUtil.lua
descrip
Calculates and returns the endpoints and vector of the arrow which points down the center of the helix defined by the param residue indices.
params
table tHelixRes = table of residue indices of the 4 end residues which define the helix (5'beg, 5'end, 3'beg, 3'end).
returns
table tArrow = { ptBeg, ptEnd, vDir }
notes
This function is mostly intended for internal use by alignPdbFromHelix().
include
GeomUtil.lua
descrip
Calculates the degrees and orthogonal vector needed to rotate from 1st param vector to the 2nd param vector.
params
table v1
table v2
returns
number degRot
table vRot
notes
If the cross product between the param vectors is zero, a rotation of 0 degrees
about the x axis is returned if the angle is 0, else if angle 180, 180 degrees is returned.
The input vectors do not need to be normalized. The return vector will be normalized.
If either of the param vectors is the zero vector, nil will be returned.
include
GeomUtil.lua
descrip
Creates a script object to draw arrows pointing down the length of the param helices.
params
string sHelixFile
string sPdbChain
table tHelixNums
returns
number bRet = 1
string sAnnName
or
number bRet = nil
string sErrMsg
notes
All helix arrows will be drawn with a color equal to the first 5' residue
of the first helix in the list.
include
GeomUtil.lua
descrip
Returns list of atoms of residues of pdb chain J which are in param distance of atoms of param residue of chain I.
params
string sPdbChainResI = name of source pdb and chain (ex: '1ffk.0.A2602')
string sPdbChainJ = name of target pdb and chain (ex: '1tra.a')
number fMaxDist = maximum distance between vdw bounds of atoms
returns
number bRet = 1 on success, else nil
string sResJList = "<res0> <res1> ..." (ex: "C69 G71 C72 C73 G74" )
string sStatus = error message on fail
notes
seealso
groups
ForceObject, Geom
include
GeomUtil.lua
descrip
Returns a set of vectors defining the center point, look and up directions for param nucleic acid residue.
params
table tDynRes : index of dynamic residue
returns
table tDirs = { sRefAtomName, tCen, tLook, tUp }
or
number bRet = nil
string sStatus
if failed getting base vectors.
notes
tCen is position of the reference atom, which is the center atom on the watson-crick edge.
include
GeomUtil.lua
descrip
Returns the bounding box center of the param chain object.
params
number iPdb
number iChain
returns
table tCen = { x, y, z}
or
nil if error
notes
seealso
getChainMassCenter()
groups
Geom, Pdb
include
GeomUtil.lua
descrip
Returns the mass center of the param chain object.
params
number iPdb
number iChain
returns
table tCen = { x, y, z}
or
nil if error
notes
seealso
getChainBoxCenter()
groups
Geom, Pdb
include
GeomUtil.lua
descrip
Returns a homogeneous transform matrix that is an interpolation of the param matrices.
params
table ptBeg
table hmBeg
table ptEnd
table hmEnd
number fInterp
returns
table hmInterpTransform
or
nil if error
notes
seealso
getInterpTransform()
groups
Geom, Vector
include
GeomUtil.lua
descrip
Returns a homogeneous transform matrix that is an interpolation of the param values.
params
table ptCen
table vTrans
table hmRot
number fInterp
returns
table hmInterpTransform
or
nil if error
notes
seealso
getInterpHTransform()
groups
Geom, Vector
include
GeomUtil.lua
descrip
Returns center of mass of the param object.
params
string sObjName
returns
table ptCen = { x, y, z }
or
nil if invalid object
notes
The object name can specify a static pdb object or a dynamic object:
| object | syntax
|
|---|
| pdb model | <sPdbName>
|
| static chain | <sPdbName>.<sChainId>
|
| static residue | <sPdbName>.<sChainId>.<sResName>
|
| dynamic segment | <sPdbName>.<sChainId>$
|
| dynamic residue | <sPdbName>.<sChainId>$.<sResName>
|
| dynamic atom | <sPdbName>.<sChainId>$.<sResName>.<sAtomName>
|
seealso
getObjectBoxCenter()
groups
Geom, Pdb
include
GeomUtil.lua
descrip
Returns a normalized vector orthogonal to the param vector.
params
table vIn
returns
table vOrtho
notes
The param vector does not have to be normalized.
seealso
groups
Geom, Vector
include
GeomUtil.lua
descrip
Returns the bounding box center of the param pdb object.
params
number iPdb
returns
table tCen = { x, y, z}
or
nil if error
notes
seealso
getPdbMassCenter()
groups
Geom, Pdb
include
GeomUtil.lua
descrip
Returns the mass center of the param pdb object.
params
number iPdb
returns
table tCen = { x, y, z }
or
nil if error
notes
seealso
getPdbBoxCenter()
groups
Geom, Pdb
include
GeomUtil.lua
descrip
Returns the transform matrix of the param pdb object.
params
number iPdb
returns
table tMatrix = { m00, m01, m02, ..., m15 }
or
nil if invalid pdb index
notes
seealso
setPdbTransform()
groups
Pdb, Geom
include
GeomUtil.lua
descrip
Returns list of residues of pdb chain J whose bounding boxes intersect bounding box of residue of pdb chain I.
params
string sPdbChainResI : name of source pdb and chain (ex: '1ffk.0.A2602')
string sPdbChainJ : name of target pdb and chain (ex: '1tra.a')
number fResExtBound : distance beyond residue bounding box to check for intersection
returns
number bRet : 1 on success, else nil
string sResJList : "<res0> <res1> ..." (ex: "C69 G71 C72 C73 G74" )
string sStatus : error message on fail
notes
seealso
groups
ForceObject, Geom
include
GeomUtil.lua
descrip
Returns the bounding box center of the param residue.
params
table tResIndex = { iPdb, iChain, iRes }
returns
table tCen = { x, y, z}
or
nil if error
notes
seealso
getResidueMassCenter()
groups
Geom, Pdb
include
GeomUtil.lua
descrip
Returns the mass center of the param residue.
params
table tResIndex = { iPdb, iChain, iRes }
returns
table tCen = { x, y, z}
or
nil if error
notes
seealso
getResidueBoxCenter()
groups
Geom, Pdb
include
GeomUtil.lua
descrip
Returns the midpoint between the center of the first 2 selected pdb objects.
params
returns
table vCen
or
nil if selected pdbs not found
include
GeomUtil.lua
descrip
Inserts a ruler annotation object extending between the param endpoints.
params
string sRulerName
table vStartPos
table vEndPos
[number bEcho]
returns
1 on success
or
nil if error
notes
seealso
groups
Geom, Ann
include
GeomUtil.lua
descrip
Positions the current selection to be centered at the param point.
params
table vDstPos = Destination point (world frame).
returns
1 on success
or
nil on error
notes
seealso
translateSelection(), rotateSelection()
groups
Geom, Select
include
GeomUtil.lua
descrip
Sets the transform matrix of the param pdb object to the identity matrix.
params
number iPdb
returns
number bRet = 1 or nil
notes
seealso
setPdbTransform(), resetSelectionTransform()
groups
Pdb, Geom
include
GeomUtil.lua
descrip
Rotates the param pdb object by the param degrees about param vector around param center point.
params
number iPdb
number deg
table vRot (world frame)
table vCenter (world frame)
returns
notes
seealso
translatePdb()
groups
Geom, Pdb
include
GeomUtil.lua
descrip
Rotates current selection by param degrees about param vector around selection center point.
params
number fDeg = degrees to rotate
table vRot (world frame)
[table ptCen] (world frame)
returns
notes
If no center is given, the rotation will occur around the selection center.
If the selection includes dynamic segments, only the dynamic segment selection
will be rotated. Else, the pdb model selection will be rotated.
seealso
translateSelection(), positionSelection(), setSelectionTransform()
groups
Geom, Select
include
GeomUtil.lua
descrip
Sets the transform matrix of the param pdb object.
params
number iPdb
table tMatrix
returns
number bRet = 1 or nil
notes
seealso
resetPdbTransform()
groups
Pdb, Geom
include
GeomUtil.lua
descrip
Sets the position of an existing ruler to the param endpoints.
params
string sRulerName
table vi
table vj
number bEchoCmd
returns
notes
seealso
insertRuler()
groups
Geom, Ann
include
GeomUtil.lua
descrip
Sets the transform matrix of the current selection.
params
string sHmTransform = "<m01> <m02> ... <m16>";
returns
number bRet = 1 or nil
notes
seealso
translationSelection(), rotateSelection(), positionSelection(), resetSelectionTransform()
groups
Geom, Select
include
GeomUtil.lua
descrip
Translates the param pdb object by the param vector.
params
number iPdb
table vTrans (world frame)
returns
number bRet = 1
or
nil if invalid index
notes
seealso
rotatePdb()
groups
Geom, Pdb
include
GeomUtil.lua
descrip
Translates current selection by param vector.
params
table vTrans (world frame)
returns
notes
If the selection includes dynamic segments, only the dynamic segment selection
will be translated. Else, the pdb model selection will be translated.
seealso
rotateSelection(), positionSelection(), setSelectionTransform()
groups
Geom, Select
include
GeomUtil.lua
descrip
Returns the current frame number of the currently loaded movie.
params
returns
number iFrame
notes
seealso
include
MovieUtil.lua
descrip
Returns a number indicating current direction of movie playback.
params
returns
number iRet = 1 if forward, else -1 for reverse play
notes
seealso
setMoviePlaybackDir()
include
MovieUtil.lua
descrip
Returns total number of frames in currently loaded movie.
params
returns
number iTotalFrames
notes
seealso
include
MovieUtil.lua
descrip
Returns true if movie playback is paused.
params
returns
number bRet = 1 or nil
notes
seealso
include
MovieUtil.lua
descrip
Returns true if movie playback is stopped.
params
returns
number bRet = 1 or nil
notes
seealso
include
MovieUtil.lua
descrip
Sets pause state of movie.
params
number iPause = 1 or 0
returns
number bRet = 1 or nil
notes
seealso
isMoviePaused()
include
MovieUtil.lua
descrip
Sets the param frame number as the current frame of the currently loaded movie.
params
number iFrame
returns
number bRet = 1 or nil
notes
iFrame is a 0-based index, valid range is [0, iTotalMovieFrames - 1].
seealso
getMovieFrame(), getTotalMovieFrames()
include
MovieUtil.lua
descrip
Sets the name of the file from which a movie is played.
params
string sFile
returns
number bRet = 1
or
nil if error
notes
seealso
setMovieOutfile()
include
MovieUtil.lua
descrip
Sets the name of the file to which a movie is recorded.
params
string sFile
returns
number bRet = 1
or
nil if error
notes
If the file currently exists, an overwrite conformation dialog will appear in
the application window. To avoid this, make sure that the file has been
previously deleted.
seealso
setMovieInfile()
include
MovieUtil.lua
descrip
Sets movie state to playing.
params
returns
number bRet = 1 or nil
notes
seealso
setMovieStop(), setMovieRecord(), pauseMovie()
include
MovieUtil.lua
descrip
Sets direction of movie playback.
params
number iDir = 1 for forward play or -1 for reverse play
returns
number bRet = 1 or nil
notes
seealso
getMoviePlaybackDir()
include
MovieUtil.lua
descrip
Sets movie state to recording.
params
returns
number bRet = 1 or nil
notes
seealso
setMovieStop(), setMoviePlay(), pauseMovie()
include
MovieUtil.lua
descrip
Sets movie record rate. This is the number of ticks per recorded movie frame.
params
number fRate
returns
number bRet = 1 or nil
notes
seealso
tickRecordMovie()
include
MovieUtil.lua
descrip
Sets movie state to stopped.
params
returns
number bRet = 1 or nil
notes
seealso
setMovieRecord(), setMoviePlay(), pauseMovie()
include
MovieUtil.lua
descrip
Calls the tick event for the forcefield movie playback.
params
returns
number bRet = 1 if a frame was recorded back, else nil
notes
This is a way for recording movies independently of the forcefield timestep.
The movie must currently be in the recording state for this function to
have an effect.
The condition that determines whether a frame will be recorded as a result
of this call depends on the current movie record rate.
seealso
setMovieRecordRate()
include
MovieUtil.lua
descrip
Adds an inter-residue bond between a static residue and previous residue in chain.
params
table tRes = { iPdb, iChain, iRes }
number iAtom = index of atom in residue
number jAtom = index of atom in previous residue
returns
number bRet = 1
or
nil if error
notes
The current implementation only creates inter-residue betweens between residues
that are in a standard sequence direction. For nucleic acids, this means that
the PDB sequence of residues corresponds to a 5' to 3' sequence. For proteins,
this means the PDB sequence corresponds to an amino to carboxyl sequence of residues.
This function can be used to create bonds between residues which are in a reversed
sequence.
seealso
include
PdbUtil.lua
descrip
Appends a PDB ATOM or HETATOM record to param file.
params
string sFile = name of pdb file to append to
table tRecord =
{
bHetAtom = number bHetAtom,
iAtomSerial = number iAtomSerial,
sAtomName = string sAtomName,
sResName = string sResidueName,
sChainId = string sChainId,
iResSeqNum = number iResidueSequenceNum,
tAtomPos = numbers tAtomPos = { x, y, z },
}
returns
number bRet = 1
or
nil if error
notes
seealso
include
PdbUtil.lua
descrip
Deletes all loaded pdb objects.
params
returns
number 1
or
number nil, string sStatus
notes
seealso
deletePdbObject(), deleteSelection(), closeDocument()
include
PdbUtil.lua
descrip
Deletes named pdb object.
params
sPdbName
returns
number 1
or
number nil, string sStatus
notes
seealso
deleteAllPdbObjects(), deleteSelection()
include
PdbUtil.lua
descrip
Returns the element number of the param atom.
params
table tAtomIdx = { iPdb, iChain, iRes, iAtom }
returns
number iEl
or
nil
notes
Atom index is 0-based. Element number is 1 based: 1 = Hydrogen, 2 = Helium, etc.
include
PdbUtil.lua
descrip
Returns the full atom index from the full name of the param atom.
params
string sFullName = 'pdbName.chainId.resName.atomName'
returns
table tAtomIdx = { iPdb, iChain, iRes, iAtom }
or
nil
notes
Index is 0-based. Dynamic atoms are also supported by this function.
seealso
getResAtomIndex(), getAtomName()
include
PdbUtil.lua
descrip
Returns the residue index from the name of the param atom and owner residue index.
params
table tResIdx = { iPdb, iChain, iRes }
string sAtomName
returns
number iAtomInResidue
or
nil
notes
Index is 0-based. The param atom name should be the name from a PDB record, with spaces trimmed.
seealso
getAtomIndex(), getAtomName()
include
PdbUtil.lua
descrip
Returns the full dotted name of the static atom with param index.
params
table tAtomIdx = { iPdb, iChain, iRes, iAtom }
returns
string sName
or
nil
notes
Index is 0-based.
seealso
getAtomIndex(), getAtomPdbName(), getAtomPartName()
include
PdbUtil.lua
descrip
Returns the string from the atom name field of the PDB ATOM record of the static atom with the param index.
params
table tAtomIdx = { iPdb, iChain, iRes, iAtom }
returns
string sName
or
nil
notes
Index is 0-based. The name is from the atom name field in a
PDB ATOM record of a PDB file, and so any spaces from that field will be
included in the returned name.
seealso
getResAtomIndex(), getAtomIndex(), getAtomName(), getAtomPartName()
include
PdbUtil.lua
descrip
Returns the trimmed string from the atom name field of the PDB ATOM record of the static atom with the param index.
params
table tAtomIdx = { iPdb, iChain, iRes, iAtom }
returns
string sName
or
nil
notes
Index is 0-based. The name is from the atom name field in a
PDB ATOM record of a PDB file, with spaces trimmed.
seealso
getAtomIndex(), getAtomName(), getAtomPdbName()
include
PdbUtil.lua
descrip
Returns the position of the param atom.
params
table tAtomIdx = { iPdb, iChain, iRes, iAtom }
returns
table ptPos
or
nil
notes
Index is 0-based. This function is for static atoms only. For dynamic atoms,
call getForceObj_AtomPos().
seealso
getForceObj_AtomPos()
include
PdbUtil.lua
descrip
Returns the PDB atom serial number of the param atom
params
table tAtomIdx = { iPdb, iChain, iRes, iAtom }
returns
number iSerial or nil
notes
Index is 0-based.
include
PdbUtil.lua
descrip
Returns the position of the backbone atom of the param residue.
params
table tResIdx = { iPdb, iChain, iRes }
returns
table vPos = { x, y, z }
or
nil
include
PdbUtil.lua
descrip
Returns the PDB file COMPND record description of the param chain.
params
number iPdb
number iChain
returns
string sChainDescrip
include
PdbUtil.lua
descrip
Returns the pdb and chain index of the chain with the param name.
params
string sPdbName.ChainName (ex: '1kpj.0')
returns
table tChainIndex = { number iPdbInDoc, iChainInPdb }
or
nil if error
notes
seealso
getChainName(), getPdbIndexFromName(), getResidueIndex()
include
PdbUtil.lua
descrip
Returns the name of the chain with param index.
params
table tChainIndex = { number iPdbInDoc, iChainInPdb }
or
nil if invalid index
returns
string sPdbName.ChainName (ex: '1kpj.0')
notes
seealso
getChainIndex()
include
PdbUtil.lua
descrip
Returns atom indices of ith inter-residue bond between param residues.
params
number iPdb
number iChain
number iRes
number jRes
number iBond
returns
number iAtom index of atom in iRes
number jAtom index of atom in jRes
or
nil if invalid bond
notes
seealso
getTotalInterResidueBonds(), getIntraResidueBond().
include
PdbUtil.lua
descrip
Returns atom indices of ith intra-residue bond within param residue.
params
number iPdb
number iChain
number iRes
number iBond
returns
number iAtom index of atom in iRes
number jAtom index of atom in iRes
or
nil if invalid bond
notes
seealso
getTotalIntraResidueBonds(), getInterResidueBond().
include
PdbUtil.lua
descrip
Returns center point of the bounding box around the param object.
params
string sObjName
returns
table vCen = { x, y, z }
or
nil if invalid object
notes
Currently, dynamic objects are not supported.
seealso
getObjectBoxExtent(), getObjectMassCenter()
groups
Pdb, Geom
include
PdbUtil.lua
descrip
Returns extent of param object.
params
string sObjName
returns
table vMin = { xmin, ymin, zmin }
table vMax = { xmax, ymax, zmax }
or
nil if invalid object
notes
Currently, dynamic objects are not supported.
seealso
getObjectBoxCenter()
groups
Pdb, Geom
include
PdbUtil.lua
descrip
Returns index of a static object, or multi-hierarchy index for a dynamic object, from param name.
params
string sObjName
returns
table tIdx = { iPdb [, (iChain | iTotalStaticChains + iSeg) [, iRes [, iAtom]] }
number bDynObj = 1 or nil
or
nil if object not found from name
notes
Warning!! For dynamic objects, the chain index value must be subsequently converted to a
dynamic segment value before it can be used as a dynamic index parameter. This can be
done by calling getTotalChainsInPdb().
A new function, getDynamicObjectIndexFromName(), has been added, which performs this
conversion.
seealso
getTotalChainsInPdb(), getDynamicObjectIndexFromName()
groups
Pdb, ForceObject
include
PdbUtil.lua
descrip
Returns size of param object.
params
string sObjName
returns
table vSize = { width, height, depth }
or
nil if error
notes
Currently, dynamic objects are not supported.
seealso
getObjectExtent(), getObjectBoxCenter()
groups
Pdb, Geom
include
PdbUtil.lua
descrip
Returns the base directory path from which pdb files are loaded.
params
returns
string sBaseDirOfPdbFiles
notes
seealso
setPdbDir()
groups
Pdb, Script, File
include
PdbUtil.lua
descrip
Returns the filename of the pdb object with the param index.
params
number iPdbInDoc
returns
string sFileName (ex: 'pdb/1kpj.pdb')
or
nil if invalid index
notes
The param index is 0-based and should be in the range [0, iTotalPdbsInDoc).
The returned value is the name of the pdb file from which the pdb model was loaded.
seealso
getPdbName()
include
PdbUtil.lua
descrip
Returns the index (in document list) of the pdb object with the param name.
params
string sNameOfPdbMol
returns
number iPdbInDoc
or
nil if error
notes
seealso
getPdbIndexFromName(), getChainIndex(), getResidueIndex()
include
PdbUtil.lua
descrip
Returns the name of the pdb object with the param index.
params
number iPdbInDoc
returns
string sNameOfPdbMol (ex: '1kpj')
or
nil if invalid index
notes
The param index is 0-based and should be in the range [0, iTotalPdbsInDoc).
seealso
getTotalPdbs(), getPdbIndexFromName(), getPdbFileName()
include
PdbUtil.lua
descrip
Returns the index of the previous residue in the chain of the param residue, if it exists.
params
table tRes = index of residue
returns
table tPrevResInChain
or
nil if param residue was first residue in chain.
notes
If param residue index is invalid, a runtime error should occur.
seealso
getNextResidue()
include
PdbUtil.lua
descrip
Returns the index of the next residue in the chain of the param residue, if it exists.
params
table tRes = index of residue
returns
table tNextResInChain
or
nil if param residue was final residue in chain.
notes
If param residue index is invalid, a runtime error should occur.
seealso
getPrevResidue()
include
PdbUtil.lua
descrip
Returns the residue portion of the full name of the residue with the param index.
params
table tResIdx = { iPdb, iChain, iRes }
returns
string sResName (ex: 'G1')
or
nil if invalid index
notes
Applies to static residues only.
seealso
getResidueName()
include
PdbUtil.lua
descrip
Returns the fully-qualified name of the residue with the param index.
params
table tResIdx
returns
string sPdbName.sChainName.sResName (ex: '1kpj.0.G1')
or
nil if invalid index
notes
seealso
getResidueIndex(), getResidueBaseName()
include
PdbUtil.lua
descrip
Returns the index of the residue with the param name.
params
string sPdbName.sChainName.sResName (ex: '1kpj.0.G1')
returns
table tResIdx
or
nil if error
notes
seealso
getReisdueName(), getPdbIndexFromName(), getChainIndex()
include
PdbUtil.lua
descrip
Returns the total number of atoms in the param residue object.
params
table tRes = { iPdb, iChain, iRes }
returns
number iTotalAtomsInResidue
include
PdbUtil.lua
descrip
Returns the total number of chains in the param Pdb object.
params
number iPdb (index of pdb object in document)
returns
number iTotalChainsInPdb
notes
seealso
getTotalPdbs()
include
PdbUtil.lua
descrip
Returns total number of inter-residue bonds between param residues.
params
number iPdb
number iChain
number iRes
number jRes
returns
number iTotal
or
nil if invalid bond
notes
seealso
getTotalIntraResidueBonds(), getInterResidueBond().
include
PdbUtil.lua
descrip
Returns total number of intra-residue bonds within param residue.
params
number iPdb
number iChain
number iRes
returns
number iTotal
or
nil if invalid bond
notes
seealso
getTotalInterResidueBonds(), getIntraResidueBond().
include
PdbUtil.lua
descrip
Returns total number of pdb objects in the current document.
params
returns
number iTotalPdbsInDocument
include
PdbUtil.lua
descrip
Returns total number of residues in the param chain.
params
number iPdb, iChain
returns
number iTotalResiduesInChain
include
PdbUtil.lua
descrip
Returns the total number of all residues in all pdb objects in the current document.
params
returns
number iTotalResiduesInDoc
include
PdbUtil.lua
descrip
Inserts the param pdb file into the current document.
params
string sPdbFilename
[number iEchoCmd = 0]
returns
1 or nil, sStatus
notes
seealso
openPdbFile()
groups
File, Pdb
include
PdbUtil.lua
descrip
Returns true if param residue is a nucleic acid residue.
params
table tResIdx
returns
number 1 or nil
notes
Currently, only static model residues are supported.
include
PdbUtil.lua
descrip
Returns true if pdb model with param name is loaded.
params
string sPdbName
returns
number 1 or nil
notes
seealso
groups
Pdb, File
include
PdbUtil.lua
descrip
Returns true if param index is a valid pdb index.
params
number iPdb
returns
number bValid = 1 or nil
notes
seealso
isValidForceObjectIndex()
groups
ForceObject
include
PdbUtil.lua
descrip
Opens the param movie file.
params
string sMovieFilename
[number iEchoCmd = 0]
[number iEchoStatus = 1]
returns
number bRet = 1
or
nil if failed
notes
seealso
groups
File, Pdb, ForceField
include
PdbUtil.lua
descrip
Opens the param pdb file as a new document.
params
string sPdbFilename
[number iEchoCmd = 0]
[number iEchoStatus = 1]
returns
number bRet = 1
or
nil if failed
notes
seealso
insertPdbFile(), openRbdFile(), closeDocument()
groups
File, Pdb
include
PdbUtil.lua
descrip
Opens the param rbd file as a new document, after closing any existing document.
params
string sRbdFilename
[number iEchoCmd = 0]
[number iEchoStatus = 1]
returns
number bRet = 1
or
nil
notes
The file must have an .rbd extension to be detected as an rbd document.
An RBD file defines loading, placement and display of multiple PDB models.
The atom data for the models is not contained within the RBD file. Instead,
the file contains references to external PDB files that hold the atom data.
seealso
openPdbFile(), closeDocument()
groups
File, Pdb
include
PdbUtil.lua
descrip
Sets the base directory from which standard pdb files are loaded.
params
string sBaseDirOfPdbFiles
returns
notes
This method is used by many of the scripts under the 'Script', 'Models'
submenu to load ribosome-related pdb models. The default directory
is the 'pdb' sub-directory of the application directory, but this
method can be called to change it.
seealso
getPdbDir()
groups
File, Pdb, Script
include
PdbUtil.lua
descrip
Sets the name of the pdb object with the param index.
params
number iPdbInDoc
string sNewName
returns
number bRet = 1
or
nil if error
notes
The param index is 0-based and should be in the range [0, iTotalPdbsInDoc).
seealso
getPdbame()
include
PdbUtil.lua
descrip
Adds data which can persist between script invocations. The data is stored as member data of a CRbqScriptObject. Before execution of any script by that object, the data is set in the script's global data space. At the end of the script, the data is read from the global data space and saved back to the CRbqScriptObject member data list.
params
string sScriptObjectName
string sVarName
string sVal
returns
number bRet = 1 if successfully added, else nil
notes
If the script object is in a fail state, the variable will not be added and nil will
always be returned.
Also, in the current implementation, the name and value parameters must be non-zero in length,
so if it is desired to define a new script object variable with an empty value,
the user must assign some unused string token such as "NULL" to represent this
empty value.
The actual value is also converted to and from a string format, so the user may need
convert the result using the Lua tonumber() function for numerical variables. To
convert floating point values to integer, the Lua floor() function can be used.
For examples of script object variable addition, see ChainRunner.lua
seealso
createScriptObject(), getScriptObjectVar(), setScriptObjectVar(), isScriptVarDefined(),
isScriptObjectFailStateSet()
groups
ScriptObject
include
ScriptUtil.lua
descrip
Stores current command status enable state on stack, disables command status.
params
returns
notes
This is used in scripts which want to disable echoing of status to the
status window which result from execution of commands in the script.
Calls of this function must be matched with subsequent calls of
cmdStatusRestore().
seealso
cmdStatusRestore(), enableCmdStatus()
include
ScriptUtil.lua
descrip
Restores saved command status enable state from stack.
params
returns
notes
seealso
cmdStatusOff(), enableCmdStatus()
include
ScriptUtil.lua
descrip
Creates a script object and copies associated script event files to the script object directory.
params
table tSoData =
{
sSoName = sScriptObjectName,
sSrcDir = sSourceDirectory,
[tVars = tScriptObjectVars],
[sDrawScript = <sDrawScriptFile>],
[sDrawTransScript = <sDrawTransScriptFile>],
[sTickScript = <sTickFile>],
[sFiTickScript = <sFiTickFile>],
[sKeyDownScript = <sKeyDownFile>],
[sKeyUpScript = <sKeyUpFile>],
}
returns
number bRet = 1 if success, else nil
string sStatus
notes
This function provides some additional functionality around the more basic function 'createScriptObject()'.
Specifically, this function will perform some file operations needed for defining the script object
event handlers, and also script object variable definitions.
The param table of data is used to create the script object. The varible 'sSoName' is the name
of the script object. The variable 'tVars' is a table of (key, value) pairs that will be used
to create script object variables.
If the 'sDrawScript' param is not nil, the function will attempt to copy the draw script from
'<sSrcDir>/<sDrawScript>.lua' to '<sScriptObjectDir>/draw.lua'. If there is no draw script,
this param should be nil.
If the 'sDrawTransScript' param is not nil, the function will attempt to copy the drawTransparent script from
'<sSrcDir>/<sDrawTransScript>.lua' to '<sScriptObjectDir>/drawTransparent.lua'. If there is no drawTransparent script,
this param should be nil.
If the 'sTickScript' param is not nil, the function will attempt to copy the tick script from
'<sSrcDir>/<sTickScript>.lua' to '<sScriptObjectDir>/tick.lua'. If there is no tick script,
this param should be nil.
If the 'sFiTickScript' param is not nil, the function will attempt to copy the fiTick script from
'<sSrcDir>/<sFiTickScript>.lua' to '<sScriptObjectDir>/fiTick.lua'. If there is no fiTick script,
this param should be nil.
See the script 'exp/dev/tst/testDrawBox.lua' for an example of using this function in constructing
a script object.
seealso
createScriptObject()
groups
ScriptObject
include
ScriptUtil.lua
descrip
Creates a persistent object which can execute user-defined scripts for certain types of events. The object can be added to the list of objects which can draw in the graphics window and output graphics via a user-defined 'draw.lua' script. It can also be added to a time user list and execute periodic code during each tick in the main loop via a user-defined 'tick.lua' script. Complete list of event scripts:
- draw.lua
- drawTransparent.lua
- tick.lua
- keyDown.lua
- keyUp.lua
If a script with one of the above names exists in the script object directory, that script will be executed when the associated event occurs.
params
string sScriptObjectName
[number iTimeUser = 0 or 1]
[number iKbUser = 0 or 1]
returns
1 or nil
notes
Typical steps in creating a script object are:
1. Get a unique name for the script object using getFreeGraphicObjectName().
2. Create the script object using createScriptObject().
3. Define some variables for the script object using addScriptObjectVar().
4. Define one or more event script files such as 'aScript.tick.lua'
5. Copy the event script source file to the script object directory using getScriptObjectDir(), makePath() and copyFile(), with dest file named 'tick.lua'.
Inside the tick.lua file, get and set script object vars using getglobal() and setglobal().
To enable persistence of the script object vars outside of the script file execution, the variables
must be updated by calling setScriptObjectVar().
If the iTimeUser param is 1, the tick.lua script will be run for the script object each timer tick.
If the iKbUser param is 1, the keyDown.lua and keyUp.lua scripts will be run for the script object on key events.
When the keyDown or the keyUp event is called, a global variable named 'g_KeyValue' will be set to the
name of the key associated with the event.
seealso
constructScriptObject()
existScriptObject(), getFreeGraphicObjectName(),
getScriptObjectDir(), makePath(), copyFile()
addScriptObjectVar(), getScriptObjectVar(), setScriptObjectVar()
deleteScriptObject()
groups
Script, ScriptObject
include
ScriptUtil.lua
descrip
Returns number of seconds since the Epoch (1/1/1970).
params
returns
number iTotalSeconds
notes
Will this still be valid after 2038 AD?
seealso
include
ScriptUtil.lua
descrip
Deletes script object with param name.
params
string sScriptObjectName
returns
number bRet = 1 if success, else nil
notes
This is currently just a wrapper for deleteAnnotation(). This function
will fail if called during execution of script object tick event code.
scheduleDeleteScriptObject() can be called instead to handle deletion in
that case.
seealso
scheduleDeleteScriptObject(), deleteAnnotation(), createScriptObject()
groups
Script, ScriptObject
include
ScriptUtil.lua
descrip
Deletes all files in the 'tmp' subdir, which is located in the application base directory.
params
returns
number bRet = 1 or nil
notes
Only files, not directories will be deleted.
The tmp directory is typically used by scripts as a repository for
intermediate files during report generation.
seealso
getAppDir()
groups
Script, File
include
ScriptUtil.lua
descrip
Enables output of status produced during command processing.
params
number iEnable = 1 or 0
returns
notes
seealso
cmdStatusOff(), cmdStatusRestore()
include
ScriptUtil.lua
descrip
Enables tick event for all script objects.
params
number iEnable = 1 or 0
returns
number bRet = 1 or nil
notes
If this function is called within a script object tick event, the remaining
script objects with tick events will still be called for the current timer
tick, but subsequent applicaiton timer ticks will skip script object tick events until
the flag is reenabled.
This function can be used to implement a 'single-step' mode for script object tick events.
A script object tick event script can call this function to disable subsequent
tick events for all script objects. The user can manually reenable
the ticks by clicking the 'Enable Tick Event' icon or entering the command
'script so enableTick', in order to step to the next tick cycle.
seealso
isScriptObjectTickEnabled()
groups
Script, ScriptObject
include
ScriptUtil.lua
descrip
Enables call of lua_error() in rbq API functions.
params
number iEnable = 1 or 0
returns
notes
This function is typically used in test driver scripts that want to
pass invalid parameters to rbq-lua api functions.
seealso
isLuaErrorEnabled()
include
ScriptUtil.lua
descrip
Outputs a message indicating failure to create param directory.
params
string sDir = name of directory
returns
notes
This function just outputs a descriptive error message to errOut.
seealso
mkdir()
groups
File, Script
include
ScriptUtil.lua
descrip
Outputs a message indicating failure to convert param string to a number.
params
string sNum = string that failed conversion
returns
notes
This function does not do the actual conversion, use tonumber() for that.
This function just outputs a descriptive error message to errOut.
The param string should not be nil.
seealso
errNilParam(), errOut()
include
ScriptUtil.lua
descrip
Does check for nil param, outputs message to error out if found.
params
var vParam = param to check
[string sMsgPre] = preamble error message, prepended to error msg.
returns
number bRet = 1 if nil param found
or
nil
notes
seealso
errFailedParseNum(), errOut()
include
ScriptUtil.lua
descrip
Outputs a message to the application 'Error out' (status window).
params
string sErrMsg
returns
notes
seealso
stdOut()
include
ScriptUtil.lua
descrip
Returns true if script object with param name exists.
params
string sName
returns
number bRet = 1 or nil
notes
If a non-script object annotation exists with the param name, this
function will still return true.
This is a duplicate function of isScriptObjectExist()
seealso
isScriptObjectExist()
groups
Script, ScriptObject
include
ScriptUtil.lua
descrip
Returns the full path to the base directory of the application.
params
returns
string sAppDir
notes
The application base directory is often assumed to be the current working
directory by many of the scripts, which use relative path names such as
'seq/<seqFile>' or 'lua/<scriptFile>' to access files in the application
subdirectories. If the application directory is not the current working
directory, this function can be used to set the correct absolute path to
the desired subdirectories.
seealso
getScriptDir()
groups
Script, File
include
ScriptUtil.lua
descrip
Returns the number of arguments passed to the currently-executing script.
params
returns
number iTotalCmdLineArgs
notes
seealso
getArgv(), getCmdLine()
include
ScriptUtil.lua
descrip
Returns the ith command-line argument for the currently-executing script.
params
number iArg = 0-based index
returns
string sArgI
notes
seealso
getArgc(), getCmdLine()
include
ScriptUtil.lua
descrip
Returns a hash of (key,value) pairs extracted from the script cmd-line, where the 1st arg is a CGI-encoded string received from a web browser.
params
returns
table tHash = { ["key0"]=val0, ["key1"]=val1, ... } where script arg0 = 'key0=val0&key1=val1...'
or
nil if invalid format in CGI string
notes
This function is used in scripts that are executed in response to a web browser request.
See 'Web Browser Interface' in the User Manual docs for more information.
If no (key,value) pairs are found, an empty table is returned.
seealso
getCgiParamValues(), getArgc(), getArgv(), getCmdLine()
include
ScriptUtil.lua
descrip
Returns an array of values extracted from the script cmd-line, where the 1st arg is a CGI-encoded string received from a web browser.
params
returns
table tHash = { [1] = val1, [2]=val2, ... } where script arg0 = 'key1=val1&key2=val2...'
or
nil if invalid format in CGI string
notes
This function is used in scripts that are executed in response to a web browser request.
See 'Web Browser Interface' in the User Manual docs for more information.
If no (key,value) pairs are found, an empty table is returned.
seealso
getCgiParams(), getArgc(), getArgv(), getCmdLine()
include
ScriptUtil.lua
descrip
Returns the command-line for the currently-executing script.
params
returns
string 'sArg0 sArg1 ... sArgN'
or
nil if no command-line args
notes
seealso
getCgiParams(), getArgc(), getArgv()
include
ScriptUtil.lua
descrip
Returns a unique name not used by any current graphics object (including script objects). This is used when creating a new script object, which must be created with a unique name.
params
string sStartingName
returns
string sUnusedGraphicObjectName
include
ScriptUtil.lua
descrip
Returns name of var in global data which holds key code for keyDown script
params
returns
string sVarName
include
ScriptUtil.lua
descrip
Displays a dialog box prompting input from the user.
params
string sPrompt = Prompt message to be shown in dialog
[string sCaption] = Caption to be set in dialog window
[string sDefInput] = Default input to appear in text box of dialog
returns
string sUserInput
or
nil if user cancelled input from dialog
notes
seealso
getArgc(), getArgv(), getCmdLine(), msgBox()
groups
Script, Win
include
ScriptUtil.lua
descrip
Returns the string used to separate path components ('/' in unix, '\\' in dos).
params
returns
string sPathSep
notes
Defined as a global var in 'SetLocalEnv.lua'
seealso
makePath()
groups
Script, File
include
ScriptUtil.lua
descrip
Returns the fully-qualified path to the script directory of the application. This directory holds much of the predefined scripting code, including the utility files (*Util.lua) which define these functions.
params
returns
string sScriptDir
notes
seealso
getAppDir()
groups
Script, File
include
ScriptUtil.lua
descrip
Returns full path to the base directory which script object directories are created. For each new script object which is created, a subdirectory is created in this base directory. The subdirectory has the same name as that of the script object, which should have a unique name.
params
returns
string sScriptObjectsBaseDir
notes
This base script object directory, typically called 'tmp', is a
subdirectory of the script directory. For proper operation, all script
object sudirectories should be deleted when the script objects are
deleted. In some cases, such as abnormal program termination, this
cleanup will not occur, and subsequent attempts to create a script
object will fail if the directory already exists. Currently, to fix this
situation, the script object directories must be manually deleted by
the user.
seealso
getScriptDir(), createScriptObject()
groups
Script, ScriptObject, File
include
ScriptUtil.lua
descrip
Returns the name of the param script object.
params
number iScriptObject = 0-based index of script object in document
returns
string sScriptObjectName
or
nil if error
notes
The script object name is defined when a script object is created
in createScriptObject(). This name is the unique handle used to
access functions and data belonging to the script object.
seealso
getTotalScriptObjects(), createScriptObject()
groups
Script, ScriptObject
include
ScriptUtil.lua
descrip
Returns the value of the param var of the param script object, typically from outside of the param script object execution context.
params
string sScriptObjName
string sVarName
returns
string sVarValue
or
nil if error
notes
If execution is ocurring within the context of the named script object, the
value of 'sVarName' can be accessed via the Lua functions getglobal() and setglobal().
However, if the value needs to be accessed from some other script, then
the functions 'getScriptObjectVar()' and 'setScriptObjectVar()' must be used.
seealso
setScriptObjectVar()
groups
Script, ScriptObject
include
ScriptUtil.lua
descrip
Returns value of a global var that was set by a called script.
params
returns
number iNum
notes
This function, along with setScriptReturnCode(), allows a caller script to determine
the success or failure of a child script (because current implementation of
runScript() only returns 1 or nil to communicate a successful execution of the
script via dofile()).
seealso
setScriptReturnCode()
include
ScriptUtil.lua
descrip
Returns the total number of script objects that currently exist.
params
returns
number iTotal
notes
seealso
getScriptObjectName()
groups
Script, ScriptObject
include
ScriptUtil.lua
descrip
Returns the total number of variables for the script object with param name.
params
string sSoName = name of script object
returns
number iTotalVars
notes
This total can be used for iterating script object vars.
seealso
getScriptObjectVarName()
groups
Script, ScriptObject
include
ScriptUtil.lua
descrip
Returns the name of the script object variable from param index.
params
string sSoName = name of script object
number iIndex = [0 .. iTotalScriptObjectVars - 1]
returns
string sVarName
notes
seealso
getTotalScriptObjectVars(), getScriptObjectVar()
groups
Script, ScriptObject
include
ScriptUtil.lua
descrip
Inputs a command to the application command processor. In addition to the script-application API, the application supports a number of text commands which can be input to the application. The commands are documented in the html command reference files.
params
string sCmd
returns
1 or nil
notes
seealso
enableCmdStatus(), enableCmdEcho(), cmdStatusOff(), cmdStatusRestore()
include
ScriptUtil.lua
descrip
Returns true if command status output is enabled.
params
returns
number iRet = 1 or nil
notes
seealso
enableCmdStatus(), cmdStatusOff(), cmdStatusRestore(), inputCommand()
include
ScriptUtil.lua
descrip
Returns true if echoing progress info to status window is enabled.
params
returns
number bRet = 1 or nil
notes
seealso
progressBar_EchoToStatusWindow()
include
ScriptUtil.lua
descrip
Returns true if a help arg is specified in the argument list of a script.
params
returns
number iRet = 1 or nil
notes
The intent of this script is to localize detection of a help arg to
a single point in the code. The help arg is defined to exist if
getArgc() > 0 and getArgv( 0 ) is either "-h" or "--help".
seealso
getArgc(), getArgv()
include
ScriptUtil.lua
descrip
Returns true if lua_error() calls in rbq API functions is enabled.
params
returns
number iRet = 1 or nil
notes
This function is typically used in test driver scripts that want to
pass invalid parameters to rbq-lua api functions.
seealso
enableLuaError()
include
ScriptUtil.lua
descrip
Returns true if param script object exists.
params
string sSoName = name of script object
returns
number bRet = 1 or nil
notes
This is a duplicate function of existScriptObject().
seealso
createScriptObject(), existScriptObject()
groups
Script, ScriptObject
include
ScriptUtil.lua
descrip
Returns true if the fail state is set for the script object with param name.
params
string sSoName = name of script object
returns
number bRet = 1 or nil
notes
If the fail state is set for a script object, then processing of script events
is disabled.
The fail state is set for a script object if an error occurred in setting or getting
its global variables, or while running one of its event scripts.
An error in running an event script is defined by a non-zero return value from
the lua_dofile() function. See the Lua reference manual, section 5.8 for details.
The user can also force such a non-zero return result by doing an explict call in the script
code to the Lua error() function.
Currently, there is no way to clear the fail flag once it is set.
seealso
groups
Script, ScriptObject
include
ScriptUtil.lua
descrip
Returns true if tick events are enabled for script objects.
params
returns
number bRet = 1 if enabled, else nil
notes
seealso
enableScriptObjectTick()
groups
Script, ScriptObject
include
ScriptUtil.lua
descrip
Returns true if param script var is been defined in the globals() table.
params
string sVar = name of variable
returns
number iRet = 1 or nil
include
ScriptUtil.lua
descrip
Display a message box dialog.
params
string sMsg
[string sCaption = "Message"]
[number bShowCancel = nil]
returns
number iRet = 1 if user hit OK, else 0
notes
seealso
stdOut(), errOut(), getInputString()
groups
Script, Win
include
ScriptUtil.lua
descrip
Returns all param args as a table.
params
... (variable number of args)
returns
table tRet = { arg1, arg2, ... }
include
ScriptUtil.lua
descrip
Enables echoing of progress bar info to status window (in addition to gui widget).
params
number bEnable = 1 or nil
returns
notes
The progress bar is a gui widget. In addition to indication of progress
through the widget, the progress can be echoed in a text form to the
status window.
seealso
isEchoProgressToStatusWindowSet(), progressBar_Init()
include
ScriptUtil.lua
descrip
Updates the progress bar by param percent.
params
[number iPct] = 1
returns
notes
seealso
progressBar_Init(), progressBar_SetDone()
include
ScriptUtil.lua
descrip
Initializes and shows a progress bar in the graphics window.
params
string sDescrip = description of progress activity
returns
notes
Initializes and displays a gui widget which shows progress for long operations.
The widget has a text description and a cancel button in addition to the progress
bar.
seealso
progressBar_IncPercentDone(), progressBar_SetDone()
progressBar_WasCancelled(), progressBar_EchoToStatusWindow()
include
ScriptUtil.lua
descrip
Finalizes and closes the active progress bar in the graphics window.
params
returns
notes
seealso
progressBar_Init(), progressBar_IncPercentDone(), progressBar_SetDone(),
progressBar_WasCancelled()
include
ScriptUtil.lua
descrip
Returns true if user pressed the cancel button in the progress bar.
params
returns
number 1 or nil
notes
seealso
progressBar_Init(), progressBar_IncPercentDone(), progressBar_SetDone()
include
ScriptUtil.lua
descrip
Reports the amount of free stack space in the lua scripting context.
params
returns
include
ScriptUtil.lua
descrip
Runs a script in the 'lua' subdirectory.
params
string sScript = filename of script
[string sCmdLine] = optional command-line passed to the script
returns
number iRet = 1
or
nil if error
notes
The script is assumed to exist in the 'lua' subdirectory, so the
param 'sScript' should consist of the filename only.
This function, and its more general version, runScript(), have
an important capability that is useful for chaining scripts.
The current implementation of the console command 'script run <sScript>'
has a limitation in that it will not run a script if another script
is running. This limitation has to do with setting and saving
script object variables for script object event scripts. The upshot is
that trying to run one script from inside of another using the
inputCommand() function with the parameter "script run <sScript>" will fail.
This function, along with 'runScript()', can be used instead, because
they do a direction Lua 'dofile()' call of the script code, placing it
into the Lua context. Note: there is currently no HTML documentation
for the 'runScript()' function because it is implemented in the
startup.lua startup script.
In addition, the command-line parameter of this function is tokenized
and made available to the script via the getArgc() and getArgv() functions.
seealso
runPerlScript(), runProcess(), getArgc(), getArgv()
include
ScriptUtil.lua
descrip
Runs a perl script with param args
params
string sScript = fully-qualified filename of script
[string sArgs] = optional command-line arguments passed to the script
[string sWorkDir] = optional working dir
[string sIncDir] = optional dir to add "-I <sIncDir>" argument to perl
returns
number iRet = 1
or
nil if error
notes
The working directory for the script is the current working directory.
Redirection operators such as '>', as specified in sArgs, doesn't appear to work.
If the return code from the perl script is not 0, an error will be reported to errout
and the return code from this function will be nil.
seealso
runLuaScript(), runProcess()
include
ScriptUtil.lua
descrip
Runs a process specified by param command line and returns exit status code.
params
string sCmdLine
[string sWorkDir = "."]
returns
number iRet = exit code
or
number nil
string sStatus
if error spawning process
notes
Execution of the calling process will be suspended until the child process
is ended.
seealso
runLuaScript(), runPerlScript()
include
ScriptUtil.lua
descrip
Schedules a script object with param name for deletion.
params
string sScriptObjectName
[number bEchoCmd = (nil, 0) or 1]
returns
number bRet = 1 or nil
notes
This function is a more certain form of script object deletion than
deleteScriptObject() because this function will succeed in deleting the
script object even if script object code is currently executing.
In that latter case, the script object will be deleted following the execution
of all script object tick events in the current timer tick.
seealso
deleteScriptObject()
groups
ScriptObject
include
ScriptUtil.lua
descrip
Sets level for echoing input command strings to the status window.
params
number iLevel = { 0 = nothing, 1 = console, 2 = menu, 3 = script, 4 = mouse, 5 = all }
returns
notes
Useful for script debugging.
seealso
enableCmdStatus()
include
ScriptUtil.lua
descrip
Sets the value of the param var of the param script object.
params
string sScriptObjName
string sVarName
string sVarValue
returns
number bRet = 1
or
nil if error
notes
See notes in 'getScriptObjectVar()' function.
seealso
getScriptObjectVar()
groups
Script, ScriptObject
include
ScriptUtil.lua
descrip
Sets a global var to param number value that can be accessed by a caller script.
params
number iNum
returns
notes
This function, along with getScriptReturnCode(), allows a caller script to determine
the success or failure of a child script (because current implementation of
runScript() only returns 1 or nil to communicate a successful execution of the
script via dofile().
seealso
getScriptReturnCode(), runLuaScript()
include
ScriptUtil.lua
descrip
Sets or clears display of an hourglass cursor used during long operations.
params
number bShow = 1 or 0
returns
include
ScriptUtil.lua
descrip
Outputs param text to the application 'Standard out' (status window).
params
string sText
returns
notes
The text is output to the application status window if present. If the
application status window has not been created, the text is output to std::cout
instead. The text is also output to the application logfile in the log
subdirectory. Nothing is appended to the text; carriage returns ( "\n" ) must
be supplied by the user.
seealso
errOut(), msgBox()
include
ScriptUtil.lua
descrip
Writes a script file containing a single script object function. This is a utility method used during creation and initialization of a script object.
params
string sFile
string sFuncDef
string sFuncName
returns
bRet = 1 or nil
notes
seealso
groups
Script, ScriptObject
include
ScriptUtil.lua
descrip
Writes values of all vars of script object with param name to param file.
params
string sSoName = name of script object
string sFile = name of file where vars will be written
returns
number bRet = 1 if success
or
nil if error
notes
Variables are written in an XML format. This function is used to save
and subsequently restore the complete state of a script object.
seealso
setScriptObjectVar(), getScriptObjectVar()
groups
Script, ScriptObject, File
include
ScriptUtil.lua
descrip
Deletes all currently selected objects (static and dynamic pdb models).
params
returns
number bRet = 1 or nil if error
notes
seealso
deleteAllPdbObjects(), deleteAllAnnotations(), scheduleDeleteScriptObject()
include
SelectUtil.lua
descrip
Enables coloring of current selection.
params
number iEnable = 1 or [0 or nil]
returns
number bRet = 1
or
nil if error
notes
seealso
include
SelectUtil.lua
descrip
Returns a table containing the indices of the 1st 2 selected pdb objects.
params
returns
table { iPdb0 , iPdb1 } or nil
include
SelectUtil.lua
descrip
Returns a list of indices of the 1st 2 selected residues.
params
returns
number iPdb, iChain, iRes, jPdb, jChain, jRes or nil
include
SelectUtil.lua
descrip
Returns index of first fully-selected pdb if any.
params
returns
number iPdb
or
nil if no selected pdb found.
include
SelectUtil.lua
descrip
Returns the pdb and chain index for the ith selected chain.
params
[number iSelChain] = 0
returns
table tChainIdx = { iPdb, iChain } or nil
include
SelectUtil.lua
descrip
Returns the pdb, chain and residue index for the ith selected residue.
params
[number iSelRes] = 0 (0-based index)
returns
table tResIdxI = { iPdb, iChain, iRes}
or
nil if selected residue not found.
notes
seealso
getTotalSelectedResidues(), getSelectedResidues()
include
SelectUtil.lua
descrip
Returns the pdb, chain and residue index for the ith selected residue.
params
[number iSelRes] = 0 (0-based index)
returns
table tResIdxI = { iPdb, iChain, iRes}
or
nil if selected residue not found.
notes
This function is deprecated in place of the differently-named
function getSelectedResidue() above.
seealso
getSelectedResidue()
include
SelectUtil.lua
descrip
Returns a table of indices for all selected residues.
params
returns
table tResRet = { tSelRes0, tSelRes1, ..., tSelResN }
notes
If a large number of residues is selected, the lua stack may overflow.
seealso
getTotalSelectedResidues(), getSelectedResidue()
include
SelectUtil.lua
descrip
Returns center of current selection.
params
returns
table vCen
notes
If there is no current selection, the origin point will be returned.
The selection center is defined as the center of mass of all selected
objects.
seealso
getSelectionExtent(), getSelectionSize()
include
SelectUtil.lua
descrip
Returns selection color.
params
returns
table vColor = { r, g, b }.
notes
The returned color is the color used for selected objects, if the 'Color Selection'
option is set.
seealso
setFlashSelection()
include
SelectUtil.lua
descrip
Returns extent of current selection.
params
returns
table vExtent = { vMin, vMax }
notes
If there is no current selection, a zero-extent will be returned.
seealso
getSelectionCenter(), getSelectionSize()
include
SelectUtil.lua
descrip
Returns extent of current selection.
params
returns
table vSize = { vSize }
notes
If there is no current selection, a size of zero will be returned.
seealso
getSelectionCenter(), getSelectionExtent()
include
SelectUtil.lua
descrip
Returns the total number of currently selected atoms.
params
returns
number iTotalSelAtoms
notes
seealso
include
SelectUtil.lua
descrip
Returns the total number of currently selected chains.
params
returns
number iTotalSelChains
notes
seealso
getTotalSelectedResidues()
include
SelectUtil.lua
descrip
Returns the total number of currently selected residues.
params
returns
number iTotalSelRes
notes
For dynamic residues, use getTotalSelectedForceObjects() instead.
seealso
getSelectedResidue(), getTotalSelectedForceObjects()
include
SelectUtil.lua
descrip
Returns true if there is a current selection.
params
returns
number bRet = 1 or nil
notes
The minimum selection required is at the residue level (selected
nodes are not used to determine if there is a current dynamic selection).
seealso
haveSelection(), haveStaticSelection()
groups
Select
include
SelectUtil.lua
descrip
Returns true if there is a current selection, which is defined as a current static selection or a current dynamic selection.
params
returns
number bRet = 1 or nil
notes
seealso
haveDynamicSelection(), haveStaticSelection()
groups
Select
include
SelectUtil.lua
descrip
Returns true if there is a current static selection.
params
returns
number bRet = 1 or nil
notes
seealso
haveSelection(), haveDynamicSelection()
groups
Select
include
SelectUtil.lua
descrip
Returns true if 'add-to-selection' mode is on.
params
returns
number bRet = 1 or nil
notes
seealso
setSelectAdd(), SelectUtil.pushSelectAdd(), SelectUtil.popSelectAdd()
groups
Select
include
SelectUtil.lua
descrip
Returns true if param residue is selected.
params
table tRes = { iPdb, iChain, iRes }
returns
number bRet = 1 or nil
notes
seealso
groups
Pdb, Select
include
SelectUtil.lua
descrip
Restores saved 'isAddToSelectionSet()' state from stack.
params
returns
notes
If the stack is empty, a lua_error() will occur, so this
function should only be called after a previous call to
pushSelectAdd().
seealso
SelectUtil.pushSelectAdd(), isAddToSelectionSet(), setSelectAdd()
groups
Select
include
SelectUtil.lua
descrip
Saves current 'isAddToSelectionSet()' state on a stack.
params
returns
notes
This function and its counter-part 'popSelectAdd()' can be used
in a script to temporarily alter the 'add-to-selection' mode
and then subsequently restore it to the previous state.
seealso
SelectUtil.popSelectAdd(), isAddToSelectionSet(), setSelectAdd()
groups
Select
include
SelectUtil.lua
descrip
Resets the PDB transform matrix for current selection.
params
returns
number bRet = 1
or
nil if error
notes
seealso
setSelectionTransform(), resetPdbTransform()
groups
Select, Geom
include
SelectUtil.lua
descrip
Selects all pdb models
params
number bEcho
returns
number bRet = 1
or
nil if error
notes
seealso
selectNone()
include
SelectUtil.lua
descrip
Selects the param object by 0-based index into the document.
params
string sIndex
number bEchoCmd
returns
1 or nil
notes
The param sIndex is a string composed as a 'dotted-index-specification'.
Ex: '0.0.0' specifies the first residue of the first chain of the first pdb
in the current document.
seealso
selectName()
include
SelectUtil.lua
descrip
Selects the param named object or object range.
params
string sName or 'sNameBegin - sNameEnd'
[number bSel = { 0, 1 (default), 2} ] 0 = "off", 1 = "on", 2 = "toggle"
[number bEchoCmd = nil or 1]
returns
number bRet = 1
or
nil if error
notes
seealso
selectIdx0()
include
SelectUtil.lua
descrip
Selects param node of param force object.
params
table tForceObj
number iNode
[number bEcho]
returns
number bRet = 1
or
nil if error
notes
seealso
groups
Select, ForceObject
include
SelectUtil.lua
descrip
Clears the current selection.
params
[number bEcho = nil]
returns
number bRet = 1
or
nil if error
notes
seealso
selectAll()
include
SelectUtil.lua
descrip
Sets current selection mode to 'add/remove'. In the default mode, any prior selection is cleared when doing a new selection. In 'add/remove' mode, the new selection command can specify that objects should be added or removed from the currently-selected set of objects.
params
number bSet = (0 or 1) ( 0 = turn add/remove mode off, 1 = turn add/remove mode on).
number bEchoCmd
returns
number bRet = 1 or nil
notes
seealso
isAddToSelectionSet(), SelectUtil.pushSelectAdd(), SelectUtil.popSelectAdd()
include
SelectUtil.lua
descrip
Returns name of a file, with app base path added, which maps residues of a reference chain to param chain.
params
string sPdbChain
returns
string sBasePathMapfile
or
nil
notes
sBasePathMapfile is the 'app-base-path' to the map file in the
sequence data subdir.
include
SeqUtil.lua
descrip
Returns name of a file which maps residues of a reference chain to param chain.
params
string sPdbChain
returns
string sMapfile = base file name, not full path name
or
nil
notes
To get the map file name, the module map data table is searched, not
actual map files in the seq subdirectory.
include
SeqUtil.lua
descrip
Returns a pathname to a file which lists helices for the param nucleic acid chain.
params
string sPdbChain
returns
string sBasePathHelixFile
or
nil
notes
sBasePathHelixFile is the 'app base path' to the helix file in the
sequence data subdir.
include
SeqUtil.lua
descrip
Returns a file which lists helices for the param nucleic acid chain.
params
string sPdbChain
returns
string sHelixFile
or
nil
notes
The module data for helix files is searched, not helix files in the seq subdirectory.
Only the base filename is returned, not the full path of the actual file.
New: If the param pdb chain is not found in the module list, a helix file
will be returned that is based upon the param name.
include
SeqUtil.lua
descrip
Returns a string describing a mapping from one param base to the other.
params
table tSeqMapLine = { iLineNum, seq1Sym, seq1Pos, seq2Sym, seq2Pos }
number iFwdDir
returns
string sMapReport = "BN -> BN\n"
notes
The param table holds fields from a line in a sequence map file. The first field
is not used.
include
SeqUtil.lua
descrip
Returns a list of pdb chain names which have helix definition files.
params
returns
table tRet = { sPdbChain0, sPdbChain1, ... }
notes
These are the chains from the module array of helix data 'f_HelixData'.
include
SeqUtil.lua
descrip
Returns the name of the final helix in param helix data file.
params
string sHelixFile = name of file in 'seq' subdirectory.
returns
string sFinalHelixNumInFile
or
nil
notes
The name of the final helix is the 2nd field of the helix data file, also
referred to as the Helix Number, which may be non-numeric (ie: Helix 23a).
If an error occurs, it is output to app err out.
include
SeqUtil.lua
descrip
Returns a table of data for all helices in param file.
params
string sHelixFile = name of file in 'seq' subdirectory.
returns
table tRet = { [sHelixNum0] = {5b, 5e, 3b, 3e}, ... }
or
nil
include
SeqUtil.lua
descrip
Returns a list of files which define helix endpoints.
params
returns
table tRet = { sFilename1, sFilename2, ... }
include
SeqUtil.lua
descrip
Returns the name of a helix file, either automatically, if one exists for the param chain, or through a dialog with the user, if they submit one after being shown the list of defined helix files.
params
string sPdbChain = name of chain, in 'pdb.chain' format, for which helix definition is desired.
returns
string sHelixFile
or
nil if no file found for param chain and user didn't specify one either in dialog.
notes
include
SeqUtil.lua
descrip
Returns a list of the start and end points of the 2 sides of the param helix.
params
string sHelixFile = name of helix definition file located in 'seq' sudirectory
string sHelixNum = number of helix for which endpoints are desired (can be non-numeric)
returns
table tRet = { h5start, h5end, h3start, h3end }
or
nil, sStatus
notes
Table elements are strings which are residue names (symbol + sequence number)
Format of helix definition file: 6 fields: iHelixIdx0 sHelixNum 5'start 5'end 3'start 3'end
include
SeqUtil.lua
descrip
Returns a table of full residue indexes for the param helix endpoints.
params
string sPdbChain
table tHelixEndpoints = { sResName_5b, sResName_5e, sResName_3b, sResName_3e }
returns
table tHelixResIdx = { tResIdx_5b, tResIdx_5e, tResIdx_3b, tResIdx_3e }
or
number nil
notes
tResIdx is a table: { iPdb, iChain, iRes }.
include
SeqUtil.lua
descrip
Returns the name of the first sequence of the param map file.
params
string sMapFile
returns
string sSeq1 or nil
notes
include
SeqUtil.lua
descrip
Returns base which maps to param base, as found in param map file.
params
string sMapFile = name of .smap file located in 'seq' subdir
string sBaseIn
number bMapSecondToFirst
returns
string sBaseOut
or
number bFail = nil
string sStatus = reason why mapping failed
notes
Sequence map files for selected PDB chains are located in *.smap files
in the seq subdirectory.
Example: getMappedBase( "1giy.A-1ffk.0.smap", "C1836" ) should return "C1892".
On error, a message is output to errout.
Format of columns in mapfile:
col 0: align pos
col 1: seq1 base symbol
col 2: seq1 base pos or '.' or '-'
col 3: seq2 base symbol
col 4: seq2 base pos or '.' or '-'
include
SeqUtil.lua
descrip
Returns the helix num which follows the param helix num in the param helix file.
params
string sHelixFile = name of Helix definition file in 'seq' subdirectory
string sHelixNum = Helix num which precedes desired helix num or nil to return first helix num.
returns
string sNextHelixNum
or
nil if not found
notes
Message output to app std err if failed opening input file.
The helix number may be a non-numeric string (e.g. '6a' for helix 6a).
include
SeqUtil.lua
descrip
Returns a string representing the sequence of a nucleic acid chain, in Pearson/FASTA format.
params
number iPdb
number iChain
[string sSeqId] = sequence identifier (will be on first line, following the '>' character.
returns
string sSeq
or
nil if error
notes
The residue sequence numbers are used in formatting the sequence, which consists
of single letters 'a', 'c', 'g', 't', or 'u'. If there is a gap in the sequence,
a '-' will be inserted.
The first line of the sequence will be the '>' character followed by the sequence id.
The next line will be blank, and subsequent lines will be filled with sequence
letters, up to 50 characters per line.
include
SeqUtil.lua
descrip
Returns the name of the reference pdb chain associated with the param helix file.
params
string sHelixFile
returns
string sRefPdbChain or nil
include
SeqUtil.lua
descrip
Returns full relative path to directory of sequence info (map and helix data files).
params
returns
string sSequenceDir
notes
seealso
groups
Seq, File
include
SeqUtil.lua
descrip
Returns total number of helices in param helix data file.
params
string sHelixEndpointsFile = name of helix file in 'seq' subdirectory
returns
number iTotalHelicesInFile or nil
include
SeqUtil.lua
descrip
Returns the greater of the 2 param base positions.
params
string sBaseSymAndNumA
string sBaseSymAndNumB
returns
number: 1 if sBaseA has a larger sequence number than sBaseB, else nil
include
SeqUtil.lua
descrip
Returns true if param chain has a helix definition file.
params
string sPdbChain
returns
number iRet = 1 if chain has helix def file, else nil
notes
The helix file must exist in the 'seq' subdirectory.
include
SeqUtil.lua
descrip
Returns true if no other helices between 5' end and 3' start of param helix.
params
string sHelixFile
string sHelixNum
returns
number bInLoop = 1 if no other helices in loop
or
nil if other helices in loop or if error occurred.
notes
include
SeqUtil.lua
descrip
Maps a table of helix endpoints from one sequence to another sequence.
params
string sMapFile = filename of .smap file located in 'seq' subdir
table tHelixEndPoints = { s5, e5, s3, e3 }
returns
table tMappedHelixEndpoints = { ms5, me5, ms3, me3 }
or
nil, sStatus
include
SeqUtil.lua
descrip
Returns symbol and sequence number for the param base.
params
string sBaseNameAndSeqNum
returns
string sSym
string sSeqPos
or
nil if error
notes
Example: sBase = 'G1432' will return 'G', '1432'.
seealso
parseBaseNum()
include
SeqUtil.lua
descrip
Returns sequence number for the param base.
params
string sBaseSymAndNum (ie: 'A1')
returns
number iSeqNum
or
nil if invalid format in param base.
notes
Example: sBase = 'G1432' will return '1432'.
seealso
parseBase()
include
SeqUtil.lua
descrip
Reports (to stdOut) a sequence of base mappings from param chain.
params
string sChainIn = used in prompt string to request input base
string sMapFile = name of .smap file located in 'seq' subdirectory
number iFwdDir = direction of translation : 1 = map 1st seq to 2nd seq, 0 = map 2nd seq to 1st seq
returns
notes
First requests the input base from the user in a dialog.
Results are sent to app std out.
include
SeqUtil.lua
descrip
Selects all residues in param helix of param pdb chain. If the helix is a simple loop helix, then all residues in the loop will be selectd as well. Otherwise, if other helices are within the helix loop, then only the residues within the helix sides will be selected.
params
string sPdbChain
string sHelixNum
number bNoEchoP (if true, disables echo in rbq commands)
[string sHelixFileP = nil] helix file to obtain helix info from
returns
number bSuccess = 1 or nil
number iTotalResSelected or 0 on error
string sStatus = range(s) of selected residues or message on error
notes
1. bNoEchoP refers to echoing the object selection commands in the app status window.
2. sHelixFile, if given, will be used to obtain the helix endpoint data. If not given,
the function will look for a predefined helix file associated with the param
pdb chain. If not found, the function will fail.
include
SeqUtil.lua
descrip
Returns a list of lines reporting mappings of bases from param mapfile.
params
string sMapFile = name of file in 'seq' subdirectory
number iMapDir = direction of mapping (1 = map first sequence to second sequence, 0 = map 2nd to 1st)
string sBaseIn = '<sSym><iPos>' (ex: 'C503')
number iTotalReportLines = total number of sequence positions to list
returns
string sMapReportLines = "BN -> BN\n..."
or
string sErrMsg = "no match found..."
include
SeqUtil.lua
descrip
Returns a string which is a concatenation of tokens in param table.
params
table tToks
[string sDelim = ' ']
[number iStartTok = 1]
[number iEndTok = getn(tToks)]
returns
string sToksSeparatedByDelim
include
StringUtil.lua
descrip
Returns the ith token extracted from the param string, delim is whitespace.
params
string sIn
number iStartTok
returns
string sIthTok
or
nil
include
StringUtil.lua
descrip
Returns true if param character is in param string.
params
string ch
string sDelims
returns
1 or nil
include
StringUtil.lua
descrip
Returns true if param string is a space character or a tab character or a newline character.
params
string sChar
returns
number 1 or nil
include
StringUtil.lua
descrip
Returns a table of numbers parsed from param string.
params
string sNums
[string sDelim = ' ']
returns
table tNums = { f1, f2, ..., fN }
or
nil if failed parsing a number from a string token
notes
If the param string is empty, an empty table will be returned.
Currently, vectorFromString() is a duplicate implementation of
numbersFromString().
seealso
vectorFromString()
include
StringUtil.lua
descrip
Extracts options from param list of tokens and returns them in several tables. Short option tokens have the format '-a[b][c][...]'. Long option tokens have the format '--optionName[=value]'.
params
table tToks = { [sTok1, [sTok2 [,... ]]] }
returns
table tRet =
{
tShortOptions = { ['<ch1>'] = 1, ['<ch2>'] = 1, ... },
tLongOptions =
{
['<optionName1>'] = { sVal = <value1> },
['<optionName2>'] = { sVal = <value2> },
...
},
tNonOptionToks = { <nonOptionTok1>, <nonOptionTok2>, ... }
}
notes
Example: a param list of tokens = { "-ltr", "--infile=c:\tmp\1ffk.pdb", "--verbose", "proteins" } would return the following:
tRet =
{
tShortOptions = { 'l', 't', 'r', },
tLongOptions =
{
infile = { sVal = 'c:\tmp\1ffk.pdb' },
verbose = { sVal = nil },
},
tNonOptionToks = { 'proteins' }
}
seealso
groups
String, Script
include
StringUtil.lua
descrip
Returns the param var or the string "(nil)" if var is nil.
params
var v
returns
var or string "(nil)"
include
StringUtil.lua
descrip
Replaces all occurences of param substring in param string.
params
string sIn
string sSub
string sRep
returns
string sRet
notes
include
StringUtil.lua
descrip
Returns a table of elements which are tokens in param string separated by delimiter chars in 'sDelimChars'.
params
string sIn
[string sDelimChars = " \t\n"]
[iLimit] = maximum number of tokens to produce
returns
table tToks = { sTok1, sTok2, ... }
or
nil if sIn is empty
notes
If the input string is non-empty, but no non-delim tokens are found,
an empty table is returned.
include
StringUtil.lua
descrip
Returns a table of elements which are tokens in param string separated by delimiter a delimiter string.
params
string sIn
string sDelim
[iLimit] maximum number of tokens to produce
returns
table tToks = { sTok1, sTok2, ... }
or
nil if sIn is empty
notes
If the input string is non-empty, but no non-delim tokens are found,
an empty table is returned.
include
StringUtil.lua
descrip
Returns a string which is param string without leading or trailing whitespace.
params
string sIn
returns
string sTrim
notes
If the input string is non-empty, but no non-delim tokens are found,
an empty table is returned.
include
StringUtil.lua
descrip
Concatenates the elements from param table t2 to param table t1.
params
table t1
table t2
returns
number bRet = 1 or nil
include
TableUtil.lua
descrip
Returns a shallow copy of the param table.
params
table t
returns
table tRet
notes
A shallow copy is a copy of the values of the param table. If these
values are references to other objects, no copying of those objects
is done.
include
TableUtil.lua
descrip
Returns index of table element that is equal to param item, if exists, else nil.
params
table t
(variable type) vItem
returns
number iPosInTable (1-based index)
or
nil if not equal item found in table
notes
The equality is tested using the == operator.
include
TableUtil.lua
descrip
Prints each item in the param table, preceded by an index descriptor and followed by a newline.
params
table t
[string sPrependedDescrip]
returns
include
TableUtil.lua
descrip
Removes and returns the final item from the param table.
params
table t
returns
var vItem
notes
No error checking done.
seealso
pop_front()
include
TableUtil.lua
descrip
Removes and returns the first item from the param table.
params
table t
returns
var vItem
notes
No error checking done.
seealso
pop_back()
include
TableUtil.lua
descrip
Pushes the param item onto the end of the param table.
params
table t
var v
returns
notes
If param table ref is nil, an error will occur.
seealso
push_front()
include
TableUtil.lua
descrip
Pushes the param item onto the front of the param table, initializing the table first if needed.
params
table t
var v
returns
notes
If param table ref is nil, a new one will be assigned to it.
seealso
push_back()
include
TableUtil.lua
descrip
Returns true if param tables have equal items.
params
table t1
table t2
returns
1 if all respective items are equal, else nil
notes
If either table param is nil, then the return result will always be nil.
include
TableUtil.lua
descrip
Concatenates table elements into a return string.
params
table t
[string sDelim = ' ']
returns
string s = 't[1] t[2] t[3] ...'
include
TableUtil.lua
descrip
Returns the first 2 items from the param table.
params
table t
returns
t[1], t[2]
include
TableUtil.lua
descrip
Returns the first 3 items from the param table.
params
table t
returns
t[1], t[2], t[3]
include
TableUtil.lua
descrip
Returns the first 4 items from the param table.
params
table t
returns
t[1], t[2], t[3], t[4]
include
TableUtil.lua
descrip
Returns a new table which contains the 2 param items.
params
v1, v2
returns
table t = { v1, v2 }
include
TableUtil.lua
descrip
Returns a new table which contains the 3 param items.
params
v1, v2, v3
returns
table t = { v1, v2, v3 }
include
TableUtil.lua
descrip
Returns -1 or +1 with 50% probability.
params
returns
number iRet = -1 or +1
notes
seealso
getRandomString()
include
TestUtil.lua
descrip
Returns a string of random length and content, along with a printable coded version.
params
[number iMaxLen = 259]
returns
string sRand
string sRandCode
notes
The coded form can be printed to a log file, bypassing problems that may occur if
the actual string was logged, as the random string may include non-printable
characters. The coded form contains the extended ASCII hexadecimal value of each
character in the string. The character values can range from 0 to 255.
The length of the return string will be a random length in the range [0, iMaxLen - 1].
seealso
getRandomSign()
include
TestUtil.lua
descrip
Returns a normalized vector pointing in a random direction.
params
returns
number vRet = { x, y, z }
notes
seealso
getRandomString(), getRandomSign()
include
TestUtil.lua
descrip
Returns local path to base directory of rbq-lua unit tests.
params
returns
string sPath
notes
seealso
groups
Test, File
include
TestUtil.lua
descrip
Returns full path to the test log file.
params
returns
string sFile
notes
This file receives detailed info from testBegin(), testEnd(), testFailed() functions.
seealso
setTestLogFile(), testLog()
include
TestUtil.lua
descrip
Returns full path to the test logfile.
params
returns
string sFile
notes
This file simply holds the names and pass/fail results of each test.
seealso
setTestResultFile()
include
TestUtil.lua
descrip
Does setup ops at the start of a test. This sets the current test name and clears the fail flag, and logs test begin info to the test logfile.
params
string sTestName
returns
number bRet = 1 if success, else nil
notes
seealso
setTestLogFile(), setTestResultFile(), testEnd()
include
TestUtil.lua
descrip
Does cleanup ops at end of a test. Currently, this is just writing test results to result file and logging of test end to test logfile.
params
string sTestName
returns
number bRet = 1 if success, else nil
notes
seealso
setTestLogFile(), setTestResultFile(), testBegin(), testFailed()
include
TestUtil.lua
descrip
Records failure of a test. Sets a fail flag and logs fail status to test log file.
params
string sStatus
returns
number bRet = 1 if success, else nil
notes
Also echos fail status to app errOut.
seealso
testBegin(), testEnd()
include
TestUtil.lua
descrip
Writes param string to the test log file. A test script can call this function to log extra information if desired, during the running of the test.
params
string sText
returns
number bRet = 1 if success, else nil
notes
seealso
setTestLogFile(), getTestLogFile()
include
TestUtil.lua
descrip
Sets full path to the test logfile.
params
string sFile
returns
notes
This file receives detailed info from testBegin(), testEnd(), testFailed() functions.
seealso
getTestLogFile(), testLog()
include
TestUtil.lua
descrip
Sets full path to the test results file.
params
string sFile
returns
notes
This file simply holds the names and pass/fail results of each test.
seealso
getTestResultFile()
include
TestUtil.lua
descrip
Returns a vector which is the sum of the param vector and scalar.
params
table v
number s
returns
table vs = { v[1] + s, v[2] + s, v[3] + s }
notes
seealso
multiplyVectorByScalar()
include
VectorUtil.lua
descrip
Returns a vector which is the sum of the 2 param vectors.
params
table vi
table vj
returns
table vij
notes
seealso
subtractVector()
include
VectorUtil.lua
descrip
Returns a vector which is the normal of the plane defined by the param points.
params
table tPoints = { pt1, pt2, pt3 }
returns
table vNormal
or
nil if points are colinear
notes
The direction of the normal is determined by v12 x v32 where v12 = (pt2 - pt1) and v32 = (pt2 - pt3).
Note: these vector directions have been implemented backwards from the usual convention. This should
be reversed at some point.
The return vector is normalized.
seealso
groups
Vector, Geom
include
VectorUtil.lua
descrip
Returns a vector which is a copy of the param vector.
params
table vIn
returns
table v = { vIn[1], vIn[2], vIn[3] }
include
VectorUtil.lua
descrip
Returns a vector which is the cross product of the 2 param vectors.
params
table va
table vb
returns
table vc = va x vb
notes
If the vectors are colinear, the zero vector should be returned.
seealso
dotProduct()
include
VectorUtil.lua
descrip
Returns a vector from division of the param vector and scalar.
params
table v
number s
returns
table vRet = { v[1] / s, v[2] / s, v[3] / s }
notes
No error checking is for s equal to zero.
seealso
multiplyVectorByScalar()
include
VectorUtil.lua
descrip
Returns the dot product of the param vectors.
params
table v1
table v2
returns
number fDotProduct
include
VectorUtil.lua
descrip
Returns a 3 x 3 matrix extracted from param homogeneous matrix.
params
returns
table tMat = { vx, vy, vz }
notes
seealso
extractTranslation()
groups
Vector, Geom
include
VectorUtil.lua
descrip
Returns the translation component extracted from the param homogeneous matrix.
params
table tHmat
returns
table vTrans
notes
seealso
extractRotation()
groups
Vector, Geom
include
VectorUtil.lua
descrip
Converts a 16 float homogenous matrix to a coordinate frame.
params
table tHMat = { m00, ..., m15 }
returns
table tFrame = { vTrans, tMat }
notes
A frame is a table with 2 components: a translation vector and a rotation
matrix. By extracting the combined translation and rotation out of
a homogenous matrix, certain geometrical operations are easier to perform.
format of tFrame.vTrans =
{x, y, z}
format of tFrame.tMat =
{
[1] = { r00, r01, r02 },
[2] = { r10, r11, r12 },
[3] = { r20, r21, r22 },
}
seealso
rotateFrame(), translateFrame(), getHMatrixFromFrame()
groups
Vector, Geom
include
VectorUtil.lua
descrip
Returns the origin point of the param frame, in world coords.
params
table tFrame = { vTrans = {...}, tMat = {...} }
returns
table ptOrg
include
VectorUtil.lua
descrip
Returns a homogeneous transform matrix with rotation constructed by CGrTransform3f class.
params
number fDeg
table vRot
table ptCen
returns
table hmRot = { hm00, ..., hm15 }
notes
This matrix can be used to rotate a point in space by the param degrees
about the param vector around the param rotation center point.
seealso
multiplyVectorAndHMatrix()
getRotatedHMatrix(), getTranslatedHMatrix(), multiplyHMatrix(), extractTranslation()
include
VectorUtil.lua
descrip
Converts a coordinate frame into a 16 float homogeneous matrix.
params
table tFrame = { vTrans = {...}, tMat = {...} }
returns
table tHMat = { m00, ..., m15 }
notes
seealso
getFrameFromHMatrix()
groups
Vector, Geom
include
VectorUtil.lua
descrip
Returns a coordinate frame set to the world frame.
params
returns
table tFrame = { vTrans = { 0, 0, 0 }, tMat = identity 3x3 matrix }
notes
seealso
getIdentityMatrix(), getIdentityHMatrix(), translateFrame(), rotateFrame()
include
VectorUtil.lua
descrip
Returns a 3 x 3 identity matrix.
params
returns
table tMat = { vx, vy, vz }
notes
seealso
getIdentityFrame(), getIdentityHMatrix()
include
VectorUtil.lua
descrip
Returns a 16 float identity matrix.
params
returns
table tMat = { m00, ..., m15 }
notes
seealso
getIdentityFrame(), getIdentityMatrix()
include
VectorUtil.lua
descrip
Returns the transpose of the param 3x3 matrix.
params
table tMat
returns
table tRet
notes
seealso
getInverseHMatrix()
include
VectorUtil.lua
descrip
Returns inverse of param 16 float homogenous matrix.
params
table hm
returns
table hmi
notes
seealso
getInverseMatrix()
include
VectorUtil.lua
descrip
Returns a local coordinate frame from param table of origin and direction vectors.
params
table tLoc = { ptOrg = pt, vDir1 = v, vDir2 = v }
returns
table tFrame = { vTrans = pt, tMat = { vi, vj, vk }}
include
VectorUtil.lua
descrip
Returns the coord with maximum scalar value from param vector.
params
table v
returns
number fMax
notes
seealso
getMinCoord()
include
VectorUtil.lua
descrip
Returns a point which is the midpoint of the param points.
params
table pt1
table pt2
returns
table ptMid
include
VectorUtil.lua
descrip
Returns the coord with minimum scalar value from param vector.
params
table v
returns
number fMin
notes
seealso
getMaxCoord()
include
VectorUtil.lua
descrip
Returns a point which is the projection of the param vector onto the plane defined by the param normal (and located at the Origin).
params
table vNormal
table vIn
returns
table vProjectedOntoPlane
notes
Input vectors should be normalized. This is because the plane is implicitly
defined as passing through the origin, which is why only the normal vector
is needed as a parameter to define the plane.
seealso
groups
Vector, Geom
include
VectorUtil.lua
descrip
Returns a 3x3 matrix which is rotated by param degrees about param vector.
params
number fDeg
table vRot
returns
table tRotMatrix
notes
Input vector vRot does not have to be normalized.
seealso
rotateMatrix(), getRotatedHMatrix()
groups
Vector, Geom
include
VectorUtil.lua
descrip
Returns a 16 float homogeneous identity matrix which has been rotated by param degrees about param vector.
params
number fDeg
table vRot
returns
table hmr
notes
Input vector vRot does not have to be normalized.
seealso
getTranslatedHMatrix(), rotateHMatrix(), getRotatedMatrix()
getGrtRotation()
groups
Vector, Geom
include
VectorUtil.lua
descrip
Returns a 16 float homogeneous identity matrix which has been translated by param vector.
params
table vTrans
returns
table hmt
notes
seealso
getRotatedHMatrix()
groups
Vector, Geom
include
VectorUtil.lua
descrip
Returns the transpose of the param 3x3 matrix.
params
table tMat
returns
table tRet
notes
seealso
getInverseMatrix(), getTransposeHMatrix()
include
VectorUtil.lua
descrip
Returns the transpose of the param 16 float homogeneous matrix.
params
table hm
returns
table hmt
notes
seealso
getTransposeMatrix()
include
VectorUtil.lua
descrip
Returns a unit vector from the param vector.
params
table vIn = { x, y, z }
returns
table vUnit
number fMag length of original vector
or
nil if failed to make unit vector
notes
seealso
makeUnitVector()
include
VectorUtil.lua
descrip
Returns true if param homogeneous matricies are equal within param delta.
params
table m1
table m2
number d = amount by which vector component can differ, inclusive.
returns
number bRet = 1 if matrices is equal in range, else nil
notes
seealso
isEqualVectorDelta()
include
VectorUtil.lua
descrip
Returns true if param vectors are equal
params
table v1
table v2
returns
number bRet = 1 if vector is equal, else nil
notes
seealso
isEqualVectorDelta()
include
VectorUtil.lua
descrip
Returns true if param vectors are equal with param delta.
params
table v1
table v2
number d = amount by which vector component can differ, inclusive.
returns
number bRet = 1 if vector is equal in range, else nil
notes
seealso
isEqualVector(), isEqualHMatrixDelta()
include
VectorUtil.lua
descrip
Returns true if param point is within the param bounds.
params
table pt
table vMin
table vMax
returns
number bRet = 1 if all point coords are >= vMin and <= vMax, else nil
notes
seealso
include
VectorUtil.lua
descrip
Returns true if param is a vector.
params
table v = { x, y, z }
returns
number bRet = 1 if vector, else nil
notes
seealso
include
VectorUtil.lua
descrip
Returns true if param vector is the zero vector.
params
table v = { x, y, z }
returns
number bRet = 1 if vector is zero, else nil
notes
seealso
zeroVector()
include
VectorUtil.lua
descrip
Makes the param vector a unit vector.
params
table v = { x, y, z }
returns
number bRet = 1 or nil
notes
Nothing is returned, param v elements are altered. If v has zero magnitude,
nothing is done and nil is returned.
seealso
getUnitVector()
include
VectorUtil.lua
descrip
Returns a 3x3 rotation matrix from param quaternion.
params
table tQuat = vector[4] ( { tQuat[1] = w, tQuat[2] = x, tQuat[3] = y, tQuat[4] = z } ).
returns
table tMatRet = matrix[3][3]
notes
The param quaternion must be normalized.
seealso
quatFromMatrix(), slerpQuat()
include
VectorUtil.lua
descrip
Returns a homogeneous matrix which is the product of the param homogeneous matrices.
params
table hMat1
table hMat2
returns
table hMatRet = hMat1 * hMat2
notes
Multiplication is done 'OpenGL-style' (column-major order).
seealso
multiplyMatrix()
include
VectorUtil.lua
descrip
Returns a 3x3 matrix which is the product of the param 3x3 matrices.
params
table ma
table mb
returns
table mp = ma * mb
notes
Multiplication is done in row-major order.
seealso
multiplyHMatrix()
include
VectorUtil.lua
descrip
Returns a vector which is the product of the param 3x1 vector and 4x4 homogeneous matrix.
params
table v
table m
returns
table vRet =
{
v[1]*m[ 1] + v[2]*m[ 5] + v[3]*m[ 9] + m[13],
v[1]*m[ 2] + v[2]*m[ 6] + v[3]*m[10] + m[14],
v[1]*m[ 3] + v[2]*m[ 7] + v[3]*m[11] + m[15]
}
or
nil if invalid params
notes
Note that the matrix is multiplied in column-major order (OpenGL-style).
seealso
multiplyVectorAndMatrix()
include
VectorUtil.lua
descrip
Returns a vector which is the product of the param 3x1 vector and 3x3 matrix.
params
table v
table m
returns
table vRet = { v * m[1], v * m[2], v * m[3] }
or
nil if invalid params
notes
Matrix m should be defined as m[1] = vx, m[2] = vy, m[3] = vz
where vx, vy and vz are vectors.
v * m[i] indicates dot product between 2 vectors.
seealso
multiplyVectorAndHMatrix()
include
VectorUtil.lua
descrip
Returns a vector from division of the param vector and scalar.
params
table v
number s
returns
table vRet = { v[1] * s, v[2] * s, v[3] * s }
notes
seealso
divideVectorByScalar(), addScalarToVector(), negateVector()
include
VectorUtil.lua
descrip
Returns the negation of the param vector.
params
table v
returns
table vRet = { -v[1], -v[2], -v[3] }
notes
seealso
multiplyVectorByScalar()
include
VectorUtil.lua
descrip
Converts param point from param local frame to world frame.
params
table tLocalFrame
table ptLoc = { x, y, z }
returns
table ptWorld
notes
tFrame should be defined with 2 components :
vTrans = { x, y, z }
tMat = { vi, vj, vk } where vi, vj, vk are unit vectors
seealso
pt_WorldToLocal(), vec_LocalToWorld()
groups
Vector, Geom
include
VectorUtil.lua
descrip
Converts param point from world frame to param local frame.
params
table tLocalFrame
table ptWorld = { x, y, z }
returns
table ptLocal
notes
tLocalFrame should be defined with 2 components :
vTrans = { x, y, z }
tMat = { vi, vj, vk } where vi, vj, vk are vectors
seealso
pt_LocalToWorld(), vec_WorldToLocal()
groups
Vector, Geom
include
VectorUtil.lua
descrip
Prints value of param coordinate frame to app stdout.
params
table tFrame
[string sFmt]
returns
notes
seealso
printHMatrix(), printMatrix()
include
VectorUtil.lua
descrip
Prints contents of param homogeneous matrix to app stdout.
params
table hm
[string sFmt]
returns
notes
seealso
printMatrix(), printFrame()
include
VectorUtil.lua
descrip
Prints contents of param location object.
params
table tLoc
[string sFmt]
returns
notes
include
VectorUtil.lua
descrip
Prints contents of param 3 x 3 matrix to app stdout.
params
table tMat = matrix[3][3]
[string sFormat = "%7.1f"]
returns
notes
seealso
printHMatrix(), printFrame()
include
VectorUtil.lua
descrip
Returns a quaternion from param 3x3 rotation matrix.
params
table tMat = matrix[3][3]
returns
table tQuat = vector[4] ( tQuat[1] = w, tQuat[2] = x, tQuat[3] = y, tQuat[4] = z )
notes
Code is derived from "http://www.euclideanspace.com/maths/geometry/rotations/conversions/matrixToQuaternion/"
seealso
matrixFromQuat(), slerpQuat()
include
VectorUtil.lua
descrip
Reads homogeneous transform matrix from param file.
params
string sFile
returns
table tMatrix
or
number bRet = nil if error
notes
An error message is printed to stdout on failure to open the param file.
seealso
writeHMatrix()
groups
Vector, File
include
VectorUtil.lua
descrip
Reads vector from param file.
params
string sFile
returns
table tVector
or
number bRet = nil if error
notes
An error message is printed to stdout on failure to open the param file.
The vector must be an list of scalar numbers, with list length of 1 or greater.
seealso
writeVector()
groups
Vector, File
include
VectorUtil.lua
descrip
Rotates param frame by param degrees about param vector.
params
table tFrame
number fDeg
table vRot
returns
table tFrameRot
notes
Internally, the sign of rotation is switched so that the frame rotates
according to the right-hand rule.
seealso
translateFrame(), getIdentityFrame()
groups
Vector, Geom
include
VectorUtil.lua
descrip
Adds param rotation to param 4x4 homogeneous matrix.
params
table hmIn
number fDeg
table vRot
returns
table hmRet = hmIn * hmRot
notes
Input vector vRot does not have to be normalized. The param rotation is
applied to an identity matrix that is then post-multiplied into the param matrix.
seealso
translateHMatrix(), getRotatedHMatrix(), rotateMatrix()
groups
Vector, Geom
include
VectorUtil.lua
descrip
Returns a 3x3 matrix which is the param matrix rotated by param degrees about param vector.
params
table tMatrix
number fDeg
table vRot
returns
table tRotMatrix
notes
Input vector vRot does not have to be normalized.
seealso
getRotatedMatrix(), rotateHMatrix()
include
VectorUtil.lua
descrip
Returns a vector from a string representation.
params
string s = 'x y z'
[string chDelim = ' ']
returns
table v = { x, y, z } if successfully converted
or
nil if failed conversion
notes
seealso
v2s(), vectorFromString(), vectorToString()
groups
Vector, String
include
VectorUtil.lua
descrip
Shifts param point ptIn in the param direction by param distance.
params
table ptIn
table vShiftDir
number fShiftDistance
returns
table ptShiftedPoint
notes
vShiftDir must be normalized
include
VectorUtil.lua
descrip
Returns a quaternion that is a spherical linear interpolation of the param quaternions.
params
table q1 = array[4]
table q2 = array[4]
number t = slerp factor in range [0, 1]
returns
table qSlerp = array[4] = interpolated quaternion between q1 and q2 by t
notes
Code is derived from 'quaternions.cpp', Steve Collins, 24/11/98.
array[4] = { q[1] = w, q[2] = x, q[3] = y, q[4] = z }
seealso
matrixFromQuat(), quatFromMatrix()
include
VectorUtil.lua
descrip
Returns v2 - v1.
params
table v1
table v2
returns
table vij
include
VectorUtil.lua
descrip
Adds param translation to param frame.
params
table tFrame
table vTrans
returns
table tFrameTrans
notes
seealso
rotateFrame(), getIdentityFrame()
groups
Vector, Geom
include
VectorUtil.lua
descrip
Adds param translation to param homogeneous matrix.
params
table tHmIn
table vTrans
returns
table tHmTrans = hmIn * hmTrans
notes
The param translation is applied to an identity matrix that is
then post-multiplied into the param matrix.
seealso
rotateHMatrix(), getTranslatedHMatrix()
groups
Vector, Geom
include
VectorUtil.lua
descrip
Returns a string representation of param vector. The vector is assumed to be a table of 3 numbers.
params
table v
[string sFmt = %.1f]
[chDelim = ' ']
returns
string sv
notes
seealso
s2v(), vectorFromString(), vectorToString()
groups
Vector, String
include
VectorUtil.lua
descrip
Converts param vector from param local frame to world frame.
params
table tLocalFrame
table vLocal = { x, y, z }
returns
table vWorld
notes
tFrame should be defined with 2 components :
vTrans = { x, y, z }
tMat = { vi, vj, vk } where vi, vj, vk are unit vectors
If the input vector is the zero vector, then the zero vector will be returned.
seealso
pt_LocalToWorld(), vec_WorldToLocal()
groups
Vector, Geom
include
VectorUtil.lua
descrip
Converts param vector from world frame to param local frame.
params
table tLocalFrame
table vWorld = { x, y, z }
returns
table vLocal
notes
tLocalFrame should be defined with 2 components :
vTrans = { x, y, z }
tMat = { vi, vj, vk } where vi, vj, vk are vectors
If the input vector is the zero vector, then the zero vector will be returned.
seealso
pt_WorldToLocal(), vec_LocalToWorld()
groups
Vector, Geom
include
VectorUtil.lua
descrip
Returns the angle (in degrees) between the param vectors.
params
table v1
table v2
returns
number degAngle
notes
The param vectors do not need to be normalized. The resulting
angle is always non-negative and in the range [0, 180].
If the dot product between the param vectors is exactly 0 then an
angle of 0 will be returned.
include
VectorUtil.lua
descrip
Returns the distance between the param points.
params
table v1
table v2
returns
number fDist
include
VectorUtil.lua
descrip
Returns the magnitude of the param vector.
params
table v
returns
number vMag
include
VectorUtil.lua
descrip
Returns a vector (table of numbers) from a string representation.
params
string sX_Y_Z = 'x y z...' or 'xDyDz...' (depending on delimiter)
[string sDelim = " "]
returns
table v = { x, y, z... }
or
nil if failed parsing a number from a string token
notes
If the param string is empty, an empty table will be returned.
Currently, numbersFromString() is a duplicate implementation of
vectorFromString().
seealso
vectorToString(), s2v(), v2s(), numbersFromString()
groups
Vector, String
include
VectorUtil.lua
descrip
Returns a string representation of the param vector.
params
table v = { x, y, z, ... }
[string sDelim = " "] = optional delimiter
[string sDigitFormatSpec] = optional printf format specifier to limit the zillion decimal places (such as "%2.4f").
returns
string sX_Y_Z = 'x y z...' or 'x, y, z...' (depending on bComma)
notes
seealso
vectorFromString(), s2v(), v2s()
groups
Vector, String
include
VectorUtil.lua
descrip
Writes param hmatrix to param file.
params
string sFile
table tMatrix
returns
number bRet = 1 or nil if error
notes
An error message is printed to stdout on failure to open the param file.
seealso
readHMatrix()
groups
Vector, File
include
VectorUtil.lua
descrip
Writes param vector to param file.
params
string sFile
table tVec
returns
number bRet = 1 or nil if error
notes
An error message is printed to stdout on failure to open the param file.
seealso
readHMatrix()
groups
Vector, File
include
VectorUtil.lua
descrip
Returns the 0 vector.
params
returns
table v = { 0, 0, 0 }
notes
seealso
isZeroVector()
include
VectorUtil.lua
descrip
Translates view so that param object is just fully visible in view frame.
params
string sObj = name of static or dynamic object
returns
number iRet = 1 or nil if error
notes
If the menu item 'Enable Center on Inserted Object' is not checked in the
view menu, a newly-loaded model may not be visible from the current view.
This function can be called to reproduce the behaviour of that menu item.
seealso
centerSelectionInView()
groups
View, Pdb, File
include
ViewUtil.lua
descrip
Sets option to center view on newly-inserted object.
params
number iEnable = 1 or 0
returns
number iRet = 1
or
nil if error
notes
seealso
isCenterViewOnInsertedObjectSet()
groups
View, Pdb, File
include
ViewUtil.lua
descrip
Translates view so that selection is just fully visible in view frame, looking in -z dir and up in +y dir.
params
returns
number iRet = 1 or nil if error
notes
seealso
centerObjectInView()
groups
View, Select
include
ViewUtil.lua
descrip
Returns view lookDir vector, upDir vector and center point (in world frame).
params
returns
table tLook
table tUp
table tCenter
notes
seealso
setView()
include
ViewUtil.lua
descrip
Returns true if option to center view on newly-inserted object is set.
params
returns
number bRet = 1 or nil
notes
If the application option to center on a newly-inserted object is set,
the application will automatically center the view on the object. However,
a script may often adjust the position of an object after its insertion.
This function allows the script to determine whether it should center the
view after making the adjustment.
seealso
enableCenterOnNewObject(), resetView()
groups
View, File, Script
include
ViewUtil.lua
descrip
Returns view center point, in world frame coords.
params
returns
table ptCen
notes
seealso
setViewCenter()
include
ViewUtil.lua
descrip
Returns view look dir vector, in world frame coords.
params
returns
table tLookDir = { x, y, z }
notes
seealso
setLookDir()
include
ViewUtil.lua
descrip
Returns homogeneous matrix of the view frame.
params
returns
table tLook = { m00, m01, ..., m15 }
include
ViewUtil.lua
descrip
Returns view rotation center point, in world frame coords.
params
returns
table tRotCen
notes
seealso
rotateView(), setRotCenter()
include
ViewUtil.lua
descrip
Returns view up dir vector, in world frame coords.
params
returns
table tUp
notes
seealso
setUpDir()
include
ViewUtil.lua
descrip
Resets the view to a default viewpoint.
params
returns
number iRet = 1 or nil
notes
The default viewpoint is with look direction in the -z direction, up
direction in +y direction and view origin at world frame origin (0,0,0).
If the option 'Enable Center on Inserted Object' is set, the view will
instead be set to a viewpoint that shows a full view of the most recently
inserted object, if it still exists.
seealso
rotateView(), translateView(), setView(), isCenterViewOnInsertedObjectSet()
include
ViewUtil.lua
descrip
Rotates view by param deg about param vector (in view frame) around current rotation center.
params
number fDeg
table vRot
[number iEchoCmd = 0 or 1]
returns
number iRet = 1 or nil
notes
Because the view frame is inverted with respect to the world frame, rotation of the
view follows the left-hand rule. For example, with the initial view look dir of {0, 0, -1},
a rotation of 90 degrees about the +y axis would result in a new view look dir of {1, 0, 0}
instead of {-1, 0, 0}.
seealso
translateView(), resetView(), setView()
getViewRotCenter(), setRotCenter(), rotateViewAroundCenter()
include
ViewUtil.lua
descrip
Rotates view by param deg around param point (in world frame) [with param up vector].
params
number fDeg
table ptCen
[table vUpDir]
returns
number bRet = 1
or
nil if error
notes
The look direction of the view will be set to the param rotation center, if
it is different from the current view center.
If no param vUpDir is given, the current view up direction will be used.
seealso
rotateView()
include
ViewUtil.lua
descrip
Sets view look direction to param coords (in world frame).
params
number x, y, z
[number iEchoCmd = 0] or 1
returns
number iRet = 1 or nil
notes
seealso
getViewLookDir()
setLookDirV(), setUpDir(), setViewCenter(), setView()
include
ViewUtil.lua
descrip
Sets view look direction to param vector (in world frame).
params
v (table [3] = {x, y, z})
[number iEchoCmd = 0] or 1
returns
number iRet = 1 or nil
notes
seealso
getViewLookDir()
setLookDir(), setUpDir(), setViewCenter(), setView()
include
ViewUtil.lua
descrip
Sets rotation center to the param coords (in world frame).
params
numbers x, y, z
[number iEchoCmd = 0 or 1]
returns
number iRet = 1 or nil
notes
This is the center point around which view rotation occurs.
seealso
getViewRotCenter(), setRotCenterV(), setRotCenterAtSel()
include
ViewUtil.lua
descrip
Sets rotation center to the param vector (in world frame).
params
table vCen
[number iEchoCmd = 0 or 1]
returns
number iRet = 1 or nil
notes
seealso
setRotCenter(), getViewRotCenter()
include
ViewUtil.lua
descrip
Sets rotation center to center of current selection.
params
[number iEchoCmd = 0 or 1]
returns
number iRet = 1 or nil
notes
seealso
setRotCenter()
groups
View, Select
include
ViewUtil.lua
descrip
Sets view up direction to param coords (in world frame).
params
number x, y, z
[number iEchoCmd = 0] or 1
returns
number iRet = 1 or nil
notes
seealso
getViewUpDir()
setLookDir(), setViewCenter(), setView()
include
ViewUtil.lua
descrip
Sets view look direction to param vector (in world frame).
params
v (table [3] = {x, y, z})
[number iEchoCmd = 0] or 1
returns
number iRet = 1 or nil
notes
seealso
getViewUpDir()
setLookDir(), setViewCenter(), setUpDir()
include
ViewUtil.lua
descrip
Sets view to param lookDir vector, upDir vector and center point (in world frame).
params
table tLook
table tUp
table tCenter
[number bEchoCmd = 0 or nil] or 1
returns
number iRet = 1 or nil
notes
seealso
setLookDir(), setUpDir(), setViewCenter(), getView(), resetView()
translateView(), rotateView()
include
ViewUtil.lua
descrip
Sets view center to param coords (in world frame).
params
number x, y, z
[number iEchoCmd = 0] or 1
returns
number iRet = 1 or nil
notes
seealso
setLookDir(), setUpDir(), setViewCenterV(), setView(), getViewCenter()
include
ViewUtil.lua
descrip
Sets view center to param vector (in world frame).
params
table v = {x, y, z}
[number iEchoCmd = 0 or 1]
returns
number iRet = 1 or nil
notes
seealso
setLookDir(), setUpDir(), setViewCenter(), getViewCenter()
include
ViewUtil.lua
descrip
Sets display of rotation axes.
params
number iShow = 0 or 1
returns
number bRet = 1 or nil
notes
The rotation axes are three orthogonal lines displayed at the center of
the view rotation center.
seealso
showWorldAxes()
include
ViewUtil.lua
descrip
Sets display of rotation axes.
params
number iShow = 0 or 1
returns
number bRet = 1 or nil
notes
The rotation axes are three orthogonal lines displayed at the center of
the view rotation center.
seealso
showWorldAxes()
include
ViewUtil.lua
descrip
Translates view by param coords (in view frame).
params
table vTrans = { tx, ty, tz }
[number iEchoCmd = 0 or 1]
returns
number iRet = 1 or nil
notes
seealso
rotateView(), resetView(), setView()
include
ViewUtil.lua
descrip
Converts param vector from view frame to world frame.
params
table vView = { x, y, z }
returns
table vWorld
notes
Currently, this function doesn't work.
seealso
vec_WorldToView()
groups
View
include
ViewUtil.lua
descrip
Converts param vector from world frame to view frame.
params
table vWorld = { x, y, z }
returns
table vView
notes
Currently, this function doesn't work.
seealso
vec_ViewToWorld()
groups
View
include
ViewUtil.lua
descrip
Writes image of graphics window to file.
params
string sOutfile
[string sFormat = ("PNG" | "BMP" )]
returns
number bRet = 1 or nil if error
notes
seealso
groups
Win, Graphics
include
WinUtil.lua
descrip
Returns width and height of main window, in pixels.
params
returns
number iWidth
number iHeight
notes
This is the size of the entire window including the frame (non-client area).
The actual enclosed client area will be a smaller size.
seealso
resizeMainWin(), getGraphicsWinSize()
groups
Win, Graphics
include
WinUtil.lua
descrip
Returns width and height of graphics window, in pixels.
params
returns
number iWidth
number iHeight
notes
seealso
getMainWinSize(), resizeMainWin()
groups
Win, Graphics
include
WinUtil.lua
descrip
Returns total number of toolbars in main window.
params
returns
number iTotalToolbars
notes
This function can be used for iterating toolbars.
seealso
include
WinUtil.lua
descrip
Sets position of main window.
params
number x
number y
returns
number = bRet = 1 or nil if error
notes
Moves the main window so that the upper-left corner of the frame
(non-client area) is located at the param coordinates.
seealso
resizeMainWin()
groups
Win, Graphics
include
WinUtil.lua
descrip
Sets size of main window.
params
number iWidth
number iHeight
returns
number = bRet = 1 or nil if error
notes
This is the size of the entire window including the frame (non-client area).
The actual enclosed client area will be a smaller size.
seealso
moveMainWin(), getMainWinSize(), getGraphicsWinSize()
groups
Win, Graphics
include
WinUtil.lua
descrip
Sets show state of the graphics window.
params
number iShow = 0 or 1
returns
number = bRet = 1 or nil if error
notes
seealso
showToolbar(), showStatusWin()
groups
Win, Graphics
include
WinUtil.lua
descrip
Sets show state of the status window.
params
number iShow = 0 or 1
returns
number = bRet = 1 or nil if error
notes
seealso
showToolbar(), showGraphicsWin()
include
WinUtil.lua
descrip
Sets show state of param toolbar.
params
number iToolbar
number iShow = 0 or 1
returns
number = bRet = 1 or nil if error
notes
seealso
getTotalToolbars(), showGraphicsWin(), showStatusWin()
include
WinUtil.lua