faceoff-mri 1.9.8__tar.gz

faceoff_mri-1.9.8/.dockerignore

@@ -0,0 +1,11 @@
+# Allowlist: only what the build needs. testdata/ holds a real scan with a face and must never
+# end up in an image.
+*
+!pyproject.toml
+!uv.lock
+!README.md
+!LICENCE
+!bundle_template.py
+!faceoff
+!licences
+**/__pycache__

faceoff_mri-1.9.8/.github/workflows/ci.yml

@@ -0,0 +1,130 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  # Only pull requests are cancelled by a newer push; a run on master may be tagging a release.
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  quality:
+    name: Quality checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Check formatting
+        run: uv run ruff format --check
+
+      - name: Lint
+        run: uv run ruff check
+
+      - name: Type-check
+        run: uv run mypy .
+
+  test:
+    name: Test Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked --python ${{ matrix.python }}
+
+      - name: Test
+        run: uv run --python ${{ matrix.python }} pytest
+
+  package:
+    name: Build and check the package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+
+      # The wheel build downloads the five template files from Zenodo and bundles them.
+      - name: Build
+        run: uv build --no-sources --out-dir dist
+
+      - name: Check what is inside
+        run: python3 scripts/check_dist.py dist
+
+      - name: Install the wheel in a clean environment and run it
+        run: |
+          uv venv --python 3.13 "$RUNNER_TEMP/clean"
+          uv pip install --python "$RUNNER_TEMP/clean/bin/python" dist/*.whl
+          cd "$RUNNER_TEMP"
+          clean/bin/faceoff --version
+          clean/bin/python - <<'PY'
+          from faceoff.template import Template
+          from faceoff.template_files import is_complete
+
+          folder = Template.default().folder
+          assert "site-packages" in str(folder), folder
+          assert is_complete(folder), folder
+          PY
+
+  tag-release:
+    name: Tag a version bump
+    # A new version in pyproject.toml, merged to master and green, is released: the tag starts
+    # the image, the GitHub release (which Zenodo archives) and PyPI.
+    needs: [quality, test, package]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      actions: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Tag and start the release workflows if pyproject.toml's version is new
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          tag="v${version}"
+          if git rev-parse -q --verify "refs/tags/${tag}" >/dev/null; then
+            echo "Tag ${tag} already exists; nothing to do."
+            exit 0
+          fi
+          # A version below an existing tag is a mistake (a revert, a typo), not a release.
+          latest="$(git tag --list 'v*' | sort -V | tail -n 1)"
+          if [[ -n "${latest}" && "$(printf '%s\n%s\n' "${latest}" "${tag}" | sort -V | tail -n 1)" != "${tag}" ]]; then
+            echo "Version ${version} is lower than the existing tag ${latest}; not tagging." >&2
+            exit 1
+          fi
+          git tag "${tag}"
+          git push origin "${tag}"
+          # A tag pushed with the default token does not start other workflows'
+          # `on: push: tags` (GitHub's safeguard against loops), so start them explicitly.
+          gh workflow run release.yml --ref "${tag}"
+          gh workflow run container.yml --ref "${tag}"

faceoff_mri-1.9.8/.github/workflows/container.yml

@@ -0,0 +1,94 @@
+name: Container image
+
+on:
+  push:
+    tags: ["v*"]
+  pull_request:
+    paths:
+      - Dockerfile
+      - .dockerignore
+      - pyproject.toml
+      - uv.lock
+      - licences/**
+      - faceoff/**
+      - bundle_template.py
+      - .github/workflows/container.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  # Lower case is required by GHCR, so this is not built from github.repository.
+  IMAGE: ghcr.io/srikash/faceoff
+
+jobs:
+  docker:
+    name: Build, check and push the Docker image
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Work out the version and check a tag matches pyproject.toml
+        id: version
+        run: |
+          version="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          if [[ "${GITHUB_REF_TYPE}" == "tag" && "${GITHUB_REF_NAME#v}" != "${version}" ]]; then
+            echo "Tag ${GITHUB_REF_NAME} does not match version ${version} in pyproject.toml." >&2
+            exit 1
+          fi
+          echo "version=${version}" >> "${GITHUB_OUTPUT}"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      # The build downloads the template files from Zenodo, as the release build does.
+      - name: Build (not pushed yet)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64
+          load: true
+          tags: faceoff:check
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Check the image
+        run: |
+          docker run --rm faceoff:check --version | grep -F "${{ steps.version.outputs.version }}"
+          docker run --rm --entrypoint python faceoff:check -c '
+          from faceoff.template import Template
+          from faceoff.template_files import is_complete
+          folder = Template.default().folder
+          assert "site-packages" in str(folder) and is_complete(folder), folder'
+          scans="$(docker run --rm --entrypoint sh faceoff:check -c "find / -xdev \( -name '*.nii' -o -name '*.nii.gz' \) -not -path '*/nibabel/tests/*'" | wc -l)"
+          test "${scans}" -eq 5 || { echo "Expected only the 5 template files, found ${scans} images." >&2; exit 1; }
+          docker run --rm --entrypoint antsRegistration faceoff:check --version | grep -F "ANTs Version"
+          # Every ANTs tool FaceOff runs is there and finds all its libraries.
+          docker run --rm --entrypoint sh faceoff:check -c '
+          for t in antsAI antsRegistration antsApplyTransforms ConvertTransformFile; do
+            path="$(command -v "$t")" || { echo "$t is missing" >&2; exit 1; }
+            if ldd "$path" | grep -q "not found"; then echo "$t is missing a library" >&2; exit 1; fi
+          done'
+
+      - name: Log in to GHCR
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Push the image that was just checked, not a second build of it.
+      - name: Push
+        if: github.ref_type == 'tag'
+        run: |
+          for tag in "${{ steps.version.outputs.version }}" latest; do
+            docker tag faceoff:check "${IMAGE}:${tag}"
+            docker push "${IMAGE}:${tag}"
+          done

faceoff_mri-1.9.8/.github/workflows/release.yml

@@ -0,0 +1,108 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build the package
+    runs-on: ubuntu-latest
+    outputs:
+      name: ${{ steps.meta.outputs.name }}
+      version: ${{ steps.meta.outputs.version }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+
+      - name: Read the name and version, and check a tag matches pyproject.toml
+        id: meta
+        run: |
+          read -r name version < <(python3 -c 'import tomllib; p = tomllib.load(open("pyproject.toml", "rb"))["project"]; print(p["name"], p["version"])')
+          if [[ "${GITHUB_REF_TYPE}" == "tag" && "${GITHUB_REF_NAME#v}" != "${version}" ]]; then
+            echo "Tag ${GITHUB_REF_NAME} does not match version ${version} in pyproject.toml." >&2
+            exit 1
+          fi
+          echo "name=${name}" >> "${GITHUB_OUTPUT}"
+          echo "version=${version}" >> "${GITHUB_OUTPUT}"
+
+      - name: Test
+        run: uv run --locked pytest
+
+      # The wheel build downloads the five template files from Zenodo and bundles them.
+      - name: Build
+        run: uv build --no-sources --out-dir dist
+
+      - name: Check what is inside
+        run: python3 scripts/check_dist.py dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  github-release:
+    name: Create the GitHub release
+    # The release is what Zenodo archives.
+    if: github.ref_type == 'tag'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create the release if it does not exist yet
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh release view "${GITHUB_REF_NAME}" --repo "${GITHUB_REPOSITORY}" >/dev/null 2>&1; then
+            echo "Release ${GITHUB_REF_NAME} already exists; nothing to do."
+          else
+            gh release create "${GITHUB_REF_NAME}" dist/* \
+              --repo "${GITHUB_REPOSITORY}" --verify-tag --generate-notes \
+              --title "FaceOff ${GITHUB_REF_NAME#v}"
+          fi
+
+  pypi:
+    name: Publish to PyPI
+    # Needs the trusted publisher and the pypi environment (docs/development.md).
+    if: github.ref_type == 'tag'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Skip if this version is already on PyPI
+        id: check
+        run: |
+          status="$(curl --silent --output /dev/null --write-out '%{http_code}' \
+            "https://pypi.org/pypi/${{ needs.build.outputs.name }}/${{ needs.build.outputs.version }}/json")"
+          case "${status}" in
+            200) echo "Already on PyPI; skipping."; echo "skip=true" >> "${GITHUB_OUTPUT}" ;;
+            404) echo "skip=false" >> "${GITHUB_OUTPUT}" ;;
+            *) echo "Unexpected PyPI answer ${status}." >&2; exit 1 ;;
+          esac
+
+      - name: Publish
+        if: steps.check.outputs.skip != 'true'
+        run: uv publish dist/*

faceoff_mri-1.9.8/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+faceoff/data/
+dist/
+tempData/
+testdata/
+HANDOFF.md
+registration_review/
+*.sif
+.venv/

faceoff_mri-1.9.8/CITATION.cff

@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: Kashyap
+    given-names: Sriranga
+    orcid: https://orcid.org/0000-0003-0307-9773
+title: "FaceOff"
+version: 1.9.8
+date-released: 2026-11-07
+license: MIT
+repository-code: https://github.com/srikash/FaceOff

faceoff_mri-1.9.8/Dockerfile

@@ -0,0 +1,57 @@
+# syntax=docker/dockerfile:1
+#
+# FaceOff with ANTs inside: run it on a folder of scans without installing anything else.
+#
+#   docker run --rm --init --user "$(id -u):$(id -g)" -v "$PWD":/data ghcr.io/srikash/faceoff -i scan.nii.gz
+#
+# The image is amd64 only, because the ANTs image it takes ANTs from is.
+
+# Keep in step with ANTS_IMAGE in faceoff/ants.py (a test checks this).
+ARG ANTS_IMAGE=antsx/ants:2.6.5
+
+FROM ghcr.io/astral-sh/uv:0.12.10 AS uv
+
+# Take only what FaceOff runs from the ANTs image: the four tools and the libraries they load
+# (about 130 MB of the 340 MB in /opt/ants).
+FROM ${ANTS_IMAGE} AS ants
+RUN set -eu; \
+    mkdir -p /ants/bin /ants/lib; \
+    for tool in antsAI antsRegistration antsApplyTransforms ConvertTransformFile; do \
+        cp "/opt/ants/bin/${tool}" /ants/bin/; \
+        ldd "/opt/ants/bin/${tool}" | awk '/=> \/opt\/ants/ {print $3}' >> /tmp/libs.txt; \
+    done; \
+    test -s /tmp/libs.txt; \
+    sort -u /tmp/libs.txt | xargs -I{} cp -L {} /ants/lib/; \
+    test "$(ls /ants/lib | wc -l)" -gt 20
+
+FROM python:3.13-slim-bookworm AS builder
+COPY --from=uv /uv /uvx /bin/
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_PYTHON_DOWNLOADS=never \
+    UV_PROJECT_ENVIRONMENT=/opt/venv
+WORKDIR /src
+COPY pyproject.toml uv.lock ./
+RUN uv sync --locked --no-dev --no-install-project
+# A normal (not editable) install builds the wheel, which downloads the five template files
+# from Zenodo and bundles them, so the image needs no download when it runs.
+COPY README.md LICENCE bundle_template.py ./
+COPY faceoff ./faceoff
+RUN uv sync --locked --no-dev --no-editable
+
+# Same Debian release as the ANTs image, so its libraries match.
+FROM python:3.13-slim-bookworm
+LABEL org.opencontainers.image.title="FaceOff" \
+      org.opencontainers.image.description="Deface MRI scans with ANTs and a modified MNI152 template" \
+      org.opencontainers.image.source="https://github.com/srikash/FaceOff" \
+      org.opencontainers.image.licenses="MIT AND Apache-2.0"
+COPY --from=ants /ants /opt/ants
+COPY licences /usr/share/doc/faceoff/licences
+COPY --from=builder /opt/venv /opt/venv
+COPY --from=builder /src/faceoff/COPYING-MNI /usr/share/doc/faceoff/licences/MNI-COPYING.txt
+# The copied libraries are all ITK's and ANTs' own (libitk*-5.4), none named like a system
+# library, so putting their folder on the library path cannot shadow Python's.
+ENV PATH="/opt/venv/bin:/opt/ants/bin:${PATH}" \
+    LD_LIBRARY_PATH=/opt/ants/lib
+WORKDIR /data
+ENTRYPOINT ["faceoff"]

faceoff_mri-1.9.8/GLOSSARY.md

@@ -0,0 +1,20 @@
+# Glossary
+
+The words FaceOff's code and documentation use, and what they mean.
+
+- **Deface mask** (`_defaceMask`): 1 where the scan is kept, 0 where it was removed (the face, and the eyes with `--enucleate` or `--renucleate`).
+- **Face mask**: the template's mask of the face, 1 over the region to remove. It is moved onto each scan by the registration.
+- **Eye mask**: the template's mask of the eyes, 1 over the eyes. It is used with `--enucleate` and `--renucleate`.
+- **Reface**: fill the removed face with the template's face, scaled to the scan's brightness (`--reface`).
+- **Enucleate**: remove the eyes as well as the face (`--enucleate`).
+- **Renucleate**: remove the eyes and fill them with the template's eyes (`--renucleate`; `--reface --enucleate` does the same, plus the face).
+- **Fill**: put template voxels into a removed region (the face, the eyes, or both). The filled image is written as `_refaced`.
+- **Regions** (`faceoff/regions.py`): works out once, from `--reface`, `--enucleate`, `--renucleate`, and `--syn`, which regions are removed, which are filled, and which registration moves each mask. Every other part of FaceOff asks it.
+- **Affine registration**: rigid, then affine, fitted inside the brain with mutual information (MI). It is always run, and moves the face mask by default.
+- **Nonlinear brain registration** (`--syn`): SyN over the whole head with MI, then inside the brain with cross-correlation (CC). With `--syn` it moves the face mask instead of the affine.
+- **Nonlinear face registration**: SyN over the face with MI, starting from the registrations above. It moves the eye mask, and the template face and eyes that fill the removed regions.
+- **Stage** (`AFFINE`, `NONLINEAR_BRAIN`, `NONLINEAR_FACE`): which of those three registrations moves a template image onto the scan. Each image is moved by one ANTs call with the whole chain of transforms, so it is resampled once.
+- **Template orientation** (`_tal_` files): the scan rotated to line up with the template by changing only its header; the voxels are not resampled.
+- **Extra images** (`--extra-images`): other images from the same session and scanner space (other MP2RAGE images, GRE echoes). They get the same masks, moved onto their own voxel grid.
+- **Scan to deface** (`faceoff/inputs.py`): one scan and its extra images, with every file already checked. All files given are checked before the first scan starts, and every problem is listed at once.
+- **Stand-in registration** (`tests/conftest.py`): used only by the tests. It moves template images with a known affine, without ANTs.

faceoff_mri-1.9.8/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2026 Sriranga Kashyap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

faceoff_mri-1.9.8/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.5
+Name: faceoff-mri
+Version: 1.9.8
+Summary: MRI defacing tool using ANTs registration (your own install, Docker, or Apptainer) to an MNI152 template
+License-Expression: MIT
+License-File: LICENCE
+Requires-Python: >=3.12
+Requires-Dist: click<9,>=8.1
+Requires-Dist: nibabel>=5
+Requires-Dist: numpy>=1.26
+Requires-Dist: pillow>=10
+Requires-Dist: rich-click<2,>=1.9
+Requires-Dist: rich<15,>=13
+Description-Content-Type: text/markdown
+
+# FaceOff [![Version](https://img.shields.io/badge/version-1.9.8-purple.svg)](https://github.com/srikash/FaceOff/releases/tag/v1.9.8) [![Licence](https://img.shields.io/badge/licence-MIT-orange.svg)](LICENCE) [![DOI](https://zenodo.org/badge/307797054.svg)](https://zenodo.org/badge/latestdoi/307797054)
+
+Deface anatomical MRI scans with ANTs. FaceOff removes the face, and the eyes if you ask, and can put the template's face and eyes back.
+
+- Reorients to template orientation and crops in the same run, with no interpolation.
+- `--extra-images` (MP2RAGE, GRE echoes) and `--batch` (many scans).
+- A QC page with every run.
+- ANTs from your PATH, Docker, or Apptainer.
+
+<p align="center">
+  <img src="https://gitlab.com/skash/images-and-gifs/-/raw/master/face-off/faceoff.gif" alt="Face swap scene from the film Face/Off">
+  <br>
+  <em>Face/Off (1997)</em>
+</p>
+
+## Install
+
+You need Python 3.12 or newer, and ANTs (2.3.3 or newer, tested with 2.6.5) on your PATH, Docker, or Apptainer (or Singularity).
+
+```bash
+pip install "git+https://github.com/srikash/FaceOff.git"
+faceoff --help
+```
+
+The package will be called `faceoff-mri` on PyPI; `pip install faceoff-mri` works once the first release is published. The name `faceoff` on PyPI is a different program, so if you ran `pip install faceoff` earlier, run `pip uninstall faceoff` first.
+
+A container image with ANTs inside is described in [docs/installation.md](docs/installation.md).
+
+Conda, clusters, and Apptainer: [docs/installation.md](docs/installation.md).
+
+## Quick start
+
+```bash
+faceoff -i sub-01_T1w.nii.gz                    # deface and reorient
+faceoff -i sub-01_T1w.nii.gz --reface           # also put a face back
+faceoff -i sub-01_T1w.nii.gz --enucleate        # remove the eyes too
+faceoff -i sub-01_T1w.nii.gz --renucleate       # remove the eyes and put template eyes back
+faceoff --batch sub-*_T1w.nii.gz                # several scans, one after another
+faceoff -i sub-01_UNIT1.nii.gz --extra-images sub-01_inv-*_MP2RAGE.nii.gz   # MP2RAGE or GRE echoes
+```
+
+Outputs go next to the input: [docs/outputs.md](docs/outputs.md).
+
+## Example outputs
+
+![Sagittal sweep of FaceOff's outputs: defaced, with the eyes removed, refaced, and refaced with the template's eyes](docs/images/faceoff_examples.gif)
+
+The template's face and eyes are shown in turbo.
+
+## How it compares
+
+FaceOff, [pydeface](https://github.com/poldracklab/pydeface) 2.1.0, and AFNI's `afni_refacer2` on the same 1 mm MPRAGE, 12 cores:
+
+| | **FaceOff** | pydeface | afni_refacer2 |
+| --- | --- | --- | --- |
+| Deface | **12 s** | 2 min 35 s | 2 min 54 s |
+| Reface | **56 s** | not available | 2 min 59 s |
+| Remove the eyes | **47 s** (`--enucleate`)<br>**59 s** with `--reface` | not available | not available |
+
+- Median of 3 runs. FaceOff's reorientation to template orientation comes for free, with no interpolation.
+- [Results](docs/results.md): the three tools' outputs side by side.
+
+**Planned:** an option to use AFNI's refacer template and shell in place of FaceOff's own template.
+
+## More
+
+[Installation](docs/installation.md) · [Usage](docs/usage.md) · [Outputs](docs/outputs.md) · [Results](docs/results.md) · [Template](docs/template.md) · [Development](docs/development.md) · [Citation](docs/citation.md)
+
+## Licence and citation
+
+MIT licence; the template files keep the [MNI licence](faceoff/COPYING-MNI). If you use FaceOff, please cite it, the MNI ICBM152 template, and ANTs: [docs/citation.md](docs/citation.md).

faceoff_mri-1.9.8/README.md

@@ -0,0 +1,71 @@
+# FaceOff [![Version](https://img.shields.io/badge/version-1.9.8-purple.svg)](https://github.com/srikash/FaceOff/releases/tag/v1.9.8) [![Licence](https://img.shields.io/badge/licence-MIT-orange.svg)](LICENCE) [![DOI](https://zenodo.org/badge/307797054.svg)](https://zenodo.org/badge/latestdoi/307797054)
+
+Deface anatomical MRI scans with ANTs. FaceOff removes the face, and the eyes if you ask, and can put the template's face and eyes back.
+
+- Reorients to template orientation and crops in the same run, with no interpolation.
+- `--extra-images` (MP2RAGE, GRE echoes) and `--batch` (many scans).
+- A QC page with every run.
+- ANTs from your PATH, Docker, or Apptainer.
+
+<p align="center">
+  <img src="https://gitlab.com/skash/images-and-gifs/-/raw/master/face-off/faceoff.gif" alt="Face swap scene from the film Face/Off">
+  <br>
+  <em>Face/Off (1997)</em>
+</p>
+
+## Install
+
+You need Python 3.12 or newer, and ANTs (2.3.3 or newer, tested with 2.6.5) on your PATH, Docker, or Apptainer (or Singularity).
+
+```bash
+pip install "git+https://github.com/srikash/FaceOff.git"
+faceoff --help
+```
+
+The package will be called `faceoff-mri` on PyPI; `pip install faceoff-mri` works once the first release is published. The name `faceoff` on PyPI is a different program, so if you ran `pip install faceoff` earlier, run `pip uninstall faceoff` first.
+
+A container image with ANTs inside is described in [docs/installation.md](docs/installation.md).
+
+Conda, clusters, and Apptainer: [docs/installation.md](docs/installation.md).
+
+## Quick start
+
+```bash
+faceoff -i sub-01_T1w.nii.gz                    # deface and reorient
+faceoff -i sub-01_T1w.nii.gz --reface           # also put a face back
+faceoff -i sub-01_T1w.nii.gz --enucleate        # remove the eyes too
+faceoff -i sub-01_T1w.nii.gz --renucleate       # remove the eyes and put template eyes back
+faceoff --batch sub-*_T1w.nii.gz                # several scans, one after another
+faceoff -i sub-01_UNIT1.nii.gz --extra-images sub-01_inv-*_MP2RAGE.nii.gz   # MP2RAGE or GRE echoes
+```
+
+Outputs go next to the input: [docs/outputs.md](docs/outputs.md).
+
+## Example outputs
+
+![Sagittal sweep of FaceOff's outputs: defaced, with the eyes removed, refaced, and refaced with the template's eyes](docs/images/faceoff_examples.gif)
+
+The template's face and eyes are shown in turbo.
+
+## How it compares
+
+FaceOff, [pydeface](https://github.com/poldracklab/pydeface) 2.1.0, and AFNI's `afni_refacer2` on the same 1 mm MPRAGE, 12 cores:
+
+| | **FaceOff** | pydeface | afni_refacer2 |
+| --- | --- | --- | --- |
+| Deface | **12 s** | 2 min 35 s | 2 min 54 s |
+| Reface | **56 s** | not available | 2 min 59 s |
+| Remove the eyes | **47 s** (`--enucleate`)<br>**59 s** with `--reface` | not available | not available |
+
+- Median of 3 runs. FaceOff's reorientation to template orientation comes for free, with no interpolation.
+- [Results](docs/results.md): the three tools' outputs side by side.
+
+**Planned:** an option to use AFNI's refacer template and shell in place of FaceOff's own template.
+
+## More
+
+[Installation](docs/installation.md) · [Usage](docs/usage.md) · [Outputs](docs/outputs.md) · [Results](docs/results.md) · [Template](docs/template.md) · [Development](docs/development.md) · [Citation](docs/citation.md)
+
+## Licence and citation
+
+MIT licence; the template files keep the [MNI licence](faceoff/COPYING-MNI). If you use FaceOff, please cite it, the MNI ICBM152 template, and ANTs: [docs/citation.md](docs/citation.md).