cmpl 0.2.2__tar.gz → 0.2.3__tar.gz

{cmpl-0.2.2/src/cmpl.egg-info → cmpl-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmpl
-Version: 0.2.2
+Version: 0.2.3
 Summary: CMRR MRI Processing Libraries
 Author: Eisa Hedayati
 License: Copyright (c) 2025 Eisa Hedayati
@@ -71,23 +71,31 @@ Dynamic: license-file
 
 # CMPL — CMRR MRI Processing Libraries
 
-[![PyPI](https://img.shields.io/pypi/v/cmpl.svg)](https://pypi.org/project/cmpl/)
-[![Python](https://img.shields.io/pypi/pyversions/cmpl.svg)](https://pypi.org/project/cmpl/)
+[![PyPI version](https://img.shields.io/pypi/v/cmpl.svg)](https://pypi.org/project/cmpl/)
+[![Python versions](https://img.shields.io/pypi/pyversions/cmpl.svg)](https://pypi.org/project/cmpl/)
 
-CMPL is a Python package for MRI processing workflows developed at CMRR. It provides tools for MRI reconstruction, quantitative MRI, visualization, DICOM/NIfTI I/O, and supporting numerical/data utilities.
+PyPI: https://pypi.org/project/cmpl/
+
+GitHub: https://github.com/ehedayati/cmpl
+
+CMPL is a Python package for MRI processing workflows developed at CMRR. It provides tools for MRI reconstruction, quantitative MRI, visualization, DICOM/NIfTI conversion and I/O, and supporting numerical and data utilities.
 
 CMPL is organized as a modular library: the base installation stays lightweight, while larger or domain-specific dependencies are installed only when the corresponding functionality is needed.
 
 ## Highlights
 
+- Direct, geometry-aware conventional and Enhanced DICOM to NIfTI conversion with JSON metadata sidecars
+- Multi-echo DICOM support, including 4D NIfTI output ordered by echo time
+- Packaged `cmpl-dicom-to-nifti` command-line converter
+- DICOM geometry and acquisition-metadata utilities
 - Parallel MRI reconstruction with 1D/2D GRAPPA and conjugate-gradient SENSE
 - Quantitative MRI tools for T2* fitting, signal reconstruction, and fitting-error analysis
-- MRI visualization utilities for 2D comparisons, 3D volume browsing, and segmentation overlays
-- DICOM, enhanced-DICOM, NIfTI, and SimpleITK utilities
+- MRI visualization utilities for 2D comparisons and 3D volume browsing
+- Conventional and Enhanced DICOM, NIfTI, HDF5, and SimpleITK utilities
 - Lightweight numerical utilities shared across CMPL
 - Optional pandas-based indexing for CMPL-style medical-data directory structures
 - Lazy package imports so `import cmpl` does not eagerly load large optional dependencies
-- Backward-compatible convenience aliases such as `cmpl.recon`, `cmpl.qmr`, `cmpl.vis`, and `cmpl.utils`
+- Convenient aliases such as `cmpl.recon`, `cmpl.qmr`, `cmpl.vis`, and `cmpl.io`
 
 ## Requirements
 
@@ -149,144 +157,192 @@ CMPL exposes convenient aliases for commonly used subpackages:
 cmpl.recon   # reconstruction
 cmpl.qmr     # quantitative MRI
 cmpl.vis     # visualization
-cmpl.utils   # utilities
 cmpl.io      # I/O utilities
+cmpl.dicom   # DICOM metadata and geometry utilities
+cmpl.utils   # utilities
 ```
 
 The aliases are resolved lazily, so importing CMPL itself does not require every optional dependency to be loaded.
 
-## Visualization
+## DICOM and NIfTI I/O
 
-Install the visualization extra:
+Install the I/O extra:
 
 ```bash
-python -m pip install "cmpl[viz]"
+python -m pip install "cmpl[io]"
 ```
 
-### Browse or display a 3D MRI volume
+### Convert a DICOM series directly to NIfTI
+
+CMPL includes direct DICOM-series to NIfTI conversion for both conventional and Enhanced DICOM. The converter detects the DICOM representation automatically, preserves spatial geometry, supports single- and multi-echo acquisitions, writes the NIfTI image, and creates a matching JSON sidecar containing acquisition metadata and source geometry.
 
 ```python
-from cmpl.visualization import plot_3D_mri
+import cmpl
 
-plot_3D_mri(
-    volume,
-    slice_number=volume.shape[2] // 2,
-    alpha=0.5,
-    direction="sagittal",
-    cmap="gray",
-    vmin=0,
-    vmax=1,
-    dpi=300,
+metadata = cmpl.io.dicom_to_nifti(
+    "/path/to/dicom_series",
+    "output.nii.gz",
 )
 ```
 
-If an interactive Matplotlib backend is available, `plot_3D_mri` can use interactive controls. Otherwise it falls back to static redraw mode.
+This creates:
 
+```text
+output.nii.gz
+output.json
+```
 
-### Compare images side by side
+If the output path does not end in `.nii` or `.nii.gz`, CMPL appends `.nii.gz` automatically.
 
-```python
-from cmpl.visualization import side_by_side_view
+For a single echo, the output is a 3D image. When multiple echoes are present, CMPL groups volumes by DICOM `EchoTime`, orders them by echo time, and writes a 4D NIfTI image.
 
-side_by_side_view(
-    image_a,
-    image_b,
-    titles=["Reference", "Reconstruction"],
-    color_palette="gray",
+The JSON sidecar includes:
+
+- selected acquisition metadata
+- echo time or echo times in milliseconds
+- original DICOM slice-plane geometry in LPS coordinates
+- the SimpleITK image size, origin, spacing, and direction used for conversion
+
+The returned value is the same metadata dictionary written to the JSON sidecar.
+
+If a directory contains multiple DICOM series, a specific `SeriesInstanceUID` can be selected:
+
+```python
+metadata = cmpl.io.dicom_to_nifti(
+    "/path/to/dicom_directory",
+    "output.nii.gz",
+    series_id="1.2.840...",
 )
 ```
 
-### Overlay a segmentation
+### Command-line DICOM conversion
 
-```python
-from cmpl.visualization import visualize_segmentation_slice
+Installing the I/O extra also installs the `cmpl-dicom-to-nifti` command:
 
-visualize_segmentation_slice(
-    grayscale_image,
-    segmentation,
-    slice_number=20,
-    dimension="axial",
-)
+```bash
+python -m pip install "cmpl[io]"
 ```
 
-## Quantitative MRI
+Convert a DICOM series with automatic conventional/Enhanced-DICOM detection:
 
-Quantitative MRI functionality is available under:
+```bash
+cmpl-dicom-to-nifti /path/to/dicom_series
+```
 
-```python
-cmpl.qmr
+The same CLI can also be invoked as a Python module:
+
+```bash
+python -m cmpl.cli.dicom_to_nifti /path/to/dicom_series
 ```
 
-Install the PyTorch and visualization dependencies:
+If the output path is omitted, CMPL writes the NIfTI image and JSON sidecar to the current directory using the DICOM directory name:
+
+```text
+./<series_directory_name>.nii.gz
+./<series_directory_name>.json
+```
+
+An explicit output path can also be supplied:
 
 ```bash
-python -m pip install "cmpl[torch,viz]"
+cmpl-dicom-to-nifti \
+    /path/to/dicom_series \
+    /path/to/output.nii.gz
 ```
 
-### Reconstruct a multi-echo signal from T2* and S0 maps
+Progress output is enabled by default. Disable it with:
+
+```bash
+cmpl-dicom-to-nifti /path/to/dicom_series --no-verbose
+```
+
+The same CLI handles conventional single-frame DICOM series and Enhanced multi-frame DICOM series. For multi-echo data, echo volumes are ordered by EchoTime and written as a 4D NIfTI image.
+
+### Read a NIfTI file
 
 ```python
-import numpy as np
+from cmpl.utilities.io import nifti_read
 
-from cmpl.quantitative_MRI import reconstruct_images
+nifti_image, data = nifti_read("image.nii.gz")
+```
 
-t2_star = np.full((64, 64, 8), 20.0, dtype=np.float32)
-s0 = np.full((64, 64, 8), 100.0, dtype=np.float32)
-echo_times = np.array([0.0, 5.0, 10.0, 15.0], dtype=np.float32)
+### Replace NIfTI data while preserving geometry
 
-images = reconstruct_images(
-    t2_star,
-    s0,
-    echo_times,
-    device="cpu",
-    return_numpy=True,
+```python
+from cmpl.utilities.io import update_nifti_data
+
+updated = update_nifti_data(
+    "reference.nii.gz",
+    new_data,
+    output_path="updated.nii.gz",
 )
+```
 
-print(images.shape)
-# (64, 64, 8, 4)
+### Load a DICOM directory as a NumPy array
+
+```python
+from cmpl.utilities.io import load_dicom_scan_from_dir
+
+volume = load_dicom_scan_from_dir(
+    "/path/to/dicom_directory",
+    reshape=True,
+)
 ```
 
-The signal model is:
+For multi-echo data, the loader can return data arranged as:
 
 ```text
-S(TE) = S0 * exp(-TE / T2*)
+x, y, z, echo
 ```
 
-### Fit a 3D two-parameter T2* model
+depending on the acquisition metadata and requested reshaping behavior.
 
-```python
-from cmpl.quantitative_MRI import t2_star_two_parametric_3D
+### Read a DICOM series as SimpleITK
 
-result = t2_star_two_parametric_3D(
-    echo_times,
-    images,
-    num_iterations=1000,
-    initial_lr=0.01,
-    initial_T2_star=20.0,
-    plot_error=False,
-    device="cpu",
-)
+```python
+from cmpl.utilities.io import dicom_to_SimpleITK
 
-t2_star_map = result["T2_star_map"]
-s0_map = result["S0_map"]
+image = dicom_to_SimpleITK("/path/to/dicom_directory")
 ```
 
-If CUDA is available and no device is supplied, the function can select a CUDA device automatically. CUDA usage will increase computation speed significantly.
+The returned image is 3D for a single echo and 4D when multiple echoes are detected.
 
-### Calculate normalized fitting error
+### Write a SimpleITK image as NIfTI
 
 ```python
-from cmpl.quantitative_MRI import calculate_rmse_percentage_s0
+from cmpl.utilities.io import itk_to_nifti
 
-rmse_pct, rse_pct = calculate_rmse_percentage_s0(
-    original_images,
-    reconstructed_images,
-    s0_map,
-    return_numpy=True,
+output_path = itk_to_nifti(
+    image,
+    "output.nii.gz",
 )
 ```
 
-CMPL also contains two- and three-parameter 2D/3D T2* fitting functions.
+### DICOM geometry and metadata helpers
+
+CMPL separates DICOM geometry and acquisition-metadata handling into dedicated modules under `cmpl.dicom`.
+
+```python
+from cmpl.dicom import (
+    extract_slice_geometry,
+    get_slice_position,
+)
+
+geometry = extract_slice_geometry("slice001.dcm")
+position = get_slice_position("slice001.dcm")
+```
+
+Enhanced-DICOM helpers remain available as well:
+
+```python
+from cmpl.dicom.enhanced_dicom import (
+    get_slice_thickness,
+    get_spacing_between_slices,
+    voxel_sizes_detailed,
+)
+
+details = voxel_sizes_detailed(dataset)
+```
 
 ## Reconstruction
 
@@ -338,7 +394,7 @@ reconstructed_kspace = grappa_2d_recon(
 ### Conjugate-gradient SENSE
 
 ```python
-from cmpl.reconstruction.sense import CG_sense_2D
+from cmpl.reconstruction.sense.cg import CG_sense_2D
 
 reconstructed_image = CG_sense_2D(
     undersampled_image_space,
@@ -348,82 +404,123 @@ reconstructed_image = CG_sense_2D(
 
 Inputs to the current SENSE implementation are PyTorch tensors.
 
-## I/O
+## Quantitative MRI
 
-Install the I/O extra:
+Quantitative MRI functionality is available under:
 
-```bash
-python -m pip install "cmpl[io]"
+```python
+cmpl.qmr
 ```
 
-### Read a NIfTI file
-
-```python
-from cmpl.utilities.io import nifti_read
+Install the PyTorch and visualization dependencies:
 
-nifti_image, data = nifti_read("image.nii.gz")
+```bash
+python -m pip install "cmpl[torch,viz]"
 ```
 
-### Replace NIfTI data while preserving geometry
+### Reconstruct a multi-echo signal from T2* and S0 maps
 
 ```python
-from cmpl.utilities.io import update_nifti_data
+import numpy as np
 
-updated = update_nifti_data(
-    "reference.nii.gz",
-    new_data,
-    output_path="updated.nii.gz",
+from cmpl.quantitative_MRI import reconstruct_images
+
+t2_star = np.full((64, 64, 8), 20.0, dtype=np.float32)
+s0 = np.full((64, 64, 8), 100.0, dtype=np.float32)
+echo_times = np.array([0.0, 5.0, 10.0, 15.0], dtype=np.float32)
+
+images = reconstruct_images(
+    t2_star,
+    s0,
+    echo_times,
+    device="cpu",
+    return_numpy=True,
 )
+
+print(images.shape)
+# (64, 64, 8, 4)
+```
+
+The signal model is:
+
+```text
+S(TE) = S0 * exp(-TE / T2*)
 ```
 
-### Load a DICOM directory
+### Fit a 3D two-parameter T2* model
 
 ```python
-from cmpl.utilities.io import load_dicom_scan_from_dir
+from cmpl.quantitative_MRI import t2_star_two_parametric_3D
 
-volume = load_dicom_scan_from_dir(
-    "/path/to/dicom_directory",
-    reshape=True,
+result = t2_star_two_parametric_3D(
+    echo_times,
+    images,
+    num_iterations=1000,
+    initial_lr=0.01,
+    initial_T2_star=20.0,
+    plot_error=False,
+    device="cpu",
 )
+
+t2_star_map = result["T2_star_map"]
+s0_map = result["S0_map"]
 ```
 
-For multi-echo data, the loader can return data arranged as:
+If CUDA is available and no device is supplied, the function can select a CUDA device automatically. CUDA usage can significantly accelerate fitting.
 
-```text
-x, y, z, echo
+### Calculate normalized fitting error
+
+```python
+from cmpl.quantitative_MRI import calculate_rmse_percentage_s0
+
+rmse_pct, rse_pct = calculate_rmse_percentage_s0(
+    original_images,
+    reconstructed_images,
+    s0_map,
+    return_numpy=True,
+)
 ```
 
-depending on the acquisition metadata and requested reshaping behavior.
+CMPL also contains two- and three-parameter 2D/3D T2* fitting functions.
 
-### DICOM to SimpleITK
+## Visualization
 
-```python
-from cmpl.utilities.io import dicom_to_SimpleITK
+Install the visualization extra:
 
-image = dicom_to_SimpleITK("/path/to/dicom_directory")
+```bash
+python -m pip install "cmpl[viz]"
 ```
 
-### Write a SimpleITK image as NIfTI
+### Browse or display a 3D MRI volume
 
 ```python
-from cmpl.utilities.io import itk_to_nifti
+from cmpl.visualization import plot_3D_mri
 
-output_path = itk_to_nifti(
-    image,
-    "output.nii.gz",
+plot_3D_mri(
+    volume,
+    slice_number=volume.shape[2] // 2,
+    alpha=0.5,
+    direction="sagittal",
+    cmap="gray",
+    vmin=0,
+    vmax=1,
+    dpi=300,
 )
 ```
 
-### Enhanced-DICOM helpers
+If an interactive Matplotlib backend is available, `plot_3D_mri` can use interactive controls. Otherwise it falls back to static redraw mode.
+
+### Compare images side by side
 
 ```python
-from cmpl.dicom.enhanced_dicom import (
-    get_slice_thickness,
-    get_spacing_between_slices,
-    voxel_sizes_detailed,
-)
+from cmpl.visualization import side_by_side_view
 
-details = voxel_sizes_detailed(dataset)
+side_by_side_view(
+    image_a,
+    image_b,
+    titles=["Reference", "Reconstruction"],
+    color_palette="gray",
+)
 ```
 
 ## Numerical utilities
@@ -472,12 +569,8 @@ root/
 ├── Study001/
 │   ├── Dicoms/
 │   │   └── <contrast>/
-│   ├── h5_files/
-│   │   └── <contrast>.h5
-│   └── Segmentations/
-│       └── <contrast>/
-│           └── <group>/
-│               └── <segmentation>.nii.gz
+│   └── h5_files/
+│       └── <contrast>.h5
 └── Study002/
     └── ...
 ```
@@ -494,7 +587,7 @@ For example:
 import cmpl
 ```
 
-does not immediately require PyTorch, Matplotlib, pandas, nibabel, pydicom, SimpleITK, or h5py.
+does not immediately import PyTorch, Matplotlib, pandas, nibabel, pydicom, SimpleITK, h5py, or the Jupyter visualization stack.
 
 Optional functionality is loaded when its corresponding module or function is accessed. This keeps startup lightweight and allows users to install only the dependencies required for their workflow.
 
@@ -525,6 +618,8 @@ The test suite includes:
 - GRAPPA and SENSE reconstruction tests
 - visualization smoke tests
 - synthetic NIfTI, DICOM, and SimpleITK I/O tests
+- conventional and Enhanced multi-echo DICOM-to-NIfTI conversion and JSON-sidecar tests
+- DICOM geometry and metadata tests
 - data-indexing tests
 
 ### Build the package
@@ -538,8 +633,13 @@ python -m twine check dist/*
 
 ```text
 src/cmpl/
+├── _version.py
+├── cli/
+│   └── dicom_to_nifti.py
 ├── dicom/
-│   └── enhanced_dicom.py
+│   ├── enhanced_dicom.py
+│   ├── geometry.py
+│   └── metadata.py
 ├── quantitative_MRI/
 │   └── mapping.py
 ├── reconstruction/