neuroslice 0.0.1__py3-none-any.whl

neuroslice/__init__.py

@@ -0,0 +1,10 @@
+from .core import predict, predict_mask, mask2cuboid_array, mask2cuboid_nifti, unite_masks_array, unite_masks_nifti
+
+__all__ = [
+    "predict",
+    "predict_mask",
+    "mask2cuboid_array",
+    "mask2cuboid_nifti",
+    "unite_masks_array",
+    "unite_masks_nifti",
+]

neuroslice/cli.py

@@ -0,0 +1,68 @@
+import argparse
+from pathlib import Path
+import nibabel as nib
+from .core import predict_mask, mask2cuboid_array
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Neuroslice: Brain tumor segmentation using YOLO"
+    )
+    parser.add_argument(
+        "input",
+        type=str,
+        help="Path to input NIfTI file (.nii or .nii.gz)"
+    )
+    parser.add_argument(
+        "output",
+        type=str,
+        help="Path to output mask NIfTI file"
+    )
+    parser.add_argument(
+        "--mode",
+        type=str,
+        default="union",
+        choices=["union", "cuboid"],
+        help="Processing mode: union or cuboid (bounding box)"
+    )
+    parser.add_argument(
+        "--axis",
+        type=int,
+        default=1,
+        choices=[0, 1, 2],
+        help="Slice direction for single-direction mode (default: 0 = coronal)"
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Print detailed statistics"
+    )
+
+    args = parser.parse_args()
+
+    # Validate input file exists
+    if not Path(args.input).exists():
+        print(f"Error: Input file '{args.input}' not found.")
+        return 1
+
+    # Load NIfTI for later saving
+    nifti = nib.load(args.input)
+
+    mask = predict_mask(args.input, args.axis, verbose=args.verbose)
+
+    if args.mode == "cuboid":
+        final_mask = mask2cuboid_array(mask)
+    else:
+        final_mask = mask
+
+    # Save output
+    output_nifti = nib.Nifti1Image(final_mask.astype("uint8"), nifti.affine, nifti.header)
+    nib.save(output_nifti, args.output)
+    if args.verbose:
+        print(f"Mask saved to: {args.output}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    exit(main())

neuroslice/core.py

@@ -0,0 +1,191 @@
+import cv2
+import nibabel as nib
+import numpy as np
+from tqdm import tqdm
+from ultralytics import YOLO
+
+from .utils import download_model
+
+
+def predict(data, axis, verbose):
+    """
+    Generate a binary tumor mask from a 3D image array using a trained YOLO model.
+    Args:
+        data (np.ndarray): 3D image array (e.g., FLAIR image).
+        axis (int): Axis along which to slice the 3D image (0: sagittal, 1: coronal, 2: axial).
+        model (YOLO): Loaded YOLO model.
+        verbose (bool): Whether to print statistics.
+    Returns:
+        np.ndarray: Binary mask of detected tumor regions.
+    """
+
+    assert axis in [0, 1, 2], "Axis must be 0 (sagittal), 1 (coronal), or 2 (axial)."
+
+    # Load the YOLO model
+    model_path = download_model(axis, verbose)
+    model = YOLO(model_path)
+
+    # Initialize binary mask with same shape as input
+    binary_mask = np.zeros_like(data, dtype=np.uint8)
+    n_slices = data.shape[axis]  # Number of coronal slices
+
+    # Process each coronal slice
+    for i in tqdm(range(n_slices), desc="Detecting tumors", disable=not verbose):
+        # Extract slice
+        if axis == 0:
+            slice_data = data[i, :, :]
+        elif axis == 1:
+            slice_data = data[:, i, :]
+        else:
+            slice_data = data[:, :, i]
+
+        # Normalize slice to 0-255 for YOLO input
+        slice_min, slice_max = np.min(slice_data), np.max(slice_data)
+
+        if slice_max - slice_min == 0:
+            continue  # Skip empty slices
+
+        normalized_slice = ((slice_data - slice_min) / (slice_max - slice_min) * 255).astype(np.uint8)
+
+        # Convert to BGR format for YOLO (expects 3-channel image)
+        slice_bgr = cv2.cvtColor(normalized_slice, cv2.COLOR_GRAY2RGB)  # pylint: disable=no-member
+
+        # Run YOLO prediction
+        results = model.predict(slice_bgr, verbose=False)
+        if len(results) == 0 or len(results[0].boxes) == 0:
+            continue
+
+        # Process detections
+        h, w = slice_data.shape
+        for box in results[0].boxes:
+            # Get bounding box in YOLO format (normalized)
+            x_center, y_center, width, height = box.xywhn[0].tolist()
+
+            # Convert to pixel coordinates
+            x1 = int((x_center - width / 2) * w)
+            y1 = int((y_center - height / 2) * h)
+            x2 = int((x_center + width / 2) * w)
+            y2 = int((y_center + height / 2) * h)
+
+            x1, y1 = max(0, x1), max(0, y1)
+            x2, y2 = min(w, x2), min(h, y2)
+
+            # Directly fill per-box region
+            if axis == 0:
+                binary_mask[i, y1:y2, x1:x2] = 1
+            elif axis == 1:
+                binary_mask[y1:y2, i, x1:x2] = 1
+            else:
+                binary_mask[y1:y2, x1:x2, i] = 1
+
+    if verbose:
+        # Print statistics
+        tumor_voxels = np.sum(binary_mask)
+        total_voxels = binary_mask.size
+        tumor_percentage = (tumor_voxels / total_voxels) * 100
+
+        print("Segmentation complete!")
+        print(f"   Total voxels: {total_voxels:,}")
+        print(f"   Tumor voxels: {tumor_voxels:,}")
+        print(f"   Tumor percentage: {tumor_percentage:.2f}%")
+
+    return binary_mask
+
+
+def predict_mask(nifti_path, axis, verbose=False):
+    """
+    Generate a binary tumor mask from a 3D NIfTI image using a trained YOLO model.
+
+    Args:
+        nifti_path (str): Path to the input NIfTI file (e.g., FLAIR image).
+        model_path (str): Path to the trained YOLO model (.pt file).
+        conf_threshold (float): Confidence threshold for detections (default: 0.25).
+        output_path (str, optional): Path to save the output mask. If None, saves next to input.
+
+    Returns:
+        str: Path to the saved binary mask NIfTI file.
+    """
+
+    assert axis in [0, 1, 2], "Axis must be 0 (sagittal), 1 (coronal), or 2 (axial)."
+
+    # Load the NIfTI image
+    nifti = nib.load(nifti_path)
+    data = nifti.get_fdata()
+
+    # Predict the binary mask
+    if verbose:
+        print("Generating tumor mask...")
+    binary_mask = predict(data, axis, verbose)
+
+    return binary_mask
+
+
+def mask2cuboid_array(mask):
+    """ Convert a binary mask to its bounding cuboid mask.
+     Args:
+         mask (np.ndarray): 3D binary mask.
+     Returns:
+         np.ndarray: 3D binary mask of the bounding cuboid.
+     """
+    coords = np.argwhere(mask)
+    minz, miny, minx = coords.min(axis=0)
+    maxz, maxy, maxx = coords.max(axis=0)
+    new_mask = np.zeros_like(mask)
+    new_mask[minz:maxz + 1, miny:maxy + 1, minx:maxx + 1] = 1
+    return new_mask
+
+
+def mask2cuboid_nifti(mask_path, output_path):
+    """ Convert a binary mask NIfTI file to its bounding cuboid mask NIfTI file.
+     Args:
+         mask_path (str): Path to the input binary mask NIfTI file.
+         output_path (str): Path to save the output bounding cuboid mask NIfTI file.
+     Returns:
+         str: Path to the saved bounding cuboid mask NIfTI file.
+     """
+    nifti = nib.load(mask_path)
+    mask = nifti.get_fdata()
+    cuboid_mask = mask2cuboid_array(mask)
+    output_nifti = nib.Nifti1Image(cuboid_mask.astype("uint8"), nifti.affine, nifti.header)
+    nib.save(output_nifti, output_path)
+
+
+def unite_masks_array(*masks, method="union"):
+    """
+    Combine multiple binary masks into one using union or cuboid.
+
+    Args:
+        *masks (np.ndarray): Multiple binary masks to combine.
+        method (str): Method to combine masks ('union' or 'cuboid').
+    Returns:
+        np.ndarray: Combined binary mask.
+    """
+    if method == "union":
+        return np.clip(sum(masks), 0, 1)
+    elif method == "cuboid":
+        combined_mask = np.clip(sum(masks), 0, 1)
+        return mask2cuboid_array(combined_mask)
+    else:
+        raise ValueError(f"Unknown combine method: {method}")
+
+
+def unite_masks_nifti(mask_paths, output_path, method="union"):
+    """
+    Combine multiple binary mask NIfTI files into one using union or cuboid.
+
+    Args:
+        mask_paths (list of str): Paths to the input binary mask NIfTI files.
+        output_path (str): Path to save the output combined mask NIfTI file.
+        method (str): Method to combine masks ('union' or 'cuboid').
+    Returns:
+        str: Path to the saved combined binary mask NIfTI file.
+    """
+    masks = []
+    for path in mask_paths:
+        nifti = nib.load(path)
+        mask = nifti.get_fdata()
+        masks.append(mask)
+
+    combined_mask = unite_masks_array(*masks, method=method)
+    output_nifti = nib.Nifti1Image(combined_mask.astype("uint8"), nifti.affine, nifti.header)
+    nib.save(output_nifti, output_path)

neuroslice/utils.py

@@ -0,0 +1,30 @@
+from huggingface_hub import hf_hub_download
+from huggingface_hub.utils import disable_progress_bars
+
+
+def download_model(axis, verbose):
+    """ Download the YOLO model for the specified direction from Hugging Face Hub.
+     Args:
+         direction (str): Direction of slices ('coronal', 'sagittal', 'axial').
+         verbose (bool): Whether to show download progress.
+     Returns:
+         str: Path to the downloaded model file.
+     """
+
+    assert axis in [0, 1, 2], "Axis must be 0 (sagittal), 1 (coronal), or 2 (axial)."
+    if axis == 0:
+        direction = "sagittal"
+    elif axis == 1:
+        direction = "coronal"
+    elif axis == 2:
+        direction = "axial"
+
+    if not verbose:
+        disable_progress_bars()
+    if verbose:
+        print("Downloading model...")
+    model_path = hf_hub_download(
+        repo_id="anamatoso/neuroslice",
+        filename=f"models/{direction}_best.pt",
+    )
+    return model_path

neuroslice-0.0.1.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.1
+Name: neuroslice
+Version: 0.0.1
+Summary: Slice-wise brain tumor detection and 3D mask reconstruction from MRI
+Author-email: Alice Matoso <alice@example.com>, Bob Silva <bob@example.com>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: torch
+Requires-Dist: nibabel
+Requires-Dist: numpy
+Requires-Dist: ultralytics
+Requires-Dist: tqdm
+Requires-Dist: opencv-python
+Requires-Dist: huggingface-hub
+
+# Neuroslice
+
+A Python package for brain tumor segmentation using YOLO models on MRI FLAIR data.
+
+## Table of Contents
+
+- [Description](#description)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Command Line Interface](#command-line-interface)
+  - [Python API](#python-api)
+- [Contributing](#contributing)
+- [Citation](#citation)
+
+## Description
+
+Neuroslice provides automated brain tumor bounding box detection using pre-trained YOLO models. It uses FLAIR images to segment slice wise the image, though an option to create a cuboid is available.
+The package supports three slice orientations (coronal, sagittal, and axial).
+Models are automatically downloaded from [Hugging Face](https://huggingface.co/anamatoso/neuroslice) when first used.
+
+## Installation
+
+You can install Neuroslice using pip:
+
+```bash
+pip install neuroslice
+```
+
+For development installation:
+
+```bash
+git clone https://github.com/anamatoso/neuroslice.git
+cd neuroslice
+pip install -e .
+```
+
+## Usage
+
+### Command Line Interface
+
+Basic usage with default settings (coronal direction, union mode):
+
+```bash
+neuroslice input.nii.gz output_mask.nii.gz
+```
+
+Specify slice direction and processing mode:
+
+```bash
+neuroslice input.nii.gz output_mask.nii.gz --direction 2 --mode cuboid --verbose
+```
+
+**Arguments:**
+
+Mandatory:
+
+- `input`: Path to input NIfTI file (.nii or .nii.gz)
+- `output`: Path to output mask NIfTI file
+
+Optional:
+
+- `--direction`: Slice direction - 0 (sagittal), 1 (coronal, default), 2 (axial)
+- `--mode`: Processing mode - `union` (default) or `cuboid` (bounding box)
+- `--verbose`: Print details
+
+### Python API
+
+**Generate a tumor mask:**
+
+```python
+from neuroslice import predict_mask
+import nibabel as nib
+
+# Generate mask from NIfTI file
+mask = predict_mask("input.nii.gz", 1, verbose=True)
+
+# Save the mask
+nifti = nib.load("input.nii.gz")
+output = nib.Nifti1Image(mask.astype("uint8"), nifti.affine, nifti.header)
+nib.save(output, "output_mask.nii.gz")
+```
+
+**Convert mask to bounding cuboid:**
+
+```python
+from neuroslice import mask2cuboid_array, mask2cuboid_nifti
+
+# From array
+cuboid_mask = mask2cuboid_array(mask)
+
+# From NIfTI file
+mask2cuboid_nifti("mask.nii.gz", "cuboid_mask.nii.gz")
+```
+
+**Combine multiple masks:**
+
+```python
+from neuroslice import unite_masks_array, unite_masks_nifti
+
+# Combine arrays
+combined = unite_masks_array(mask1, mask2, mask3, method="union")
+
+# Combine NIfTI files
+unite_masks_nifti(
+    ["mask1.nii.gz", "mask2.nii.gz", "mask3.nii.gz"],
+    "combined_mask.nii.gz",
+    method="cuboid"
+)
+```
+
+**Advanced usage with direct predict function:**
+
+```python
+from neuroslice import predict
+from ultralytics import YOLO
+import nibabel as nib
+
+# Load your data
+nifti = nib.load("input.nii.gz")
+data = nifti.get_fdata()
+
+# Generate mask with custom axis 
+mask = predict(data, axis=0, verbose=True)
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+1. Fork the repository
+2. Create your branch (`git checkout -b feature/AmazingFeature`)
+3. Add your changes to the branch
+4. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+5. Push to the branch (`git push origin feature/AmazingFeature`)
+6. Open a Pull Request
+
+## Citation
+
+If you use Neuroslice in your research, please cite:
+
+TBD
+
+<!-- ```bibtex
+@software{neuroslice,
+  title = {Neuroslice: Brain Tumor Segmentation using YOLO},
+  author = {Your Name},
+  year = {2024},
+  url = {https://github.com/yourusername/neuroslice}
+}
+``` -->

neuroslice-0.0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+neuroslice/__init__.py,sha256=cSNDBiF6kgUiOZhVSinoMOFgHhQlIMxV0OPQY-88vMA,266
+neuroslice/cli.py,sha256=Bwt1GUtgtP_VML5QoDMuyKTExNhmhJY3QT-xQZ4GOss,1696
+neuroslice/core.py,sha256=NYMt3lobbYWihQAptpIn3-UHf01wxlVs7m0pGNtjpLU,6542
+neuroslice/utils.py,sha256=unpNY-NbvXHZeW-OW_4WPIOmk1dHjCDxxE7EnMaZZ0I,934
+neuroslice-0.0.1.dist-info/METADATA,sha256=dlco1Y5KW9qfeWzFy7mqoHHfli5wP-dwsPK1WqmsMuw,4013
+neuroslice-0.0.1.dist-info/WHEEL,sha256=iAkIy5fosb7FzIOwONchHf19Qu7_1wCWyFNR5gu9nU0,91
+neuroslice-0.0.1.dist-info/entry_points.txt,sha256=1DBEBQCLeAluB89ipJVF4k4-IzYxINndMI0U9ZgaG0I,51
+neuroslice-0.0.1.dist-info/top_level.txt,sha256=cuV5qXnoXz7p9NOz70Ty7aQ-G87XIFa0U0hazgn_WbU,11
+neuroslice-0.0.1.dist-info/RECORD,,

neuroslice-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.3.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

neuroslice-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+neuroslice = neuroslice.cli:main

neuroslice-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+neuroslice