odx 0.3.0__tar.gz → 0.3.2__tar.gz

{odx-0.3.0 → odx-0.3.2}/Cargo.lock

@@ -1042,7 +1042,7 @@ dependencies = [
 
 [[package]]
 name = "odx-py"
-version = "0.3.0"
+version = "0.3.2"
 dependencies = [
  "bytemuck",
  "ndarray",
@@ -1054,7 +1054,7 @@ dependencies = [
 
 [[package]]
 name = "odx-rs"
-version = "0.3.0"
+version = "0.3.2"
 dependencies = [
  "assert_cmd",
  "bytemuck",

{odx-0.3.0 → odx-0.3.2}/Cargo.toml

@@ -11,7 +11,7 @@ members = [".", "python"]
 # release workflow has a verify-version step that fails if the tag and
 # this value disagree.
 [workspace.package]
-version = "0.3.0"
+version = "0.3.2"
 edition = "2021"
 # Bulk of the crate is dual MIT OR Apache-2.0 (the typical Rust ecosystem
 # license). Two files (src/peak_finder.rs, src/mrtrix_sh.rs) port code from

{odx-0.3.0 → odx-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: odx
-Version: 0.3.0
+Version: 0.3.2
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: Apache Software License
@@ -69,6 +69,8 @@ peaked.save_mrtrix("mrtrix_out/")   # → MRtrix mif (auto-converts basis)
 
 # Round-trip back to dipy if you want
 pam = odx.to_peaks_and_metrics(peaked)
+
+wmfod = odx.from_mrtrix("wmfod.mif")  # bare SH image (.mif[.gz] or 4-D .nii[.gz])
 ```
 
 ## Features

{odx-0.3.0 → odx-0.3.2}/README.md

@@ -39,7 +39,9 @@ Some formats are composite:
 
 - MRtrix fixel directories may be paired with `--sh <path>`
 - MRtrix SH images may be paired with `--fixel-dir <path>`
-- DSI Studio `fib.gz` files may use `--reference-affine <mif-or-nifti>`
+- DSI Studio `fib.gz` files may use `--reference-affine <mif-or-nifti>`: the
+  DWI the file was reconstructed from, whose affine odx reorders to DSI
+  Studio's LPS voxel order
 - TORTOISE MAP-MRI input (`--input-format tortoise-mapmri-nifti`) pairs a
   coefficient NIfTI given as `<input>` with `--mapmri-tensor <nifti>` and
   `--mapmri-uvec <nifti>`

{odx-0.3.0 → odx-0.3.2}/SPECIFICATION.md

@@ -49,7 +49,7 @@ data.odx/
 
   sphere/                           # ODF sampling sphere (optional)
     vertices.3.{dtype}              #   unit directions (NB_SPHERE_VERTICES x 3)
-    faces.3.uint32                  #   triangle indices (NB_SPHERE_FACES x 3)
+    faces.3.uint32                  #   triangle indices (NB_SPHERE_FACES x 3, optional)
 
   odf/                              # ODF amplitudes (optional)
     amplitudes.{ndirs}.{dtype}      #   (NB_VOXELS x NB_SPHERE_VERTICES)
@@ -104,7 +104,7 @@ data.odx/
 | Field | Present when | Type | Description |
 |-------|-------------|------|-------------|
 | `NB_SPHERE_VERTICES` | `sphere/` exists | `u64` | Number of ODF sampling directions. |
-| `NB_SPHERE_FACES` | `sphere/` exists | `u64` | Number of triangles in the sphere mesh. |
+| `NB_SPHERE_FACES` | `sphere/faces` exists | `u64` | Number of triangles in the sphere mesh. |
 | `SH_ORDER` | `sh/` exists | `u64` | Maximum spherical harmonic order. |
 | `SH_BASIS` | `sh/` exists | `string` | SH basis convention: `"descoteaux07"` (Dipy) or `"tournier07"` (MRtrix). |
 | `SH_FULL_BASIS` | optional | `bool` | When `true`, the SH array uses the full basis with both even and odd ℓ (ncoeffs = `(SH_ORDER + 1)²`); when `false` or absent, the symmetric even-only basis is used (ncoeffs = `(SH_ORDER + 1)(SH_ORDER + 2)/2`). Full basis is required for asymmetric ODFs (e.g. pyAFQ aodf). |
@@ -182,7 +182,9 @@ RAS+mm orientation.
 ### `sphere/faces.3.uint32`
 
 Shape `(NB_SPHERE_FACES, 3)`. Triangle indices into the vertex array, for
-mesh visualization and interpolation.
+mesh visualization and interpolation. Optional: a sphere known only by its
+sampling directions (e.g. one imported from a dipy PAM5 file) has vertices but
+no faces, and readers must accept a `sphere/` without `faces`.
 
 The sphere directory is required when `odf/` data is present on a noncanonical
 sphere. It may be omitted when `SPHERE_ID` identifies a standard sphere. It is
@@ -361,7 +363,7 @@ This applies to:
 
 | Source | Transform |
 |--------|-----------|
-| DSI Studio (LPS+) | Negate x and y components: `x_ras = -x_lps`, `y_ras = -y_lps`, `z_ras = z_lps` |
+| DSI Studio (voxel frame of its LPS+-reordered grid) | `d_ras = R · d_dsi`, with `R` the 3×3 linear part of `trans` with its columns normalized; this is `diag(-1, -1, 1)` (negate x and y) only for a non-oblique image. Applies to `odf_vertices`, `dir{p}` and so to `index{p}`. A `.fib.gz` without `trans` uses the reference DWI affine reordered to LPS+ voxel order. |
 | MRtrix (RAS) | No change needed for directions. Affine from NIfTI header. |
 | Dipy (RAS) | No change needed. Affine from NIfTI header. |
 

{odx-0.3.0 → odx-0.3.2}/docs/cli.md

@@ -474,7 +474,8 @@ can). The loader also reads them back in preference to `index{p}`.
 Useful options:
 
 - `--reference-affine <nifti>`: required for a native-space `.fib.gz`/`.fz`
-  without a `trans` record (e.g. the preprocessed DWI it was built from).
+  without a `trans` record (e.g. the preprocessed DWI it was built from); it
+  is reordered to DSI Studio's LPS voxel order automatically.
 - `--odf-lmax <even-int>`, `--apsf-dirs <N>`: accuracy knobs for the dense-ODF
   and SH paths.
 - `--json`: machine-readable summary including the correction report
@@ -504,7 +505,7 @@ Useful options:
 Some formats are composite:
 
 - MRtrix fixel directories may be accompanied by an SH image.
-- DSI Studio `fib.gz` inputs may need `--reference-affine` when the file does not contain a usable transform.
+- DSI Studio `fib.gz` inputs may need `--reference-affine` when the file does not contain a usable transform (no `trans` record). Pass the DWI NIfTI the file was reconstructed from: DSI Studio reorders voxels to LPS on import, and odx reorders the reference affine the same way (as nibabel's `io_orientation` + `ornt_transform` + `inv_ornt_aff` would), so a LAS or otherwise ordered DWI lands its voxels correctly. An affine that is already LPS-ordered is used as is.
 - ODX may hold sparse fixels, dense ODFs, and SH together in one dataset.
 
 The CLI therefore treats `<input>` as the primary object and accepts companion inputs as flags instead of requiring a manifest format.

{odx-0.3.0 → odx-0.3.2}/python/README.md

@@ -32,6 +32,8 @@ peaked.save_mrtrix("mrtrix_out/")   # → MRtrix mif (auto-converts basis)
 
 # Round-trip back to dipy if you want
 pam = odx.to_peaks_and_metrics(peaked)
+
+wmfod = odx.from_mrtrix("wmfod.mif")  # bare SH image (.mif[.gz] or 4-D .nii[.gz])
 ```
 
 ## Features

{odx-0.3.0 → odx-0.3.2}/python/src/lib.rs

@@ -1720,6 +1720,11 @@ fn from_fz(path: PathBuf, skip_odf: bool) -> PyResult<PyOdx> {
 
 /// Load a DSI Studio `.fib.gz`. `skip_odf=True` discards the dense ODFs
 /// while decompressing, for fixel-only work.
+///
+/// `affine` is only used when the file has no `trans` record: pass the
+/// affine of the DWI NIfTI the file was reconstructed from. DSI Studio
+/// reorders voxels to LPS on import, and the affine is reordered the same
+/// way (a no-op for an affine already in LPS order).
 #[pyfunction]
 #[pyo3(signature = (path, affine=None, *, skip_odf=false))]
 fn from_fibgz(
@@ -1733,13 +1738,25 @@ fn from_fibgz(
     Ok(PyOdx::from_dataset(dataset))
 }
 
-/// Load an MRtrix dataset from a directory containing a fixel directory and
-/// (optionally) a sibling SH `.mif` file. If `sh_filename` is provided the
-/// SH is loaded from `directory/sh_filename`; otherwise common defaults are
-/// tried (`wmfod.mif`, `WM_FODs.mif`).
+/// Load MRtrix data. `path` is either a bare SH image (`.mif`, `.mif.gz`,
+/// `.nii`, `.nii.gz`; voxel order is canonicalized to RAS+) or a directory
+/// containing a fixel directory and (optionally) a sibling SH `.mif` file.
+/// For a directory, if `sh_filename` is provided the SH is loaded from
+/// `path/sh_filename`; otherwise common defaults are tried (`wmfod.mif`,
+/// `WM_FODs.mif`). `sh_filename` is not accepted with a bare SH image.
 #[pyfunction]
-#[pyo3(signature = (directory, sh_filename=None))]
-fn from_mrtrix(directory: PathBuf, sh_filename: Option<String>) -> PyResult<PyOdx> {
+#[pyo3(signature = (path, sh_filename=None))]
+fn from_mrtrix(path: PathBuf, sh_filename: Option<String>) -> PyResult<PyOdx> {
+    if path.is_file() {
+        if sh_filename.is_some() {
+            return Err(PyValueError::new_err(
+                "from_mrtrix: sh_filename is only valid when path is a directory",
+            ));
+        }
+        let dataset = odx_rs::mrtrix::load_mrtrix_sh(&path).map_err(map_io)?;
+        return Ok(PyOdx::from_dataset(dataset));
+    }
+    let directory = path;
     let candidates: Vec<PathBuf> = match sh_filename {
         Some(name) => vec![directory.join(&name), directory.join(format!("{name}.gz"))],
         None => vec![

{odx-0.3.0 → odx-0.3.2}/python/tests/test_foreign_io.py

@@ -42,6 +42,43 @@ def test_save_mif_then_from_mrtrix_roundtrips_sh(tmp_path):
     np.testing.assert_allclose(loaded_sh, src_sh, atol=1e-3)
 
 
+def test_from_mrtrix_accepts_a_bare_sh_image(tmp_path):
+    src = _make_dataset()
+    # save_mif gzips by default and writes "fod.mif.gz" even when given "fod.mif".
+    path = tmp_path / "fod.mif.gz"
+    src.save_mif(path, which="sh")
+    assert path.is_file()
+    loaded = odx.from_mrtrix(path)
+    # The bare-image loader derives its own mask from the SH, so compare on
+    # the full grid rather than masked rows.
+    np.testing.assert_allclose(
+        np.asarray(loaded.densify_sh()), np.asarray(src.densify_sh()), atol=1e-3
+    )
+    np.testing.assert_array_equal(np.asarray(loaded.affine), np.asarray(src.affine))
+    assert loaded.dimensions == src.dimensions
+
+
+def test_from_mrtrix_accepts_a_bare_nifti_sh_image(tmp_path):
+    nib = pytest.importorskip("nibabel")
+    src = _make_dataset()
+    dense = np.asarray(src.densify_sh(), dtype=np.float32)
+    path = tmp_path / "fod.nii.gz"
+    nib.save(nib.Nifti1Image(dense, np.eye(4)), path)
+    loaded = odx.from_mrtrix(path)
+    np.testing.assert_allclose(np.asarray(loaded.densify_sh()), dense, atol=1e-3)
+    np.testing.assert_array_equal(np.asarray(loaded.affine), np.eye(4))
+    assert loaded.dimensions == dense.shape[:3]
+
+
+def test_from_mrtrix_rejects_sh_filename_with_a_file_path(tmp_path):
+    src = _make_dataset()
+    path = tmp_path / "fod.mif.gz"
+    src.save_mif(path, which="sh")
+    assert path.is_file()
+    with pytest.raises(ValueError, match="sh_filename"):
+        odx.from_mrtrix(path, sh_filename="wmfod.mif")
+
+
 # ─── DSI Studio FZ ────────────────────────────────────────────────────────────