[Feature] Python bindings for variable-shape image batches

[zacharyvincze]

Python bindings for variable-shape image batches

Summary

Exposes the varshape image-batch types to rocpycv: Image, ImageBatchVarShape, and Format (ImageFormat), plus the eSwizzle enum and DLPack-based zero-copy helpers. Builds on the C++ varshape work from the base branches.

Changes

• Format — pybind binding for ImageFormat, constructed from (dtype, channels, swizzle). Named constants (Format.RGB8, etc.) live on a metaclass so they're class-only (Format.RGB8, not Format.RGB8.RGB8), matching the C++ __getattribute__ guard. Exposes dtype, channels, planes, swizzle, equality/hash/repr.
• Image — __init__(size, format, device) and Image.zeros(...); copy_to, device, format, width/height/size; DLPack interop via __dlpack__ / __dlpack_device__.
• ImageBatchVarShape — __init__(capacity, device); pushback (single + sequence), popback, clear; __len__, __getitem__, __iter__; capacity, device, maxsize, uniqueformat.
• as_image / as_images — wrap existing DLPack buffer(s) into an Image / ImageBatchVarShape without copying.
• eSwizzle enum — added to py_enums (XYZW, ZYXW).
• Registration — new exporters wired into main.cpp; type stubs updated in rocpycv.pyi.

Notes

• Based on [Feature] Resize varshape to constant sized Tensor path #159

[Copilot]

Pull request overview

Adds variable-shape image primitives to rocCV (C++ core + wrappers) and exposes them to Python (rocpycv) with DLPack zero-copy interop, plus extends Resize to accept ImageBatchVarShape inputs and updates tests/samples accordingly.

Changes:

• Introduces C++ Image, ImageBatchVarShape, ImageData / ImageBatchData snapshot types, and a kernel-friendly ImageBatchVarShapeWrapper.
• Refactors border/interpolation composition to be wrapper-generic (MakeBorderWrapper / MakeInterpolationWrapper) and updates operators/tests from ImageWrapper to TensorWrapper.
• Adds Python bindings for Format (ImageFormat), Image, ImageBatchVarShape, eSwizzle, and as_images(...), plus a new var-shape resize sample and extended resize test coverage.

Reviewed changes

Copilot reviewed 91 out of 91 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/roccv/cpp/src/tests/operators/test_op_warp_perspective.cpp	Updates golden path to new wrapper factories + TensorWrapper.
tests/roccv/cpp/src/tests/operators/test_op_warp_affine.cpp	Updates golden path to new wrapper factories + TensorWrapper.
tests/roccv/cpp/src/tests/operators/test_op_thresholding.cpp	Switches test wrappers/include to TensorWrapper.
tests/roccv/cpp/src/tests/operators/test_op_rotate.cpp	Updates golden path to new wrapper factories + TensorWrapper.
tests/roccv/cpp/src/tests/operators/test_op_resize.cpp	Adds var-shape resize correctness tests; updates wrappers; expands cubic coverage.
tests/roccv/cpp/src/tests/operators/test_op_normalize.cpp	Switches include to TensorWrapper.
tests/roccv/cpp/src/tests/operators/test_op_histogram.cpp	Switches test wrappers/include to TensorWrapper.
tests/roccv/cpp/src/tests/operators/test_op_gamma_contrast.cpp	Switches test wrappers/include to TensorWrapper.
tests/roccv/cpp/src/tests/operators/test_op_flip.cpp	Switches test wrappers/include to TensorWrapper.
tests/roccv/cpp/src/tests/operators/test_op_cvt_color.cpp	Switches golden wrappers/include to TensorWrapper.
tests/roccv/cpp/src/tests/operators/test_op_custom_crop.cpp	Switches golden wrappers/include to TensorWrapper.
tests/roccv/cpp/src/tests/operators/test_op_copy_make_border.cpp	Updates golden border wrapping to factory + TensorWrapper.
tests/roccv/cpp/src/tests/operators/test_op_convert_to.cpp	Switches golden wrappers/include to TensorWrapper.
tests/roccv/cpp/src/tests/operators/test_op_composite.cpp	Switches golden wrappers/include to TensorWrapper.
tests/roccv/cpp/src/tests/operators/test_op_center_crop.cpp	Switches golden wrappers/include to TensorWrapper.
tests/roccv/cpp/src/tests/operators/test_op_brightness_contrast.cpp	Switches golden wrappers/include to TensorWrapper.
tests/roccv/cpp/src/tests/operators/test_op_bnd_box.cpp	Switches golden wrappers/include to TensorWrapper.
tests/roccv/cpp/src/tests/operators/test_op_bilateral_filter.cpp	Updates border wrapper construction + template args; formatting tweaks.
tests/roccv/cpp/src/tests/core/wrappers/test_tensor_wrapper.cpp	Renames tests to TensorWrapper and updates references.
tests/roccv/cpp/src/tests/core/wrappers/test_interpolation_wrapper.cpp	Updates golden/interp composition to new wrapper types; formatting tweaks.
tests/roccv/cpp/src/tests/core/wrappers/test_border_wrapper.cpp	Updates golden logic and border construction to TensorWrapper + factories.
tests/roccv/cpp/src/tests/core/image/test_image_data.cpp	Adds unit tests for ImageData* construction, casting, and kind checks.
tests/roccv/cpp/src/tests/core/image/test_image_batch_data.cpp	Adds unit tests for ImageBatchData* construction, casting, and kind checks.
tests/roccv/cpp/include/test_helpers.hpp	Adds AsInt/AsAddr/AsSize helpers for stable EXPECT_EQ comparisons.
tests/roccv/cpp/include/image_test_helpers.hpp	Adds shared helpers/sentinels + a counting allocator for image-layer tests.
src/op_warp_perspective.cpp	Moves to TensorWrapper + wrapper factories for interpolation/border.
src/op_thresholding.cpp	Switches operator implementation to TensorWrapper.
src/op_rotate.cpp	Moves to TensorWrapper + wrapper factories; formatting tweaks.
src/op_resize.cpp	Adds var-shape overload and shared launch path; moves scale derivation into kernels.
src/op_remap.cpp	Moves to TensorWrapper + wrapper factories for map + input interpolation.
src/op_reformat.cpp	Switches operator implementation to TensorWrapper.
src/op_normalize.cpp	Switches operator implementation to TensorWrapper.
src/op_histogram.cpp	Switches operator implementation to TensorWrapper.
src/op_gamma_contrast.cpp	Switches operator implementation to TensorWrapper.
src/op_flip.cpp	Switches operator implementation to TensorWrapper.
src/op_cvt_color.cpp	Switches operator implementation to TensorWrapper for host/device paths.
src/op_custom_crop.cpp	Switches operator implementation to TensorWrapper.
src/op_copy_make_border.cpp	Moves to TensorWrapper + border factory; formatting tweaks.
src/op_convert_to.cpp	Switches operator implementation to TensorWrapper.
src/op_composite.cpp	Switches operator implementation to TensorWrapper.
src/op_brightness_contrast.cpp	Switches operator implementation to TensorWrapper.
src/op_bnd_box.cpp	Switches operator implementation to TensorWrapper.
src/op_bilateral_filter.cpp	Moves to TensorWrapper + border factory; updates host threading template args.
src/op_adv_cvt_color.cpp	Switches operator implementation to TensorWrapper for host/device paths.
src/core/tensor_storage.cpp	Removes unused HIP assert include.
src/core/image.cpp	Implements Image allocation, requirement calc, export, and ImageWrapData.
src/core/image_data.cpp	Implements ImageData hierarchy behavior and kind tagging.
src/core/image_batch_var_shape.cpp	Implements producer-side var-shape batch with cached maxSize/uniqueFormat + export sync.
src/core/image_batch_data.cpp	Implements ImageBatchData hierarchy behavior and kind tagging.
src/core/detail/var_shape_descriptor_table.cpp	Implements device/host descriptor table ownership + lazy H2D sync and fence.
samples/resize_var_shape.cpp	New sample app demonstrating var-shape batch resize (GPU).
samples/README.md	Documents the new var-shape resize sample.
samples/common/utils.hpp	Fixes per-image output copy offsets when writing batched tensor images.
samples/CMakeLists.txt	Adds resize_var_shape sample target.
python/src/py_image_format.cpp	Adds Python Format binding for ImageFormat with constants and repr/hash/eq.
python/src/py_image_batch_var_shape.cpp	Adds Python ImageBatchVarShape binding + as_images zero-copy wrapper.
python/src/py_enums.cpp	Exposes eSwizzle enum to Python.
python/src/main.cpp	Registers new Python exporters (Format/Image/ImageBatchVarShape).
python/include/py_image.hpp	Declares PyImage wrapper (allocation + DLPack interop).
python/include/py_image_format.hpp	Declares PyImageFormat exporter.
python/include/py_image_batch_var_shape.hpp	Declares PyImageBatchVarShape wrapper/exporter.
include/op_resize.hpp	Adds Resize overload for ImageBatchVarShape and updates supported interpolation doc.
include/kernels/host/resize_host.hpp	Moves resize scale derivation inside kernel loop (per-image for var-shape).
include/kernels/host/reformat_host.hpp	Updates host kernel signature to TensorWrapper.
include/kernels/host/convert_to_host.hpp	Updates includes to TensorWrapper.
include/kernels/host/brightness_contrast_host.hpp	Updates includes to TensorWrapper.
include/kernels/device/resize_device.hpp	Moves resize scale derivation inside kernel (per-image for var-shape).
include/kernels/device/reformat_device.hpp	Updates device kernel signature to TensorWrapper.
include/kernels/device/copy_make_border_device.hpp	Updates comments to reflect TensorWrapper.
include/kernels/device/convert_to_device.hpp	Updates includes to TensorWrapper.
include/kernels/device/brightness_contrast_device.hpp	Updates includes to TensorWrapper.
include/core/wrappers/tensor_wrapper.hpp	Renames and extends wrapper API (width/height accept optional batch index).
include/core/wrappers/interpolation_wrapper.hpp	Refactors interpolation wrapper to be templated on BorderWrapper type + adds factory.
include/core/wrappers/image_batch_var_shape_wrapper.hpp	Adds wrapper for var-shape batch descriptor table (host/device usable).
include/core/wrappers/border_wrapper.hpp	Refactors border wrapper to be templated on underlying wrapper + adds factory.
include/core/image.hpp	Adds public Image API + ImageWrapData.
include/core/image_storage.hpp	Adds shared storage backing for Image.
include/core/image_format.hpp	Fixes default ctor semantics; adds equality; defines FMT_NONE.
include/core/image_data.hpp	Adds ImageData hierarchy for strided host/hip snapshots + cast<>().
include/core/image_buffer.hpp	Adds strided plane/buffer descriptors.
include/core/image_batch_var_shape.hpp	Adds ImageBatchVarShape producer container + export snapshot API.
include/core/image_batch_data.hpp	Adds ImageBatchData hierarchy for var-shape batch snapshots + cast<>().
include/core/image_batch_buffer.hpp	Adds var-shape batch buffer descriptor struct.
include/core/detail/var_shape_descriptor_table.hpp	Declares descriptor table owner/sync primitive for var-shape batches.
include/common/validation_helpers.hpp	Adds validation macros for ImageBatchVarShape and includes ImageFormat.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 83.07453% with 109 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
include/common/validation_helpers.hpp	17.39%	13 Missing and 6 partials ⚠️
src/core/detail/var_shape_descriptor_table.cpp	81.32%	8 Missing and 9 partials ⚠️
src/core/image_batch_var_shape.cpp	85.47%	10 Missing and 7 partials ⚠️
src/op_adv_cvt_color.cpp	63.64%	16 Missing ⚠️
src/op_resize.cpp	74.14%	2 Missing and 13 partials ⚠️
src/core/image.cpp	85.88%	7 Missing and 5 partials ⚠️
include/core/image_batch_var_shape.hpp	33.33%	4 Missing ⚠️
include/core/image_data.hpp	66.67%	3 Missing and 1 partial ⚠️
include/core/image.hpp	57.14%	3 Missing ⚠️
include/core/image_format.hpp	80.00%	0 Missing and 1 partial ⚠️
... and 1 more

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #160      +/-   ##
===========================================
+ Coverage    79.40%   80.35%   +0.95%     
===========================================
  Files           81       93      +12     
  Lines         3544     4041     +497     
  Branches       765      841      +76     
===========================================
+ Hits          2814     3247     +433     
- Misses         368      389      +21     
- Partials       362      405      +43     

Files with missing lines	Coverage Δ
include/core/detail/var_shape_descriptor_table.hpp	100.00% <100.00%> (ø)
include/core/image_batch_data.hpp	100.00% <100.00%> (ø)
include/core/image_storage.hpp	100.00% <100.00%> (ø)
include/core/wrappers/border_wrapper.hpp	74.14% <100.00%> (+1.92%)	⬆️
...de/core/wrappers/image_batch_var_shape_wrapper.hpp	100.00% <100.00%> (ø)
include/core/wrappers/interpolation_wrapper.hpp	100.00% <100.00%> (+56.60%)	⬆️
include/kernels/host/brightness_contrast_host.hpp	100.00% <ø> (ø)
include/kernels/host/convert_to_host.hpp	100.00% <ø> (ø)
include/kernels/host/reformat_host.hpp	100.00% <100.00%> (ø)
include/kernels/host/resize_host.hpp	100.00% <100.00%> (ø)
... and 31 more

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.