geometry: Points and coordinate systems

place: Coordinate systems

A coordinate system is represented by a Place object which defines an origin and three axes specified relative to another coordinate system. A Place can specify the position and orientation of a model in a scene, defining the local coordinate system of the model relative to the global coordinate system of the scene. A Place can also represent the position and orientation of a camera within a scene. A Place can also be thought of as a coordinate transformation mapping Place coordinates to the other coordinate system. The transform consists of a linear part (often a rotation, but more generally a 3 by 3 matrix) followed by a shift along the 3 axes. Place objects use 64-bit coordinates for axes and origin.

A point or vector is a one-dimensional numpy array of 3 floating point values. Multiple points or vectors are represented as two-dimensional numpy arrays of size N by 3. Points and vectors can have 32-bit or 64-bit floating point coordinates.

class Place(matrix=None, axes=None, origin=None)

The Place class gives the origin and axes vectors for a model in the global coordinate system. A Place is often thought of as a coordinate transformation from local to global coordinates.

The axes can be specified as a sequence of three axis vectors. The origin can be specified as a point. Or both axes and origin can be specified as a 3 by 4 array where the first 3 columns are the axes and the last column is the origin.

The axes do not need to be orthogonal, for instance a crystallographic density map may use skewed axes, and the axis vectors need not be of unit length. The axes and origin are represented as 64-bit floating point values.

apply_without_translation(v)

Transform a vector. This applies the linear part of the transform without the shift. If the linear part is a rotation, then tangent and normal vectors are rotated.

axes()

Return the coordinate system axes.

axis_center_angle_shift()

Parameterize the transform as a rotation about a point around an axis and shift along that axis. Return the rotation axis, a point on the axis, rotation angle (in degrees), and shift distance parallel to the axis. This assumes the transformation linear part is a rotation.

description()

Return a text description of the transformation including the 3 by 4 matrix, and the decomposition as a rotation about a point through an axis and shift along that axis.

determinant()

Return the determinant of the linear part of the transformation.

interpolate(tf, center, frac)

Interpolate from this transform to the specified one by a specified fraction. A fraction of 0 gives this transform while a fraction 1 gives transform tf. The interpolation is done by finding the transform mapping to tf, treating it as a rotation about the specified center point followed by a shift, then perform the specified fraction of the full rotation, and specified fraction of the shift.

inverse()

Return the inverse transform.

is_identity(tolerance=1e-06)

Is the transform the identity transformation? Tests if each of the 3 by 4 matrix elements is within the specified tolerance of the identity transform.

matrix = None

3 by 4 numpy array, first 3 columns are axes, last column is origin.

move(xyz)

Apply transform to an array of points, modifying the points in place.

moved(xyz)

Returned transformed array of points. Makes a copy of points if place is not identity.

opengl_matrix()

Return a numpy 4x4 array which is the transformation matrix in OpenGL order (columns major).

origin()

Return the transformation shift vector, or equivalently the coordinate system origin.

rotation_angle()

Return the rotation angle of the transform, or equivalently the rotation of the coordinate axes from the global axes. The return values is in radians from 0 to pi. The rotation is about the unique axis that takes the local to global coordinates. This assumes the transform is a rotation, or equivalently that the coordinate axes are orthonormal and right handed.

rotation_axis_and_angle()

Return the rotation axis and angle (degrees) of the transform.

same(p, angle_tolerance=0, shift_tolerance=0)

Is this transform the same as the given one to within a rotation angle tolerance (degrees), and shift tolerance (distance)

shift_and_angle(center)

Return the shift distance and rotation angle for the transform. The rotation angle is in radians the same as returned by rotation_angle(), and the shift is the distance the given center point is moved by the transformation.

translation()

Return the transformation shift vector, or equivalently the coordinate system origin.

transpose()

Return a copy of the transform with the linear part transposed.

z_axis()

Return the coordinate system z axis.

zero_translation()

Return a copy of the transform with zero shift.

class Places(places=None, place_array=None, shift_and_scale=None, opengl_array=None)

The Places class represents a list of 0 or more Place objects. The advantage of Places over using a list of Place objects is that it doesn’t need to create a separate Python Place object for each position, instead it is able to represent for example 10,000 atom positions as a numpy array of positioning matrices. So this class is primarily to allow efficient handling of large numbers of positions.

opengl_matrices()

Return array of 4x4 matrices with column-major order.

cross_product(u)

Return the transform representing vector crossproduct with vector u (on the left) and zero shift.

identity()

Return the identity transform.

orthonormal_frame(zaxis, ydir=None, xdir=None)

Return a Place object with the specified z axis. Any rotation about that z axis is allowed, unless a vector ydir is given in which case the y axis will be in the plane define by the z axis and ydir.

product(plist)

Product of a sequence of Place transforms.

rotation(axis, angle, center=(0, 0, 0))

Return a transform which is a rotation about the specified center and axis by the given angle (degrees).

scale(s)

Return a transform which is a scale by factor s.

skew_axes(cell_angles)

Return a Place object representing the skewing with cell angles alpha, beta and gamma (degrees). The first axis is (1, 0, 0), the second axis makes angle gamma with the first and is in the xy plane, and the third axis makes angle beta with the first and angle alpha with the second axes. The axes are unit length and form a right handed coordinate system. The angles alpha, beta and gamma are the angles between yz, xz, and xy axes.

translation(v)

Return a transform which is a shift by vector v.

vector_rotation(u, v)

Return a rotation transform taking vector u to vector v by rotation about an axis perpendicular to u and v. The vectors can have any length and the transform maps the direction of u to the direction of v.

vector: Point and vector operations

These are convenience functions that act on points and vectors which are one-dimensional numpy arrays of 3 elements, or for multiple points and vectors two-dimensional numpy arrays of size N by 3. Vectors of any dimensions are allowed, not just 3-dimensional, except where noted. Coordinate values can be 32 or 64-bit floating point numbers.

distance(p, q)

Return the distance between two points.

norm(u)

Return the length of a vector.

normalize_vector(v)

Return a unit vector in the same direction as v.

normalize_vectors(v)

Modify an array of vectors, making each have unit length.

vector_sum(weights, vectors)

Return a vector which is a linear combination of vectors with specified weights.

cross_product(u, v)

Return the cross-product of two vectors. Vectors must be 3-dimensonal.

inner_product(u, v)

Return the inner product of two vectors.

inner_product_64(u, v)

Return the inner-product of two vectors accumulated as a 64-bit floating point value even if the vector components are 32-bit values.