Rasterization API

This module provides spatial-to-sequence rasterization for autoregressive modeling of 2D/3D spatial data.

Rasterization Methods

RasterScan

Simple row-by-row or slice-by-slice scanning.

class medlatents.rasterization.RasterScan[source][source]

Bases: object

Standard raster scan ordering: row-by-row (or slice-by-slice for 3D).

Simple and fast. Consecutive tokens in the sequence may be spatially distant (e.g., end of row N and start of row N+1).

Example 2x2 image:

[[0, 1],: [2, 3]]

Sequence: [0, 1, 2, 3]

static spatial_to_sequence_2d(spatial, order='row')[source][source]

Convert 2D spatial data to 1D sequence using raster scan.

Parameters:

spatial (Tensor) – [batch, channels, height, width] or [batch, height, width]
order (Literal['row', 'col'], default: 'row') – ‘row’ (row-major) or ‘col’ (column-major)

Returns:

[batch, channels, height*width] or [batch, height*width]

Return type:

sequence

static sequence_to_spatial_2d(sequence, height, width, order='row')[source][source]

Convert 1D sequence back to 2D spatial data.

Parameters:

sequence (Tensor) – [batch, channels, height*width] or [batch, height*width]
height (int) – spatial height
width (int) – spatial width
order (Literal['row', 'col'], default: 'row') – ‘row’ or ‘col’

Returns:

[batch, channels, height, width] or [batch, height, width]

Return type:

spatial

static spatial_to_sequence_3d(spatial, order='DHW')[source][source]

Convert 3D spatial data to 1D sequence.

Parameters:

spatial (Tensor) – [batch, channels, depth, height, width] or [batch, D, H, W]
order (Literal['DHW', 'WHD', 'HWD'], default: 'DHW') – dimension ordering (‘DHW’ = slice-by-slice, etc.)

Returns:

[batch, channels, D*H*W] or [batch, D*H*W]

Return type:

sequence

static sequence_to_spatial_3d(sequence, depth, height, width, order='DHW')[source][source]

Convert 1D sequence back to 3D spatial data.

Parameters:

sequence (Tensor) – [batch, channels, D*H*W] or [batch, D*H*W]
depth (int) – spatial dimensions
height (int) – spatial dimensions
width (int) – spatial dimensions
order (Literal['DHW', 'WHD', 'HWD'], default: 'DHW') – dimension ordering

Returns:

[batch, channels, D, H, W] or [batch, D, H, W]

Return type:

spatial

SCurve

Serpentine/boustrophedon scan pattern with alternating row directions.

class medlatents.rasterization.SCurve[source][source]

Bases: object

S-curve (serpentine/boustrophedon) scan: alternating row direction.

Traverses rows left-to-right then right-to-left alternately, creating a continuous snake-like path.

Properties: - Simple to implement - All horizontal neighbors remain adjacent in sequence - Vertical neighbors have same distance as standard raster scan

Example 4x4 image:: Row 0: [0, 1, 2, 3 ] → Row 1: [7, 6, 5, 4 ] ← Row 2: [8, 9, 10, 11] → Row 3: [15, 14, 13, 12] ←

Sequence: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]

static spatial_to_sequence_2d(spatial, order='row')[source][source]

Convert 2D spatial data to 1D sequence using S-curve scan.

Parameters:

spatial (Tensor) – [batch, channels, height, width] or [batch, height, width]
order (Literal['row', 'col'], default: 'row') – ‘row’ (horizontal serpentine) or ‘col’ (vertical serpentine)

Returns:

[batch, channels, height*width] or [batch, height*width]

Return type:

sequence

static sequence_to_spatial_2d(sequence, height, width, order='row')[source][source]

Convert 1D sequence back to 2D spatial data.

Parameters:

sequence (Tensor) – [batch, channels, height*width] or [batch, height*width]
height (int) – spatial height
width (int) – spatial width
order (Literal['row', 'col'], default: 'row') – ‘row’ or ‘col’

Returns:

[batch, channels, height, width] or [batch, height, width]

Return type:

spatial

static spatial_to_sequence_3d(spatial, order='D')[source][source]

Convert 3D spatial data to 1D sequence using S-curve scan.

Parameters:

spatial (Tensor) – [batch, channels, depth, height, width] or [batch, D, H, W]
order (Literal['D', 'H', 'W'], default: 'D') – which dimension to serpentine (‘D’, ‘H’, or ‘W’)

Returns:

[batch, channels, D*H*W] or [batch, D*H*W]

Return type:

sequence

static sequence_to_spatial_3d(sequence, depth, height, width, order='D')[source][source]

Convert 1D sequence back to 3D spatial data.

Parameters:

sequence (Tensor) – [batch, channels, D*H*W] or [batch, D*H*W]
depth (int) – spatial dimensions
height (int) – spatial dimensions
width (int) – spatial dimensions
order (Literal['D', 'H', 'W'], default: 'D') – which dimension was serpentined

Returns:

[batch, channels, D, H, W] or [batch, D, H, W]

Return type:

spatial

HilbertCurve

Space-filling curve with optimal locality preservation.

class medlatents.rasterization.HilbertCurve[source][source]

Bases: object

Hilbert space-filling curve for locality-preserving rasterization.

The Hilbert curve traverses a 2D grid such that nearby points in the sequence are also nearby in 2D space, maintaining strong spatial correlations between consecutive positions.

Properties: - Strong locality preservation (nearby points remain nearby) - Smooth, continuous traversal - Requires power-of-2 dimensions (pads if needed)

Example 2x2:

[[0, 1],: [3, 2]] (U-shape)

Example 4x4:

[[0, 1, 14, 15],: [3, 2, 13, 12], [4, 7, 8, 11], [5, 6, 9, 10]]

static spatial_to_sequence_2d(spatial)[source][source]

Convert 2D spatial data to sequence using Hilbert curve.

Parameters:: spatial (Tensor) – [batch, channels, height, width] or [batch, height, width]
Returns:: [batch, channels, height*width] or [batch, height*width] metadata: dict with ‘curve’, ‘original_shape’, ‘padding’ for reconstruction
Return type:: sequence

static sequence_to_spatial_2d(sequence, metadata)[source][source]

Convert sequence back to 2D spatial data using Hilbert curve.

Parameters:

sequence (Tensor) – [batch, channels, seq_len] or [batch, seq_len]
metadata (dict) – returned from spatial_to_sequence_2d

Returns:

original shape

Return type:

spatial

static spatial_to_sequence_3d(spatial)[source][source]

Convert 3D spatial data to sequence using Hilbert curve.

Parameters:: spatial (Tensor) – [batch, channels, depth, height, width] or [batch, D, H, W]
Returns:: [batch, channels, D*H*W] or [batch, D*H*W] metadata: dict with ‘curve’, ‘original_shape’, ‘padding’ for reconstruction
Return type:: sequence

static sequence_to_spatial_3d(sequence, metadata)[source][source]

Convert sequence back to 3D spatial data using Hilbert curve.

Parameters:

sequence (Tensor) – [batch, channels, seq_len] or [batch, seq_len]
metadata (dict) – returned from spatial_to_sequence_3d

Returns:

original shape

Return type:

spatial

ZOrderCurve

Morton/Z-order curve using bit interleaving.

class medlatents.rasterization.ZOrderCurve[source][source]

Bases: object

Z-order (Morton) curve for hierarchical locality-preserving rasterization.

The Z-order curve interleaves the bits of x and y coordinates, creating a hierarchical quad-tree traversal with fast computation via bit operations.

Properties: - Hierarchical locality preservation - Fast computation via bit interleaving - Natural quad-tree structure - Requires power-of-2 dimensions

Example 4x4:

[[0, 1, 4, 5],: [2, 3, 6, 7], [8, 9, 12, 13], [10, 11, 14, 15]]

static spatial_to_sequence_2d(spatial)[source][source]

Convert 2D spatial to sequence using Z-order curve.

Parameters:: spatial (Tensor)
Return type:: tuple[Tensor, dict]

static sequence_to_spatial_2d(sequence, metadata)[source][source]

Convert sequence back to spatial using Z-order curve.

Parameters:

sequence (Tensor)
metadata (dict)

Return type:

Tensor

static spatial_to_sequence_3d(spatial)[source][source]

Convert 3D spatial data to sequence using Z-order curve.

Parameters:: spatial (Tensor) – [batch, channels, D, H, W] or [batch, D, H, W]
Returns:: [batch, channels, D*H*W] or [batch, D*H*W] metadata: dict with curve, padding, original_shape, order
Return type:: sequence

static sequence_to_spatial_3d(sequence, metadata)[source][source]

Convert sequence back to 3D spatial using Z-order curve.

Parameters:

sequence (Tensor) – [batch, channels, seq_len] or [batch, seq_len]
metadata (dict) – dict from spatial_to_sequence_3d

Returns:

[batch, channels, D, H, W] or [batch, D, H, W]

Return type:

spatial

Convenience Functions

medlatents.rasterization.rasterize_2d(spatial, method='raster', **kwargs)[source][source]

Convert 2D spatial data to 1D sequence.

Parameters:

spatial (Tensor) – [batch, channels, H, W] or [batch, H, W]
method (Literal['raster', 'scurve', 'hilbert', 'zorder'], default: 'raster') – ‘raster’ (row-by-row), ‘scurve’ (serpentine), ‘hilbert’ (space-filling curve), ‘zorder’ (Morton/quad-tree)
**kwargs – method-specific arguments (e.g., order=’row’/’col’)

Returns:

[batch, channels, H*W] or [batch, H*W] metadata: None for raster/scurve, dict for hilbert/zorder (needed for reconstruction)

Return type:

sequence

medlatents.rasterization.unrasterize_2d(sequence, height, width, method='raster', metadata=None, **kwargs)[source][source]

Convert 1D sequence back to 2D spatial data.

Parameters:

sequence (Tensor) – [batch, channels, H*W] or [batch, H*W]
height (int) – spatial dimensions
width (int) – spatial dimensions
method (Literal['raster', 'scurve', 'hilbert', 'zorder'], default: 'raster') – must match the rasterization method used
metadata (dict | None, default: None) – required for hilbert/zorder, None for raster/scurve
**kwargs – method-specific arguments (e.g., order=’row’/’col’)

Returns:

[batch, channels, H, W] or [batch, H, W]

Return type:

spatial