siibra 1.0a19__py3-none-any.whl → 1.0.1a1__py3-none-any.whl

siibra/volumes/providers/neuroglancer.py

@@ -1,4 +1,4 @@
-# Copyright 2018-2024
+# Copyright 2018-2025
 # Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
 
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -37,6 +37,37 @@ from typing import Union, Dict, Tuple
 import json
 
 
+def shift_ng_transfrom(
+    transform_nm: np.ndarray, scale_resolution_nm: np.ndarray, max_resolution_nm: np.ndarray
+) -> np.ndarray:
+    """
+    Helper method to get nifti standard affine.
+
+    transfrorm.json stored with neuroglancer precomputed images and meshes
+    are meant to be used for neuroglancer viewers and hence they are not
+    representative of the affine in other tools. This method shifts back
+    half a voxel in each axis.
+    (see https://neuroglancer-scripts.readthedocs.io/en/latest/neuroglancer-info.html#different-conventions-for-coordinate-transformations)
+
+    Parameters
+    ----------
+    transform_nm: np.ndarray
+        Transform array created for displaying an image correctly from
+        neuroglancer precomputed format in neuroglancer viewer.
+    max_resolution_nm: np.ndarray
+        The voxel resolution of the highest level of resolution.
+
+    Returns
+    -------
+    np.ndarray
+        Standard affine in nm
+    """
+    scaling = np.diag(np.r_[scale_resolution_nm, 1.0])
+    affine = np.dot(transform_nm, scaling)
+    affine[:3, 3] += (max_resolution_nm * 0.5)
+    return affine
+
+
 class NeuroglancerProvider(_provider.VolumeProvider, srctype="neuroglancer/precomputed"):
 
     def __init__(self, url: Union[str, Dict[str, str]]):
@@ -128,28 +159,22 @@ class NeuroglancerProvider(_provider.VolumeProvider, srctype="neuroglancer/preco
                 label = None
             if label is not None:
                 result = nib.Nifti1Image(
-                    (result.get_fdata() == label).astype('uint8'),
-                    result.affine
+                    (np.asanyarray(result.dataobj) == label).astype('uint8'),
+                    result.affine,
+                    dtype='uint8',
                 )
 
         return result
 
-    def get_boundingbox(self, clip=False, background=0, **fetch_kwargs) -> "_boundingbox.BoundingBox":
+    def get_boundingbox(self, **fetch_kwargs) -> "_boundingbox.BoundingBox":
         """
         Return the bounding box in physical coordinates of the union of
         fragments in this neuroglancer volume.
 
         Parameters
         ----------
-        clip: bool, default: True
-            Whether to clip the background of the volume.
-        background: float, default: 0.0
-            The background value to clip.
-            Note
-            ----
-            To use it, clip must be True.
         fetch_kwargs:
-            key word arguments that are used for fetchin volumes,
+            key word arguments that are used for fetching volumes,
             such as voi or resolution_mm.
         """
         bbox = None
@@ -159,23 +184,17 @@ class NeuroglancerProvider(_provider.VolumeProvider, srctype="neuroglancer/preco
                     f"N-D Neuroglancer volume has shape {frag.shape}, but "
                     f"bounding box considers only {frag.shape[:3]}"
                 )
-            if clip:
-                img = frag.fetch(**fetch_kwargs)
-                next_bbox = _boundingbox.from_array(
-                    np.asanyarray(img.dataobj), threshold=background, space=None
-                ).transform(img.affine)  # use the affine of the image matching fetch_kwargs
+            resolution_mm = fetch_kwargs.get("resolution_mm")
+            if resolution_mm is None:
+                affine = frag.affine
+                shape = frag.shape[:3]
             else:
-                resolution_mm = fetch_kwargs.get("resolution_mm")
-                if resolution_mm is None:
-                    affine = frag.affine
-                    shape = frag.shape[:3]
-                else:
-                    scale = frag._select_scale(resolution_mm=resolution_mm)
-                    affine = scale.affine
-                    shape = scale.size[:3]
-                next_bbox = _boundingbox.BoundingBox(
-                    (0, 0, 0), shape, space=None
-                ).transform(affine)
+                scale = frag._select_scale(resolution_mm=resolution_mm)
+                affine = scale.affine
+                shape = scale.size[:3]
+            next_bbox = _boundingbox.BoundingBox(
+                (0, 0, 0), shape, space=None
+            ).transform(affine)
             bbox = next_bbox if bbox is None else bbox.union(next_bbox)
         return bbox
 
@@ -246,7 +265,11 @@ class NeuroglancerVolume:
         self._io: PrecomputedIO = None
 
     @property
-    def transform_nm(self):
+    def transform_nm(self) -> np.ndarray:
+        """
+        This is the transformation matrix created to cater neuroglancer viewer
+        for a neuroglancer precomputed images.
+        """
         if self._transform_nm is not None:
             return self._transform_nm
         try:
@@ -326,7 +349,7 @@ class NeuroglancerVolume:
     ):
         # the caller has to make sure voi is defined in the correct reference space
         scale = self._select_scale(resolution_mm=resolution_mm, bbox=voi, max_bytes=max_bytes)
-        return scale.fetch(voi=voi)
+        return scale.fetch(voi=voi, **kwargs)
 
     def get_shape(self, resolution_mm=None, max_bytes: float = MAX_BYTES):
         scale = self._select_scale(resolution_mm=resolution_mm, max_bytes=max_bytes)
@@ -399,7 +422,7 @@ class NeuroglancerScale:
         return self.res_nm / 1e6
 
     def resolves(self, resolution_mm):
-        """Test wether the resolution of this scale is sufficient to provide the given resolution."""
+        """Test whether the resolution of this scale is sufficient to provide the given resolution."""
         return all(r / 1e6 <= resolution_mm for r in self.res_nm)
 
     def __lt__(self, other):
@@ -445,10 +468,13 @@ class NeuroglancerScale:
 
     @property
     def affine(self):
-        scaling = np.diag(np.r_[self.res_nm, 1.0])
-        affine = np.dot(self.volume.transform_nm, scaling)
-        affine[:3, :] /= 1e6
-        return affine
+        affine_ = shift_ng_transfrom(
+            transform_nm=self.volume.transform_nm,
+            scale_resolution_nm=self.res_nm,
+            max_resolution_nm=self.volume.scales[0].res_nm[0],
+        )
+        affine_[:3, :] /= 1e6
+        return affine_
 
     def _point_to_lower_chunk_idx(self, xyz):
         return (
@@ -508,9 +534,9 @@ class NeuroglancerScale:
         for dim in range(3):
             if bbox_.shape[dim] < 1:
                 logger.warning(
-                    f"Bounding box in voxel space will be enlarged to voxel size 1 along axis {dim}."
+                    f"Bounding box in voxel space will be enlarged to by {self.res_mm[dim]} along axis {dim}."
                 )
-                bbox_.maxpoint[dim] = bbox_.maxpoint[dim] + 1
+                bbox_.maxpoint[dim] = bbox_.maxpoint[dim] + self.res_mm[dim]
 
         # extract minimum and maximum the chunk indices to be loaded
         gx0, gy0, gz0 = self._point_to_lower_chunk_idx(tuple(bbox_.minpoint))
@@ -533,7 +559,7 @@ class NeuroglancerScale:
         # exact bounding box requested, to cut off undesired borders
         data_min = np.array([gx0, gy0, gz0]) * self.chunk_sizes
         x0, y0, z0 = (np.array(bbox_.minpoint) - data_min).astype("int")
-        xd, yd, zd = np.ceil((np.array(bbox_.maxpoint))).astype(int) - np.floor((np.array(bbox_.minpoint))).astype(int)  # TODO: consider 0.5 voxel shift
+        xd, yd, zd = np.ceil((np.array(bbox_.maxpoint))).astype(int) - np.floor((np.array(bbox_.minpoint))).astype(int)
         offset = tuple(bbox_.minpoint)
 
         # build the nifti image
@@ -552,7 +578,7 @@ class NeuroglancerMesh(_provider.VolumeProvider, srctype="neuroglancer/precompme
 
     @staticmethod
     def _fragmentinfo(url: str) -> Dict[str, Union[str, np.ndarray, Dict]]:
-        """ Prepare basic mesh fragment information from url. """
+        """Prepare basic mesh fragment information from url."""
         return {
             "url": url,
             "transform_nm": np.array(requests.HttpRequest(f"{url}/transform.json").data),
@@ -568,7 +594,7 @@ class NeuroglancerMesh(_provider.VolumeProvider, srctype="neuroglancer/precompme
         elif isinstance(resource, dict):
             self._meshes = {n: self._fragmentinfo(u) for n, u in resource.items()}
         else:
-            raise ValueError(f"Resource specificaton not understood for {self.__class__.__name__}: {resource}")
+            raise ValueError(f"Resource specification not understood for {self.__class__.__name__}: {resource}")
 
     @property
     def _url(self) -> Union[str, Dict[str, str]]:
@@ -609,7 +635,7 @@ class NeuroglancerMesh(_provider.VolumeProvider, srctype="neuroglancer/precompme
                 result[name] = (f"{spec['url']}/{mesh_key}/{fragment_names[0]}", transform)
             else:
                 # only one mesh was configures, so we might still
-                # see muliple fragments under the mesh url
+                # see multiple fragments under the mesh url
                 for fragment_name in fragment_names:
                     result[fragment_name] = (f"{spec['url']}/{mesh_key}/{fragment_name}", transform)
 

siibra/volumes/providers/nifti.py

@@ -1,4 +1,4 @@
-# Copyright 2018-2024
+# Copyright 2018-2025
 # Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
 
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -17,7 +17,7 @@ from . import provider as _provider
 
 from ...commons import logger, resample_img_to_img
 from ...retrieval import requests
-from ...locations import pointset, boundingbox as _boundingbox
+from ...locations import pointcloud, boundingbox as _boundingbox
 
 from typing import Union, Dict, Tuple
 import nibabel as nib
@@ -65,28 +65,16 @@ class NiftiProvider(_provider.VolumeProvider, srctype="nii"):
     def fragments(self):
         return [k for k in self._img_loaders if k is not None]
 
-    def get_boundingbox(self, clip=True, background=0., **fetch_kwargs) -> "_boundingbox.BoundingBox":
+    def get_boundingbox(self, **fetch_kwargs) -> "_boundingbox.BoundingBox":
         """
         Return the bounding box in physical coordinates of the union of
         fragments in this nifti volume.
 
         Parameters
         ----------
-        clip : bool, default: True
-            Whether to clip the background of the volume.
-        background : float, default: 0.0
-            The background value to clip.
-            Note
-            ----
-            To use it, clip must be True.
         fetch_kwargs:
             Not used
         """
-        if fetch_kwargs:
-            logger.warning(
-                "`volume.fetch()` keyword arguments supplied. Nifti volumes"
-                " cannot pass them for bounding box calculation."
-            )
         bbox = None
         for loader in self._img_loaders.values():
             img = loader()
@@ -95,19 +83,17 @@ class NiftiProvider(_provider.VolumeProvider, srctype="nii"):
                     f"N-D NIfTI volume has shape {img.shape}, but "
                     f"bounding box considers only {img.shape[:3]}"
                 )
-            if clip:
-                next_bbox = _boundingbox.from_array(
-                    np.asanyarray(img.dataobj), threshold=background, space=None
-                ).transform(img.affine)
-            else:
-                shape = img.shape[:3]
-                next_bbox = _boundingbox.BoundingBox(
-                    (0, 0, 0), shape, space=None
-                ).transform(img.affine)
+            shape = img.shape[:3]
+            next_bbox = _boundingbox.BoundingBox(
+                (0, 0, 0), shape, space=None
+            ).transform(img.affine)
             bbox = next_bbox if bbox is None else bbox.union(next_bbox)
         return bbox
 
     def _merge_fragments(self) -> nib.Nifti1Image:
+        """
+        Merge all fragments this volume contains into one Nifti1Image.
+        """
         bbox = self.get_boundingbox(clip=False, background=0.0)
         num_conflicts = 0
         result = None
@@ -243,7 +229,7 @@ class NiftiProvider(_provider.VolumeProvider, srctype="nii"):
 
         Returns:
         --------
-        PointSet
+        PointCloud
         """
 
         from skimage.feature.peak import peak_local_max
@@ -257,7 +243,7 @@ class NiftiProvider(_provider.VolumeProvider, srctype="nii"):
             min_distance=dist,
         )
         return (
-            pointset.PointSet(
+            pointcloud.PointCloud(
                 [np.dot(img.affine, [x, y, z, 1])[:3] for x, y, z in voxels],
                 space=self.space,
             ),

siibra/volumes/providers/provider.py

@@ -1,4 +1,4 @@
-# Copyright 2018-2024
+# Copyright 2018-2025
 # Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
 
 # Licensed under the Apache License, Version 2.0 (the "License");