# mni2mz3
[![crates.io](https://img.shields.io/crates/v/mni2mz3?label=version)](https://crates.io/crates/mni2mz3)
[![MIT License](https://img.shields.io/github/license/fnndsc/mni2mz3)](https://github.com/FNNDSC/mni2mz3/blob/main/LICENSE)
[![test](https://github.com/FNNDSC/mni2mz3/actions/workflows/test.yml/badge.svg)](https://github.com/FNNDSC/mni2mz3/actions/workflows/test.yml)
[![codecov](https://codecov.io/gh/FNNDSC/mni2mz3/branch/master/graph/badge.svg?token=1YQRZWW95S)](https://codecov.io/gh/FNNDSC/mni2mz3)
Converts a file from MNI polygonal surface mesh format (`.obj`\*) or
vertex-wise data (e.g. curvature, cortical thickness, `*.txt`)
to [Surf-Ice MZ3 (`.mz3`)](https://github.com/neurolabusc/surf-ice/tree/master/mz3).
Useful for visualizing surfaces using [Surf-Ice](https://github.com/neurolabusc/surf-ice) or [NiiVue](https://github.com/niivue/niivue).
> [!WARNING]
> \*Not to be confused with Wavefront .obj, which is a different spec but with the same file extension.
## Installation
There are many ways to install and use `mni2mz3`. Linux, Mac, and Windows are supported.
### Using _ChRIS_
The easiest way to run `mni2mz3` is on [_ChRIS_](https://chrisproject.org), no installation needed.
Simply upload your data to a feed in https://app.chrisproject.org, then run `pl-mni2common`.
### Using Apptainer
`pl-mni2common` is a _ChRIS_ plugin wrapper for `mni2mz3`, which means you can
use its container image to run `mni2mz3`.
```shell
apptainer run docker://ghcr.io/fnndsc/pl-mni2common:latest mni2mz3 input.obj output.mz3
```
Call the wrapper script `mni2mz3` instead to do bulk processing on an input directory.
```shell
apptainer run docker://ghcr.io/fnndsc/pl-mni2common:latest mni2mz3 inputdir/ outputdir/
```
### Using [cargo-binstall](https://github.com/cargo-bins/cargo-binstall)
```shell
cargo binstall mni2mz3
```
### Using pip
```shell
pip install mni2mz3
```
### Manual Download
Select and download the right binary for your architecture and OS from GitHub Releases:
https://github.com/FNNDSC/mni2mz3/releases/latest
### Compile From Source
Install [Rust](https://rustup.rs), then run
```shell
cargo install mni2mz3
```
## Usage
```shell
# convert mesh
mni2mz3 surface_81920.obj surface.mz3
# convert data
mni2mz3 thickness.txt thickness.mz3
```
To do bulk conversions, use the [_ChRIS_ plugin wrapper](#using-chris).
## Details
- Output file will be gzip compressed.
- For surfaces, only triangle meshes are supported.
- For data, only 32-bit single-precision "float" is supported.
## Testing
It is recommended to install [cargo-nextest](https://nexte.st/).
```shell
cargo nextest run
```