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

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




