stl2mask 0.1.0
Convert STL segmentations to binary masks.
Requires Python: <3.14,>=3.10

# `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`:

```bash
pipx install stl2mask
```

Or with `uv`:

```bash
uv tool install stl2mask
```

## 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.

```bash
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.

```bash
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.
- `-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:

```bash
stl2mask tumor.stl reference_image.nii.gz
```

Specify custom output location and mask value:

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

Adjust threshold for better mesh alignment:

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

### Converting a mask to a mesh

Basic conversion:

```bash
mask2stl tumor_mask.nii.gz
```

With a reference image for coordinate system transformation:

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

## Troubleshooting

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

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

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