porespy.io.to_stl

porespy.io.to_stl(im, filename=None, voxel_size=1, method='direct', fmt='openstl', remove_duplicates=False, tol=None, close_faces=True)

Converts an voxel image to an STL mesh in a variety of formats

Parameters:

• im (3D image) – The image of the porous material

• voxel_size (float) – The side length of the voxels (voxels are cubic)

• method (str) –

  Can be one of the options listed below:

  method	Description
  ’direct’	Converts each exposed face of each voxel into 2 triangles to generate a mesh that maps directly to the voxel image.
  ’marching-cubes’	Uses the marching cubes method in scikit-image to generate a mesh. The result is naturally smoother than the ‘direct’ approach, but this is due to last information.

• fmt (str) –

  The format of the returned mesh. Options are:

  • ’openstl’ or ‘triangles’ (default)

  • ’skimage’ or ‘vfn’ (as in verts, faces, vertex normals)

  • ’pyvista’ (installed with PoreSpy)

  • ’trimesh’ (not automatically installed with PoreSpy)

  • ’open3d’ (not automatically installed with PoreSpy)

  • ’numpy-stl’ (not automatically installed with PoreSpy)

  • ’meshio’ (not automatically installed with PoreSpy)

• close_faces (bool, optional) – If True (default), cap the selected phase where it meets the image boundary. If False, return only interfaces between True and False regions inside the image, treating the exterior as unknown. Uniform images return an empty mesh in open mode.

Notes

With close_faces=False, interfaces that reach the crop boundary remain open. Such meshes may not be watertight, so volume calculations require additional assumptions. Downstream smoothing may need to pin boundary vertices to prevent the interface from retracting.

Coordinates follow the image axis order and are scaled by voxel_size. The direct method places voxel corners at integer coordinates, spanning 0 to im.shape before scaling. Marching cubes retains the historical padding offset: original voxel samples are at coordinates 1 through im.shape. In open mode it extracts only within that sampling domain, so its boundary lies half a voxel inward from the closed caps. The flag does not translate internal geometry. The methods have different discretizations and need not give the same interfacial area. Open marching cubes returns an empty mesh when any axis has fewer than two samples, since there are no three-dimensional sampling cells.

The openstl package has the fastest read/write performance. It uses a basic numpy array of shape [N, 4, 3]. N is the number of triangles, 4 refers to norms, vert1, vert2, vert3, where norms and vert<i> are each 3 components long. Nn ‘stl’ file saved using openstl can be opened by most other packages, which convert it to a usable mesh. For example mesh = pyvista.read(‘openstl-formatted-file.stl’) will create mesh that can be plotted with pyvista.plot(mesh, eye_dome_lighting=True).

Examples

Click here to view online example.