Utilities

castalign.utils.phase_correlation(x, y)

castalign.utils.rotation_matrix(z, y, x)

Build a clockwise 3D rotation matrix from Euler angles.

Parameters:

• z (float) – Clockwise rotation angle (degrees) around the z axis.

• y (float) – Clockwise rotation angle (degrees) around the y axis.

• x (float) – Clockwise rotation angle (degrees) around the x axis.

Returns:

Rotation matrix with shape (3, 3).

Return type:

numpy.ndarray

castalign.utils.blit(source, target, loc)

Paste one 3D block into another, clipping to valid bounds.

This is an internal helper for building composite volumes (for example in bake_images()). It exists so higher-level code can place data by absolute location without manual slicing logic.

Parameters:

• source (ndarray) – Source volume of shape (Z, Y, X)

• target (ndarray) – Destination volume of shape (Z, Y, X). Modified in place.

• loc (array-like of int, shape (3,)) – Voxel coordinate in target where source[0, 0, 0] should be placed. Can be negative or out of bounds.

Returns:

target is modified in place.

Return type:

None

castalign.utils.bake_images(im_fixed, im_movable, transform)

Build one combined 3D volume from fixed and movable volumes.

The function applies transform to the movable volume, finds a canvas large enough to hold both volumes in absolute space, and returns the merged result.

Parameters:

• im_fixed (ndarray or ndarray_shifted) – Fixed/reference 3D volume in shape (Z, Y, X).

• im_movable (ndarray or ndarray_shifted) – Movable 3D volume in (Z, Y, X) order.

• transform (castalign.base.Transform) – Transform that maps movable-space coordinates into fixed-space coordinates

Returns:

Combined 3D volume in absolute coordinates.

Return type:

castalign.ndarray_shifted.ndarray_shifted

See also

castalign.base.Transform.transform_image

Method used to resample the movable image into the fixed frame.

castalign.base.Transform.origin_and_maxpos

Method used to estimate transformed bounds before baking.

castalign.utils.blit

Internal helper used for clipped array placement.

castalign.utils.absolute_coords_to_voxel_coords(img, coords)

Convert absolute coordinates to voxel indices for a 3D volume.

For ndarrays, in index i refers to the i’th voxel, or equivalently, the voxel located at position i in the image’s coordinate system. However, in ndarray_shifted, these two do not necessarily coincide. This converts position i in the ndarray_shifted’s coordinate system into the voxel located at that position.

Parameters:

• img (ndarray or ndarray_shifted) – 3D volume. If plain ndarray, origin is assumed to be (0, 0, 0).

• coords (array-like) – Absolute coordinate(s), shape (3,) or (N, 3).

Returns:

Rounded voxel indices: round(coords - img.origin).

Return type:

ndarray of int

See also

castalign.utils.voxel_coords_to_absolute_coords

Inverse conversion from voxel indices to absolute coordinates.

castalign.ndarray_shifted.ndarray_shifted

Array type that stores the origin used by this conversion.

castalign.utils.voxel_coords_to_absolute_coords(img, coords)

Convert voxel indices to absolute coordinates for a 3D volume.

This is the inverse of castalign.utils.absolute_coords_to_voxel_coords().

Parameters:

• img (ndarray or ndarray_shifted) – 3D volume. If plain ndarray, origin is assumed to be (0, 0, 0).

• coords (array-like) – Voxel coordinate(s), shape (3,) or (N, 3).

Returns:

Absolute coordinates: coords + img.origin.

Return type:

ndarray

See also

castalign.utils.absolute_coords_to_voxel_coords

Inverse conversion from absolute coordinates to voxel indices.

castalign.ndarray_shifted.ndarray_shifted

Array type that stores the origin used by this conversion.

castalign.utils.crop_to_intersection(img1, img2)

Crop two 3D volumes to the same overlapping region in absolute space.

This is useful when two volumes are in the same coordinate frame and you need matching fields of view for comparison or visualization.

Parameters:

• img1 (ndarray or ndarray_shifted) – First 3D volume.

• img2 (ndarray or ndarray_shifted) – Second 3D volume.

Returns:

(img1_crop, img2_crop) with the same origin and shape.

Return type:

tuple of ndarray_shifted

See also

castalign.utils.absolute_coords_to_voxel_coords

Coordinate conversion used to compute voxel slices at the intersection.

castalign.utils.voxel_coords_to_absolute_coords

Coordinate conversion used to compute absolute intersection bounds.

castalign.ndarray_shifted.ndarray_shifted

Shift-aware array class used for inputs and outputs.

castalign.utils.load_image(fn, channel=None)

Load a 2D image file and convert it to a single-slice 3D volume.

CASTalign is built for 3D volumes. This helper exists mostly for convenience of converting a 2D channel-last image into (1, Y, X) 3D image

Parameters:

• fn (str or path-like) – Path to an image readable by imageio.imread.

• channel (int or None, optional) – Channel index to extract from a (Y, X, C) image. If None, non-blank channels are averaged.

Returns:

Single-slice volume with shape (1, Y, X).

Return type:

ndarray

castalign.utils.image_is_label(img)

Guess whether a 3D volume is a label volume.

Internally used as a heuristic to pick things like compression behavior for label-like vs intensity-like data.

Parameters:

img (ndarray) – 3D volume of shape (Z, Y, X).

Returns:

True if sampled stats look label-like, else False.

Return type:

bool

castalign.utils.compress_image(img, level='normal')

Compress a 3D volume for CASTalign storage.

This is the main package helper used when image volumes need to be saved in graph files or passed around compactly.

Parameters:

• img (ndarray) – Volume data of shape (Z, Y, X) or (Y, X) (interpreted as (1, Y, X))

• level ({‘low’, ‘normal’, ‘high’, ‘label’}, optional) – Compression mode.

  • 'label' forces lossless label-style compression.

  • 'low', 'normal', 'high' are lossy settings for

    non-label-like data.

Returns:

• data (bytes-like or ndarray of uint8) – Compressed payload.

• kind (list) – Metadata used by decompress_image() to decode data.

castalign.utils.decompress_image(data, kind)

Decompress a volume payload produced by compress_image().

This is the read-side helper used when loading graph data.

Parameters:

• data (bytes-like or ndarray) – Compressed payload bytes/array.

• kind (sequence) – Metadata returned by compress_image(). kind[0] is the format code (0/1/2/3).

Returns:

Decompressed volume array (typically (Z, Y, X)).

Return type:

ndarray

castalign.utils.invert_function_numerical(func, point)

Numerically find an input point that maps to a target output point.

This is an internal optimization helper used by invert_transform_numerical.

Parameters:

• func (callable) – Forward point-mapping function. It is called as func(np.asarray([x])).

• point (array-like) – Target coordinate of shape (3,).

Returns:

Estimated input point.

Return type:

ndarray

castalign.utils.invert_transform_numerical(tform, points)

Invert one or more 3D points through a transform.

This is used internally for transform types without an analytic inverse.

Parameters:

• tform (object) – Transform object with invert() and transform(...) methods.

• points (array-like) – Point(s) in (z, y, x) order. Shape (3,) or (N, 3).

Returns:

Inverse-mapped point(s).

Return type:

ndarray

castalign.base.compose_transforms(a, b)

Compose two transforms into one transform chain.

This is the implementation behind a + b. It handles composing transform instances, and also the mixed case where a is an already-fit transform instance and b is a transform class.

Parameters:

• a (Transform) – Left-hand transform. Must be an instantiated transform.

• b (Transform or type) – Right-hand transform, either as an instance or as a transform class.

Returns:

Depending on inputs:

• If both are instances, returns an instantiated composed transform.

• If b is a class, returns a composed transform class.

• Identity components are simplified away when possible.

Return type:

Transform or type

Notes

For affine + affine composition, the returned composed class uses affine shortcuts (combined matrix/shift). For non-affine composition, point mapping is composed directly.