brainhops.datamodel.geometry

The geometry of an image: its sampling grid and voxel-to-world transformation.

Classes

Geometry

Geometry(
    _transformations: tuple[CartesianField, Transformation],
    shape: tuple[int, ...] | None = None,
    grid: CartesianField | None = None,
    transformation: Transformation | None = None,
)

Bases: _GeometryFields, ImmutableSequence

A Cartesian field and a voxel-to-world transformation that, together, define the geometry of an image.

The Cartesian field defines the grid onto which the image is defined. The transformation maps the voxel coordinates to world coordinates.

Attributes

transformation `property` `writable`

transformation: Transformation

The voxel-to-world transformation that defines the image geometry.

grid `property` `writable`

grid: CartesianField

The Cartesian field that defines the grid of the image.

shape `property` `writable`

shape: tuple[int, ...]

The shape of the image data.

Methods:

rmatmul

__rmatmul__(other: Transformation) -> Self

Compose other with this geometry's transformation.

Returns a new Geometry with the same grid, whose transformation is the composition of other and this geometry's transformation.

getitem

__getitem__(index: tuple[int | slice | None, ...]) -> Self

This mimics indexing into the data array of an image and returns the geometry of the resulting sub-image.

compute

compute(
    mode: ModeLike | None = None,
    *,
    simplify: SimplifyLike = "analytic",
    factor: bool = False,
) -> Self

Compute the geometry by simplifying its transformation.

A Geometry holds a grid and a voxel-to-world transformation. The transformation part is computed, and the result is returned as a Geometry with the same grid and the simplified transformation. The grid is preserved, so the geometry keeps its grid-and- transformation pair and the domain it defines is never lost.

from_dict `classmethod`

from_dict(other: Mapping, *args, **kwargs) -> Self

Create an instance of the class from a dictionary-like object.

Only keys in the dictionary that match keyword-like fields of this class, or the keywords its constructor takes without storing them (its InitVars, such as the matrix= of an Affine), will be used. Other keys are ignored, but see from_other, which refuses them.

Additional positional and/or keyword arguments can be provided, and will take precedence over the values in the dictionary.

A key naming a field that this class fixes (a field that cannot be passed to its constructor) is checked instead of used: a dictionary that sets it to anything other than None or the value of this class is refused with a ValueError.

from_instance `classmethod`

from_instance(other: Self, *args, **kwargs) -> Self

Create an instance of the class from an instance of a similar class.

Only attributes of the other instance that match keyword-like fields of this class will be used. An attribute that is None is unset, and leaves the default of this class in place.

Additional positional and/or keyword arguments can be provided, and will take precedence over the attributes in the instance.

Unless the other instance is already an instance of this class, an attribute naming a field that this class fixes (a field that cannot be passed to its constructor) is checked instead of used: an instance that sets it to anything other than None or the value of this class is refused with a ValueError. A generic Axis whose orientation is right-to-left, for example, cannot be read as a LeftToRightAxis.

from_other `classmethod`

from_other(other: Any, *args, **kwargs) -> Self

Create an instance of the class from any object that can be interpreted as a dictionary, or an instance of a similar class, or an arguments to be passed to the constructor.

A similar class is this class or one of its parents within the data model, or another member of a polymorphic family this class belongs to: calling a polymorphic class such as Axis builds the subclass its arguments select, so a "generic" axis is usually an instance of a sibling (a RightToLeftAxis, a TimeAxis) rather than of a parent. Any other object, including an instance of a parent that is not a data model (such as a plain object), is passed to the constructor.

Unlike from_dict, a dictionary with a key that matches no field of this class is refused with a TypeError naming the keys, so that a misspelt key is not silently dropped.

simplify

simplify(
    policy: SimplifyLike = "analytic",
    *,
    compute: ModeLike | bool | None = False,
) -> Self

Simplify this transformation under a per-kind policy.

Convenience sugar for compute: t.simplify(policy, compute=mode) is t.compute(mode, simplify=policy).

By default simplify() does no computation at all: compute=False maps to mode=False, which composes nothing (no matrices multiplied, no fields sampled, no lazy inverse materialized). It only downcasts each leaf under policy (analytic by default). Pass an explicit compute=<mode> to also compose that kind.

Parameters:

Name	Type	Description	Default
`policy`	`simplify policy`	The simplify policy, in the grammar `compute` accepts.	`"analytic"`
`compute`	`[list of] name or type`	The compose mode. The default, `False`, composes nothing (`mode=False` in `compute`); `None` would compose every kind. A real mode passes straight through.	`False`

square

square(compute: bool = False, **kwargs) -> Transformation

Return the square of this transformation, self @ self.

The square is the sequence [self, self], which composes when it is computed. It is defined for a transformation that maps a space to itself.

Parameters:

Name	Type	Description	Default
`compute`	`bool`	Whether to compute the result now rather than return it lazily.	`False`
`**kwargs`		Passed to `compute` when `compute` is true.	`{}`

Raises:

Type	Description
`DomainError`	If the transformation does not map a space to itself.

sqrt

sqrt(compute: bool = False, **kwargs) -> Transformation

Return the principal square root of this chain.

The chain is first simplified, which costs nothing. A chain [P, *X, P^-1], where P^-1 is the lazy inverse of P, or both are affines whose product is exactly the identity, is a change of coordinates around X, and its square root is [P, sqrt(X), P^-1]: a field stored in voxels between a world-to-voxel affine and its lazy inverse keeps that form. Any other chain is composed now, and the square root of the transformation it composes to is returned.

Raises:

Type	Description
`DomainError`	If the chain does not map a space to itself, or if the square root of what it reduces to is not defined.
`NotImplementedError`	If the chain does not compose to a single transformation.

to

to(
    cls: Type[Transformation] | None = None, **kwargs
) -> Transformation

Convert this chain to a different type or encoding.

See Transformation.to. A chain has no tangent of its own -- the tangent of a composition is not the sum of the tangents -- so log= re-encodes the transformation it reduces to, and anything else is refused before it is computed:

a chain that simplifies to one transformation is that one;
a change of coordinates [P, *X, P^-1] (see sqrt) keeps its ends, and re-encodes X: the flow of a velocity commutes with the conjugation, so this is exact. A velocity read between a world-to-voxel affine and its inverse (|svf) is turned into its displacement that way;
a chain of affines is composed, which is cheap and exact.

Any other chain -- one with a field, between ends that do not undo each other -- raises ConversionError.

brainhops.datamodel.geometry

Classes

Geometry

Attributes

transformation property writable

grid property writable

shape property writable