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

siibra/locations/__init__.py

@@ -16,7 +16,7 @@
 
 from .location import Location
 from .point import Point
-from .pointset import PointSet, from_points
+from .pointcloud import PointCloud, from_points
 from .boundingbox import BoundingBox
 
 
@@ -36,11 +36,11 @@ def reassign_union(loc0: 'Location', loc1: 'Location') -> 'Location':
     Returns
     -------
     Location
-        - Point U Point = PointSet
-        - Point U PointSet = PointSet
-        - PointSet U PointSet = PointSet
+        - Point U Point = PointCloud
+        - Point U PointCloud = PointCloud
+        - PointCloud U PointCloud = PointCloud
         - BoundingBox U BoundingBox = BoundingBox
-        - BoundingBox U PointSet = BoundingBox
+        - BoundingBox U PointCloud = BoundingBox
         - BoundingBox U Point = BoundingBox
         - WholeBrain U Location = NotImplementedError
         (all operations are commutative)
@@ -53,14 +53,14 @@ def reassign_union(loc0: 'Location', loc1: 'Location') -> 'Location':
     # location that has its own union method since it is not a part of locations
     # module and to avoid importing Volume here.
     if not all(
-        isinstance(loc, (Point, PointSet, BoundingBox)) for loc in [loc0, loc1]
+        isinstance(loc, (Point, PointCloud, BoundingBox)) for loc in [loc0, loc1]
     ):
         try:
             return loc1.union(loc0)
         except Exception:
             raise NotImplementedError(f"There are no union method for {(loc0.__class__.__name__, loc1.__class__.__name__)}")
 
-    # convert Points to PointSets
+    # convert Points to PointClouds
     loc0, loc1 = [
         from_points([loc]) if isinstance(loc, Point) else loc
         for loc in [loc0, loc1]
@@ -69,8 +69,8 @@ def reassign_union(loc0: 'Location', loc1: 'Location') -> 'Location':
     # adopt the space of the first location
     loc1_w = loc1.warp(loc0.space)
 
-    if isinstance(loc0, PointSet):
-        if isinstance(loc1_w, PointSet):
+    if isinstance(loc0, PointCloud):
+        if isinstance(loc1_w, PointCloud):
             points = list(dict.fromkeys([*loc0, *loc1_w]))
             return from_points(points)
         if isinstance(loc1_w, BoundingBox):

siibra/locations/boundingbox.py

@@ -14,7 +14,7 @@
 # limitations under the License.
 """A box defined by two farthest corner coordinates on a specific space."""
 
-from . import point, pointset, location
+from . import point, pointcloud, location
 
 from ..commons import logger
 from ..exceptions import SpaceWarpingFailedError
@@ -85,7 +85,7 @@ class BoundingBox(location.Location):
                     self.maxpoint[d] = self.minpoint[d] + minsize
 
         if self.volume == 0:
-            logger.warning("Created BoundedBox's have zero volume.")
+            logger.warning(f"Zero-volume bounding box from points {point1} and {point2} in {self.space} space.")
 
     @property
     def id(self) -> str:
@@ -144,16 +144,16 @@ class BoundingBox(location.Location):
         if isinstance(other, point.Point):
             warped = other.warp(self.space)
             return other if self.minpoint <= warped <= self.maxpoint else None
-        if isinstance(other, pointset.PointSet):
+        if isinstance(other, pointcloud.PointCloud):
             points_inside = [p for p in other if self.intersects(p)]
-            result = pointset.PointSet(
+            if len(points_inside) == 0:
+                return None
+            result = pointcloud.PointCloud(
                 points_inside,
                 space=other.space,
                 sigma_mm=[p.sigma for p in points_inside]
             )
-            if len(result) == 0:
-                return None
-            return result[0] if len(result) == 1 else result  # if PointSet has single point return as a Point
+            return result[0] if len(result) == 1 else result  # if PointCloud has single point return as a Point
 
         return other.intersection(self)
 
@@ -240,8 +240,8 @@ class BoundingBox(location.Location):
             )
         else:
             return self._intersect_bbox(
-                pointset
-                .PointSet(XYZ, space=self.space, sigma_mm=voxel_size.max())
+                pointcloud
+                .PointCloud(XYZ, space=self.space, sigma_mm=voxel_size.max())
                 .boundingbox
             )
 
@@ -259,7 +259,7 @@ class BoundingBox(location.Location):
     @property
     def corners(self):
         """
-        Returns all 8 corners of the box as a pointset.
+        Returns all 8 corners of the box as a pointcloud.
 
         Note
         ----
@@ -279,7 +279,7 @@ class BoundingBox(location.Location):
         TODO: deal with sigma. Currently, returns the mean of min and max point.
         """
         xs, ys, zs = zip(self.minpoint, self.maxpoint)
-        return pointset.PointSet(
+        return pointcloud.PointCloud(
             coordinates=[[x, y, z] for x, y, z in product(xs, ys, zs)],
             space=self.space,
             sigma_mm=np.mean([self.minpoint.sigma, self.maxpoint.sigma])
@@ -360,7 +360,7 @@ class BoundingBox(location.Location):
         x1, y1, z1 = self.maxpoint
 
         # set of 8 corner points in source space
-        corners1 = pointset.PointSet(
+        corners1 = pointcloud.PointCloud(
             [
                 (x0, y0, z0),
                 (x0, y0, z1),
@@ -417,14 +417,15 @@ class BoundingBox(location.Location):
         return super().__hash__()
 
 
-def _determine_bounds(array: np.ndarray, threshold=0):
+def _determine_bounds(masked_array: np.ndarray, background: float = 0.0):
     """
-    Bounding box of nonzero values in a 3D array.
+    Bounding box of nonzero (background) values in a 3D array.
+
     https://stackoverflow.com/questions/31400769/bounding-box-of-numpy-array
     """
-    x = np.any(array > threshold, axis=(1, 2))
-    y = np.any(array > threshold, axis=(0, 2))
-    z = np.any(array > threshold, axis=(0, 1))
+    x = np.any(masked_array != background, axis=(1, 2))
+    y = np.any(masked_array != background, axis=(0, 2))
+    z = np.any(masked_array != background, axis=(0, 1))
     nzx, nzy, nzz = [np.where(v) for v in (x, y, z)]
     if any(len(nz[0]) == 0 for nz in [nzx, nzy, nzz]):
         # empty array
@@ -435,15 +436,19 @@ def _determine_bounds(array: np.ndarray, threshold=0):
     return np.array([[xmin, xmax + 1], [ymin, ymax + 1], [zmin, zmax + 1], [1, 1]])
 
 
-def from_array(array: np.ndarray, threshold=0, space: "Space" = None) -> "BoundingBox":
+def from_array(
+    array: np.ndarray,
+    background: Union[int, float] = 0.0,
+    space: "Space" = None
+) -> BoundingBox:
     """
-    Find the bounding box of an array.
+    Find the bounding box of non-background values for any 3D array.
 
     Parameters
     ----------
-    array : np.ndarray
-    threshold : int, default: 0
-    space : Space, default: None
+    array: np.ndarray
+    background: int or float, default: 0.0
+    space: Space, default: None
     """
-    bounds = _determine_bounds(array, threshold)
-    return BoundingBox(bounds[:3, 0], bounds[:3, 1], space=space)
+    bounds = _determine_bounds(array, background)
+    return BoundingBox(point1=bounds[:3, 0], point2=bounds[:3, 1], space=space)

siibra/locations/point.py

@@ -14,7 +14,7 @@
 # limitations under the License.
 """Singular coordinate defined on a space, possibly with an uncertainty."""
 
-from . import location, boundingbox, pointset
+from . import location, boundingbox, pointcloud
 
 from ..commons import logger
 from ..retrieval.requests import HttpRequest
@@ -115,7 +115,7 @@ class Point(location.Location):
     def intersection(self, other: location.Location) -> "Point":
         if isinstance(other, Point):
             return self if self == other else None
-        elif isinstance(other, pointset.PointSet):
+        elif isinstance(other, pointcloud.PointCloud):
             return self if self in other else None
         else:
             return self if other.intersection(self) else None
@@ -190,8 +190,8 @@ class Point(location.Location):
         return super().__hash__()
 
     def __eq__(self, other: 'Point'):
-        if isinstance(other, pointset.PointSet):
-            return other == self  # implemented at pointset
+        if isinstance(other, pointcloud.PointCloud):
+            return other == self  # implemented at pointcloud
         if not isinstance(other, Point):
             return False
         o = other if self.space is None else other.warp(self.space)

siibra/locations/{pointset.py → pointcloud.py}

@@ -18,7 +18,7 @@ from . import location, point, boundingbox as _boundingbox
 
 from ..retrieval.requests import HttpRequest
 from ..commons import logger
-from ..exceptions import SpaceWarpingFailedError
+from ..exceptions import SpaceWarpingFailedError, EmptyPointCloudError
 
 from typing import List, Union, Tuple
 import numbers
@@ -32,13 +32,13 @@ except ImportError:
     _HAS_HDBSCAN = False
     logger.warning(
         f"HDBSCAN is not available with your version {sklearn.__version__} of sckit-learn."
-        "`PointSet.find_clusters()` will not be avaiable."
+        "`PointCloud.find_clusters()` will not be avaiable."
     )
 
 
-def from_points(points: List["point.Point"], newlabels: List[Union[int, float, tuple]] = None) -> "PointSet":
+def from_points(points: List["point.Point"], newlabels: List[Union[int, float, tuple]] = None) -> "PointCloud":
     """
-    Create a PointSet from an iterable of Points.
+    Create a PointCloud from an iterable of Points.
 
     Parameters
     ----------
@@ -48,16 +48,17 @@ def from_points(points: List["point.Point"], newlabels: List[Union[int, float, t
 
     Returns
     -------
-    PointSet
+    PointCloud
     """
     if len(points) == 0:
-        return PointSet([])
+        raise EmptyPointCloudError("Cannot create a PointCloud without any points.")
+
     spaces = {p.space for p in points}
-    assert len(spaces) == 1, f"PointSet can only be constructed with points from the same space.\n{spaces}"
+    assert len(spaces) == 1, f"PointCloud can only be constructed with points from the same space.\n{spaces}"
     coords, sigmas, labels = zip(*((p.coordinate, p.sigma, p.label) for p in points))
     if all(lb is None for lb in set(labels)):
         labels = None
-    return PointSet(
+    return PointCloud(
         coordinates=coords,
         space=next(iter(spaces)),
         sigma_mm=sigmas,
@@ -65,7 +66,7 @@ def from_points(points: List["point.Point"], newlabels: List[Union[int, float, t
     )
 
 
-class PointSet(location.Location):
+class PointCloud(location.Location):
     """A set of 3D points in the same reference space,
     defined by a list of coordinates."""
 
@@ -91,6 +92,9 @@ class PointSet(location.Location):
         """
         location.Location.__init__(self, space)
 
+        if len(coordinates) == 0:
+            raise EmptyPointCloudError(f"Cannot create a {self.__class__.__name__} without any coordinates.")
+
         self._coordinates = coordinates
         if not isinstance(coordinates, np.ndarray):
             self._coordinates = np.array(self._coordinates).reshape((-1, 3))
@@ -113,7 +117,7 @@ class PointSet(location.Location):
         NOTE: The affine matrix of the image must be set to warp voxels
         coordinates into the reference space of this Bounding Box.
         """
-        if not isinstance(other, (point.Point, PointSet, _boundingbox.BoundingBox)):
+        if not isinstance(other, (point.Point, PointCloud, _boundingbox.BoundingBox)):
             return other.intersection(self)
 
         intersections = [(i, p) for i, p in enumerate(self) if p.intersects(other)]
@@ -122,7 +126,7 @@ class PointSet(location.Location):
         ids, points = zip(*intersections)
         labels = None if self.labels is None else [self.labels[i] for i in ids]
         sigma = [p.sigma for p in points]
-        intersection = PointSet(
+        intersection = PointCloud(
             points,
             space=self.space,
             sigma_mm=sigma,
@@ -186,7 +190,7 @@ class PointSet(location.Location):
         return self.__class__(coordinates=tuple(tgt_points), space=spaceobj, labels=self.labels)
 
     def transform(self, affine: np.ndarray, space=None):
-        """Returns a new PointSet obtained by transforming the
+        """Returns a new PointCloud obtained by transforming the
         coordinates of this one with the given affine matrix.
 
         Parameters
@@ -207,7 +211,7 @@ class PointSet(location.Location):
     def __getitem__(self, index: int):
         if (abs(index) >= self.__len__()):
             raise IndexError(
-                f"Pointset with {self.__len__()} points "
+                f"pointcloud with {self.__len__()} points "
                 f"cannot be accessed with index {index}."
             )
         return point.Point(
@@ -229,10 +233,10 @@ class PointSet(location.Location):
             for i in range(len(self))
         )
 
-    def __eq__(self, other: 'PointSet'):
+    def __eq__(self, other: 'PointCloud'):
         if isinstance(other, point.Point):
             return len(self) == 1 and self[0] == other
-        if not isinstance(other, PointSet):
+        if not isinstance(other, PointCloud):
             return False
         return list(self) == list(other)
 
@@ -240,7 +244,7 @@ class PointSet(location.Location):
         return super().__hash__()
 
     def __len__(self):
-        """The number of points in this PointSet."""
+        """The number of points in this PointCloud."""
         return self.coordinates.shape[0]
 
     def __str__(self):
@@ -249,9 +253,13 @@ class PointSet(location.Location):
     @property
     def boundingbox(self):
         """
-        Return the bounding box of these points.
+        Return the bounding box of these points, or None in the
+        special case of an empty PointCloud.
         """
+        if len(self.coordinates) == 0:
+            return None
         coords = self.coordinates
+        # TODO this needs a more precise treatment of the sigmas
         sigma_min = max(self.sigma[i] for i in coords.argmin(0))
         sigma_max = max(self.sigma[i] for i in coords.argmax(0))
         return _boundingbox.BoundingBox(
@@ -292,8 +300,8 @@ class PointSet(location.Location):
 
         Parameters
         ----------
-        min_fraction: min cluster size as a fraction of total points in the PointSet
-        max_fraction: max cluster size as a fraction of total points in the PointSet
+        min_fraction: min cluster size as a fraction of total points in the PointCloud
+        max_fraction: max cluster size as a fraction of total points in the PointCloud
 
         Returns
         -------
@@ -302,7 +310,7 @@ class PointSet(location.Location):
 
             Note
             ----
-            Replaces the labels of the PointSet instance with these labels.
+            Replaces the labels of the PointCloud instance with these labels.
 
         Raises
         ------
@@ -312,7 +320,7 @@ class PointSet(location.Location):
         if not _HAS_HDBSCAN:
             raise RuntimeError(
                 f"HDBSCAN is not available with your version {sklearn.__version__} "
-                "of sckit-learn. `PointSet.find_clusters()` will not be avaiable."
+                "of sckit-learn. `PointCloud.find_clusters()` will not be avaiable."
             )
         points = np.array(self.as_list())
         N = points.shape[0]
@@ -322,7 +330,7 @@ class PointSet(location.Location):
         )
         if self.labels is not None:
             logger.warning(
-                "Existing labels of PointSet will be overwritten with cluster labels."
+                "Existing labels of PointCloud will be overwritten with cluster labels."
             )
         self.labels = clustering.fit_predict(points)
         return self.labels

siibra/retrieval/repositories.py

@@ -19,7 +19,8 @@ from .requests import (
     EbrainsRequest,
     SiibraHttpRequestError,
     find_suitiable_decoder,
-    DECODERS
+    DECODERS,
+    FileLoader
 )
 from .cache import CACHE
 
@@ -124,34 +125,16 @@ class LocalFileRepository(RepositoryConnector):
         self._folder = pathlib.Path(folder)
         assert pathlib.Path.is_dir(self._folder)
 
-    def _build_url(self, folder: str, filename: str):
-        return pathlib.Path.joinpath(self._folder, folder, filename)
-
-    class FileLoader:
-        """
-        Just a loads a local file, but mimics the behaviour
-        of cached http requests used in other connectors.
-        """
-        def __init__(self, file_url, decode_func):
-            self.url = file_url
-            self.func = decode_func
-            self.cached = True
-
-        @property
-        def data(self):
-            with open(self.url, 'rb') as f:
-                return self.func(f.read())
+    def _build_url(self, folder: str, filename: str) -> str:
+        return pathlib.Path.joinpath(self._folder, folder, filename).as_posix()
 
     def get_loader(self, filename, folder="", decode_func=None):
         """Get a lazy loader for a file, for loading data
         only once loader.data is accessed."""
-        url = self._build_url(folder, filename)
-        if url is None:
-            raise RuntimeError(f"Cannot build url for ({folder}, {filename})")
-        if decode_func is None:
-            return self.FileLoader(url, lambda b: self._decode_response(b, filename))
-        else:
-            return self.FileLoader(url, decode_func)
+        filepath = self._build_url(folder, filename)
+        if not pathlib.Path(filepath).is_file():
+            raise RuntimeError(f"No file is found in {filepath}")
+        return FileLoader(filepath, decode_func)
 
     def search_files(self, folder="", suffix=None, recursive=False):
         results = []
@@ -165,7 +148,7 @@ class LocalFileRepository(RepositoryConnector):
     def __str__(self):
         return f"{self.__class__.__name__} at {self._folder}"
 
-    def __eq__(self, other):
+    def __eq__(self, other: "LocalFileRepository"):
         return self._folder == other._folder
 
 

siibra/retrieval/requests.py

@@ -117,8 +117,7 @@ def find_suitiable_decoder(url: str) -> Callable:
     suitable_decoders = [
         dec for sfx, dec in DECODERS.items() if urlpath.endswith(sfx)
     ]
-    if len(suitable_decoders) > 0:
-        assert len(suitable_decoders) == 1
+    if len(suitable_decoders) == 1:
         return suitable_decoders[0]
     else:
         return None
@@ -270,6 +269,24 @@ class HttpRequest:
         return self.get()
 
 
+class FileLoader(HttpRequest):
+    """
+    Just a loads a local file, but mimics the behaviour
+    of cached http requests used in other connectors.
+    """
+    def __init__(self, filepath, func=None):
+        HttpRequest.__init__(
+            self, filepath, refresh=False,
+            func=func or find_suitiable_decoder(filepath)
+        )
+        self.cachefile = filepath
+
+    def _retrieve(self, **kwargs):
+        if kwargs:
+            logger.info(f"Keywords {list(kwargs.keys())} are supplied but won't be used.")
+        assert os.path.isfile(self.cachefile)
+
+
 class ZipfileRequest(HttpRequest):
     def __init__(self, url, filename, func=None, refresh=False):
         HttpRequest.__init__(

siibra/volumes/__init__.py

@@ -16,7 +16,7 @@
 
 from .parcellationmap import Map
 from .providers import provider
-from .volume import from_array, from_file, from_pointset, from_nifti, Volume
+from .volume import from_array, from_file, from_pointcloud, from_nifti, Volume
 
 from ..commons import logger
 from typing import List, Union