Rename transport to depthz; apply review cleanups; add package README

The transport, package, classes and parameters are now "depthz"
(depthz_image_transport). The vendored codec keeps its internal method
names ("dpred"/"dpred16"), so blobs stay interchangeable with the
standalone library.

Cleanups from a four-angle review (reuse/simplification/efficiency/
altitude):
- bytes_per_pixel(PixelFormat) in the codec header replaces the ad-hoc
  bpp ternaries in publisher and subscriber
- default CMAKE_BUILD_TYPE=RelWithDebInfo (never build the codec at -O0)
  and target-level cxx_std_20 instead of a directory-wide standard
- decode reads the dictionary in place instead of copying it; the
  dictionary-overflow fallback no longer zero-fills its staging buffer
- dict_size serialized via memcpy like the surrounding fields; begin_blob
  drops a temporary std::string; dead n==0 payload branch removed
- dead ParameterDescriptor::name assignment and two unused includes
  removed; the gtest round-trip harness is now one template instead of
  two near-verbatim copies
- new README: motivation vs compressedDepth and how to select the
  transport (image_transport parameter, enable_pub_plugins, republish)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: facontidavide

README.md

@@ -57,7 +57,7 @@ Currently provided are:
 
 - [compressed_image_transport](https://github.com/ros-perception/image_transport_plugins/tree/rolling/compressed_image_transport)
 
-- [dpred_image_transport](https://github.com/ros-perception/image_transport_plugins/tree/rolling/dpred_image_transport) - A library compressing 32FC1 and 16UC1 depth images losslessly (value dictionary + 2D prediction + zstd).
+- [depthz_image_transport](https://github.com/ros-perception/image_transport_plugins/tree/rolling/depthz_image_transport) - A library compressing 32FC1 and 16UC1 depth images losslessly (value dictionary + 2D prediction + zstd).
 
 - [zstd_image_transport](https://github.com/ros-perception/image_transport_plugins/tree/rolling/zstd_image_transport) - A libraory using ZSTD to compress the pointclouds.
 

dpred_image_transport/CMakeLists.txt depthz_image_transport/CMakeLists.txtdpred_image_transport/CMakeLists.txt renamed to depthz_image_transport/CMakeLists.txt

@@ -1,10 +1,10 @@
 cmake_minimum_required(VERSION 3.20)
 
-project(dpred_image_transport)
+project(depthz_image_transport)
 
-# The vendored depth codec uses C++20 (std::bit_cast, std::countr_zero).
-if(NOT CMAKE_CXX_STANDARD)
-  set(CMAKE_CXX_STANDARD 20)
+# The codec is performance-critical: never build it unoptimized by default.
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  set(CMAKE_BUILD_TYPE RelWithDebInfo)
 endif()
 
 if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
@@ -39,11 +39,13 @@ include_directories(include)
 add_library(
   ${PROJECT_NAME} SHARED
   src/depth_codec.cpp
-  src/dpred_publisher.cpp
-  src/dpred_subscriber.cpp
+  src/depthz_publisher.cpp
+  src/depthz_subscriber.cpp
   src/manifest.cpp
 )
 
+# The vendored depth codec uses C++20 (std::countr_zero, std::endian).
+target_compile_features(${PROJECT_NAME} PRIVATE cxx_std_20)
 target_link_libraries(${PROJECT_NAME}
   ${ZSTD_DEPENDENCY}
   image_transport::image_transport
@@ -62,14 +64,15 @@ install(
   DIRECTORY "include/"
   DESTINATION include
 )
-pluginlib_export_plugin_description_file(image_transport dpred_plugins.xml)
+pluginlib_export_plugin_description_file(image_transport depthz_plugins.xml)
 
 if(BUILD_TESTING)
   find_package(ament_lint_auto REQUIRED)
   ament_lint_auto_find_test_dependencies()
 
   find_package(ament_cmake_gtest REQUIRED)
   ament_add_gtest(test_depth_codec test/test_depth_codec.cpp)
+  target_compile_features(test_depth_codec PRIVATE cxx_std_20)
   target_include_directories(test_depth_codec PRIVATE src)
   target_link_libraries(test_depth_codec ${PROJECT_NAME})
 endif()

depthz_image_transport/README.md

@@ -0,0 +1,42 @@
+# depthz_image_transport
+
+Lossless `image_transport` plugin for depth images (`32FC1` and `16UC1`).
+
+Compared to `compressedDepth` (PNG), `depthz` compresses better, encodes
+roughly 10× faster, and is truly lossless: `compressedDepth` quantizes
+32FC1 to 16 bits before the PNG stage, `depthz` reproduces the input
+bit-exactly (NaN included). The codec is vendored from
+[facontidavide/depth_image_compression](https://github.com/facontidavide/depth_image_compression),
+where the algorithm is documented.
+
+## Usage
+
+Subscribers select the transport with the standard `image_transport`
+parameter (in rviz2: the *Transport Hint* dropdown of the Image/Camera
+display):
+
+```bash
+ros2 run my_pkg my_depth_consumer --ros-args -p image_transport:=depthz
+```
+
+Publishers advertise all installed transports, so `<base_topic>/depthz`
+appears automatically. To publish only selected transports (saving encoder
+CPU), use the publishing node's `enable_pub_plugins` parameter:
+
+```yaml
+/camera_node:
+  ros__parameters:
+    depth.image_rect.enable_pub_plugins:
+      - image_transport/raw
+      - image_transport/depthz
+```
+
+An existing stream can be converted with
+`ros2 run image_transport republish` (`out_transport:=depthz`), e.g. for
+bag recording: record `<base_topic>/depthz` instead of
+`<base_topic>/compressedDepth`.
+
+Parameters: `<base_topic>.depthz.zstd_level` (1–3, default 1).
+
+Only `32FC1` and `16UC1` encodings are accepted; other encodings are
+declined with an error log (use `compressed` or `zstd` for color images).

depthz_image_transport/depthz_plugins.xml

@@ -0,0 +1,13 @@
+<library path="depthz_image_transport">
+  <class name="image_transport/depthz_pub" type="depthz_image_transport::DepthzPublisher" base_class_type="image_transport::PublisherPlugin">
+    <description>
+      This plugin losslessly compresses 32FC1 and 16UC1 depth images with the dpred codec
+      (value dictionary + 2D MED prediction + zstd).
+    </description>
+  </class>
+  <class name="image_transport/depthz_sub" type="depthz_image_transport::DepthzSubscriber" base_class_type="image_transport::SubscriberPlugin">
+    <description>
+      This plugin decodes depthz-compressed depth images back to 32FC1 or 16UC1.
+    </description>
+  </class>
+</library>

…pred_image_transport/dpred_publisher.hpp …thz_image_transport/depthz_publisher.hppdpred_image_transport/include/dpred_image_transport/dpred_publisher.hpp renamed to depthz_image_transport/include/depthz_image_transport/depthz_publisher.hpp dpred_image_transport/include/dpred_image_transport/dpred_publisher.hpp renamed to depthz_image_transport/include/depthz_image_transport/depthz_publisher.hpp

@@ -27,11 +27,10 @@
 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 // POSSIBILITY OF SUCH DAMAGE.
 
-#ifndef DPRED_IMAGE_TRANSPORT__DPRED_PUBLISHER_HPP_
-#define DPRED_IMAGE_TRANSPORT__DPRED_PUBLISHER_HPP_
+#ifndef DEPTHZ_IMAGE_TRANSPORT__DEPTHZ_PUBLISHER_HPP_
+#define DEPTHZ_IMAGE_TRANSPORT__DEPTHZ_PUBLISHER_HPP_
 
 #include <string>
-#include <vector>
 
 #include <sensor_msgs/msg/compressed_image.hpp>
 #include <sensor_msgs/msg/image.hpp>
@@ -40,20 +39,20 @@
 
 #include <rclcpp/node.hpp>
 
-namespace dpred_image_transport
+namespace depthz_image_transport
 {
 
 using CompressedImage = sensor_msgs::msg::CompressedImage;
 
-class DpredPublisher : public image_transport::SimplePublisherPlugin<CompressedImage>
+class DepthzPublisher : public image_transport::SimplePublisherPlugin<CompressedImage>
 {
 public:
-  DpredPublisher();
-  ~DpredPublisher() override = default;
+  DepthzPublisher();
+  ~DepthzPublisher() override = default;
 
   std::string getTransportName() const override
   {
-    return "dpred";
+    return "depthz";
   }
 
 protected:
@@ -74,6 +73,6 @@ class DpredPublisher : public image_transport::SimplePublisherPlugin<CompressedI
   std::string level_param_name_;
 };
 
-}  // namespace dpred_image_transport
+}  // namespace depthz_image_transport
 
-#endif  // DPRED_IMAGE_TRANSPORT__DPRED_PUBLISHER_HPP_
+#endif  // DEPTHZ_IMAGE_TRANSPORT__DEPTHZ_PUBLISHER_HPP_

…red_image_transport/dpred_subscriber.hpp …hz_image_transport/depthz_subscriber.hppdpred_image_transport/include/dpred_image_transport/dpred_subscriber.hpp renamed to depthz_image_transport/include/depthz_image_transport/depthz_subscriber.hpp dpred_image_transport/include/dpred_image_transport/dpred_subscriber.hpp renamed to depthz_image_transport/include/depthz_image_transport/depthz_subscriber.hpp

@@ -27,8 +27,8 @@
 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 // POSSIBILITY OF SUCH DAMAGE.
 
-#ifndef DPRED_IMAGE_TRANSPORT__DPRED_SUBSCRIBER_HPP_
-#define DPRED_IMAGE_TRANSPORT__DPRED_SUBSCRIBER_HPP_
+#ifndef DEPTHZ_IMAGE_TRANSPORT__DEPTHZ_SUBSCRIBER_HPP_
+#define DEPTHZ_IMAGE_TRANSPORT__DEPTHZ_SUBSCRIBER_HPP_
 
 #include <string>
 
@@ -38,20 +38,20 @@
 
 #include <rclcpp/node.hpp>
 
-namespace dpred_image_transport
+namespace depthz_image_transport
 {
 
 using CompressedImage = sensor_msgs::msg::CompressedImage;
 
-class DpredSubscriber : public image_transport::SimpleSubscriberPlugin<CompressedImage>
+class DepthzSubscriber : public image_transport::SimpleSubscriberPlugin<CompressedImage>
 {
 public:
-  DpredSubscriber();
-  ~DpredSubscriber() override = default;
+  DepthzSubscriber();
+  ~DepthzSubscriber() override = default;
 
   std::string getTransportName() const override
   {
-    return "dpred";
+    return "depthz";
   }
 
 protected:
@@ -62,6 +62,6 @@ class DpredSubscriber : public image_transport::SimpleSubscriberPlugin<Compresse
   rclcpp::Logger logger_;
 };
 
-}  // namespace dpred_image_transport
+}  // namespace depthz_image_transport
 
-#endif  // DPRED_IMAGE_TRANSPORT__DPRED_SUBSCRIBER_HPP_
+#endif  // DEPTHZ_IMAGE_TRANSPORT__DEPTHZ_SUBSCRIBER_HPP_

dpred_image_transport/package.xml depthz_image_transport/package.xmldpred_image_transport/package.xml renamed to depthz_image_transport/package.xml

@@ -1,9 +1,9 @@
 <?xml version="1.0"?>
 <package format="3">
-  <name>dpred_image_transport</name>
+  <name>depthz_image_transport</name>
   <version>7.0.1</version>
   <description>
-    dpred_image_transport provides a plugin to image_transport for transparently sending
+    depthz_image_transport provides a plugin to image_transport for transparently sending
     32FC1 and 16UC1 depth images losslessly compressed with the dpred codec (per-image value
     dictionary + 2D prediction + zstd).
   </description>
@@ -27,6 +27,6 @@
 
   <export>
     <build_type>ament_cmake</build_type>
-    <image_transport plugin="${prefix}/dpred_plugins.xml" />
+    <image_transport plugin="${prefix}/depthz_plugins.xml" />
   </export>
 </package>

dpred_image_transport/src/depth_codec.cpp …pthz_image_transport/src/depth_codec.cppdpred_image_transport/src/depth_codec.cpp renamed to depthz_image_transport/src/depth_codec.cpp dpred_image_transport/src/depth_codec.cpp renamed to depthz_image_transport/src/depth_codec.cpp

@@ -382,9 +382,11 @@ void dpred_encode(
   std::vector<uint16_t> idx;
   if (!build_value_dict(words, n, entries, idx)) {
     // > 65536 distinct values (e.g. full-precision float depth): store raw.
-    std::vector<uint8_t> plain(1 + n * 4);
-    plain[0] = 0;
-    std::memcpy(plain.data() + 1, words, n * 4);
+    const uint8_t * bytes = reinterpret_cast<const uint8_t *>(words);
+    std::vector<uint8_t> plain;
+    plain.reserve(1 + n * 4);
+    plain.push_back(0);
+    plain.insert(plain.end(), bytes, bytes + n * 4);
     zstd_append(out, plain.data(), plain.size(), level);
     return;
   }
@@ -432,10 +434,9 @@ void dpred_encode(
   std::vector<uint8_t> plain(6 + ds * 4 + n * 2);
   plain[0] = 1;
   plain[1] = 2;  // residuals are always 2 bytes (split into two planes)
-  for (int b = 0; b < 4; ++b) {
-    plain[2 + b] = static_cast<uint8_t>(ds >> (8 * b));
-  }
   static_assert(std::endian::native == std::endian::little, "format is little-endian");
+  const uint32_t ds32 = static_cast<uint32_t>(ds);
+  std::memcpy(plain.data() + 2, &ds32, 4);
   std::memcpy(plain.data() + 6, sorted_entries.data(), ds * 4);
 
   uint8_t * lo = plain.data() + 6 + ds * 4;
@@ -448,9 +449,6 @@ void dpred_decode(const uint8_t * comp, size_t comp_size, float * out, uint32_t
   const size_t n = static_cast<size_t>(w) * h;
   std::vector<uint8_t> plain = zstd_unpack(comp, comp_size);
   if (plain.empty()) {
-    if (n == 0) {
-      return;
-    }
     fail("dpred_decode: empty payload");
   }
   uint32_t * words = reinterpret_cast<uint32_t *>(out);
@@ -468,9 +466,7 @@ void dpred_decode(const uint8_t * comp, size_t comp_size, float * out, uint32_t
   if (plain.size() != 6 + ds * 4 + n * 2) {
     fail("dpred_decode: size mismatch");
   }
-  static_assert(std::endian::native == std::endian::little, "format is little-endian");
-  std::vector<uint32_t> dict(ds);
-  std::memcpy(dict.data(), plain.data() + 6, ds * 4);
+  const uint8_t * dict = plain.data() + 6;  // read in place (get_u32 handles alignment)
   const uint8_t * lo = plain.data() + 6 + ds * 4;
 
   std::vector<uint16_t> idx(n);
@@ -479,7 +475,7 @@ void dpred_decode(const uint8_t * comp, size_t comp_size, float * out, uint32_t
     if (idx[i] >= ds) {
       fail("dpred_decode: bad index");
     }
-    words[i] = dict[idx[i]];
+    words[i] = get_u32(dict + 4 * static_cast<size_t>(idx[i]));
   }
 }
 
@@ -497,9 +493,9 @@ void begin_blob(
   out.clear();
   const char magic[4] = {'D', 'P', 'C', '1'};
   out.insert(out.end(), magic, magic + 4);
-  const std::string name_str = name;
-  out.push_back(static_cast<uint8_t>(name_str.size()));
-  out.insert(out.end(), name_str.begin(), name_str.end());
+  const size_t name_len = std::strlen(name);
+  out.push_back(static_cast<uint8_t>(name_len));
+  out.insert(out.end(), name, name + name_len);
   put_u32(out, static_cast<uint32_t>(level));
   put_u32(out, width);
   put_u32(out, height);

dpred_image_transport/src/depth_codec.hpp …pthz_image_transport/src/depth_codec.hppdpred_image_transport/src/depth_codec.hpp renamed to depthz_image_transport/src/depth_codec.hpp dpred_image_transport/src/depth_codec.hpp renamed to depthz_image_transport/src/depth_codec.hpp

@@ -64,6 +64,11 @@ struct BlobHeader
   PixelFormat format;
 };
 
+constexpr size_t bytes_per_pixel(PixelFormat format)
+{
+  return format == PixelFormat::FLOAT32 ? 4 : 2;
+}
+
 /// Compress width*height float32 (32FC1) depth pixels into `out` (replacing
 /// its contents; existing capacity is reused, so a caller that keeps the
 /// vector alive across frames pays no steady-state output allocations).