stl2mask

Convert segmentations in mesh format (e.g. STL, OBJ) to binary masks in image format (e.g. NIfTI, MHA).

Installation

stl2mask is intended to be used as a standalone command-line tool.

Install with pipx:

pipx install stl2mask

Or with uv:

uv tool install stl2mask

If you are not familiar with uv, read this guide to get started.

Usage

stl2mask

Convert STL mesh files to binary mask images. A reference image is required to define the output image space. Based on this reference image, a distance volume is created from the mesh, and a binary mask is generated by thresholding the distance volume.

stl2mask path/to/mesh.stl path/to/image.nii.gz

Parameters:

• -o, --output: Path to the output mask image file. If not provided, the output file will be saved in the current directory with the same name as the input mesh file but with a .nii.gz extension.
• -s, --suffix: Suffix for the output file if --output is not provided. Default is .nii.gz.
• -t, --threshold: Threshold value for converting the mesh to a binary mask. Default is 0.0.
• -f, --offset: Offset to apply to the origin of the distance volume, in terms of voxel spacing. This can help with alignment issues. Default is 0.5.
• -m, --mask-value: Value to assign to the mask voxels inside the mesh. Default is 255.
• -l, --log-level: Set the logging level. Options are DEBUG, INFO, WARNING, or ERROR. Default is INFO.

mask2stl

Convert binary mask images to STL mesh files. The binary mask is converted to a mesh using the Marching Cubes algorithm. Optionally, a reference image can be provided to define the output mesh space. This is not required if the mask image already has the correct spacing, origin, and direction.

mask2stl path/to/mask.nii.gz

Parameters:

• -i, --image: Path to a reference image file to define the output mesh space.
• -o, --output: Path to the output mesh file. If not provided, the output file will be saved in the current directory with the same name as the input mask file but with a .stl extension.
• -s, --suffix: Suffix for the output file if --output is not provided. Default is .stl.
• -v, --iso-value: Iso-value for the Marching Cubes algorithm. Defaults to the midpoint between the minimum and maximum values in the mask image.
• -f, --fill-holes: Whether to fill holes in the binary mask before converting to a mesh. Default is False.
• -l, --log-level: Set the logging level. Options are DEBUG, INFO, WARNING, or ERROR. Default is INFO.

Examples

Converting a mesh to a mask

Basic conversion with default parameters:

stl2mask tumor.stl reference_image.nii.gz

Specify custom output location and mask value:

stl2mask tumor.stl reference_image.nii.gz -o output/tumor_mask.nii.gz -m 1

Adjust threshold for better mesh alignment:

stl2mask tumor.stl reference_image.nii.gz -t 0.5 -f 0.25

Converting a mask to a mesh

Basic conversion:

mask2stl tumor_mask.nii.gz

With a reference image for coordinate system transformation:

mask2stl tumor_mask.nii.gz -i reference_image.nii.gz -o tumor.stl

Troubleshooting

For detailed debugging information, use the --log-level DEBUG option:

stl2mask mesh.stl image.nii.gz --log-level DEBUG

This will show detailed information about image dimensions, spacing, and processing steps.