siibra 1.0.1a1__py3-none-any.whl → 1.0.1a4__py3-none-any.whl

siibra/{experimental/plane3d.py → locations/experimental.py}

@@ -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):
@@ -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.
@@ -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
@@ -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

@@ -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,34 @@ 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):
+            if self._space_spec is None:
+                return None
+            elif isinstance(self._space_spec, _space.Space):
+                self._space_cached = self._space_spec
+            elif 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)
+            elif isinstance(self._space_spec, str):
+                self._space_cached = _space.Space.get_instance(self._space_spec)
             else:
-                self._space_cached = Space.get_instance(self._space_spec)
+                raise ValueError(f"Invalid space spec type: '{type(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

@@ -14,19 +14,22 @@
 # 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
+from typing import Tuple, Union, Dict, TYPE_CHECKING
+
+import numpy as np
+
+from . import location, pointcloud
+from ..commons import logger
+from ..retrieval.requests import HttpRequest
+from ..exceptions import SpaceWarpingFailedError, NoneCoordinateSuppliedError
+
+if TYPE_CHECKING:
+    from ..core.space import Space
 
 
 class Point(location.Location):
@@ -115,18 +118,17 @@ 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, pointcloud.PointCloud):
-            return self if self in other else None
         else:
             return self if other.intersection(self) else None
 
-    def warp(self, space):
+    def warp(self, space: Union[str, Dict, "Space"]):
         """
         Creates a new point by warping this point to another space
         TODO this needs to maintain the sigma parameter!
         """
         from ..core.space import Space
-        spaceobj = Space.get_instance(space)
+
+        spaceobj = space if isinstance(space, Space) else Space.get_instance(space)
         if spaceobj == self.space:
             return self
         if any(_ not in location.Location.SPACEWARP_IDS for _ in [self.space.id, spaceobj.id]):
@@ -305,13 +307,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

@@ -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
+from typing import List, Union, Tuple, Dict, TYPE_CHECKING
 import numbers
 import json
+
 import numpy as np
 try:
     from sklearn.cluster import HDBSCAN
@@ -30,10 +25,14 @@ 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 available."
-    )
+
+from . import location, point, boundingbox as _boundingbox
+from ..retrieval.requests import HttpRequest
+from ..commons import logger
+from ..exceptions import SpaceWarpingFailedError, EmptyPointCloudError
+
+if TYPE_CHECKING:
+    from ..core.space import Space
 
 
 def from_points(points: List["point.Point"], newlabels: List[Union[int, float, tuple]] = None) -> "PointCloud":
@@ -122,6 +121,8 @@ class PointCloud(location.Location):
 
         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:
@@ -142,9 +143,10 @@ class PointCloud(location.Location):
     def has_constant_sigma(self) -> bool:
         return len(set(self.sigma)) == 1
 
-    def warp(self, space, chunksize=1000):
+    def warp(self, space: Union[str, Dict, "Space"], chunksize: int = 1000):
         """Creates a new point set by warping its points to another space"""
         from ..core.space import Space
+
         spaceobj = space if isinstance(space, Space) else Space.get_instance(space)
         if spaceobj == self.space:
             return self
@@ -342,3 +344,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") -> List["Contour"]:
+        """
+        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/cache.py

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

siibra/retrieval/datasets.py

@@ -14,19 +14,18 @@
 # limitations under the License.
 """Metadata connection to EBRAINS datasets."""
 
-from .requests import MultiSourcedRequest, GitlabProxy, GitlabProxyEnum
-
 import re
-from typing import Union, List
-from abc import ABC, abstractproperty
+from abc import ABC, abstractmethod
 from hashlib import md5
-
+from typing import Union, List
 try:
     from typing import TypedDict
 except ImportError:
     # support python 3.7
     from typing_extensions import TypedDict
 
+from .requests import MultiSourcedRequest, GitlabProxy, GitlabProxyEnum
+
 
 class EbrainsDatasetUrl(TypedDict):
     url: str
@@ -48,31 +47,38 @@ EbrainsDatasetEmbargoStatus = TypedDict("EbrainsDatasetEmbargoStatus", {
 
 
 class EbrainsBaseDataset(ABC):
-    @abstractproperty
+    @property
+    @abstractmethod
     def id(self) -> str:
         raise NotImplementedError
 
-    @abstractproperty
+    @property
+    @abstractmethod
     def name(self) -> str:
         raise NotImplementedError
 
-    @abstractproperty
+    @property
+    @abstractmethod
     def urls(self) -> List[EbrainsDatasetUrl]:
         raise NotImplementedError
 
-    @abstractproperty
+    @property
+    @abstractmethod
     def description(self) -> str:
         raise NotImplementedError
 
-    @abstractproperty
+    @property
+    @abstractmethod
     def contributors(self) -> List[EbrainsDatasetPerson]:
         raise NotImplementedError
 
-    @abstractproperty
+    @property
+    @abstractmethod
     def ebrains_page(self) -> str:
         raise NotImplementedError
 
-    @abstractproperty
+    @property
+    @abstractmethod
     def custodians(self) -> List[EbrainsDatasetPerson]:
         raise NotImplementedError
 
@@ -342,7 +348,7 @@ class EbrainsV3Dataset(EbrainsBaseDataset):
         return [version.get("id") for version in self._detail.get("versions", [])]
 
 
-class GenericDataset():
+class GenericDataset:
 
     def __init__(
         self,

siibra/retrieval/repositories.py

@@ -14,25 +14,24 @@
 # limitations under the License.
 """Connect to repositories to browse and pull files within."""
 
+from abc import ABC, abstractmethod
+from urllib.parse import quote
+import pathlib
+import os
+from zipfile import ZipFile
+from typing import List
+
+from .cache import CACHE
 from .requests import (
     HttpRequest,
     EbrainsRequest,
     SiibraHttpRequestError,
-    find_suitiable_decoder,
+    find_suitable_decoder,
     DECODERS,
     FileLoader
 )
-from .cache import CACHE
-
 from ..commons import logger, siibra_tqdm
 
-from abc import ABC, abstractmethod
-from urllib.parse import quote
-import pathlib
-import os
-from zipfile import ZipFile
-from typing import List
-
 
 class RepositoryConnector(ABC):
     """
@@ -67,7 +66,7 @@ class RepositoryConnector(ABC):
         pass
 
     def _decode_response(self, response, filename: str):
-        decoder = find_suitiable_decoder(filename)
+        decoder = find_suitable_decoder(filename)
         return decoder(response) if decoder else response
 
     def get(self, filename, folder="", decode_func=None):

siibra/retrieval/requests.py

@@ -14,35 +14,37 @@
 # limitations under the License.
 """Request files with decoders, lazy loading, and caching."""
 
-from .cache import CACHE, cache_user_fn
-from .exceptions import EbrainsAuthenticationError
-from ..commons import (
-    logger,
-    HBP_AUTH_TOKEN,
-    KEYCLOAK_CLIENT_ID,
-    KEYCLOAK_CLIENT_SECRET,
-    siibra_tqdm,
-    SIIBRA_USE_LOCAL_SNAPSPOT,
-)
-from .. import __version__
-
 import json
 from zipfile import ZipFile
 import requests
 import os
-from nibabel import Nifti1Image, GiftiImage, streamlines, freesurfer
-from skimage import io as skimage_io
 import gzip
 from io import BytesIO
 import urllib.parse
-import pandas as pd
-import numpy as np
 from typing import List, Callable, TYPE_CHECKING
 from enum import Enum
 from functools import wraps
 from time import sleep
 import sys
+
 from filelock import FileLock as Lock
+import numpy as np
+import pandas as pd
+from skimage import io as skimage_io
+from nibabel import Nifti1Image, GiftiImage, streamlines, freesurfer
+
+from . import exceptions as _exceptions
+from .cache import CACHE, cache_user_fn
+from .. import __version__
+from ..commons import (
+    logger,
+    HBP_AUTH_TOKEN,
+    KEYCLOAK_CLIENT_ID,
+    KEYCLOAK_CLIENT_SECRET,
+    siibra_tqdm,
+    SIIBRA_USE_LOCAL_SNAPSPOT,
+)
+
 if TYPE_CHECKING:
     from .repositories import GitlabConnector
 
@@ -91,7 +93,7 @@ DECODERS = {
 }
 
 
-def find_suitiable_decoder(url: str) -> Callable:
+def find_suitable_decoder(url: str) -> Callable:
     """
     By supplying a url or a filename, obtain a suitable decoder function
     for siibra to digest based on predefined DECODERS. An extra layer of
@@ -108,7 +110,7 @@ def find_suitiable_decoder(url: str) -> Callable:
     """
     urlpath = urllib.parse.urlsplit(url).path
     if urlpath.endswith(".gz"):
-        dec = find_suitiable_decoder(urlpath[:-3])
+        dec = find_suitable_decoder(urlpath[:-3])
         if dec is None:
             return lambda b: gzip.decompress(b)
         else:
@@ -183,7 +185,7 @@ class HttpRequest:
         ----------
         func : Callable, default: None
         """
-        self.func = func or find_suitiable_decoder(self.url)
+        self.func = func or find_suitable_decoder(self.url)
 
     @property
     def cached(self):
@@ -277,7 +279,7 @@ class FileLoader(HttpRequest):
     def __init__(self, filepath, func=None):
         HttpRequest.__init__(
             self, filepath, refresh=False,
-            func=func or find_suitiable_decoder(filepath)
+            func=func or find_suitable_decoder(filepath)
         )
         self.cachefile = filepath
 
@@ -291,7 +293,7 @@ class ZipfileRequest(HttpRequest):
     def __init__(self, url, filename, func=None, refresh=False):
         HttpRequest.__init__(
             self, url, refresh=refresh,
-            func=func or find_suitiable_decoder(filename)
+            func=func or find_suitable_decoder(filename)
         )
         self.filename = filename
 
@@ -388,7 +390,7 @@ class EbrainsRequest(HttpRequest):
                 ),  # if explicitly enabled by env var, do not raise
             ]
         ):
-            raise EbrainsAuthenticationError(
+            raise _exceptions.EbrainsAuthenticationError(
                 "sys.stdout is not tty, SIIBRA_ENABLE_DEVICE_FLOW is not set,"
                 "and not running in a notebook. Are you running in batch mode?"
             )
@@ -444,7 +446,7 @@ class EbrainsRequest(HttpRequest):
                     f"exceeded max attempts: {cls._IAM_DEVICE_MAXTRIES}, aborting..."
                 )
                 logger.error(message)
-                raise EbrainsAuthenticationError(message)
+                raise _exceptions.EbrainsAuthenticationError(message)
             attempt_number += 1
             resp = requests.post(
                 url=cls._IAM_TOKEN_ENDPOINT,
@@ -470,7 +472,7 @@ class EbrainsRequest(HttpRequest):
                 logger.debug(f"400 error: {resp.content}")
                 continue
 
-            raise EbrainsAuthenticationError(resp.content)
+            raise _exceptions.EbrainsAuthenticationError(resp.content)
 
     @classmethod
     def set_token(cls, token):

siibra/vocabularies/__init__.py

@@ -14,11 +14,10 @@
 # limitations under the License.
 """Abbreviations and aliases."""
 
-from ..commons import InstanceTable
-
 import json
 from os import path
 
+from ..commons import InstanceTable
 
 RT_DIR = path.dirname(__file__)
 

siibra/volumes/__init__.py

@@ -14,10 +14,11 @@
 # limitations under the License.
 """Package handling variety of volumes and volume operations"""
 
+from typing import List, Union
+
+import numpy as np
+
 from .parcellationmap import Map
 from .providers import provider
 from .volume import from_array, from_file, from_pointcloud, from_nifti, Volume
-
 from ..commons import logger
-from typing import List, Union
-import numpy as np