Motivation
NumKong 7.7.0 already exports N-D Tensor operations and sin, cos, and atan vector kernels. AlbumentationsX still returns to NumPy or OpenCV for common elementary-math passes:
exp for Gaussian kernels and reconstruction from optical density.log for optical-density transforms.sqrt for distances, norms, and standard deviations.abs for magnitudes and error maps.floor, ceil, and rint for coordinate and integer conversion.atan2 for dense direction and polar-angle fields.hypot for stable Euclidean magnitudes.
The 2026-07-24 AlbumentationsX source audit found 8 np.arctan2 and 4 np.hypot call sites. Some operate on full image-sized coordinate fields; others are small and remain dispatch-bound. These operations are useful beyond computer vision and fit the existing elementwise kernel model.
Verified result from existing 7.7.0 kernels
AlbumentationsX WaterRefraction can already replace its dense NumPy sin followed by scalar multiplication with NumKong 7.7.0 sin and scale.
On Apple arm64 with NumPy 2.2.6 and OpenCV 5.0.0, the production candidate reduced direct displacement-map generation time by 10.4–15.8% at 256², 512², and 1024². Through A.Compose, it reduced total transform time by 5.8–17.4% across the complete 256/512/1024 × C=1/3/5 grid for both uint8 and float32.
The optimized maps were bit-identical to the NumPy baseline in direct 64², 256², and 512² controls, and the transformed images were bit-identical in 512² × C=3 controls for both tested dtypes. These measurements use NumKong 7.7.0; 7.7.1 was excluded.
Requested API
Unary operations:
nk.abs(a, out=None)
nk.sqrt(a, out=None)
nk.exp(a, out=None)
nk.log(a, out=None)
nk.floor(a, out=None)
nk.ceil(a, out=None)
nk.rint(a, out=None)
Binary operations:
nk.atan2(y, x, out=None)
nk.hypot(x, y, out=None)
atan2 and hypot can follow the unary phase if binary broadcasting requires separate Tensor plumbing.
Contract
- Arbitrary-rank contiguous buffers initially; strided Tensor views as the next step.
- NumPy-compatible broadcasting for binary operations.
- Optional
out=.
float32 and float64 first.- Document output dtype for integer and mini-float inputs.
- Match documented IEEE behavior for NaN, infinity, signed zero, negative square roots, and logarithm domain errors.
- Preserve
atan2 quadrant and signed-zero behavior.
- Implement
hypot without avoidable intermediate overflow or underflow.
- Make rounding independent of process-wide floating-point control state.
- Release the GIL.
Benchmark and accuracy matrix
Compare with NumPy and the matching OpenCV operation where one exists. Test subnormals, values near one, large magnitudes, atan2 quadrants, hypot scale imbalance, and ULP error across every enabled ISA. Include HWC through NDHWC tensors from small dispatch-bound buffers to memory-bandwidth-sized buffers.
Related: #313 and #327.
Motivation
NumKong 7.7.0 already exports N-D Tensor operations and
sin,cos, andatanvector kernels. AlbumentationsX still returns to NumPy or OpenCV for common elementary-math passes:expfor Gaussian kernels and reconstruction from optical density.logfor optical-density transforms.sqrtfor distances, norms, and standard deviations.absfor magnitudes and error maps.floor,ceil, andrintfor coordinate and integer conversion.atan2for dense direction and polar-angle fields.hypotfor stable Euclidean magnitudes.The 2026-07-24 AlbumentationsX source audit found 8
np.arctan2and 4np.hypotcall sites. Some operate on full image-sized coordinate fields; others are small and remain dispatch-bound. These operations are useful beyond computer vision and fit the existing elementwise kernel model.Verified result from existing 7.7.0 kernels
AlbumentationsX
WaterRefractioncan already replace its dense NumPysinfollowed by scalar multiplication with NumKong 7.7.0sinandscale.On Apple arm64 with NumPy 2.2.6 and OpenCV 5.0.0, the production candidate reduced direct displacement-map generation time by 10.4–15.8% at 256², 512², and 1024². Through
A.Compose, it reduced total transform time by 5.8–17.4% across the complete 256/512/1024 × C=1/3/5 grid for bothuint8andfloat32.The optimized maps were bit-identical to the NumPy baseline in direct 64², 256², and 512² controls, and the transformed images were bit-identical in 512² × C=3 controls for both tested dtypes. These measurements use NumKong 7.7.0; 7.7.1 was excluded.
Requested API
Unary operations:
Binary operations:
atan2andhypotcan follow the unary phase if binary broadcasting requires separate Tensor plumbing.Contract
out=.float32andfloat64first.atan2quadrant and signed-zero behavior.hypotwithout avoidable intermediate overflow or underflow.Benchmark and accuracy matrix
Compare with NumPy and the matching OpenCV operation where one exists. Test subnormals, values near one, large magnitudes,
atan2quadrants,hypotscale imbalance, and ULP error across every enabled ISA. Include HWC through NDHWC tensors from small dispatch-bound buffers to memory-bandwidth-sized buffers.Related: #313 and #327.