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

siibra/volumes/parcellationmap.py

@@ -32,8 +32,7 @@ from ..commons import (
     generate_uuid
 )
 from ..core import concept, space, parcellation, region as _region
-from ..locations import location, point, pointset
-from ..retrieval import requests
+from ..locations import location, point, pointcloud
 
 import numpy as np
 from typing import Union, Dict, List, TYPE_CHECKING, Iterable, Tuple
@@ -160,6 +159,11 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             logger.warning(f"Non unique indices encountered in {self}: {duplicates}")
         self._affine_cached = None
 
+    @property
+    def key(self):
+        _id = self.id
+        return create_key(_id[len("siibra-map-v0.0.1"):])
+
     @property
     def species(self) -> Species:
         # lazy implementation
@@ -319,69 +323,27 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
     def regions(self):
         return list(self._indices)
 
-    def fetch(
+    def get_volume(
         self,
-        region_or_index: Union[str, "Region", MapIndex] = None,
+        region: Union[str, "Region"] = None,
         *,
         index: MapIndex = None,
-        region: Union[str, "Region"] = None,
-        **kwargs
-    ):
-        """
-        Fetches one particular volume of this parcellation map.
-
-        If there's only one volume, this is the default, otherwise further
-        specification is requested:
-        - the volume index,
-        - the MapIndex (which results in a regional map being returned)
-
-        You might also consider fetch_iter() to iterate the volumes, or
-        compress() to produce a single-volume parcellation map.
-
-        Parameters
-        ----------
-        region_or_index: str, Region, MapIndex
-            Lazy match the specification.
-        index: MapIndex
-            Explicit specification of the map index, typically resulting
-            in a regional map (mask or statistical map) to be returned.
-            Note that supplying 'region' will result in retrieving the map index of that region
-            automatically.
-        region: str, Region
-            Specification of a region name, resulting in a regional map
-            (mask or statistical map) to be returned.
-        **kwargs
-            - resolution_mm: resolution in millimeters
-            - format: the format of the volume, like "mesh" or "nii"
-            - voi: a BoundingBox of interest
-
-
-            Note
-            ----
-            Not all keyword arguments are supported for volume formats. Format
-            is restricted by available formats (check formats property).
-
-        Returns
-        -------
-        An image or mesh
-        """
+        **kwargs,
+    ) -> Union[_volume.Volume, _volume.FilteredVolume, _volume.Subvolume]:
         try:
-            length = len([arg for arg in [region_or_index, region, index] if arg is not None])
+            length = len([arg for arg in [region, index] if arg is not None])
             assert length == 1
         except AssertionError:
             if length > 1:
-                raise exceptions.ExcessiveArgumentException("One and only one of region_or_index, region, index can be defined for fetch")
-            # user can provide no arguments, which assumes one and only one volume present
-
-        if isinstance(region_or_index, MapIndex):
-            index = region_or_index
-
-        if isinstance(region_or_index, (str, _region.Region)):
-            region = region_or_index
-
+                raise exceptions.ExcessiveArgumentException(
+                    "One and only one of region or index can be defined for `get_volume`."
+                )
         mapindex = None
         if region is not None:
-            assert isinstance(region, (str, _region.Region))
+            try:
+                assert isinstance(region, (str, _region.Region))
+            except AssertionError:
+                raise TypeError(f"Please provide a region name or region instance, not a {type(region)}")
             mapindex = self.get_index(region)
         if index is not None:
             assert isinstance(index, MapIndex)
@@ -390,19 +352,17 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             if len(self) == 1:
                 mapindex = MapIndex(volume=0, label=None)
             elif len(self) > 1:
+                assert self.maptype == MapType.LABELLED, f"Cannot merge multiple volumes of map type {self.maptype}. Please specify a region or index."
                 logger.info(
                     "Map provides multiple volumes and no specification is"
                     " provided. Resampling all volumes to the space."
                 )
                 labels = list(range(len(self.volumes)))
                 merged_volume = _volume.merge(self.volumes, labels, **kwargs)
-                return merged_volume.fetch()
+                return merged_volume
             else:
                 raise exceptions.NoVolumeFound("Map provides no volumes.")
 
-        if "resolution_mm" in kwargs and kwargs.get("format") is None:
-            kwargs["format"] = 'neuroglancer/precomputed'
-
         kwargs_fragment = kwargs.pop("fragment", None)
         if kwargs_fragment is not None:
             if (mapindex.fragment is not None) and (kwargs_fragment != mapindex.fragment):
@@ -418,17 +378,60 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             raise IndexError(
                 f"{self} provides {len(self)} mapped volumes, but #{mapindex.volume} was requested."
             )
-        try:
-            result = self.volumes[mapindex.volume or 0].fetch(
-                fragment=mapindex.fragment, label=mapindex.label, **kwargs
-            )
-        except requests.SiibraHttpRequestError as e:
-            print(str(e))
+        if mapindex.label is None and mapindex.fragment is None:
+            return self.volumes[mapindex.volume]
+
+        return _volume.FilteredVolume(
+            parent_volume=self.volumes[mapindex.volume],
+            label=mapindex.label,
+            fragment=mapindex.fragment,
+        )
+
+    def fetch(
+        self,
+        region: Union[str, "Region"] = None,
+        *,
+        index: MapIndex = None,
+        **fetch_kwargs
+    ):
+        """
+        Fetches one particular volume of this parcellation map.
+
+        If there's only one volume, this is the default, otherwise further
+        specification is requested:
+        - the volume index,
+        - the MapIndex (which results in a regional map being returned)
+
+        You might also consider fetch_iter() to iterate the volumes, or
+        compress() to produce a single-volume parcellation map.
+
+        Parameters
+        ----------
+        region: str, Region
+            Specification of a region name, resulting in a regional map
+            (mask or statistical map) to be returned.
+        index: MapIndex
+            Explicit specification of the map index, typically resulting
+            in a regional map (mask or statistical map) to be returned.
+            Note that supplying 'region' will result in retrieving the map index of that region
+            automatically.
+        **fetch_kwargs
+            - resolution_mm: resolution in millimeters
+            - format: the format of the volume, like "mesh" or "nii"
+            - voi: a BoundingBox of interest
 
-        if result is None:
-            raise RuntimeError(f"Error fetching {mapindex} from {self} as {kwargs.get('format', f'{self.formats}')}.")
 
-        return result
+            Note
+            ----
+            Not all keyword arguments are supported for volume formats. Format
+            is restricted by available formats (check formats property).
+
+        Returns
+        -------
+        An image or mesh
+        """
+        vol = self.get_volume(region=region, index=index, **fetch_kwargs)
+        return vol.fetch(**fetch_kwargs)
 
     def fetch_iter(self, **kwargs):
         """
@@ -531,7 +534,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                 disable=(len(self.fragments) == 1 or self.fragments is None)
             ):
                 mapindex = MapIndex(volume=volidx, fragment=frag)
-                img = self.fetch(mapindex)
+                img = self.fetch(index=mapindex)
                 if np.allclose(img.affine, result_affine):
                     img_data = np.asanyarray(img.dataobj)
                 else:
@@ -572,11 +575,11 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             )]
         )
 
-    def compute_centroids(self, split_components: bool = True) -> Dict[str, pointset.PointSet]:
+    def compute_centroids(self, split_components: bool = True, **fetch_kwargs) -> Dict[str, pointcloud.PointCloud]:
         """
         Compute a dictionary of all regions in this map to their centroids.
         By default, the regional masks will be split to connected components
-        and each point in the PointSet corresponds to a region component.
+        and each point in the PointCloud corresponds to a region component.
 
         Parameters
         ----------
@@ -589,6 +592,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         Dict[str, point.Point]
             Region names as keys and computed centroids as items.
         """
+        assert self.provides_image, "Centroid computation for meshes is not supported yet."
         centroids = dict()
         for regionname, indexlist in siibra_tqdm(
             self._indices.items(), unit="regions", desc="Computing centroids"
@@ -600,7 +604,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                     merged_volume = _volume.merge(
                         [
                             _volume.from_nifti(
-                                self.fetch(index=index),
+                                self.fetch(index=index, **fetch_kwargs),
                                 self.space,
                                 f"{self.name} - {index}"
                             )
@@ -611,13 +615,16 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                     mapimg = merged_volume.fetch()
                 elif len(indexlist) == 1:
                     index = indexlist[0]
-                    mapimg = self.fetch(index=index)  # returns a mask of the region
+                    mapimg = self.fetch(index=index, **fetch_kwargs)  # returns a mask of the region
             props = _volume.ComponentSpatialProperties.compute_from_image(
                 img=mapimg,
                 space=self.space,
                 split_components=split_components,
             )
-            centroids[regionname] = pointset.from_points([c.centroid for c in props])
+            try:
+                centroids[regionname] = pointcloud.from_points([c.centroid for c in props])
+            except exceptions.EmptyPointCloudError:
+                centroids[regionname] = None
         return centroids
 
     def get_resampled_template(self, **fetch_kwargs) -> _volume.Volume:
@@ -742,7 +749,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
 
         Returns
         -------
-        PointSet
+        PointCloud
             Sample points in physcial coordinates corresponding to this
             parcellationmap
         """
@@ -760,7 +767,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             np.unravel_index(np.random.choice(len(p), numpoints, p=p), W.shape)
         ).T
         XYZ = np.dot(mask.affine, np.c_[XYZ_, np.ones(numpoints)].T)[:3, :].T
-        return pointset.PointSet(XYZ, space=self.space)
+        return pointcloud.PointCloud(XYZ, space=self.space)
 
     def to_sparse(self):
         """
@@ -831,10 +838,10 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
 
         if isinstance(item, point.Point):
             return self._assign_points(
-                pointset.PointSet([item], item.space, sigma_mm=item.sigma),
+                pointcloud.PointCloud([item], item.space, sigma_mm=item.sigma),
                 lower_threshold
             )
-        if isinstance(item, pointset.PointSet):
+        if isinstance(item, pointcloud.PointCloud):
             return self._assign_points(item, lower_threshold)
         if isinstance(item, _volume.Volume):
             return self._assign_volume(
@@ -989,9 +996,9 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             .dropna(axis='columns', how='all')
         )
 
-    def _assign_points(self, points: pointset.PointSet, lower_threshold: float) -> List[MapAssignment]:
+    def _assign_points(self, points: pointcloud.PointCloud, lower_threshold: float) -> List[MapAssignment]:
         """
-        assign a PointSet to this parcellation map.
+        assign a PointCloud to this parcellation map.
 
         Parameters
         -----------

siibra/volumes/providers/neuroglancer.py

@@ -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 dispalying 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,26 +159,20 @@ 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,
             such as voi or resolution_mm.
@@ -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)
@@ -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),

siibra/volumes/providers/nifti.py

@@ -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,
             ),