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.

__eq__(p)

Supported API . Are matrix values of this Place equal to matrix values of another Place.

__init__(matrix=None, axes=None, origin=None)

Supported API . Coordinate axes and origin can be specified as a 3 by 4 array where the first 3 columns are the axes vectors and the fourth column is the origin. Alternatively axes can be specified as a list of axes vectors and the origin can be specifed as a vector.

__mul__(p)

Supported API . Multiplication of a Place and a point transforms from local point coordinates to global coordinates, the result being a new point. Multiplication of a Place by another Place composes the coordinate transforms acting in right to left order producing a new Place object.

apply_without_translation(v)

Supported API . Apply the linear part (3x3 matrix) of the transform without the shift.

axes()

Supported API . Return the coordinate system axes.

axes_lengths()

Supported API . Return the lengths of the axes vectors.

axis_center_angle_shift()

Supported API . 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.

axis_length(axis_number)

Supported API . Return the length of the axix (0,1 or 2 for x,y,z).

description()

Supported API . 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()

Supported API . Return the determinant of the linear part of the transformation.

interpolate(tf, center, frac)

Supported API . 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. When the interpolated places are thought of as coordinate systems positions, the center point is in local coordinates.

inverse(is_orthonormal=False)

Supported API . Return the inverse transform. If is_orthonormal is True then the transform is assumed to be orthonormal so the inverse is the transpose, allowing faster computation.

is_identity(tolerance=0)

Supported API . 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.

property matrix

Supported API. Returns a copy of the 3x4 float64 transformation matrix as a numpy array.

opengl_matrix()

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

origin()

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

remove_scale()

Experimental API . Return a copy of the transform with unit scale factor assuming it is a rotation times a scale factor.

rotation_angle()

Supported API . 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()

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

rotation_quaternion()

Supported API . Return the quaternion of the rotation part of the transform.

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

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

scale_factor()

Experimental API . Scale factor assuming a rotation times a scale factor.

scale_translation(s)

Experimental API . Return a copy of the transform with scaled shift.

shift_and_angle(center)

Supported API . 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.

transform_normals(xyz, in_place=False, is_rotation=False)

Supported API . Apply inverse transpose of transform with zero shift to an array of normal vectors, modifying the vectors in place. If is_rotation is true then the transform is assumed to be a rotation with no scaling or skewing so that the inverse transpose is the same as the original transform, allowing for faster computation.

transform_points(xyz, in_place=False)

Supported API . Returned transformed array of points. Makes a copy of points if place is not identity or in_place is False.

transform_vector(v)

Supported API . Apply the linear part (3x3 matrix) of the transform without the shift.

transform_vectors(v, in_place=False)

Supported API . Apply the linear part (3x3 matrix) of the transform without the shift. A new copy of the numpy Nx3 array of vectors is returned unless in_place = True.

translation()

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

transpose()

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

z_axis()

Supported API . Return the coordinate system z axis.

zero_translation()

Supported API . 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.

__eq__(p)

Supported API . Test if these places identical in order and matrix elements.

__init__(places=None, place_array=None, shift_and_scale=None, opengl_array=None)

Supported API . Places can be specified as a list of Place instances, or a numpy N x 3 x 4 array, or a shift and scale N x 4 array, or a 4 x 4 numpy array (opengl format).

__iter__()

Supported API . Iterator returning Place instances.

__len__()

Supported API . Number of places.

__mul__(places_or_vector)

Supported API . Can multiply by another Places which produces all-by-all products of matrices, or can multiply by a single Place, or can multiply by a single vector or array of vectors.

array()

Supported API . Return a numpy float64 N x 3 x 4 array.

is_identity()

Supported API . Whether this Places contains just one place which is the identity.

masked(mask)

Supported API . Return a Places instance containing only the places where boolean mask array is true. The mask array must have length equal to the number of places.

opengl_matrices()

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

place_list()

Supported API . Return a list of Place instances.

shift_and_scale_array()

Supported API . Only valid if this Places was specified using a shift and scale matrix, otherwise None is returned.

transform_coordinates(csys)

Supported API . Transform these places to a new coordinate system. Argument csys maps new coordinates to old coordinates.

cross_product_matrix(u)

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

identity()

Supported API . Return the identity transform.

interpolate_rotation(place1, place2, fraction)

Supported API . Interpolate the rotation parts of place1 and place2. The rotation axis taking one coordinate frame to the other is linearly interpolated. The translations are ignored and the returned Place has translation set to zero.

look_at(from_pt, to_pt, up)

Supported API . Return a Place object that represents looking from ‘from_pt’ to ‘to_pt’ with ‘up’ pointing up.

multiply_transforms(tf1, tf2, result=None)

Experimental API . Multiply Place or Places times another Place or Places. Returns tf1 * tf2. If the result argument is specified (Place or Places) it modifies the matrices of that instance. This violates the assumption that Place and Places are immutable, and is only done for optimization purposes. Use of this method is discouraged. Instead use tf1 * tf2.

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

Supported API . 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. If the zaxis is 0 then (0,0,1) is used.

product(plist)

Supported API . Product of a sequence of Place transforms.

quaternion_rotation(q, shift=(0, 0, 0))

Supported API .

Return a transform which is a rotation for quaternion (q0, q1, q2, q3) followed by a translation.

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

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

scale(s)

Supported API . Return a transform which is a scale by factor s.

skew_axes(cell_angles)

Supported API . 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.

transform_planes(coord_sys, planes)

Experimental API . Planes are given by 4 vectors v defining plane v0*x + v1*y + v2*z + v3 = 0. Returns planes in new coordinate system.

translation(v)

Supported API . Return a transform which is a shift by vector v.

vector_rotation(u, v)

Supported API . 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.

z_align(pt1, pt2)

Supported API . Return a Place object that puts the pt1->pt2 vector on the Z axis

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.

cross_product(u, v)

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

distance(p, q)

Supported API . Return the distance between two points.

inner_product(u, v)

Supported API . Return the inner product of two vectors.

norm(u)

Supported API . Return the length of a vector.

normalize_vector(v)

Supported API . Return a unit vector in the same direction as v.

normalize_vectors(v)

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

vector_sum(weights, vectors)

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

inner_product_64(u, v) → float64

Experimental API . Return the inner-product of two vectors accumulated as a 64-bit floating point value even if the vector components are 32-bit values. Input arrays are 1-dimensional with any value type.

bounds: Bounding boxes

Compute bounding boxes for objects in scene. The bounds of no object is represented as None rather than a Bounds object.

class Bounds(xyz_min, xyz_max)

Bounding box specified by minimum and maximum x,y,z coordinates.

__init__(xyz_min, xyz_max)

Supported API . Define a bounding box using two corner points.

box_corners()

Supported API . Return a float32 numpy array of the 8 corners of the bounding box.

center()

Supported API . Center of bounding box.

radius()

Supported API . Radius of sphere containing bounding box.

size()

Supported API . Size of box along x,y,z axes. Returns 3 values.

width()

Supported API . Maximum of size of box x,y,z axes.

xyz_max

Supported API . Maximum x,y,z bounds as numpy float32 array.

xyz_min

Supported API . Minimum x,y,z bounds as numpy float32 array.

clip_bounds(b, planes)

Supported API . Clip a bounding box using planes each given as a plane point and normal.

copies_bounding_box(bounds, positions)

Supported API . Return Bounds that covers a specified bounding box replicated at Places.

copy_tree_bounds(bounds, positions_list)

Experimental API . Return Bounds that covers a specified bounding box replicated at a hierarchy of Places.

point_bounds(xyz, placements=None)

Supported API . Return Bounds for a set of points, optionally multiple positions given by a Places instance.

sphere_bounds(centers, radii)

Supported API . Return Bounds containing a set of spheres.

union_bounds(blist)

Supported API . Return Bounds that is the union of a list of Bounds. The list can contain None elements which are ignored. If the list contains no Bounds then None is returned.

Miscellaneous Routines

align_points(xyz, ref_xyz)

Supported API . Computes rotation and translation to align one set of points with another. The sum of the squares of the distances between corresponding positions is minimized.

Parameters:

  • xyz (numpy float n by 3 array)

  • ref_xyz (numpy float n by 3 array)

Returns:

  • place (Place) – transformation taking xyz onto ref_xyz.

  • rms (float) – root mean square (RMS) value calculated from distances between aligned points.

closest_cylinder_intercept(base1, base2, radii, xyz1, xyz2) → f, cnum

Supported API Find first cylinder intercept along line segment from xyz1 to xyz2. Cylinder endcaps are not considered. Implemented in C++.

Parameters:

  • base1 (n by 3 float arrays) – x,y,z cylinder end center coordinates.

  • base2 (n by 3 float arrays) – x,y,z cylinder end center coordinates.

  • radii (float array) – cylinder radii.

  • xyz1 (float 3-tuples) – x,y,z coordinates of line segment endpoints.

  • xyz2 (float 3-tuples) – x,y,z coordinates of line segment endpoints.

Returns:

  • f (float) – fraction of distance from xyz1 to xyz2. None if no intercept.

  • cnum (int) – cylinder number, or None if no intercept.

closest_sphere_intercept(centers, radii, xyz1, xyz2) → f, snum

Supported API Find first sphere intercept along line segment from xyz1 to xyz2. Implemented in C++.

Parameters:

  • centers (n by 3 float array) – x,y,z sphere center coordinates.

  • radii (length n float array) – sphere radii.

  • xyz1 (float 3-tuples) – x,y,z coordinates of line segment endpoints.

  • xyz2 (float 3-tuples) – x,y,z coordinates of line segment endpoints.

Returns:

  • f (float) – fraction of distance from xyz1 to xyz2. None if no intercept.

  • snum (int) – sphere number, or None if no intercept.

closest_triangle_intercept(vertices, tarray, xyz1, xyz2) → f, tnum

Supported API Find first triangle intercept along line segment from xyz1 to xyz2. Implemented in C++.

Parameters:

  • vertices (n by 3 float array) – triangle vertex x,y,z coordinates.

  • triangles (m by 3 int array) – vertex indices specifying 3 vertices for each triangle.

  • xyz1 (float 3-tuples) – x,y,z coordinates of line segment endpoints.

  • xyz2 (float 3-tuples) – x,y,z coordinates of line segment endpoints.

Returns:

  • f (float) – fraction of distance from xyz1 to xyz2. None if no intercept.

  • tnum (int) – triangle number, or None if no intercept.

find_close_points(xyz1, xyz2, max_distance) → i1, i2

Supported API Find close points between two sets of points, returning indices for each point that is close to some point in the other set. It does not report all pairs of close points, only which points have some close neighbor in the other set. The calculation is optimized for specified maximum distance small compared to the extent of the point sets, so that only positions close to a point need to be considered. Implemented in C++.

Parameters:

  • xyz1 (n by 3 float array)

  • xyz2 (m by 3 float array)

  • max_distance (float) – consider only points less than this distance away.

Returns:

i1, i2 – Two arrays of indices into the xyz1 and xyz2 arrays. The index arrays are generally not of the same length.

Return type:

numpy int32 arrays

find_close_points_sets(tp1, tp2, max_distance) → i1, i2

Supported API Find close points between two sets of points, returning indices for each point that is close to some point in the other set. Each set of points is defined by a list of pairs, each pair being an array of points and an affine transform to apply to those points. The calculation is optimized for specified maximum distance small compared to the extent of the point sets, so that only positions close to a point need to be considered. Implemented in C++.

Parameters:

  • tp1 (list of (n by 3 float array, 3 by 4 float array)) – The first array of each pair are x,y,z point coordinates, and the second array is an affine transformation with the first 3 columns being a 3 by 3 matrix to applied (left multiplied) to each point and the last column being a translation (added to the point) applied after the matrix multiplication.

  • tp2 (list of (n by 3 float array, 3 by 4 float array)) – The first array of each pair are x,y,z point coordinates, and the second array is an affine transformation with the first 3 columns being a 3 by 3 matrix to applied (left multiplied) to each point and the last column being a translation (added to the point) applied after the matrix multiplication.

  • max_distance (float) – consider only points less than this distance away.

Returns:

i1, i2 – Two tuples of arrays of indices with lengths matching the lengths of the tp1 and tp2 arguments. Each index array list indices into the corresponding transformed point array for points that have some nearby point in the other set.

Return type:

tuples of numpy int32 arrays

find_closest_points(xyz1, xyz2, max_distance[, scale2]) → i1, i2, near1

Supported API Find close points between two sets of points, returning indices for each point that is close to some point in the other set, and also return the closest point in set 2 for each point in set 1. The calculation is optimized for specified maximum distance small compared to the extent of the point sets, so that only positions close to a point need to be considered. Implemented in C++.

Parameters:

  • xyz1 (n by 3 float array)

  • xyz2 (m by 3 float array)

  • max_distance (float) – consider only points less than this distance away.

  • scale2 (length m float array) – Optional argument giving a distance scale factor for each point in set 2. The scale factor is only used for determining the closest point, and causes the closest scaled distance to be used. This is an obscure feature.

Returns:

  • i1, i2 (numpy int32 array) – Two arrays of indices into the xyz1 and xyz2 arrays respectively for points that are within the maximum distance of some other point in the other array.

  • near1 (numpy int32 array) – A third array is returned that gives the index in xyz2 of the closest point for each xyz1 point in the i1 array. This array has length equal to the length of array i1.

natural_cubic_spline(path, segment_subdivisions) → spath, tangents

Supported API Compute a natural cubic spline through path points in M dimensions, producing a finer set of points and tangent vectors at those points. Implemented in C++.

Parameters:

  • path (N by M float array) – N points in M-dimensions that spline will pass through.

  • segment_subdivisions (int or int array of length n-1) – place this number of additional points between every two consecutive path points. If an array is given each pair of path points can have a different number of subdivisions.

  • tangents (bool) – whether spline path tangents are returned, default true.

Returns:

  • spath (m by M float array) – points on cubic spline including original points and subdivision points.

  • tangents (m by M float array) – tangent vector at point of returned path.