siibra.locations

Handles spatial concepts and spatial operation like warping between spaces.

Submodules

• siibra.locations.boundingbox
• siibra.locations.location
• siibra.locations.point
• siibra.locations.pointset

Classes

BoundingBox	A 3D axis-aligned bounding box spanned by two 3D corner points.
Point	A single 3D point in reference space.
PointSet	A set of 3D points in the same reference space,
WholeBrain	Trivial location class for formally representing

Package Contents

class siibra.locations.BoundingBox(point1, point2, space=None, minsize: float = None, sigma_mm=None)

A 3D axis-aligned bounding box spanned by two 3D corner points. The box does not necessarily store the given points, instead it computes the real minimum and maximum points from the two corner points.

clip(xyzmax, xyzmin=(0, 0, 0))

Returns a new bounding box obtained by clipping at the given maximum coordinate.

contained_in(other: siibra.locations.location.Location | nibabel.Nifti1Image)

contains(other: siibra.locations.location.Location)

Returns true if the bounding box contains the given location.

estimate_affine(space)

Computes an affine transform which approximates the nonlinear warping of the eight corner points to the desired target space. The transform is estimated using a least squares solution to A*x = b, where A is the matrix of point coefficients in the space of this bounding box, and b are the target coefficients in the given space after calling the nonlinear warping.

fetch_regional_map()

Generate a volumetric binary mask of this bounding box in the reference template space.

classmethod from_image(image: nibabel.Nifti1Image, space, ignore_affine=False, threshold=0)

Construct a bounding box from a nifti image

intersection(other, dims=[0, 1, 2], threshold=0)

Computes the intersection of this bounding box with another one.

TODO process the sigma values o the points

Args:

other (BoundingBox): Another bounding box dims (list of int): Dimensions where the intersection should be computed (applies only to bounding boxes) Default: all three. Along dimensions not listed, the union is applied instead. threshold: optional intensity threshold for intersecting with image mask

intersects(other: siibra.locations.location.Location | nibabel.Nifti1Image)

Verifies wether this 3D location intersects the given mask.

NOTE: The affine matrix of the image must be set to warp voxels coordinates into the reference space of this Bounding Box.

shift(offset)

transform(affine: numpy.ndarray, space=None)

Returns a new bounding box obtained by transforming the min- and maxpoint of this one with the given affine matrix.

TODO process the sigma values o the points

Parameters:

• affine (numpy 4x4 ndarray) – affine matrix

• space (reference space (str, Space, or None)) – Target reference space which is reached after applying the transform. Note that the consistency of this cannot be checked and is up to the user.

union(other)

Computes the union of this boudning box with another one.

Args:

other (BoundingBox): Another bounding box

warp(space)

Returns a new bounding box obtained by warping the min- and maxpoint of this one into the new target space.

TODO process the sigma values o the points

zoom(ratio: float)

Create a new bounding box by zooming this one around its center.

property center

property id: str

property is_planar

maxpoint

minpoint

property shape

property volume

class siibra.locations.Point(coordinatespec, space=None, sigma_mm: float = 0.0)

A single 3D point in reference space.

bigbrain_section()

Estimate the histological section number of BigBrain which corresponds to this point. If the point is given in another space, a warping to BigBrain space will be tried.

contained_in(other: siibra.locations.location.Location | nibabel.Nifti1Image)

contains(other: siibra.locations.location.Location | nibabel.Nifti1Image)

get_enclosing_cube(width_mm)

Create a bounding box centered around this point with the given width.

intersection(other: siibra.locations.location.Location | nibabel.Nifti1Image) → Point

All subclasses of Location must implement intersection, as it is required by SpatialFeature._test_mask()

intersects(other: siibra.locations.location.Location | nibabel.Nifti1Image) → bool

Returns true if this point lies in the given mask.

NOTE: The affine matrix of the image must be set to warp voxels coordinates into the reference space of this Bounding Box.

static parse(spec, unit='mm') → Tuple[float, float, float]

Converts a 3D coordinate specification into a 3D tuple of floats.

Parameters:

• spec (Any of str, tuple(float,float,float)) – For string specifications, comma separation with decimal points are expected.

• unit (str) – specification of the unit (only ‘mm’ supported so far)

Return type:

tuple(float, float, float)

transform(affine: numpy.ndarray, space=None)

Returns a new Point obtained by transforming the coordinate of this one with the given affine matrix.

Parameters:

• affine (numpy 4x4 ndarray) – affine matrix

• space (str, Space, or None) –

  Target reference space which is reached after applying the transform

  Note

  The consistency of this cannot be checked and is up to the user.

warp(space)

Creates a new point by warping this point to another space

property boundingbox

coordinate

property homogeneous

The homogenous coordinate of this point as a 4-tuple, obtained by appending ‘1’ to the original 3-tuple.

property id: str

sigma = 0.0

property volume

The volume of a point can be nonzero if it has a location uncertainty.

class siibra.locations.PointSet(coordinates, space=None, sigma_mm=0)

A set of 3D points in the same reference space, defined by a list of coordinates.

as_list()

Return the point set as a list of 3D tuples.

intersection(other: siibra.locations.location.Location | nibabel.Nifti1Image)

Return the subset of points that are inside the given mask.

NOTE: The affine matrix of the image must be set to warp voxels coordinates into the reference space of this Bounding Box.

intersects(other: siibra.locations.location.Location | nibabel.Nifti1Image)

Verifies wether this 3D location intersects the given mask.

NOTE: The affine matrix of the image must be set to warp voxels coordinates into the reference space of this Bounding Box.

transform(affine: numpy.ndarray, space=None)

Returns a new PointSet obtained by transforming the coordinates of this one with the given affine matrix.

Parameters:

• affine (numpy 4x4 ndarray) – affine matrix

• space (reference space (id, name, or Space)) – Target reference space which is reached after applying the transform. Note that the consistency of this cannot be checked and is up to the user.

warp(space, chunksize=1000)

Creates a new point set by warping its points to another space

property boundingbox

Return the bounding box of these points.

property centroid

property has_constant_sigma

property homogeneous

Access the list of 3D point as an Nx4 array of homogeneous coorindates.

property sigma

property volume

class siibra.locations.WholeBrain(space=None)

Trivial location class for formally representing location in a particular reference space, which is not further specified.

intersection(mask: nibabel.Nifti1Image) → bool

Required for abstract class Location

intersects(*_args, **_kwargs)

Always true for whole brain features

transform(affine: numpy.ndarray, space=None)

Does nothing.

warp(space)

Generates a new whole brain location in another reference space.