siibra 1.0.1a0__py3-none-any.whl → 1.0.1a2__py3-none-any.whl

siibra/livequeries/query.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");
@@ -14,13 +14,13 @@
 # limitations under the License.
 """Handles feature queries that rely on live or on-the-fly calculations."""
 
+from abc import ABC, abstractmethod
+from typing import List
+
 from ..commons import logger
 from ..features.feature import Feature
 from ..core.concept import AtlasConcept
 
-from abc import ABC, abstractmethod
-from typing import List
-
 
 class LiveQuery(ABC):
 
@@ -46,4 +46,4 @@ class LiveQuery(ABC):
 
     @abstractmethod
     def query(self, concept: AtlasConcept, **kwargs) -> List[Feature]:
-        raise NotImplementedError(f"Dervied class {self.__class__} needs to implement query()")
+        raise NotImplementedError(f"Derived class {self.__class__} needs to implement query()")

siibra/locations/__init__.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");
@@ -13,26 +13,34 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 """Handles spatial concepts and spatial operation like warping between spaces."""
+from typing import Iterable
+from functools import reduce
 
 from .location import Location
 from .point import Point
-from .pointcloud import PointCloud, from_points
+from .pointcloud import PointCloud, Contour, from_points
+from .experimental import AxisAlignedPatch, Plane
 from .boundingbox import BoundingBox
 
 
-def reassign_union(loc0: 'Location', loc1: 'Location') -> 'Location':
+def reassign_union(*args: Iterable["Location"]) -> "Location":
+    return reduce(pairwise_union, args)
+
+
+def pairwise_union(loc0: "Location", loc1: "Location") -> "Location":
     """
-    Add two locations of same or diffrent type to find their union as a
+    Add two locations of same or different type to find their union as a
     Location object.
+
     Note
     ----
     `loc1` will be warped to `loc0` they are not in the same space.
+
     Parameters
     ----------
     loc0 : Location
-        _description_
     loc1 : Location
-        _description_
+
     Returns
     -------
     Location
@@ -58,12 +66,13 @@ def reassign_union(loc0: 'Location', loc1: 'Location') -> 'Location':
         try:
             return loc1.union(loc0)
         except Exception:
-            raise NotImplementedError(f"There are no union method for {(loc0.__class__.__name__, loc1.__class__.__name__)}")
+            raise NotImplementedError(
+                f"There are no union method for {(loc0.__class__.__name__, loc1.__class__.__name__)}"
+            )
 
     # convert Points to PointClouds
     loc0, loc1 = [
-        from_points([loc]) if isinstance(loc, Point) else loc
-        for loc in [loc0, loc1]
+        from_points([loc]) if isinstance(loc, Point) else loc for loc in [loc0, loc1]
     ]
 
     # adopt the space of the first location
@@ -82,7 +91,7 @@ def reassign_union(loc0: 'Location', loc1: 'Location') -> 'Location':
             point1=[min(p[i] for p in coordinates) for i in range(3)],
             point2=[max(p[i] for p in coordinates) for i in range(3)],
             space=loc0.space,
-            sigma_mm=[loc0.minpoint.sigma, loc0.maxpoint.sigma]
+            sigma_mm=[loc0.minpoint.sigma, loc0.maxpoint.sigma],
         )
 
     return reassign_union(loc1_w, loc0)

siibra/locations/boundingbox.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");
@@ -14,15 +14,16 @@
 # limitations under the License.
 """A box defined by two farthest corner coordinates on a specific space."""
 
-from . import point, pointcloud, location
+from itertools import product
+import hashlib
+from typing import TYPE_CHECKING, Union
+
+import numpy as np
 
+from . import location, point, pointcloud
 from ..commons import logger
 from ..exceptions import SpaceWarpingFailedError
 
-from itertools import product
-import hashlib
-import numpy as np
-from typing import TYPE_CHECKING, Union
 if TYPE_CHECKING:
     from ..core.structure import BrainStructure
     from nibabel import Nifti1Image
@@ -85,7 +86,7 @@ class BoundingBox(location.Location):
                     self.maxpoint[d] = self.minpoint[d] + minsize
 
         if self.volume == 0:
-            logger.warning(f"Zero-volume bounding box from points {point1} and {point2} in {self.space} space.")
+            logger.debug(f"Zero-volume bounding box from points {point1} and {point2} in {self.space} space.")
 
     @property
     def id(self) -> str:
@@ -148,11 +149,7 @@ class BoundingBox(location.Location):
             points_inside = [p for p in other if self.intersects(p)]
             if len(points_inside) == 0:
                 return None
-            result = pointcloud.PointCloud(
-                points_inside,
-                space=other.space,
-                sigma_mm=[p.sigma for p in points_inside]
-            )
+            result = pointcloud.from_points(points_inside)
             return result[0] if len(result) == 1 else result  # if PointCloud has single point return as a Point
 
         return other.intersection(self)
@@ -213,7 +210,7 @@ class BoundingBox(location.Location):
         X, Y, Z = np.where(mask.get_fdata() > threshold)
         h = np.ones(len(X))
 
-        # array of homogenous physical nonzero voxel coordinates
+        # array of homogeneous physical nonzero voxel coordinates
         coords = np.dot(mask.affine, np.vstack((X, Y, Z, h)))[:3, :].T
         minpoint = [min(self.minpoint[i], self.maxpoint[i]) for i in range(3)]
         maxpoint = [max(self.minpoint[i], self.maxpoint[i]) for i in range(3)]

siibra/{experimental/plane3d.py → locations/experimental.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");
@@ -13,18 +13,113 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from . import contour
-from . import patch
-from ..locations import point, pointcloud
-from ..volumes import volume
+from typing import List
+from math import atan2
 
 import numpy as np
+from nilearn import image
+
+from . import point, pointcloud, boundingbox
+from ..volumes import volume
+from ..commons import translation_matrix, y_rotation_matrix
+
+
+class AxisAlignedPatch(pointcloud.PointCloud):
+
+    def __init__(self, corners: pointcloud.PointCloud):
+        """Construct a patch in physical coordinates.
+        As of now, only patches aligned in the y plane of the physical space
+        are supported."""
+        # TODO: need to ensure that the points are planar, if more than 3
+        assert len(corners) == 4
+        assert len(np.unique(corners.coordinates[:, 1])) == 1
+        pointcloud.PointCloud.__init__(
+            self,
+            coordinates=corners.coordinates,
+            space=corners.space,
+            sigma_mm=corners.sigma_mm,
+            labels=corners.labels
+        )
+        # self.corners = corners
+
+    def __str__(self):
+        return f"Patch with boundingbox {self.boundingbox}"
+
+    def flip(self):
+        """Returns a flipped version of the patch."""
+        new_corners = self.coordinates.copy()[[2, 3, 0, 1]]
+        return AxisAlignedPatch(pointcloud.PointCloud(new_corners, self.space))
+
+    def extract_volume(
+        self,
+        image_volume: volume.Volume,
+        resolution_mm: float,
+    ):
+        """
+        fetches image data in a planar patch.
+        TODO The current implementation only covers patches which are strictly
+        define in the y plane. A future implementation should accept arbitrary
+        oriented patches.accept arbitrary oriented patches.
+        """
+        assert image_volume.space == self.space
+
+        # Extend the 2D patch into a 3D structure
+        # this is only valid if the patch plane lies within the image canvas.
+        canvas = image_volume.get_boundingbox()
+        assert canvas.minpoint[1] <= self.coordinates[0, 1]
+        assert canvas.maxpoint[1] >= self.coordinates[0, 1]
+        XYZ = self.coordinates
+        voi = boundingbox.BoundingBox(
+            XYZ.min(0)[:3], XYZ.max(0)[:3], space=image_volume.space
+        )
+        # enforce the patch to have the same y dimensions
+        voi.minpoint[1] = canvas.minpoint[1]
+        voi.maxpoint[1] = canvas.maxpoint[1]
+        patch = image_volume.fetch(voi=voi, resolution_mm=resolution_mm)
+        assert patch is not None
 
+        # patch rotation defined in physical space
+        vx, vy, vz = XYZ[1] - XYZ[0]
+        alpha = -atan2(-vz, -vx)
+        cx, cy, cz = XYZ.mean(0)
+        rot_phys = np.linalg.multi_dot(
+            [
+                translation_matrix(cx, cy, cz),
+                y_rotation_matrix(alpha),
+                translation_matrix(-cx, -cy, -cz),
+            ]
+        )
 
-class Plane3D:
+        # rotate the patch in physical space
+        affine_rot = np.dot(rot_phys, patch.affine)
+
+        # crop in the rotated space
+        pixels = (
+            np.dot(np.linalg.inv(affine_rot), self.homogeneous.T)
+            .astype("int")
+            .T
+        )
+        # keep a pixel distance to avoid black border pixels
+        xmin, ymin, zmin = pixels.min(0)[:3] + 1
+        xmax, ymax, zmax = pixels.max(0)[:3] - 1
+        h, w = xmax - xmin, zmax - zmin
+        affine = np.dot(affine_rot, translation_matrix(xmin, 0, zmin))
+        return volume.from_nifti(
+            image.resample_img(
+                patch,
+                target_affine=affine,
+                target_shape=[h, 1, w],
+                force_resample=True
+            ),
+            space=image_volume.space,
+            name=f"Rotated patch with corner points {self.coordinates} sampled from {image_volume.name}",
+        )
+
+
+class Plane:
     """
     A 3D plane in reference space.
-    This shall eventually be derived from siibra.Location
+    TODO This shall eventually be derived from siibra.Location
     """
 
     def __init__(self, point1: point.Point, point2: point.Point, point3: point.Point):
@@ -33,7 +128,7 @@ class Plane3D:
         The plane's reference space is defined by the first point.
         """
         self.space = point1.space
-        # normal is the cross product of two arbitray in-plane vectors
+        # normal is the cross product of two arbitrary in-plane vectors
         n = np.cross(
             (point2.warp(self.space) - point1).coordinate,
             (point3.warp(self.space) - point1).coordinate,
@@ -64,8 +159,6 @@ class Plane3D:
         Returns the set of intersection points.
         The line segments are given by two Nx3 arrays of their start- and endpoints.
         The result is an Nx3 list of intersection coordinates.
-        TODO This returns an intersection even if the line segment intersects the plane,
-
         """
         directions = endpoints - startpoints
         lengths = np.linalg.norm(directions, axis=1)
@@ -83,7 +176,7 @@ class Plane3D:
             )
         return result
 
-    def intersect_mesh(self, mesh: dict):
+    def intersect_mesh(self, mesh: dict) -> List[pointcloud.Contour]:
         """
         Intersects a 3D surface mesh with the plane.
         Returns a set of split 2D contours, represented by ordered coordinate lists.
@@ -107,7 +200,7 @@ class Plane3D:
         )[0]
         faces = mesh["faces"][face_indices]
 
-        # for each of N selected faces, indicate wether we cross the plane
+        # for each of N selected faces, indicate whether we cross the plane
         # as we go from vertex 2->0, 0->1, 1->2, respectively.
         # This gives us an Nx3 array, where forward crossings are identified by 1,
         # and backward crossings by -1.
@@ -148,7 +241,7 @@ class Plane3D:
         # should include the exact same set of points. Verify this now.
         sortrows = lambda A: A[np.lexsort(A.T[::-1]), :]
         err = (sortrows(fwd_intersections) - sortrows(bwd_intersections)).sum()
-        assert err == 0
+        assert err == 0, f"intersection inconsistency: {err}"
 
         # Due to the above property, we can construct closed contours in the
         # intersection plane by following the interleaved fwd/bwd roles of intersection
@@ -160,7 +253,7 @@ class Plane3D:
         face_id = 0  # index of the mesh face to consider
         while len(face_indices) > 0:
 
-            # continue the contour with the next foward edge intersection
+            # continue the contour with the next forward edge intersection
             p = fwd_intersections[face_id]
             points.append(p)
             # Remember the ids of the face and start-/end vertices for the point
@@ -175,7 +268,7 @@ class Plane3D:
 
             # finish the current contour.
             result.append(
-                contour.Contour(np.array(points), labels=labels, space=self.space)
+                pointcloud.Contour(np.array(points), labels=labels, space=self.space)
             )
             if len(face_indices) > 0:
                 # prepare to process another contour segment
@@ -236,8 +329,15 @@ class Plane3D:
         )
         err = (self.project_points(corners).coordinates - corners.coordinates).sum()
         if err > 1e-5:
-            print(f"WARNING: patch coordinates were not exactly in-plane (error={err}).")
-        return patch.Patch(self.project_points(corners))
+            print(
+                f"WARNING: patch coordinates were not exactly in-plane (error={err})."
+            )
+
+        try:
+            patch = AxisAlignedPatch(self.project_points(corners))
+        except AssertionError:
+            patch = None
+        return patch
 
     @classmethod
     def from_image(cls, image: volume.Volume):

siibra/locations/location.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");
@@ -16,14 +16,13 @@
 
 from __future__ import annotations
 
-from ..core.structure import BrainStructure
+from typing import Union, Dict
+from abc import abstractmethod
 
 import numpy as np
-from abc import abstractmethod
 
-from typing import TYPE_CHECKING, Union, Dict
-if TYPE_CHECKING:
-    from siibra.core.space import Space
+from ..core.structure import BrainStructure
+from ..core import space as _space
 
 
 class Location(BrainStructure):
@@ -46,29 +45,28 @@ class Location(BrainStructure):
     _MASK_MEMO = {}  # cache region masks for Location._assign_region()
     _ASSIGNMENT_CACHE = {}  # caches assignment results, see Region.assign()
 
-    def __init__(self, spacespec: Union[str, Dict[str, str], "Space"]):
+    def __init__(self, spacespec: Union[str, Dict[str, str], "_space.Space"]):
         self._space_spec = spacespec
         self._space_cached = None
 
     @property
-    def space(self):
+    def space(self) -> "_space.Space":
         if self._space_cached is None:
-            from ..core.space import Space
             if isinstance(self._space_spec, dict):
                 spec = self._space_spec.get("@id") or self._space_spec.get("name")
-                self._space_cached = Space.get_instance(spec)
+                self._space_cached = _space.Space.get_instance(spec)
             else:
-                self._space_cached = Space.get_instance(self._space_spec)
+                self._space_cached = _space.Space.get_instance(self._space_spec)
         return self._space_cached
 
     @abstractmethod
-    def warp(self, space):
+    def warp(self, space: Union[str, "_space.Space"]):
         """Generates a new location by warping the
         current one into another reference space."""
         pass
 
     @abstractmethod
-    def transform(self, affine: np.ndarray, space=None):
+    def transform(self, affine: np.ndarray, space: Union[str, "_space.Space", None] = None):
         """Returns a new location obtained by transforming the
         reference coordinates of this one with the given affine matrix.
 

siibra/locations/point.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");
@@ -14,20 +14,20 @@
 # limitations under the License.
 """Singular coordinate defined on a space, possibly with an uncertainty."""
 
-from . import location, boundingbox, pointcloud
-
-from ..commons import logger
-from ..retrieval.requests import HttpRequest
-from ..exceptions import SpaceWarpingFailedError, NoneCoordinateSuppliedError
-
 from urllib.parse import quote
 import re
-import numpy as np
 import json
 import numbers
 import hashlib
 from typing import Tuple, Union
 
+import numpy as np
+
+from . import location, pointcloud
+from ..commons import logger
+from ..retrieval.requests import HttpRequest
+from ..exceptions import SpaceWarpingFailedError, NoneCoordinateSuppliedError
+
 
 class Point(location.Location):
     """A single 3D point in reference space."""
@@ -108,15 +108,13 @@ class Point(location.Location):
 
     @property
     def homogeneous(self):
-        """The homogenous coordinate of this point as a 4-tuple,
+        """The homogeneous coordinate of this point as a 4-tuple,
         obtained by appending '1' to the original 3-tuple."""
         return np.atleast_2d(self.coordinate + (1,))
 
     def intersection(self, other: location.Location) -> "Point":
         if isinstance(other, Point):
             return self if self == other else None
-        elif isinstance(other, pointcloud.PointCloud):
-            return self if self in other else None
         else:
             return self if other.intersection(self) else None
 
@@ -157,7 +155,7 @@ class Point(location.Location):
         return self.sigma**3 * np.pi * 4. / 3.
 
     def __sub__(self, other):
-        """Substract the coordinates of two points to get
+        """Subtract the coordinates of two points to get
         a new point representing the offset vector. Alternatively,
         subtract an integer from the all coordinates of this point
         to create a new one.
@@ -305,13 +303,6 @@ class Point(location.Location):
         assert 0 <= index < 3
         return self.coordinate[index]
 
-    @property
-    def boundingbox(self):
-        w = max(self.sigma or 0, 1e-6)  # at least a micrometer
-        return boundingbox.BoundingBox(
-            self - w, self + w, self.space, self.sigma
-        )
-
     def bigbrain_section(self):
         """
         Estimate the histological section number of BigBrain

siibra/locations/pointcloud.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");
@@ -14,15 +14,10 @@
 # limitations under the License.
 """A set of coordinates on a reference space."""
 
-from . import location, point, boundingbox as _boundingbox
-
-from ..retrieval.requests import HttpRequest
-from ..commons import logger
-from ..exceptions import SpaceWarpingFailedError, EmptyPointCloudError
-
 from typing import List, Union, Tuple
 import numbers
 import json
+
 import numpy as np
 try:
     from sklearn.cluster import HDBSCAN
@@ -30,10 +25,11 @@ try:
 except ImportError:
     import sklearn
     _HAS_HDBSCAN = False
-    logger.warning(
-        f"HDBSCAN is not available with your version {sklearn.__version__} of sckit-learn."
-        "`PointCloud.find_clusters()` will not be avaiable."
-    )
+
+from . import location, point, boundingbox as _boundingbox
+from ..retrieval.requests import HttpRequest
+from ..commons import logger
+from ..exceptions import SpaceWarpingFailedError, EmptyPointCloudError
 
 
 def from_points(points: List["point.Point"], newlabels: List[Union[int, float, tuple]] = None) -> "PointCloud":
@@ -120,18 +116,15 @@ class PointCloud(location.Location):
         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)]
-        if len(intersections) == 0:
+        if isinstance(other, PointCloud):
+            intersecting_points = [p for p in self if p.coordinate in other.coordinates]
+        elif isinstance(other, point.Point):
+            return other if other in self else None
+        else:
+            intersecting_points = [p for p in self if p.intersects(other)]
+        if len(intersecting_points) == 0:
             return None
-        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 = PointCloud(
-            points,
-            space=self.space,
-            sigma_mm=sigma,
-            labels=labels
-        )
+        intersection = from_points(intersecting_points)
         return intersection[0] if len(intersection) == 1 else intersection
 
     @property
@@ -320,7 +313,7 @@ class PointCloud(location.Location):
         if not _HAS_HDBSCAN:
             raise RuntimeError(
                 f"HDBSCAN is not available with your version {sklearn.__version__} "
-                "of sckit-learn. `PointCloud.find_clusters()` will not be avaiable."
+                "of sckit-learn. `PointCloud.find_clusters()` will not be available."
             )
         points = np.array(self.as_list())
         N = points.shape[0]
@@ -347,3 +340,46 @@ class PointCloud(location.Location):
                 logger.error("Matplotlib is not available. Label colors is disabled.")
                 return None
             return colormaps.rainbow(np.linspace(0, 1, max(self.labels) + 1))
+
+
+class Contour(PointCloud):
+    """
+    A PointCloud that represents a contour line.
+    The only difference is that the point order is relevant,
+    and consecutive points are thought as being connected by an edge.
+
+    In fact, PointCloud assumes order as well, but no connections between points.
+    """
+
+    def __init__(self, coordinates, space=None, sigma_mm=0, labels: list = None):
+        PointCloud.__init__(self, coordinates, space, sigma_mm, labels)
+
+    def crop(self, voi: "_boundingbox.BoundingBox"):
+        """
+        Crop the contour with a volume of interest.
+        Since the contour might be split from the cropping,
+        returns a set of contour segments.
+        """
+        segments = []
+
+        # set the contour point labels to a linear numbering
+        # so we can use them after the intersection to detect splits.
+        old_labels = self.labels
+        self.labels = list(range(len(self)))
+        cropped = self.intersection(voi)
+
+        if cropped is not None and not isinstance(cropped, point.Point):
+            assert isinstance(cropped, PointCloud)
+            # Identify contour splits are by discontinuouities ("jumps")
+            # of their labels, which denote positions in the original contour
+            jumps = np.diff([self.labels.index(lb) for lb in cropped.labels])
+            splits = [0] + list(np.where(jumps > 1)[0] + 1) + [len(cropped)]
+            for i, j in zip(splits[:-1], splits[1:]):
+                segments.append(
+                    self.__class__(cropped.coordinates[i:j, :], space=cropped.space)
+                )
+
+        # reset labels of the input contour points.
+        self.labels = old_labels
+
+        return segments

siibra/retrieval/__init__.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");

siibra/retrieval/cache.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");
@@ -23,6 +23,7 @@ from enum import Enum
 from typing import Callable, List, NamedTuple, Union
 from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
+
 from filelock import FileLock as Lock
 
 from ..commons import logger, SIIBRA_CACHEDIR, SKIP_CACHEINIT_MAINTENANCE, siibra_tqdm