surface: Triangulated surface calculations

Routines for calculating surface triangulations and properties of triangulated surfaces.

Surfaces are represented using numpy arrays of vertices (N by 3 array, xyz coodinates, float32), and a numpy array of triangles which are triples of indices into the vertex list (M by 3 array, vertex indices, int32). For surface lighting, normal vectors at each vertex are used (N by 3 array, unit vectors, float32). The vertex, triangle and normal arrays are sometimes called varray, tarray, narray, and sometimes vertices, triangles, normals.

spheres_surface_area(centers, radii, npoints=1000)

Experimental API . Return the exposed surface area of a set of possibly intersecting set of spheres. An array giving the exposed area for each input sphere is returned. The area is computed by an exact method except for round-off errors. The calculation can fail in rare cases where 4 spheres intersect at a point and area values of -1 are returned for spheres where the calculation fails. TODO: The code also computes the areas using numerical approximation, and the results compared with the maximum and average discrepancy printed for debugging. This code is not needed except for debugging.

box_geometry(llb, urf)

Experimental API . Return vertex, normal vector and triangle arrays for box with corners llb and urf (lower-left-back, upper-right-front)

cone_geometry(radius=1, height=1, nc=20, caps=True, points_up=True)

Experimental API . Return vertex, normal vector and triangle arrays for cone geometry with specified radius and height with middle of cone at origin

cylinder_geometry(radius=1, height=1, nz=2, nc=10, caps=True, hexagonal_lattice=False)

Experimental API . Return vertex, normal vector and triangle arrays for cylinder geometry with specified radius and height centered at the origin.

dashed_cylinder_geometry(segments=5, radius=1, height=1, nz=2, nc=10, caps=True)

Experimental API . Return vertex, normal vector and triangle arrays for a sequence of colinear cylinders.

octahedron_geometry()

Experimental API . Return vertex, normal vector and triangle arrays for a radius 1 octahedron.

sphere_geometry(ntri)

Experimental API . Return vertex, normal vector and triangle arrays for unit sphere geometry. Only produces 20, 80, 320, … (multiples of 4) triangle count.

sphere_geometry2(ntri)

Experimental API . Return vertex, normal vector and triangle arrays for unit sphere geometry. Alternate techinque that produces any even number of triangles >= 4. Use in place of sphere_geometry() in new code.

tetrahedron_geometry()

Experimental API . Return vertex, normal vector and triangle arrays for a radius 1 tetrahedron.

enclosed_volume(varray, tarray)

Experimental API . Return the enclosed volume of a surface triangulation specified by vertex and triangle arrays. Also returns the number of holes in the surface, defined as the number of boundary curves.

surface_area(varray, tarray)

Experimental API . Return the surface area of a triangulation specified by vertex and triangle arrays.

surface_volume_and_area(model)

Experimental API . Return the surface area, enclosed volume and number of holes (i.e. boundary curves) of surface triangulations specified by vertex and triangle arrays. All triangles are used even if the surface is masked or clipped. All child models are included. Only Surface models are included.

ses_surface_geometry(xyz, radii, probe_radius=1.4, grid_spacing=0.5, sas=False)

Experimental API . Calculate a solvent excluded molecular surface using a distance grid contouring method. Vertex, normal and triangle arrays are returned. If sas is true then the solvent accessible surface is returned instead.

boundary_edge_mask(triangles)

Experimental API . Returns mask values bits 0,1,2 are set if triangle edges 01, 12, 20 are on boundary. Implemented in C++.

Returns:

edge_mask

Return type:

1d array of uint8, same length as triangle array

boundary_edges(triangles)

Experimental API . Returns N by 2 array of vertex indices for directed edges. Implemented in C++.

Returns:

vertex_pairs : N x 2 array of int

boundary_loops(triangles)

Experimental API . Returns tuple of arrays of vertex indices, one array for each loop. Implemented in C++.

Returns:

loops

Return type:

tuple of 1d arrays of int

boundary_loops(triangles)

Experimental API . Returns tuple of arrays of vertex indices, one array for each loop. Implemented in C++.

Returns:

loops

Return type:

tuple of 1d arrays of int

calculate_vertex_normals(vertices, triangles)

Experimental API . Calculate vertex normals by adding normals for each triangle that uses a vertex, and then normalizing the sum. Implemented in C++.

compute_cap(plane_normal, plane_offset, varray, tarray)

Experimental API . Compute the portion of a plane inside a given surface. Implemented in C++.

Returns:

  • cap_vertices (n by 3 array of float)

  • cap_triangles (m by 3 array of int)

connected_pieces(triangles)

Experimental API . Return each connected piece of a surface as a separate triangle array and vertex array. The return value is a tuple of pairs of vertex and triangle index arrays. Vertices connected by any sequence of triangle edges are considered connected. Implemented in C++.

connected_triangles(triangles, tindex)

Experimental API . Return sorted array of triangle indices of triangles connected to the specified triangle. Two triangles are connected if they share a vertex. The surface must be oriented and at most two triangles can share an edge. The triangle array is triples of indices of vertices (m by 3, Numpy int32). Implemented in C++.

Returns:

triangles : 1d array of int

enclosed_volume(vertices, triangles)

Experimental API . If surface has hole then returned volume is computed by capping boundary loops with fans centered at geometric center of loops. Returns volume and hole count. Implemented in C++.

Returns:

  • volume (float)

  • hole_count (int)

estimate_surface_area_of_spheres(centers, radii, sphere_points, point_weights, areas)

Experimental API . Use points on sphere, count how many are inside other spheres to estimate surface area of union of solid spheres. Third argument areas contains areas contributed by each sphere Implemented in C++.

invert_vertex_normals(normals, triangles)

Experimental API . Flip normals and reverse triangle vertex order. Implemented in C++.

refine_mesh(vertices, triangles, subdivision_factor)

Experimental API . Modify a planar surface triangulation to create uniform size triangles suited for vertex coloring. Implemented in C++.

Returns:

  • ref_vertices (n by 3 array of float)

  • ref_triangles (n by 3 array of int)

sharp_edge_patches(vertices, normals, triangles, vertex_to_atom_index_map, atom_positions, atom_radii)

Experimental API . Split triangles to create sharp boundaries equidistant between atoms. Equidistant means an equal number of atom radii away. Implemented in C++.

Returns:

  • vertices (n by 3 array of float)

  • normals (n by 3 array of float)

  • triangles (m by 3 array of int)

  • vertex_to_atom_index_map (1d array of int)

smooth_vertex_positions(vertices, triangles, smoothing_factor, smoothing_iterations)

Experimental API . Move surface vertices towards the average of neighboring vertices to give the surface a smoother appearance. Modifies vertices numpy array. Implemented in C++.

subdivide_mesh(vertices, triangles, normals, edge_length)

Experimental API . Divide triangle into smaller triangles so that edges are shorter than the specified the maximum edge length. Implemented in C++.

Returns:

  • vertices (n by 3 array of float)

  • triangles (m by 3 array of int)

  • normals (n by 3 array of float)

subdivide_triangles(vertices, triangles, normals)

Experimental API . Divide each triangle into 4 triangles placing new vertices at edge midpoints. Implemented in C++.

Returns:

  • vertices (n by 3 array of float)

  • triangles (m by 3 array of int)

  • normals (n by 3 array of float)

surface_area(vertices, triangles)

Experimental API . Sum of triangle areas. Implemented in C++.

Returns:

area

Return type:

float

surface_area_of_spheres(centers, radii, areas)

Experimental API . Compute surface area of union of solid sphere. Third argument areas contains areas contributed by each sphere Can fail in degenerate cases giving area -1 for spheres with failed area calculation. Implemented in C++.

triangle_vertices(triangles, tindices)

Experimental API . Return an array of vertex indices used the specified subset of triangles.

Returns:

vertex_indices

Return type:

1d array of int

triangulate_polygon(loops, normal, vertices)

Experimental API . Triangulate a set of loops in a plane.” Implemented in C++.

Returns:

triangles

Return type:

m by 3 array of int

tube_geometry(path, tangents, cross_section, cross_section_normals)

Experimental API . Calculates tube surface geometry from a center-line path. Arguments path and tangents are n by 3 float arrays, and the cross section arguments are m by 3 arrays. Implemented in C++.

Returns:

  • vertices (n by 3 array of float)

  • normals (n by 3 array of float)

  • triangles (m by 3 array of int)

tube_geometry_colors(colors, segment_subdivisions, circle_subdivisions, start_divisions, end_divisions)

Experimental API . Computes vertex colors for a tube with geometry determined by tube_geometry() Each segment can have a separate color. Colors argument is N by 4 array. A segment is is the interval between segment_subdivisions+1 path points not including points at ends of the path specified by start/end divisions. Arguments other than colors are integers. Implemented in C++.

Returns:

colors

Return type:

N by 4 array of uint8

tube_triangle_mask(segment_mask, segment_subdivisions, circle_subdivisions, start_divisions, end_divisions)

Experimental API . Computes triangle mask to show only specified segments of a tube generated with tube_geometry(). Segments are defined in the same way as for the tube_geometry_colors() routine. The input segment mask is a uint8 length N array, and output is a uint8 numpy array with length equal to number of triangles generated by tube_geometry(). Implemented in C++.

Returns:

triangle_mask

Return type:

1d array of uint8

unique_vertex_map(vertices)

Experimental API . Map vertex indices to unique vertex indices so vertices at the same point are treated as one. This is used for connected piece calculations. Implemented in C++.

Returns:

vertex_map

Return type:

1d array of int, maps vertex index to unique vertex index.

vertex_areas(vertices, triangles, areas)

Experimental API . Accumulate 1/3 triangle area to each vertex. Third parameter areas is a float array for returning vertex area values. Implemented in C++.

vertex_convexity(vertices, triangles, smoothing_iterations, convexity)

Experimental API . Compute convexity values for each vertex and save in the convexity array. Convexity is defined as 2*pi - (vertex cone angle). The surface should be closed so the triangles around each vertex define a cone. Optional smoothing_iterations averages each vertex convexity value with neighbor vertices connected by edges for the specified number of iterations. The vertex array is triples of float values (n by 3, numpy float32). The triangle array is triples of indices of vertices (m by 3, Numpy int32). Implemented in C++.

class Redust(surface, metric, limit)

Bases: State

classmethod restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

largest_blobs_triangle_mask(vertices, triangles, triangle_mask, blob_count=1, rank_metric='size rank')

Experimental API . Return a triangle mask which includes the N largest connected surface components using a specified metric “size rank”, “area rank”, or “volume rank”. Size rank measures maximum extent along x, y and z axes.

gaussian_surface(xyz, weights, resolution, level=None, grid_spacing=None)

Experimental API . Return vertex, normal vector and triangles for a contour surface computed from a density map created as a sum of Gaussians at specified center positions with specified heights, and Gaussian width determined by resolution. If the contour level is None then compute the lowest density value at the center point positions. Return the input level or this computed level as a fourth return value.