Add WMA-based hemisphere export mode

pyproject.toml

@@ -19,6 +19,7 @@ dependencies = [
     "numpy>=1.21",
     "torch>=2.3.1",
     "vtk>=9.0",
+    "whitematteranalysis @ git+https://github.com/SlicerDMRI/whitematteranalysis.git",
 ]
 
 [project.optional-dependencies]

src/tractcloud/README_hemisphere.md

@@ -0,0 +1,50 @@
+# Hemisphere Export Mode
+
+`tractcloud --hemisphere-atlas-dir PATH` runs TractCloud inference, keeps the
+fine cluster predictions, registers the input tractography to the ORG atlas
+with WMA, and writes hemisphere-split tractography outputs.
+
+Default CLI behavior is unchanged when `--hemisphere-atlas-dir` is omitted.
+Hemisphere mode writes only Hemisphere outputs, not the default coarse
+per-tract category folders. `--mrb` is not supported in this mode.
+
+## Requirements
+
+- WMA must be installed on the machine running the command (pip install git+https://github.com/SlicerDMRI/whitematteranalysis.git).
+- `PATH` should point to `ORG-Atlases-1.1.1` (https://www.dropbox.com/s/beju3c0g9jqw5uj/WMA_tutorial_data.zip?dl=0) or a parent directory containing:
+
+```text
+ORG-Atlases-1.1.1/ORG-RegAtlas-100HCP/registration_atlas.vtk
+ORG-Atlases-1.1.1/ORG-800FC-100HCP/cluster_hemisphere_location.txt
+```
+
+## Usage
+
+```bash
+tractcloud \
+  --input subject.vtk \
+  --output-dir results \
+  --hemisphere-atlas-dir /path/to/ORG-Atlases-1.1.1
+```
+
+## Outputs
+
+```text
+results/
+  wma_registration/
+  Hemisphere/
+    annotated_tractography.vtp
+    hemisphere_summary.json
+    left/
+      AF_left.vtp
+    right/
+      AF_right.vtp
+    commissural/
+      CC1_commissural.vtp
+```
+
+All Hemisphere `.vtp` files include these cell arrays:
+
+- `FineLabel`: raw TractCloud cluster prediction.
+- `CoarseID`: tract index from `tract_mapping.py`.
+- `HemisphereLocation`: `0=other`, `1=left`, `2=right`, `3=commissural`.

src/tractcloud/cli.py

@@ -20,7 +20,7 @@ def main():
         help="Input tractography file (.vtk or .vtp)")
     parser.add_argument(
         "--output-dir", "-o", required=True,
-        help="Output directory for per-tract VTP files")
+        help="Output directory")
     parser.add_argument(
         "--mrb", action="store_true",
         help="Also create a Slicer-compatible MRB file")
@@ -39,12 +39,20 @@ def main():
     parser.add_argument(
         "--data-dir",
         help="Override model data cache directory")
+    parser.add_argument(
+        "--hemisphere-atlas-dir",
+        help=(
+            "Run Hemisphere export mode using an ORG-Atlases-1.1.1 path. If passed, runs TractCloud inference, uses raw fine cluster_preds for hemisphere assignment, runs WMA registration, and writes only hemisphere outputs."
+        ))
     parser.add_argument(
         "--quiet", "-q", action="store_true",
         help="Suppress progress output on stdout")
 
     args = parser.parse_args()
 
+    if args.mrb and args.hemisphere_atlas_dir:
+        parser.error("--mrb cannot be used with --hemisphere-atlas-dir")
+
     # Configure logging to stderr (keep stdout clean for JSON progress)
     logging.basicConfig(
         stream=sys.stderr,
@@ -76,6 +84,7 @@ def main():
         args.input,
         args.output_dir,
         create_mrb=args.mrb,
+        hemisphere_atlas_dir=args.hemisphere_atlas_dir,
     )