albucore: Skill for Codex

Albucore Conventions

For runtime implementation or review, also read ../performance-optimization/SKILL.md and its canonical reference completely before acting.

When to Apply

• Implementing or changing code under albucore/.
• Adding or modifying tests.
• Reviewing image-processing code.
• Answering questions about shapes, dtypes, backend choice, or dependency lock consistency.

Critical Rules

1. Image Shapes - Always Explicit Channel Dimension

# Correct
grayscale = (H, W, 1)
rgb = (H, W, 3)
batch = (N, H, W, C)
volume = (D, H, W, C)

# Wrong - never use implicit channels
gray = (H, W)
gray_vol = (D, H, W)

Dimension indexing is always:

num_channels = image.shape[-1]
width = image.shape[-2]
height = image.shape[-3]

An API that explicitly accepts a torch.Tensor defines its layout independently; never infer a Tensor layout from its rank. resize3d declares NumPy DHWC and Torch CDHW. warp_affine3d uses the same prevalidated single-volume layouts. AlbumentationsX checks CPU, strided layout, eager (requires_grad=False) execution, and all control data before the call. Each volume router accepts exactly one volume.

1a. Precondition Boundary - Do Not Revalidate in Albucore

Albucore routers receive prevalidated inputs from the caller. The upstream transform layer owns validation of:

• container type, rank, layout, and explicit channel dimension;
• dtype, device, contiguity, and autograd state;
• spatial sizes, control-data shapes, interpolation, border, and fill contracts.

Do not add duplicate runtime checks for these preconditions inside Albucore routers. Keep only the dispatch needed to select the NumPy or Torch implementation and the normalization/conversion required by the selected kernel. A caller contract violation is outside the low-level router contract; tests and benchmarks must use valid inputs. Document the precondition boundary in public-router docstrings.

2. Supported Dtypes - uint8 and float32 Only