Merge pull request #27823 from armanrasta:5.x

Add ColorHashTSDFVolume implementation #27823

# Add ColorHashTSDFVolume implementation  [[#25155](https://github.com/opencv/opencv/issues/25155)]
## Description
Added a new ColorHashTSDFVolume implementation that combines the benefits of HashTSDFVolume's efficient spatial hashing with color support. This provides memory-efficient RGB-D fusion with better performance compared to regular ColorTSDFVolume.

### Key Features
- Hash-based spatial data structure for efficient storage
- Color integration during volume updates
- Raycast with color interpolation
- Compatible with existing TSDF interfaces
- CPU implementation with parallel processing support

### Implementation Details
- Added new ColorHashTSDFVolume class with create() factory method
- ColorVoxel structure combining TSDF and RGB data
- Spatial hashing for efficient voxel lookup
- Weighted running average for color updates
- Trilinear interpolation during raycasting
- Unit tests for basic operations and edge cases

### Files Modified/Added
- modules/3d/src/rgbd/color_hash_volume.hpp - New header defining ColorHashTSDFVolume interface
- modules/3d/src/rgbd/color_hash_volume.cpp - Implementation of ColorHashTSDFVolume
- modules/3d/test/test_color_hash_volume.cpp - Unit tests

### Performance
The implementation uses spatial hashing to only store voxels near surfaces, significantly reducing memory usage compared to regular ColorTSDFVolume while maintaining similar processing speed.

### Testing
Added unit tests that verify:
- Basic integration and raycasting operations
- Empty volume handling
- Memory usage patterns

### Future Work
- GPU/OpenCL implementation
- Additional color interpolation methods
- Extended comparison tests with other volume types

modules/ptcloud/include/opencv2/ptcloud/volume.hpp

@@ -20,7 +20,7 @@ class CV_EXPORTS_W Volume
 {
 public:
     /** @brief Constructor of custom volume.
-    * @param vtype the volume type [TSDF, HashTSDF, ColorTSDF].
+    * @param vtype the volume type [TSDF, HashTSDF, ColorTSDF, ColorHashTSDF].
     * @param settings the custom settings for volume.
     */
     CV_WRAP explicit Volume(VolumeType vtype = VolumeType::TSDF,
@@ -52,7 +52,7 @@ public:
     Camera intrinsics are taken from volume settings structure.
 
     * @param depth the depth image.
-    * @param image the color image (only for ColorTSDF).
+    * @param image the color image (only for ColorTSDF and ColorHashTSDF).
       For color TSDF a depth data should be registered with color data, i.e. have the same intrinsics & camera pose.
       This can be done using function registerDepth() from 3d module.
     * @param pose the pose of camera in global coordinates.
@@ -78,7 +78,7 @@ public:
     * @param cameraPose the pose of camera in global coordinates.
     * @param points image to store rendered points.
     * @param normals image to store rendered normals corresponding to points.
-    * @param colors image to store rendered colors corresponding to points (only for ColorTSDF).
+    * @param colors image to store rendered colors corresponding to points (only for ColorTSDF and ColorHashTSDF).
     */
     CV_WRAP_AS(raycastColor) void raycast(InputArray cameraPose, OutputArray points, OutputArray normals, OutputArray colors) const;
 
@@ -106,7 +106,7 @@ public:
     * @param K camera raycast intrinsics
     * @param points image to store rendered points.
     * @param normals image to store rendered normals corresponding to points.
-    * @param colors image to store rendered colors corresponding to points (only for ColorTSDF).
+    * @param colors image to store rendered colors corresponding to points (only for ColorTSDF and ColorHashTSDF).
     */
     CV_WRAP_AS(raycastExColor) void raycast(InputArray cameraPose, int height, int width, InputArray K, OutputArray points, OutputArray normals, OutputArray colors) const;
 
@@ -123,7 +123,7 @@ public:
     /** @brief Extract the all data from volume.
     * @param points the storage of all points.
     * @param normals the storage of all normals, corresponding to points.
-    * @param colors the storage of all colors, corresponding to points (only for ColorTSDF).
+    * @param colors the storage of all colors, corresponding to points (only for ColorTSDF and ColorHashTSDF).
     */
     CV_WRAP void fetchPointsNormalsColors(OutputArray points, OutputArray normals, OutputArray colors) const;
 
@@ -157,12 +157,12 @@ public:
 
     /**
      * @brief Enables or disables new volume unit allocation during integration.
-     * Makes sense for HashTSDF only.
+     * Makes sense for HashTSDF and ColorHashTSDF only.
      */
     CV_WRAP void setEnableGrowth(bool v);
     /**
      * @brief Returns if new volume units are allocated during integration or not.
-     * Makes sense for HashTSDF only.
+     * Makes sense for HashTSDF and ColorHashTSDF only.
      */
     CV_WRAP bool getEnableGrowth() const;
 

modules/ptcloud/include/opencv2/ptcloud/volume_settings.hpp

@@ -19,7 +19,8 @@ enum class VolumeType
 {
     TSDF = 0,
     HashTSDF = 1,
-    ColorTSDF = 2
+    ColorTSDF = 2,
+    ColorHashTSDF = 3
 };
 
 
@@ -98,6 +99,26 @@ public:
     */
     CV_WRAP float getTsdfTruncateDistance() const;
 
+    /** @brief Sets gradient delta factor used for normal estimation in TSDF volumes.
+    * @param val input value.
+    */
+    CV_WRAP void setGradientDeltaFactor(float val);
+
+    /** @brief Returns gradient delta factor used for normal estimation in TSDF volumes.
+    */
+    CV_WRAP float getGradientDeltaFactor() const;
+
+    /** @brief Sets threshold for number of frames after which invisible volume units are hidden/removed.
+    * For HashTSDF and ColorHashTSDF volumes, units that haven't been visible for this many frames will be removed.
+    * @param val input value.
+    */
+    CV_WRAP void setVolumeUnitHideThreshold(int val);
+
+    /** @brief Returns threshold for number of frames after which invisible volume units are hidden/removed.
+    * For HashTSDF and ColorHashTSDF volumes, units that haven't been visible for this many frames will be removed.
+    */
+    CV_WRAP int getVolumeUnitHideThreshold() const;
+
     /** @brief Sets threshold for depth truncation in meters. Truncates the depth greater than threshold to 0.
     * @param val input value.
     */
@@ -141,16 +162,16 @@ public:
 
     /** @brief Resolution of voxel space.
         Number of voxels in each dimension.
-        Applicable only for TSDF Volume.
-        HashTSDF volume only supports equal resolution in all three dimensions.
+        Applicable only for TSDF and ColorTSDF volumes.
+        HashTSDF and ColorHashTSDF volumes only support equal resolution in all three dimensions.
     * @param val input value.
     */
     CV_WRAP void setVolumeResolution(InputArray val);
 
     /** @brief Resolution of voxel space.
         Number of voxels in each dimension.
-        Applicable only for TSDF Volume.
-        HashTSDF volume only supports equal resolution in all three dimensions.
+        Applicable only for TSDF and ColorTSDF volumes.
+        HashTSDF and ColorHashTSDF volumes only support equal resolution in all three dimensions.
     * @param val output value.
     */
     CV_WRAP void getVolumeResolution(OutputArray val) const;