PyNutil 0.4.2__tar.gz → 0.5.1__tar.gz

{pynutil-0.4.2 → pynutil-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyNutil
-Version: 0.4.2
+Version: 0.5.1
 Summary: a package to quantify atlas registered brain data
 Home-page: https://github.com/Neural-Systems-at-UIO/PyNutil
 License: MIT
@@ -15,6 +15,7 @@ Requires-Dist: opencv-python
 Requires-Dist: scipy
 Requires-Dist: nibabel
 Requires-Dist: orjson
+Requires-Dist: tqdm
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page

{pynutil-0.4.2 → pynutil-0.5.1}/PyNutil/config.py

@@ -9,6 +9,7 @@ from typing import Any, Dict, Optional
 class PyNutilConfig:
     segmentation_folder: Optional[str] = None
     image_folder: Optional[str] = None
+    coordinate_file: Optional[str] = None
     alignment_json: Optional[str] = None
     colour: Optional[list] = None
     intensity_channel: Optional[str] = None
@@ -39,6 +40,7 @@ class PyNutilConfig:
         cfg = cls(
             segmentation_folder=settings.get("segmentation_folder"),
             image_folder=settings.get("image_folder"),
+            coordinate_file=settings.get("coordinate_file"),
             alignment_json=settings["alignment_json"],
             colour=settings.get("colour"),
             intensity_channel=settings.get("intensity_channel"),
@@ -77,9 +79,13 @@ class PyNutilConfig:
         self._validate_atlas()
 
     def _validate_folders(self) -> None:
-        if self.segmentation_folder and self.image_folder:
+        input_count = sum(
+            bool(x)
+            for x in [self.segmentation_folder, self.image_folder, self.coordinate_file]
+        )
+        if input_count > 1:
             raise ValueError(
-                "Please specify either segmentation_folder or image_folder, not both."
+                "Please specify only one of segmentation_folder, image_folder, or coordinate_file."
             )
 
         if self.segmentation_folder and (

{pynutil-0.4.2 → pynutil-0.5.1}/PyNutil/context.py

@@ -57,6 +57,7 @@ class PipelineContext:
     use_flat: bool
     pixel_id: object
     apply_damage_mask: bool
+    flat_label_path: Optional[str] = None
     intensity_channel: Optional[str] = None
     min_intensity: Optional[int] = None
     max_intensity: Optional[int] = None

{pynutil-0.4.2 → pynutil-0.5.1}/PyNutil/io/loaders.py

@@ -321,3 +321,37 @@ def get_current_flat_file(seg_nr, flat_files, flat_file_nrs, use_flat):
         current_flat_file_index = np.where([f == seg_nr for f in flat_file_nrs])
         return flat_files[current_flat_file_index[0][0]]
     return None
+
+
+# ---------------------------------------------------------------------------
+# Coordinate file loading
+# ---------------------------------------------------------------------------
+
+_COORDINATE_REQUIRED_COLUMNS = {"X", "Y", "image_width", "image_height", "section number"}
+
+
+def load_coordinate_file(path: str) -> pd.DataFrame:
+    """Load a coordinate CSV file.
+
+    The CSV must contain columns: X, Y, image_width, image_height, section number.
+    Coordinates are in image space and will be transformed to atlas space
+    by the coordinate pipeline.
+
+    Parameters
+    ----------
+    path : str
+        Path to the CSV file.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with coordinate data.
+    """
+    df = pd.read_csv(path)
+    missing = _COORDINATE_REQUIRED_COLUMNS - set(df.columns)
+    if missing:
+        raise ValueError(
+            f"Coordinate file is missing required columns: {missing}. "
+            f"Expected: {_COORDINATE_REQUIRED_COLUMNS}"
+        )
+    return df

{pynutil-0.4.2 → pynutil-0.5.1}/PyNutil/io/section_visualisation.py

@@ -5,7 +5,7 @@ Generates colored atlas slice PNGs and optionally overlays segmentation pixels.
 
 import os
 from typing import Dict, List, Tuple, Optional, Union
-
+from tqdm import tqdm
 import cv2
 import numpy as np
 import pandas as pd
@@ -283,7 +283,7 @@ def create_section_visualisations(
     color_lookup = _build_color_lookup(atlas_labels)
 
     slices = alignment_json.get("slices", [])
-    for i, slice_dict in enumerate(slices):
+    for i, slice_dict in tqdm(enumerate(slices), total = len(slices), desc="saving atlas images"):
         try:
             filename = slice_dict.get("filename", "")
             base_name = os.path.splitext(filename)[0] if filename else f"slice_{i:03d}"
@@ -314,6 +314,5 @@ def create_section_visualisations(
                 _color_lookup=color_lookup,
             )
 
-            print(f"Created visualisation: {output_filename}")
         except Exception as e:
             print(f"Error creating visualisation for slice {i}: {e}")

{pynutil-0.4.2 → pynutil-0.5.1}/PyNutil/main.py

@@ -17,6 +17,7 @@ from .io.loaders import open_custom_region_file
 from .processing.pipeline.batch_processor import (
     folder_to_atlas_space,
     folder_to_atlas_space_intensity,
+    file_to_atlas_space_coordinates,
 )
 from .io.volume_nifti import save_volume_niftis
 from .processing.section_volume import (
@@ -35,7 +36,15 @@ class _BinaryMode:
     """Binary / Cellpose segmentation pipeline."""
 
     @staticmethod
-    def get_coordinates(ctx, *, non_linear, object_cutoff, use_flat, apply_damage_mask):
+    def get_coordinates(
+        ctx,
+        *,
+        non_linear,
+        object_cutoff,
+        use_flat,
+        apply_damage_mask,
+        flat_label_path,
+    ):
         (
             ctx.pixel_points,
             ctx.centroids,
@@ -62,6 +71,7 @@ class _BinaryMode:
             ctx.hemi_map,
             use_flat,
             apply_damage_mask,
+            flat_label_path=flat_label_path,
             segmentation_format=ctx.segmentation_format,
         )
         ctx.apply_damage_mask = apply_damage_mask
@@ -104,7 +114,15 @@ class _IntensityMode:
     """Image intensity quantification pipeline."""
 
     @staticmethod
-    def get_coordinates(ctx, *, non_linear, object_cutoff, use_flat, apply_damage_mask):
+    def get_coordinates(
+        ctx,
+        *,
+        non_linear,
+        object_cutoff,
+        use_flat,
+        apply_damage_mask,
+        flat_label_path,
+    ):
         (
             ctx.region_intensities_list,
             ctx.segmentation_filenames,
@@ -123,6 +141,7 @@ class _IntensityMode:
             ctx.hemi_map,
             use_flat,
             apply_damage_mask,
+            flat_label_path=flat_label_path,
             min_intensity=ctx.min_intensity,
             max_intensity=ctx.max_intensity,
         )
@@ -142,6 +161,79 @@ class _IntensityMode:
         return quantify_intensity(ctx.region_intensities_list, ctx.atlas_labels)
 
 
+class _CoordinateMode:
+    """Pre-extracted coordinate data pipeline."""
+
+    @staticmethod
+    def get_coordinates(
+        ctx,
+        *,
+        non_linear,
+        object_cutoff,
+        use_flat,
+        apply_damage_mask,
+        flat_label_path,
+    ):
+        (
+            ctx.pixel_points,
+            ctx.centroids,
+            ctx.points_labels,
+            ctx.centroids_labels,
+            ctx.points_hemi_labels,
+            ctx.centroids_hemi_labels,
+            ctx.region_areas_list,
+            ctx.points_len,
+            ctx.centroids_len,
+            ctx.per_point_undamaged,
+            ctx.per_centroid_undamaged,
+            ctx.total_points_len,
+            ctx.total_centroids_len,
+        ) = file_to_atlas_space_coordinates(
+            ctx.coordinate_file,
+            ctx.alignment_json,
+            ctx.atlas_labels,
+            non_linear,
+            ctx.atlas_volume,
+            ctx.hemi_map,
+            apply_damage_mask,
+        )
+        ctx.segmentation_filenames = []
+        ctx.apply_damage_mask = apply_damage_mask
+        if ctx.custom_regions_dict is not None:
+            ctx.points_custom_labels = map_to_custom_regions(
+                ctx.custom_regions_dict, ctx.points_labels
+            )
+            ctx.centroids_custom_labels = map_to_custom_regions(
+                ctx.custom_regions_dict, ctx.centroids_labels
+            )
+
+    @staticmethod
+    def quantify(ctx):
+        if not hasattr(ctx, "pixel_points") and not hasattr(ctx, "centroids"):
+            raise ValueError(
+                "Please run get_coordinates before running quantify_coordinates."
+            )
+        points = PerEntityArrays(
+            labels=ctx.points_labels,
+            hemi_labels=ctx.points_hemi_labels,
+            undamaged=ctx.per_point_undamaged,
+            section_lengths=ctx.total_points_len,
+        )
+        centroids = PerEntityArrays(
+            labels=ctx.centroids_labels,
+            hemi_labels=ctx.centroids_hemi_labels,
+            undamaged=ctx.per_centroid_undamaged,
+            section_lengths=ctx.total_centroids_len,
+        )
+        return quantify_labeled_points(
+            points,
+            centroids,
+            ctx.region_areas_list,
+            ctx.atlas_labels,
+            ctx.apply_damage_mask,
+        )
+
+
 def _apply_custom_regions_to_quantification(ctx):
     """Shared post-quantification step: remap to custom regions if configured."""
     if ctx.custom_regions_dict is not None:
@@ -176,6 +268,7 @@ class PyNutil:
         self,
         segmentation_folder=None,
         image_folder=None,
+        coordinate_file=None,
         alignment_json=None,
         colour=None,
         intensity_channel=None,
@@ -243,6 +336,7 @@ class PyNutil:
             cfg = PyNutilConfig(
                 segmentation_folder=segmentation_folder,
                 image_folder=image_folder,
+                coordinate_file=coordinate_file,
                 alignment_json=alignment_json,
                 colour=colour,
                 intensity_channel=intensity_channel,
@@ -262,6 +356,7 @@ class PyNutil:
 
         self.segmentation_folder = cfg.segmentation_folder
         self.image_folder = cfg.image_folder
+        self.coordinate_file = cfg.coordinate_file
         self.alignment_json = cfg.alignment_json
         self.colour = cfg.colour
         self.intensity_channel = cfg.intensity_channel
@@ -290,7 +385,12 @@ class PyNutil:
         self.point_intensities = None
 
         # Select the quantification strategy based on the input mode (OCP)
-        self._mode = _IntensityMode() if self.image_folder else _BinaryMode()
+        if self.coordinate_file:
+            self._mode = _CoordinateMode()
+        elif self.image_folder:
+            self._mode = _IntensityMode()
+        else:
+            self._mode = _BinaryMode()
 
     def _load_atlas_data(self, cfg):
         """Load atlas volume, hemisphere map, and labels from config."""
@@ -330,6 +430,7 @@ class PyNutil:
         object_cutoff=0,
         use_flat=False,
         apply_damage_mask=True,
+        flat_label_path=None,
     ):
         """
         Retrieves pixel and centroid coordinates from segmentation data,
@@ -342,6 +443,8 @@ class PyNutil:
             object_cutoff (int, optional): Minimum object size.
             use_flat (bool, optional): Use flat maps if True.
             apply_damage_mask (bool, optional): Apply damage mask if True.
+            flat_label_path (str, optional): Path to flatmap region-id lookup
+                file (.csv or .label) used when flat files store indexed labels.
 
         Returns:
             None: Results are stored in class attributes.
@@ -352,6 +455,7 @@ class PyNutil:
             object_cutoff=object_cutoff,
             use_flat=use_flat,
             apply_damage_mask=apply_damage_mask,
+            flat_label_path=flat_label_path,
         )
 
     def quantify_coordinates(self):

{pynutil-0.4.2 → pynutil-0.5.1}/PyNutil/processing/__init__.py

@@ -56,8 +56,6 @@ from .adapters import (
     QuintAnchoringLoader,
     VisuAlignDeformationProvider,
     QCAlignDamageProvider,
-    # Custom deformation support
-    DisplacementFieldProvider,
     # Registry
     AnchoringLoaderRegistry,
     # Main entry point

{pynutil-0.4.2 → pynutil-0.5.1}/PyNutil/processing/adapters/__init__.py

@@ -18,11 +18,6 @@ Example:
     # Linear only (no deformation)
     data = load_registration("quicknii.json", apply_deformation=False)
 
-    # Custom deformation
-    from PyNutil.processing.adapters import DisplacementFieldProvider
-    data = load_registration(
-        "quicknii.json",
-        deformation_provider=DisplacementFieldProvider("field.npy")
     )
 """
 
@@ -44,7 +39,6 @@ from .anchoring import (
 # Deformation providers
 from .deformation import (
     VisuAlignDeformationProvider,
-    DisplacementFieldProvider,
 )
 
 # Damage providers
@@ -86,7 +80,6 @@ __all__ = [
     "QuintAnchoringLoader",
     # Deformation
     "VisuAlignDeformationProvider",
-    "DisplacementFieldProvider",
     # Damage
     "QCAlignDamageProvider",
     # Registry

pynutil-0.5.1/PyNutil/processing/adapters/anchoring.py

@@ -0,0 +1,204 @@
+"""Anchoring loaders for loading linear registration data.
+
+Anchoring loaders extract the basic slice information and linear
+transformation (anchoring) from registration files.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import re
+from typing import List
+
+import numpy as np
+
+from .base import AnchoringLoader, RegistrationData, SliceInfo
+
+
+class QuintAnchoringLoader(AnchoringLoader):
+    """Loads anchoring from QUINT JSON files (QuickNII, DeepSlice, VisuAlign).
+
+    This loader extracts only the linear registration (anchoring).
+    Non-linear deformation and damage are handled by separate providers.
+    """
+
+    name: str = "quint"
+    file_extensions: List[str] = [".json"]
+
+    def load(self, path: str) -> RegistrationData:
+        """Load anchoring from a QUINT JSON file."""
+        import json
+
+        with open(path, "r") as f:
+            data = json.load(f)
+
+        slices = []
+        for s in data.get("slices", []):
+            anchoring = s.get("anchoring", [])
+            if not anchoring:
+                continue
+
+            slices.append(
+                SliceInfo(
+                    section_id=s.get("filename", str(s.get("nr", 0))),
+                    section_number=s.get("nr", 0),
+                    width=s.get("width", 0),
+                    height=s.get("height", 0),
+                    anchoring=anchoring,
+                    deformation=None,  # Added by DeformationProvider
+                    damage_mask=None,  # Added by DamageProvider
+                    metadata={
+                        "filename": s.get("filename"),
+                        # Store raw data for providers to use
+                        "_raw_slice": s,
+                    },
+                )
+            )
+
+        return RegistrationData(
+            slices=slices,
+            grid_spacing=data.get("gridspacing"),
+            metadata={
+                "target": data.get("target"),
+                "target-resolution": data.get("target-resolution"),
+                "propagate": data.get("propagate", False),
+                "_raw_data": data,  # Keep for providers
+            },
+        )
+
+
+class BrainGlobeRegistrationLoader(AnchoringLoader):
+    """Loads anchoring from brainglobe-registration output JSON.
+
+    Converts ``atlas_slice_corners`` (in microns) to a QuickNII-compatible
+    anchoring vector by:
+    1. Converting microns to atlas voxels using the atlas resolution.
+    2. Transforming from BrainGlobe orientation to PyNutil orientation
+       (which applies ``transpose([2,0,1])[::-1,::-1,::-1]``).
+    3. Computing O, U, V vectors from the TL, TR, BL corners.
+    """
+
+    name: str = "brainglobe"
+    file_extensions: List[str] = [".json"]
+
+    @classmethod
+    def can_handle(cls, path: str) -> bool:
+        """Detect brainglobe-registration JSON by looking for atlas_slice_corners."""
+        import json
+
+        if not path.endswith(".json"):
+            return False
+        try:
+            with open(path, "r") as f:
+                data = json.load(f)
+            return "atlas_slice_corners" in data
+        except Exception:
+            return False
+
+    @staticmethod
+    def _infer_resolution(atlas_name: str) -> float:
+        """Extract voxel resolution in microns from the atlas name."""
+        m = re.search(r"(\d+(?:\.\d+)?)um$", atlas_name)
+        if not m:
+            raise ValueError(
+                f"Cannot infer resolution from atlas name '{atlas_name}'. "
+                "Expected a name ending in '<number>um' (e.g. 'allen_mouse_25um')."
+            )
+        return float(m.group(1))
+
+    @staticmethod
+    def _get_atlas_shape(atlas_name: str):
+        """Return the native (un-reoriented) atlas annotation shape."""
+        import brainglobe_atlasapi
+
+        bg = brainglobe_atlasapi.BrainGlobeAtlas(atlas_name=atlas_name)
+        return bg.annotation.shape  # (AP, DV, LR)
+
+    @staticmethod
+    def _bg_to_pynutil(corners_vx: np.ndarray, bg_shape) -> np.ndarray:
+        """Convert BrainGlobe voxel coords to PyNutil atlas coords.
+
+        PyNutil reorients the atlas via ``transpose([2,0,1])[::-1,::-1,::-1]``.
+        Given BrainGlobe coords ``(bg0, bg1, bg2)`` (AP, DV, LR) and the
+        original annotation shape ``(S0, S1, S2)``, the PyNutil coords are:
+            px = (S2 - 1) - bg2
+            py = (S0 - 1) - bg0
+            pz = (S1 - 1) - bg1
+        """
+        pn = np.zeros_like(corners_vx)
+        pn[:, 0] = (bg_shape[2] - 1) - corners_vx[:, 2]
+        pn[:, 1] = (bg_shape[0] - 1) - corners_vx[:, 0]
+        pn[:, 2] = (bg_shape[1] - 1) - corners_vx[:, 1]
+        return pn
+
+    @staticmethod
+    def _find_tiff_dims(reg_dir: str):
+        """Read the dimensions of one of the output TIFFs in *reg_dir*."""
+        import tifffile
+
+        for name in ("downsampled.tiff", "registered_atlas.tiff", "registered_hemispheres.tiff"):
+            p = os.path.join(reg_dir, name)
+            if os.path.isfile(p):
+                img = tifffile.imread(p)
+                return img.shape[0], img.shape[1]  # (height, width)
+        return None, None
+
+    def load(self, path: str) -> RegistrationData:
+        """Load anchoring from a brainglobe-registration JSON."""
+        import json
+
+        with open(path, "r") as f:
+            data = json.load(f)
+
+        atlas_name = data["atlas"]
+        corners_um = np.array(data["atlas_slice_corners"], dtype=np.float64)
+        resolution = self._infer_resolution(atlas_name)
+        corners_vx = corners_um / resolution
+
+        bg_shape = self._get_atlas_shape(atlas_name)
+        pn_corners = self._bg_to_pynutil(corners_vx, bg_shape)
+
+        # TL, TR, BL, BR
+        O = pn_corners[0]
+        U = pn_corners[1] - pn_corners[0]
+        V = pn_corners[2] - pn_corners[0]
+        anchoring = O.tolist() + U.tolist() + V.tolist()
+
+        width = int(math.floor(math.hypot(*U))) + 1
+        height = int(math.floor(math.hypot(*V))) + 1
+
+        reg_dir = os.path.dirname(os.path.abspath(path))
+        tiff_h, tiff_w = self._find_tiff_dims(reg_dir)
+
+        section_number = data.get("atlas_2d_slice_index", 0)
+
+        slices = [
+            SliceInfo(
+                section_id=str(section_number),
+                section_number=section_number,
+                width=width,
+                height=height,
+                anchoring=anchoring,
+                deformation=None,
+                damage_mask=None,
+                metadata={
+                    "registration_type": "brainglobe",
+                    "registration_dir": reg_dir,
+                    "atlas_name": atlas_name,
+                    "resolution_um": resolution,
+                    "bg_atlas_shape": bg_shape,
+                    "tiff_width": tiff_w,
+                    "tiff_height": tiff_h,
+                },
+            )
+        ]
+
+        return RegistrationData(
+            slices=slices,
+            metadata={
+                "registration_type": "brainglobe",
+                "atlas_name": atlas_name,
+                "_raw_data": data,
+            },
+        )