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)
volume_batch = (N, 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]

NumPy images use HWC, NHWC, DHWC, or NDHWC. An API that accepts a torch.Tensor defines its layout independently; never infer a Tensor layout from its rank. Common image operations use explicit CHW, NCHW, CDHW, or NCDHW layout where channel semantics matter. resize3d declares NumPy DHWC and Torch CDHW. warp_affine3d and remap3d also accept NumPy NDHWC and Torch NCDHW batches. Their shared matrix or grid applies to every item. Other 3D routers accept one volume. AlbumentationsX checks CPU, layout, strides, eager (requires_grad=False) execution, and control data before the call.

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.