User Interface

PyTessel uses two functions for the construction of isosurfaces:

  • marching_cubes

  • write_ply

Isosurface generation

PyTessel.marching_cubes(self, vector[float] grid, vector[unsigned int] dimensions, vector[float] unitcell, float isovalue) -> (npt.NDArray[np.float64], npt.NDArray[np.float64], npt.NDArray[np.float64])

Perform marching cubes algorithm to generate isosurface

Parameters

gridIterable of floats

Scalar field as a flattened array

dimensionsIterable of ints

Dimensions of the scalar field grid (nx, ny, nz)

unitcellIterable of floats

Unitcell matrix (flattened)

isovaluefloat

Isovalue of the isosurface

Returns

vertices(Nx3) numpy array of floats

Triangle vertices

normals(Nx3) numpy array of floats

Triangle normals (at the vertices)

indicesnumpy array of ints

Triangle indices

Notes

  • The scalar field needs to be encoded such that the z-coordinate is the slowest moving index and the x-coordinate the fastest moving index.

  • The dimensions of the scalar field are encoded in the order (nx, ny, nz).

  • You can use reversed(grid.shape) to pass the dimensions.

  • The output of the marching_cubes function are three arrays, corresponding to the vertices, the normals, and the indices of the isosurface. The isosurface corresponds to a number of linked triangles (polygons) whose vertices are stored in the vertices array. For each vertex, the normal vector is encoded in the normals array. Finally, the triangles are stored as a triplet of indices in the indices array. These indices refer to the position in the vertices and normals array. Because multiple triangles can use the same vertices, this is an efficient way to store the isosurface.

  • One rarely needs to perform any operations on the vertices, normals and indices arrays. Typically, these arrays are constructed and immediately relayed to the write_ply function to store them as a file which can be used in another program.

Storing the isosurface

PyTessel.write_ply(self, unicode filename: str, vertices: npt.NDArray[np.float64], normals: npt.NDArray[np.float64], indices: npt.NDArray[np.uint32]) → None

Stores isosurface as .ply file

Parameters

filenamestr

Path to file

verticesIterable of floats

Array of vertices

normalsIterable of floats

Array of normals

indicesIterable of ints

Array of triangle indices

Returns

None

Notes

  • This function is designed to be used with marching_cubes. One can directly relay the output of marching_cube as the input for write_ply.