Skip to content

VectorField

voxel.VectorField(tensor, geometry=None, space=None)

Bases: Volume

A 3-channel volume of 3D vectors, e.g. displacements or flow velocities, whose values are expressed in either world or voxel units (space).

Parameters:

  • tensor (Tensor or Volume) –

    Vector data tensor of shape \((3, W, H, D)\), or a 3-channel volume, whose geometry is adopted when geometry is not explicitly provided.

  • geometry (AcquisitionGeometry or AffineMatrix, default: None ) –

    Affine geometry or matrix representing the voxel-to-world coordinate transform.

  • space (Space, default: None ) –

    The coordinate space of the vector values, either 'world' or 'voxel'. Required.

new(tensor, geometry=None, keep_labels=True) -> VectorField | vx.Volume

Construct a new instance with the provided tensor, preserving unchanged properties. The result remains a VectorField with the same vector space when the tensor still holds 3 channels and decays to a Volume otherwise.

Parameters:

  • tensor (Tensor) –

    The new data tensor replacement.

  • geometry (AcquisitionGeometry, default: None ) –

    The new geometry. If None, the current geometry is propagated.

  • keep_labels (bool, default: True ) –

    Unused for vector fields. Present to match the Volume interface.

Returns:

in_space(space) -> VectorField

Convert the vector values to a target coordinate space, rotating and scaling them through the linear part of the geometry.

Parameters:

  • space (Space) –

    Target space of the vector values, either 'world' or 'voxel'.

Returns:

  • VectorField –

    The converted field, or the unchanged instance when already in the target space.

as_warp() -> Warp

Convert to an absolute world-space coordinate warp, built as the identity grid displaced by the world-space vectors.

Returns:

  • Warp –

    The corresponding coordinate warp.

integrate(coordinates, dt, method='euler', time=1, space=None, exact_gradient=True) -> torch.Tensor

Integrate points through the flow field with fixed-step numerical integration. Points beyond the field extent see zero velocity.

Parameters:

  • coordinates (Tensor) –

    Points to integrate, of shape \((..., 3)\).

  • dt (float) –

    Integration step size.

  • method (str, default: 'euler' ) –

    Integration scheme, either forward 'euler' or midpoint 'rk2'.

  • time (float, default: 1 ) –

    Total integration time.

  • space (Space, default: None ) –

    Coordinate space of the input and returned points. If None, the space of the field vectors is assumed.

  • exact_gradient (bool, default: True ) –

    When disabled, backprop may use cheaper approximate gradients that do not exactly match the integrated result. For rk2, the midpoint velocity is excluded from the graph, roughly halving backward time and memory at the cost of a small dt-dependent gradient bias. The forward result is unaffected.

Returns:

  • Tensor –

    The integrated points, of shape \((..., 3)\).

exponentiate(steps) -> VectorField

Exponentiate a stationary velocity field by scaling and squaring.

Parameters:

  • steps (int) –

    Number of scaling and squaring iterations.

Returns:

  • VectorField –

    The displacement field of the flowed deformation, expressed in the vector space of this field.