Albucore Conventions

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]

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 and remap3d accept either those single-volume layouts or NumPy NDHWC and Torch NCDHW batches. Their shared matrix or grid applies to every item. Other volume routers accept one volume. AlbumentationsX checks CPU, strided layout, eager (requires_grad=False) execution, and all 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.

2. Supported Dtypes - uint8 and float32 Only

No float64 in the validated public path. Callers reject unsupported dtypes before dispatch; runtime kernels may rely on the documented uint8/float32 contract.

3. Backend Routing - Benchmark-Driven Only

• Do not assume LUT is fastest for uint8; benchmark.
• NumKong is used where benchmarks win (blend, moments, scale, cdist, etc.); see docs/numkong-performance.md.
• StringZilla is a candidate for uint8 translation paths; compare it with the public LUT router and OpenCV.
• OpenCV has a 4-channel limit for many ops. Use MAX_OPENCV_WORKING_CHANNELS, then fall back to NumPy or chunking for more channels.
• Route from benchmark evidence in benchmarks/ and docs/numkong-performance.md, not convention.

4. Torch CPU Is a Mandatory Backend

• torch>=2.14.0 is a required runtime dependency, not an optional import. Use direct imports rather than sys.modules checks, class-name heuristics, or lazy imports.
• Training callers are expected to have imported Torch already. Do not optimize public CPU routing around deferred import cost.
• A public Tensor path must state its layout. For caller-prevalidated routers such as resize3d, warp_affine3d, and remap3d, AlbumentationsX owns CPU, strided-layout, and requires_grad=False validation. These routers do not silently detach or move data.
• Benchmark NumPy-to-Torch routes end-to-end: wrapper creation, permutations, dtype casts, kernel execution, and returned NumPy layout all belong inside the timed region.
• For resize3d, benchmark direct Tensor and zero-copy Tensor→NumPy→Tensor routes separately. A linear all-axis upscale may select the bridge for speed; preserve its documented float32 tolerance and uint8 delta bound.
• For warp_affine3d, benchmark rank-4 single volumes and rank-5 batches separately. Include matrix conversion, shared affine-grid creation, sampling, fill correction, uint8 conversion, NumPy/Torch views, and output materialization. Compare per-volume calls, N × C folding, native batch sampling, and Tensor/NumPy bridges on the public path.