diff --git a/README.md b/README.md index f60cc6f..ea7869a 100644 --- a/README.md +++ b/README.md @@ -5,12 +5,19 @@ [![ci](https://github.com/FNNDSC/pl-bestsurfreg-surface-resample/actions/workflows/ci.yml/badge.svg)](https://github.com/FNNDSC/pl-bestsurfreg-surface-resample/actions/workflows/ci.yml) `pl-bestsurfreg-surface-resample` is a [_ChRIS_](https://chrisproject.org/) -_ds_ plugin which takes in ... as input files and -creates ... as output files. +_ds_ plugin which does surface registration using MNI/CIVET tools. +The inputs are MNI `.obj` surfaces of either the left or right brain hemisphere. +For each surface, the registered vertex-wise data is produced as a `.txt` file, +as well as the intermediate `.sm` registration map file. -## Abstract +In its default configuration, it uses the average 29 gestational age +fetal brain template of the [Im Lab](https://research.childrenshospital.org/neuroim/) +to register a mask of the medial cut. -... +![before](img/before.png) +![after](img/after.png) + +Figure: (Left) mask does not cover medial cut. (Right) mask is registered to cover the medial cut. ## Installation @@ -25,85 +32,11 @@ To get started with local command-line usage, use [Apptainer](https://apptainer. (a.k.a. Singularity) to run `pl-bestsurfreg-surface-resample` as a container: ```shell -apptainer exec docker://fnndsc/pl-bestsurfreg-surface-resample bsr2 [--args values...] input/ output/ +apptainer exec docker://fnndsc/pl-bestsurfreg-surface-resample bsrr [--args values...] input/ output/ ``` To print its available options, run: ```shell -apptainer exec docker://fnndsc/pl-bestsurfreg-surface-resample bsr2 --help -``` - -## Examples - -`bsr2` requires two positional arguments: a directory containing -input data, and a directory where to create output data. -First, create the input directory and move input data into it. - -```shell -mkdir incoming/ outgoing/ -mv some.dat other.dat incoming/ -apptainer exec docker://fnndsc/pl-bestsurfreg-surface-resample:latest bsr2 [--args] incoming/ outgoing/ -``` - -## Development - -Instructions for developers. - -### Building - -Build a local container image: - -```shell -docker build -t localhost/fnndsc/pl-bestsurfreg-surface-resample . -``` - -### Running - -Mount the source code `bsr2.py` into a container to try out changes without rebuild. - -```shell -docker run --rm -it --userns=host -u $(id -u):$(id -g) \ - -v $PWD/bsr2.py:/usr/local/lib/python3.11/site-packages/bsr2.py:ro \ - -v $PWD/in:/incoming:ro -v $PWD/out:/outgoing:rw -w /outgoing \ - localhost/fnndsc/pl-bestsurfreg-surface-resample bsr2 /incoming /outgoing -``` - -### Testing - -Run unit tests using `pytest`. -It's recommended to rebuild the image to ensure that sources are up-to-date. -Use the option `--build-arg extras_require=dev` to install extra dependencies for testing. - -```shell -docker build -t localhost/fnndsc/pl-bestsurfreg-surface-resample:dev --build-arg extras_require=dev . -docker run --rm -it localhost/fnndsc/pl-bestsurfreg-surface-resample:dev pytest +apptainer exec docker://fnndsc/pl-bestsurfreg-surface-resample bsrr --help ``` - -## Release - -Steps for release can be automated by [Github Actions](.github/workflows/ci.yml). -This section is about how to do those steps manually. - -### Increase Version Number - -Increase the version number in `setup.py` and commit this file. - -### Push Container Image - -Build and push an image tagged by the version. For example, for version `1.2.3`: - -``` -docker build -t docker.io/fnndsc/pl-bestsurfreg-surface-resample:1.2.3 . -docker push docker.io/fnndsc/pl-bestsurfreg-surface-resample:1.2.3 -``` - -### Get JSON Representation - -Run [`chris_plugin_info`](https://github.com/FNNDSC/chris_plugin#usage) -to produce a JSON description of this plugin, which can be uploaded to a _ChRIS Store_. - -```shell -docker run --rm localhost/fnndsc/pl-bestsurfreg-surface-resample:dev chris_plugin_info > chris_plugin_info.json -``` - diff --git a/img/after.png b/img/after.png new file mode 100644 index 0000000..1f1bd9d Binary files /dev/null and b/img/after.png differ diff --git a/img/before.png b/img/before.png new file mode 100644 index 0000000..5fb61d7 Binary files /dev/null and b/img/before.png differ