geometry geometry
Jump to Geometry Objects, Geometry Operations, Background, or
Examples; explanation of how
commands are documented.
Operation Description Arguments
point Create a point object which is the point part of the argument arg arg. The argument may be a geometry point, line, or plane object. line Create a line object which is the line between the points of arg1 2 geometric objects, arg1 and arg2. These arguments may be 2 arg2 points, 2 lines, a point and a line, or a point and a plane. plane Create a plane object which is the plane which passes through arg1 the three specified geometry point objects arg1, arg2, and arg2 arg3, which must not be co-linear. arg3 vector Create a point object (a vector) defined between 2 arg1 geometric objects, arg1 and arg2. These arguments may be 2 arg2 points, 2 lines, a point and a line, or a point and a plane. When the first argument is a line, the vector is perpendicular to that line, with direction and magnitude given by the second argument. If the second argument is also a line, then the vector is perpendicular to both lines. If either argument is a plane, then the vector is normal to that plane. When only one argument is provided, it must be a plane or a line, in which case the vector is the vector part of that plane (the normal) or line. get Return either the number of items or the type of an nItems|type existing geometry object. getItem Create a geometry object which is the itemNum'th item itemNum of an existing geometry object geoObject. geoObject concat Create a geometry object which is the concatenation of two geoObject1 existing geometry objects geoObject1 and geoObject2. These geoObject2 geometry objects must be of the same type unless either is empty or the first is an array type. If both are of type array, the second is appended to the end of the contents of first directly, i.e., the contents of the second are not appended to the contents of the first. This allows arrays of geometry arrays to be composed. distance Determine the distances between 2 geometric objects arg1 ?target? and arg2 or transform a geometric object by the matrix arg1 that would move arg2 to set the distances along the arg2 vectors to arg2 to values target. The arguments may be 2 points, a point and a line, a point and a plane, or 2 lines. angle Determine the angle between 2 or 3 geometric objects arg1, ?target? arg2, and ?arg3? or transform a geometric object by the arg1 matrix that would move the last of the geometric object arg2 defining the angles to set them to values target. The ?arg3? arguments may be 3 points, 2 points and a line, 2 points and a plane, 2 lines, a line and a plane, or 2 planes. The set operation only supports the input of 3 points. torsion Determine the torsion angles between 4 geometric point ?target? objects arg1, arg2, arg3, and arg4 or transform a set of arg1 geometric points by the matrix that would move the last of arg2 the points (arg4) so that the torsion angles would be set to arg3 values target. arg4 outOfPlane Determine the Wilson out-of-plane angles between 4 ?target? geometric point objects arg1, arg2, arg3, and arg4 or arg1 transform a set of geometric points by the matrix that would arg2 move the last of the points (arg4) so that the arg3 out-of-plane angles would be set to values target. arg4 superimpose Transform a set of target points by the matrix used to ?target? produce the maximum overlap of the point objects arg1 and arg1 arg2, such that points arg2 would be superimposed on points arg2 arg1. Keywords rms and weight may be used to obtain the rms residue from the overlap of arg1 and arg2 and to weight the points for the maximum overlap or rms calculation. rms Return the root-mean-square residual for the maximum arg1 overlap of 2 sets of points defined by geometric point arg2 objects arg1 and arg2 to varName. Using the weight keyword, it is possible to set weights on points for the maximum overlap or rms calculation. principalAxes Create a geometric line object that is the centroid and arg principal axes through the set of points in the geometric point object arg. This operation also takes optional keywords. lsqLine Create a geometric line object which is the least-squares arg fit line through the set of points in the geometric point object arg. This operation also takes optional keywords. lsqPlane Create a geometric plane object which is the least-squares arg fit plane through the set of points in the geometric point object arg. This operation also takes optional keywords. translate Translate a set of points along the vectors defined by the distance point geometry object vector by the distances (magnitudes) vector specified by values distance. rotate Rotate a set of points about the lines defined by the line angle geometry object axis by the angles specified by values axis angle. orientAxes Transform a set of points by the matrix which would move arg1 the geometric line objects arg1, arg2, and arg3 onto the ?arg2? external frame axes, i.e., the Cartesian z-, y-, and x-axes, ?arg3? respectively. The first set of lines arg1 is always moved exactly onto the z-axis at the origin. If the second set of lines, arg2, is provided, then the vectors must be normal to those of arg1, and the transformation matrix rotates about the z-axis to align these vectors with the y-axis. If the third set of lines, arg3, is provided, then a further check is made that the transformed vectors of these lines lie parallel with the x-axis in the positive direction.
Jump to Syntax,
Geometry Operations, Background, or ExamplesThe arguments to a geometry command are always geometry objects, i.e., a geometry object definition string or a handle to a geometry object that already exists. There are actually four types of geometry objects:
?point? vector
A point geometric object is represented by the Cartesian coordinates of a set of points. A point geometric object is equivalent to a vector object (see the vector command).
line vector vector
A line geometric object is represented by the Cartesian coordinates of a set of points on the set of lines and a set of unit vectors along the directions of a set of lines.
plane vector vector
A plane geometric object is represented by the Cartesian coordinates of a set of points on the set of planes and a set of unit vectors perpendicular to a set of planes.
array geometry_object ?geometry_object ...?
An array is a collection of point, line, plane, and/or array geometry objects. Currently, array geometry objects may not be used as arguments to geometry commands, but they may be used in geometry set-type operations as the target set to be transformed. For further explanation of the definition of geometry objects and the use of geometry array objects, refer to the Background section and examples below.
Jump to Syntax, Geometry Objects, Background,or ExamplesThe most basic use of the geometry command is to define or examine (convert to a TCL list) geometry objects. However, most of the power of the geometry command comes from the ability to analyze and manipulate geometry objects. This is achieved by adding extra operation arguments to the geometry command, as detailed in the Syntax section and operations table. There are two distinct types of geometry operation:
The syntax for a get-type operation requires that the second argument to the geometry command, after the variable name of the geometry object to be output (i.e., got), is a keyword defining the operation. These are listed in the Geometry Operations table above.
The syntax for a get-type operation requires that the second argument to the geometry command, after the variable name of the geometry object which is to be transformed or created (set), is the keyword transform or matrix. Set-type geometry operations can be performed in two ways:
The first way is to directly use the transform keyword followed by an operation keyword to perform the desired transformation, i.e.:
geometry geoMoveSet transform operation target arg1 ...
where geoMoveSet would be a geometry object to be transformed. The second way is to perform the same operation in two steps by first creating the transformation matrix using the matrix keyword and then transforming using the transform keyword followed by a geometry (matrix) object rather than an operation keyword, i.e.:
geometry geoMat matrix operation target arg1 ...
geometry geoMoveSet transform $geoMat
Other geometry get-type and set-type operations allow specific keywords to appear in the argument list, followed by a geometry object or variable name to specify extra, optional, input or output arguments, e.g., rms for the lsqLine operation.
A summary of the get-type and set-type operations, and lists of optionally allowed keywords, are tabulated below.
All angles are specified in radians. This is the same as for the vector command.
Return to main
Geometry Operations table
Get-type Optional Set-type Optional operations keywords operations keywords
point -- -- -- line -- -- -- vector -- -- -- distance -- distance relative angle -- angle relative torsion -- torsion relative outOfPlane -- outOfPlane relative -- -- superimpose weight rms rms weight -- -- principalAxes weight -- -- moment lsqLine weight -- -- rms lsqPlane weight -- -- rms -- -- translate -- -- -- rotate -- -- -- orientAxes --
Jump to Syntax, Geometry Objects, Geometry Operations, or Examples
For example, a point geometry object can be specified by their Cartesian coordinates and represented as a string:
"{1 2 3} {4 5 6}" or "point {{1 2 3} {4 5 6}}".The geometry operations currently supported are described above. Geometry objects can be input as character strings. To specify if an input string is to be converted to a geometry object of points, lines, or planes, the keyword line or plane are needed for the latter two cases. If the keyword point is specified or if there is no keyword specified, the input string is converted to a point geometry object of points.
The string representations of geometry objects are illustrated in the examples below.
A torsion or dihedral angle formed by four points is defined by:
where sign is the sign of:
An out-of-plane angle formed by four points is defined by:
BTCL > geometry g {{1 2 3}}
or
BTCL > geometry g "{1 2 3}"
Here, g is set to a point (1,2,3). To find out what
a geometry object (g here) holds, the syntax would be:
BTCL > geometry g
{1 2 3}
The BTCL geometry command also takes a number of operations
(listed in the table above), which themselves
take arguments that are either string definitions or geometry variables
of compatible dimensions. Refer to the examples below. There are two types of geometry operations. The get operations evaluate and return the configuration formed by the input geometric objects. The set operations are used to determine the transformation matrix needed to achieve a certain configuration, given by the target, by moving one of the input geometric objects. The geometric object to be transformed is specified, by convention, to be the last one in the input. See Examples 2 and 3 below.
Jump to Syntax, Geometry Objects, Geometry Operations, Background, or
Description
BTCL > geometry p0 "{0 0 0}"; geometry p1 "{1 1 1}"; geometry p2 "{1 0 0}"
Assign the point (0,0,0) to be geometric object p0, (1,1,1) to be
geometric object p1, and (1,0,0) to be geometric object p2.
BTCL > geometry p3 "{0 1 0} {0 0 1}"; geometry p3
{0 1 0} {0 0 1}
Assign two points, (0,1,0) and (0,0,1), to be geometric object p3.
Note that p3 is a point geometric object and is, in general,
a set of points.
BTCL > geometry l1 "line $p0 {{1 0 1} {-1 0 0}}"; geometry l1
line {{0 0 0}} {{0.707107 0 0.707107} {-1 0 0}}
Assigns two lines to be geometric object l1. The first line has
direction (1,0,1) and passes through the point (0,0,0), and the second
line has direction (-1,0,0) and passes through the point (0,0,0). Note
that the vectors along the directions of the lines are normalized.
BTCL > geometry l2 line $p2 $p3; geometry l2
line {{1 0 0}} {{-0.707107 0.707107 0} {-0.707107 0 0.707107}}
Get the line formed from p2 to p3. Note that, since both lines given
in l2 pass through the point (1,0,0), the point is given only once in
l2. The vectors parallel to the lines, (-0.707107 0.707107 0) and
(-0.707107 0 0.707107), are normalized.
BTCL > geometry d1 distance $p0 $l2; geometry d1 0.707107 0.707107Get the distances between p0 and l2.
BTCL > geometry a1 torsion $p2 $p0 $p3 $p1; geometry a1 -0.785398 0.785398Get the dihedral angle formed by p2, p0, p3 and p1.
BTCL > geometry inp "{1 1 -1} {-1 1 1} {1.5 0 -1} {-1 1 1} {1 -1 1} {1.5 0 1}"
BTCL > geometry ref "{1 1 -1} {-1 1 1} {1.5 0 -1} {-1 1 1} {1 -1 1} {1.3 0 1}"
BTCL > geometry wt "2 1 1 1 1 1"
BTCL > geometry l3 lsqLine $inp weight $wt rms res1
BTCL > geometry l3
line {{0.571429 0.428571 0.142857}} {{-0.758033 0.163668 0.631346}}
BTCL > geometry res1
1.56542
Get the least-squares line passing through the points given in $inp,
weighted by the weights given in $wt, and the root-mean-square residual.
BTCL > geometry res2 rms $inp $ref weight $wt; geometry res2 0.0669741Get the minimum root-mean-square residual from comparing the set of points given in $ref and the set of points given in $inp after they are transformed (to give the minimum residual).
BTCL > geometry a "{1 2 3}"; geometry b "{1 4 3}"
BTCL > geometry c "array {{0 0 0}} {{1 1 1}}"; geometry c
array {{0 0 0}} {{1 1 1}}
BTCL > geometry c transform distance 5 $a $b; geometry c
array {{0 3 0}} {{1 4 1}}
BTCL > geometry c transform relative distance 4 $a $b; geometry c
array {{0 7 0}} {{1 8 1}}
In the above sequence, we assigned c to be a geometry array
object that is an array of two geometric point objects. We apply to
c the transformation that would move geometric point object
b along the vector formed by geometric point objects a
and b to be at a distance 5 from geometric point object
a. A further move was made to the transformed c with a
transformation that would move b by a relative distance
of 4 along the a-b vector, i.e., the magnitude of the a-b vector would
increase by 4 units.
BTCL > geometry p1 "{-2 -3 1} {-2 -2 0} {-2 -2 0} {-2 -2 0}"
BTCL > geometry p2 "{-1 -1 1} {-1 0 0} {-1 0 0} {-1 0 0}"
BTCL > geometry p3 "{1 -1 1} {1 0 0} {1 0 0} {1 0 0}"
BTCL > geometry p4 "{2 -3 1} {2 -2 2} {2 0 2} {2 2 2}"
BTCL > geometry tor1 torsion $p1 $p2 $p3 $p4; geometry tor1
0 -0.785398 -1.5708 -2.35619
BTCL > geometry target "{-1} {-2} {-4} {-6}"
BTCL > geometry mat1 matrix torsion $target $p1 $p2 $p3 $p4
BTCL > geometry p4 transform $mat1; geometry p4
{2 -2.0806 2.68294} {2 1.17704 2.57188} {2 1.30729 -1.5136} {2 -2.71577 -0.790306}
BTCL > geometry tor2 torsion $p1 $p2 $p3 $p4; geometry tor2
-1 -2 2.28319 0.283185
BTCL > geometry p4 transform torsion $target $p1 $p2 $p3 $p4
BTCL > geometry tor2 torsion $p1 $p2 $p3 $p4; geometry tor2
-1 -2 2.28319 0.283185
In the above sequence, we first determine the dihedral angle formed by
points p1, p2, p3, and p4. Then we find the transformation mat1 needed
to take p4 to a new position such that the new dihedral angle is as
given in the target $target. We test our transformation by actually
carrying out the transformation on p4 and finding the new dihedral
angle explicitly. Note that the two steps of finding the transformation matrix and performing the transformation can be implicitly done with the command:
BTCL > geometry p4 transform torsion $target $p1 $p2 $p3 $p4 BTCL > geometry tor2 torsion $p1 $p2 $p3 $p4; geometry tor2 -1 -2 2.28319 0.283185Here, we generate the transformation matrix implicitly and hence do not have access to it.
BTCL > geometry inp transform superimpose $inp $ref weight $wt rms res3
BTCL > geometry inp
{1.00742 1.00237 -1.01898} {-0.967094 0.998 1.00618} {1.51577 0.00658773 -1.0192
8} {-0.967094 0.998 1.00618} {1.04949 -0.985232 0.992898} {1.54103 0.0188793 0.9
80518}
BTCL > geometry res3
0.0669741
Here, we determine the transformation matrix implicitly and apply it
to the set of test points $inp. We also determine the root-mean-square
residual and return its value in res3.
BTCL > geometry a "{1 2 3}"; geometry b "{1 4 3}"
BTCL > geometry c concat $a $b
BTCL > geometry c concat $c {{0 0 0}}
BTCL > echo [geometry c]
{1 2 3} {1 4 3} {0 0 0}
The example above shows the use of the geometry concat
operation. First two point geometry objects are defined and
concatenated to form another geometry object c. The
concat operation is then used again to add another point
(0,0,0) to c.
BTCL > proc sum_dists {varName geo1 geo2} {
upvar 1 $varName dists
$ng = [geometry b get nItems]
vector dists fill $ng 0
$ng = [geometry a get nItems]
for {$i = 0} {$i < $ng} {incr i} {
geometry c getItem $i $a
geometry d distance $c $b
vector dists add $dists $d
}
}
BTCL > geometry a "{1 2 3} {4 5 6} {7 8 9}"
BTCL > geometry b "line {{0 0 0} {1 0 0}} {{0 1 0} {0 0 1}}"
BTCL > sum_dists distance_sum $a $b
BTCL > echo [geometry distance_sum]21.7751 17.831
The example above shows the use of the geometry get and
getItem operations from inside a procedure named
sum_dists. This procedure is designed to take two geometry objects and
calculate the summed distances from all the items in the first
geometry object to all the items in the second geometry object. Given
two geometry objects, one containing N items, it is possible to
perform geometry operations, such as distance, only if the
other object contains exactly 1 or N items. The procedure
sum_dists allows M to N operations by performing
M (1 to N) operations, using the getItem operation to
access individual items in geometry objects. In this example, this procedure is used to find the summed distances between three points a and two lines b.
Main
access page 
Advanced-Use access.
List of BTCL commands
forcefield command
help command
Copyright Biosym/MSI