syntx 0.1.7__tar.gz

syntx-0.1.7/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: syntx
+Version: 0.1.7
+Summary: Symmetric diffeomorphic and affine image registration methods in PyTorch and JAX
+Author: syntx developers
+License: Apache-2.0
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: antspyx
+Requires-Dist: torch
+Requires-Dist: torchvision
+Requires-Dist: jax
+Requires-Dist: jaxlib
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+
+# syntx
+
+`syntx` is a high-performance Python package focusing on symmetric diffeomorphic (`SyN`) and affine image registration methods, built on top of **PyTorch** and **JAX** for GPU/MPS acceleration and auto-differentiation capabilities.
+
+Ported from the registration modules of the `sulceye` package, `syntx` is designed for distribution on PyPI and works seamlessly with standard medical image types, particularly `ANTsImage` from the `antspyx` library.
+
+---
+
+### ⚠️ Disclaimer & Differences from `ants.registration`
+
+> [!IMPORTANT]
+> **Validation Status**: The deep-learning feature-space similarity metrics (VGG19, DINOv2, Swin UNETR) in this repository are **experimental** and have **not** been deeply validated on large-scale clinical cohorts. They are intended strictly for research and exploration.
+>
+> **Key Differences from `ants.registration`:**
+> 1. **GPU Acceleration**: Unlike standard `ants.registration` (which runs on CPU via ITK C++), Syntx supports **PyTorch and JAX** optimization backends for fast GPU/MPS execution.
+> 2. **Optimizers**: Syntx uses Adam/Rprop for the affine stage and greedy composition steps scaling by ITK-style CFL (Courant-Friedrichs-Lewy) max voxel displacement bounds, while ANTs relies on C++ variants of L-BFGS or regularized gradient descent.
+> 3. **Velocity-Field & Elastic Smoothing**: Separable Gaussian filters are implemented natively in JAX/PyTorch to perform fluid-like smoothing of update fields and elastic-like smoothing of composed fields, matching ITK's Gaussian regularization on the GPU.
+> 4. **Multi-Resolution Pyramid**: Downsampling is performed dynamically using bilinear/trilinear grid interpolation in PyTorch/JAX to build image pyramids, rather than ITK's C++ downsampling filters.
+> 5. **Feature-Space Metrics**: Similarity is evaluated on multi-scale feature representations (from vision transformers or CNNs) via zero-copy **DLPack** autograd sharing, rather than raw intensity maps.
+
+---
+
+## Key Features
+- **Auto-Differentiation Backends:** Choose between `'pytorch'` and `'jax'` for core computations.
+- **Symmetric Normalization (SyN):** Fully symmetric greedy optimization matching classic ITK/ANTs SyN implementations.
+- **Interoperability:** Seamless conversions between PyTorch/JAX coordinate spaces and ITK physical coordinate matrices.
+- **Direct PyPy/PyPI Packaging:** Implemented cleanly with minimum external dependencies.
+
+---
+
+## Installation
+
+To install `syntx` locally from the repository:
+```bash
+pip install -e .
+```
+
+### Dependencies
+- `numpy`
+- `scipy`
+- `matplotlib`
+- `antspyx`
+- `torch`
+- `jax`
+- `jaxlib`
+
+---
+
+## Usage Example
+
+`syntx` exposes a high-level `syn` and `registration` API that mirrors `ants.registration`:
+
+```python
+import ants
+import syntx
+
+# Load ANTs images
+fixed = ants.image_read( ants.get_data('r16') )
+moving = ants.image_read( ants.get_data('r64')  )
+
+# Run registration using PyTorch (default)
+result = syntx.syn(
+    fixed=fixed,
+    moving=moving,
+    type_of_transform='SyNTo',
+    backend='pytorch',
+    reg_iterations=[100, 100, 50],
+    affine_iterations=[100, 50, 20],
+)
+
+# Access the warped moving output image
+warped_moving = result['warpedmovout']
+
+# Access transform files (saved to temporary paths for ANTs compatibility)
+forward_transforms = result['fwdtransforms']
+inverse_transforms = result['invtransforms']
+```
+
+For JAX backend acceleration:
+```python
+result = syntx.syn(
+    fixed=fixed,
+    moving=moving,
+    type_of_transform='SyNTo',
+    backend='jax',
+    reg_iterations=[100, 100, 50],
+    affine_iterations=[100, 50, 20],
+)
+```
+
+---
+
+## Running the Examples and Generating Reports
+
+An example comparing classic ANTs, PyTorch, and JAX registration is included under `examples/`. It generates a comparison report summarizing Mutual Information, Jacobian Determinants (topological safety), and Execution Speed.
+
+To run the comparison:
+```bash
+python examples/generate_ants_2d_comparison_report.py
+```
+
+This generates an HTML report under `reports/ants_2d_syn_comparison.html`.
+
+---
+
+## Running Tests
+
+Tests can be executed via `pytest`:
+```bash
+pytest
+```
+
+---
+
+## Makefile Automation
+
+A `Makefile` is included to automate standard development tasks:
+
+*   **Install** (install package in editable mode):
+    ```bash
+    make install
+    ```
+*   **Test** (run test suite in Fast mode, skipping slow 3D registrations, and printing a code coverage table):
+    ```bash
+    make test
+    ```
+*   **Test All** (run the full test suite including slow 3D registrations, with coverage):
+    ```bash
+    make test-all
+    ```
+*   **Clean** (remove build artifacts, cached directories, and temporary files):
+    ```bash
+    make clean
+    ```
+*   **Release** (clean, build sdist and wheel packages, and upload to PyPI using twine):
+    ```bash
+    make release
+    ```
+
+It automatically detects and prioritizes the active python virtual environment (`VIRTUAL_ENV`).

syntx-0.1.7/README.md

@@ -0,0 +1,140 @@
+# syntx
+
+`syntx` is a high-performance Python package focusing on symmetric diffeomorphic (`SyN`) and affine image registration methods, built on top of **PyTorch** and **JAX** for GPU/MPS acceleration and auto-differentiation capabilities.
+
+Ported from the registration modules of the `sulceye` package, `syntx` is designed for distribution on PyPI and works seamlessly with standard medical image types, particularly `ANTsImage` from the `antspyx` library.
+
+---
+
+### ⚠️ Disclaimer & Differences from `ants.registration`
+
+> [!IMPORTANT]
+> **Validation Status**: The deep-learning feature-space similarity metrics (VGG19, DINOv2, Swin UNETR) in this repository are **experimental** and have **not** been deeply validated on large-scale clinical cohorts. They are intended strictly for research and exploration.
+>
+> **Key Differences from `ants.registration`:**
+> 1. **GPU Acceleration**: Unlike standard `ants.registration` (which runs on CPU via ITK C++), Syntx supports **PyTorch and JAX** optimization backends for fast GPU/MPS execution.
+> 2. **Optimizers**: Syntx uses Adam/Rprop for the affine stage and greedy composition steps scaling by ITK-style CFL (Courant-Friedrichs-Lewy) max voxel displacement bounds, while ANTs relies on C++ variants of L-BFGS or regularized gradient descent.
+> 3. **Velocity-Field & Elastic Smoothing**: Separable Gaussian filters are implemented natively in JAX/PyTorch to perform fluid-like smoothing of update fields and elastic-like smoothing of composed fields, matching ITK's Gaussian regularization on the GPU.
+> 4. **Multi-Resolution Pyramid**: Downsampling is performed dynamically using bilinear/trilinear grid interpolation in PyTorch/JAX to build image pyramids, rather than ITK's C++ downsampling filters.
+> 5. **Feature-Space Metrics**: Similarity is evaluated on multi-scale feature representations (from vision transformers or CNNs) via zero-copy **DLPack** autograd sharing, rather than raw intensity maps.
+
+---
+
+## Key Features
+- **Auto-Differentiation Backends:** Choose between `'pytorch'` and `'jax'` for core computations.
+- **Symmetric Normalization (SyN):** Fully symmetric greedy optimization matching classic ITK/ANTs SyN implementations.
+- **Interoperability:** Seamless conversions between PyTorch/JAX coordinate spaces and ITK physical coordinate matrices.
+- **Direct PyPy/PyPI Packaging:** Implemented cleanly with minimum external dependencies.
+
+---
+
+## Installation
+
+To install `syntx` locally from the repository:
+```bash
+pip install -e .
+```
+
+### Dependencies
+- `numpy`
+- `scipy`
+- `matplotlib`
+- `antspyx`
+- `torch`
+- `jax`
+- `jaxlib`
+
+---
+
+## Usage Example
+
+`syntx` exposes a high-level `syn` and `registration` API that mirrors `ants.registration`:
+
+```python
+import ants
+import syntx
+
+# Load ANTs images
+fixed = ants.image_read( ants.get_data('r16') )
+moving = ants.image_read( ants.get_data('r64')  )
+
+# Run registration using PyTorch (default)
+result = syntx.syn(
+    fixed=fixed,
+    moving=moving,
+    type_of_transform='SyNTo',
+    backend='pytorch',
+    reg_iterations=[100, 100, 50],
+    affine_iterations=[100, 50, 20],
+)
+
+# Access the warped moving output image
+warped_moving = result['warpedmovout']
+
+# Access transform files (saved to temporary paths for ANTs compatibility)
+forward_transforms = result['fwdtransforms']
+inverse_transforms = result['invtransforms']
+```
+
+For JAX backend acceleration:
+```python
+result = syntx.syn(
+    fixed=fixed,
+    moving=moving,
+    type_of_transform='SyNTo',
+    backend='jax',
+    reg_iterations=[100, 100, 50],
+    affine_iterations=[100, 50, 20],
+)
+```
+
+---
+
+## Running the Examples and Generating Reports
+
+An example comparing classic ANTs, PyTorch, and JAX registration is included under `examples/`. It generates a comparison report summarizing Mutual Information, Jacobian Determinants (topological safety), and Execution Speed.
+
+To run the comparison:
+```bash
+python examples/generate_ants_2d_comparison_report.py
+```
+
+This generates an HTML report under `reports/ants_2d_syn_comparison.html`.
+
+---
+
+## Running Tests
+
+Tests can be executed via `pytest`:
+```bash
+pytest
+```
+
+---
+
+## Makefile Automation
+
+A `Makefile` is included to automate standard development tasks:
+
+*   **Install** (install package in editable mode):
+    ```bash
+    make install
+    ```
+*   **Test** (run test suite in Fast mode, skipping slow 3D registrations, and printing a code coverage table):
+    ```bash
+    make test
+    ```
+*   **Test All** (run the full test suite including slow 3D registrations, with coverage):
+    ```bash
+    make test-all
+    ```
+*   **Clean** (remove build artifacts, cached directories, and temporary files):
+    ```bash
+    make clean
+    ```
+*   **Release** (clean, build sdist and wheel packages, and upload to PyPI using twine):
+    ```bash
+    make release
+    ```
+
+It automatically detects and prioritizes the active python virtual environment (`VIRTUAL_ENV`).

syntx-0.1.7/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "syntx"
+version = "0.1.7"
+description = "Symmetric diffeomorphic and affine image registration methods in PyTorch and JAX"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "Apache-2.0"}
+authors = [
+    {name = "syntx developers"}
+]
+dependencies = [
+    "numpy",
+    "scipy",
+    "matplotlib",
+    "antspyx",
+    "torch",
+    "torchvision",
+    "jax",
+    "jaxlib"
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "pytest-cov"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["syntx*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "--cov=syntx --cov-report=term-missing"

syntx-0.1.7/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

syntx-0.1.7/src/syntx/__init__.py

@@ -0,0 +1,23 @@
+from .syn import registration, SyNTo
+from .syn_jax import SyNTo as SyNToJax
+from .transform import SyNToTransform
+from .features import FeatureSpaceLoss, VGG19Extractor, DINOv2Extractor, ResNet10Extractor, SwinUNETRExtractor
+
+# Expose both syn and registration to satisfy user requirements
+syn = registration
+
+__version__ = "0.1.7"
+
+
+__all__ = [
+    "syn",
+    "registration",
+    "SyNTo",
+    "SyNToJax",
+    "SyNToTransform",
+    "FeatureSpaceLoss",
+    "VGG19Extractor",
+    "DINOv2Extractor",
+    "ResNet10Extractor",
+    "SwinUNETRExtractor",
+]