refactor!: remove deprecated t_us field from xyzit and en_xyzit point types (#95)

* refactor!: remove deprecated t_us field from xyzit and en_xyzit point types

Drop the `t_us` field from `PointXYZIT` and `PointEnXYZIT` (struct
definitions and PCL registrations), stop populating it in the Seyond
decoder, and remove README / script references to it. `time_stamp`
(uint32, nanoseconds from scan start) is now the sole per-point
relative timestamp.

BREAKING CHANGE: output PointCloud2 messages for `xyzit` and
`en_xyzit` no longer contain a `t_us` field. Downstream consumers must
read `time_stamp` (uint32 ns) instead. This was previously announced
as "Will be removed in v1.0.0".

* style: reformat PCL_REGISTER_POINT_STRUCT layout for PointXYZIT and PointEnXYZIT

Author: otenim

README.md

@@ -193,7 +193,6 @@ The output bag file contains `sensor_msgs::msg::PointCloud2` messages on topics
 - `y` (float32): Y coordinate in meters
 - `z` (float32): Z coordinate in meters
 - `intensity` (float32): Intensity value in [0, 255]. Robin W uses packet-version-dependent scaling; see [docs/seyond_intensity_scaling.md](docs/seyond_intensity_scaling.md).
-- `t_us` (uint32): Relative timestamp in microseconds from the scan start time (xyzit, en_xyzit only). **Will be removed in v1.0.0**; use `time_stamp` instead.
 - `time_stamp` (uint32): Relative timestamp in nanoseconds from the scan start time (xyzit, en_xyzit only)
 
 **Extended fields** (en_xyzit only): availability mask, refl_type, elongation, lidar_status, lidar_mode, packet version, lidar_type, is_2nd_return, multi_return_mode, and use_reflectance. Full layout, flag semantics, and value tables are in [docs/en_xyzit.md](docs/en_xyzit.md).
@@ -203,7 +202,6 @@ The output bag file contains `sensor_msgs::msg::PointCloud2` messages on topics
 All timestamps in PointCloud2 messages are based on UTC (Coordinated Universal Time).
 
 - **`header.stamp`**: Absolute timestamp representing the scan start time in UTC. This timestamp is generated by the LiDAR and represents when the scan began.
-- **`t_us` field**: Relative timestamp in microseconds from the scan start time (`header.stamp`). **Will be removed in v1.0.0**; use `time_stamp` instead.
 - **`time_stamp` field**: Relative timestamp in nanoseconds from the scan start time (`header.stamp`)
 
 The absolute timestamp for each point (in nanoseconds, UTC) can be calculated as:
@@ -212,12 +210,6 @@ The absolute timestamp for each point (in nanoseconds, UTC) can be calculated as
 absolute_timestamp_ns = (header.stamp.sec * 1,000,000,000 + header.stamp.nanosec) + time_stamp
 ```
 
-Or, using `t_us` (until v1.0.0):
-
-```text
-absolute_timestamp_ns = (header.stamp.sec * 1,000,000,000 + header.stamp.nanosec) + (t_us * 1,000)
-```
-
 ## Utility Scripts
 
 The `scripts/` directory contains Python scripts for inspecting and debugging rosbag files. See [scripts/README.md](scripts/README.md) for details.

scripts/decode_pointcloud2.py

@@ -7,7 +7,7 @@
 - Reading PointCloud2 messages from rosbag2 files
 - Automatic field detection and decoding
 - Displaying point data with configurable number of points per message
-- Handling relative timestamps (e.g., t_us field) and calculating absolute timestamps
+- Handling relative timestamps (e.g., time_stamp field) and calculating absolute timestamps
 """
 
 import argparse
@@ -120,10 +120,10 @@ def decode_pointcloud2(bag_path: str, point_step: int = 10000, delay: float | No
                     if num_points == 0:
                         continue
 
-                    # Calculate base timestamp in microseconds (if t_us field exists)
-                    base_time_us = None
-                    if 't_us' in points and len(points['t_us']) > 0:
-                        base_time_us = msg.header.stamp.sec * 1_000_000 + msg.header.stamp.nanosec // 1_000
+                    # Calculate base timestamp in nanoseconds (if time_stamp field exists)
+                    base_time_ns = None
+                    if 'time_stamp' in points and len(points['time_stamp']) > 0:
+                        base_time_ns = msg.header.stamp.sec * 1_000_000_000 + msg.header.stamp.nanosec
 
                     # Convert timestamp from nanoseconds to seconds and nanoseconds
                     received_sec = timestamp // 1_000_000_000
@@ -148,12 +148,12 @@ def decode_pointcloud2(bag_path: str, point_step: int = 10000, delay: float | No
                         for field_name in field_names:
                             field_data = points[field_name]
                             if len(field_data) > i:
-                                if field_name == 't_us' and base_time_us is not None:
-                                    # Calculate absolute timestamp for t_us
-                                    abs_time_us = base_time_us + int(field_data[i])
-                                    abs_time_sec = abs_time_us / 1_000_000.0
-                                    stamp_str = f"stamp={abs_time_sec:.6f}"
-                                    # Add t_us as a regular field
+                                if field_name == 'time_stamp' and base_time_ns is not None:
+                                    # Calculate absolute timestamp for time_stamp (nanoseconds)
+                                    abs_time_ns = base_time_ns + int(field_data[i])
+                                    abs_time_sec = abs_time_ns / 1_000_000_000.0
+                                    stamp_str = f"stamp={abs_time_sec:.9f}"
+                                    # Add time_stamp as a regular field
                                     point_info_parts.append(f"{field_name}={field_data[i]}")
                                 elif field_name == 'intensity' and isinstance(field_data[i], (float, np.floating)):
                                     point_info_parts.append(f"{field_name}={field_data[i]:.1f}")
@@ -235,8 +235,8 @@ def decode_point(msg: PointCloud2) -> dict:
 
     Note:
         msg.header.stamp represents the scan start timestamp (absolute time).
-        If a field named 't_us' exists, it contains relative timestamps from
-        the scan start in microseconds.
+        If a field named 'time_stamp' exists, it contains relative timestamps
+        from the scan start in nanoseconds.
 
     Args:
         msg: PointCloud2 message (msg.header.stamp is the scan start timestamp)

scripts/plot_field_distribution.py

@@ -198,7 +198,7 @@ def main():
     )
 
     parser.add_argument('bag_path', type=str, help='Path to the rosbag2 file')
-    parser.add_argument('field', type=str, help='PointCloud2 field name to plot (e.g., intensity, x, t_us)')
+    parser.add_argument('field', type=str, help='PointCloud2 field name to plot (e.g., intensity, x, time_stamp)')
 
     parser.add_argument('--bins', type=int, default=50, help='Number of bins (default: 50)')
 

src/bag_converter/include/point_types.hpp

@@ -55,15 +55,12 @@ struct EIGEN_ALIGN16 PointXYZI
  * It includes:
  * - x, y, z coordinates (float)
  * - intensity (float, 0–255)
- * - t_us: [DEPRECATED, will be removed in v0.6.0] Replaced by `time_stamp`.
- *         Relative timestamp from scan start in microseconds (uint32_t)
  * - time_stamp: relative timestamp from scan start in nanoseconds (uint32_t)
  */
 struct EIGEN_ALIGN16 PointXYZIT
 {
   PCL_ADD_POINT4D;
   float intensity;
-  uint32_t t_us;  ///< @deprecated Will be removed in v1.0.0. Replaced by `time_stamp`.
   uint32_t time_stamp;
   EIGEN_MAKE_ALIGNED_OPERATOR_NEW
 };
@@ -90,7 +87,7 @@ constexpr uint16_t HAS_USE_REFLECTANCE = 1u << 9;
  * Experimental. Extended fields use an availability mask (flags) and minimal unsigned types.
  * When a property is not supported, its flag bit is 0 and the value is 0 (must be ignored).
  *
- * Base: x, y, z (float), intensity (float, 0–255), t_us (deprecated), time_stamp (uint32_t).
+ * Base: x, y, z (float), intensity (float, 0–255), time_stamp (uint32_t).
  * Extended (all uint8_t except flags): flags, refl_type (0-2), elongation (0-15),
  * lidar_status (0-3), lidar_mode (0-9), pkt_version_major/minor (0-255), lidar_type (0-7),
  * is_2nd_return (0-1), multi_return_mode (0-3), use_reflectance (0-1).
@@ -100,7 +97,6 @@ struct EIGEN_ALIGN16 PointEnXYZIT
 {
   PCL_ADD_POINT4D;
   float intensity;
-  uint32_t t_us;  ///< @deprecated Will be removed in v1.0.0. Replaced by `time_stamp`.
   uint32_t time_stamp;
   uint16_t flags;        ///< en_xyzit_flags: which extended fields are valid
   uint8_t refl_type;     ///< 0=normal, 1=ground, 2=fog. When not supported: 0.
@@ -145,17 +141,18 @@ POINT_CLOUD_REGISTER_POINT_STRUCT(
 
 POINT_CLOUD_REGISTER_POINT_STRUCT(
   bag_converter::point::PointXYZIT,
-  (float, x, x)(float, y, y)(float, z, z)(float, intensity, intensity)(uint32_t, t_us, t_us)(
-    uint32_t, time_stamp, time_stamp))
+  (float, x,
+   x)(float, y, y)(float, z, z)(float, intensity, intensity)(uint32_t, time_stamp, time_stamp))
 
 POINT_CLOUD_REGISTER_POINT_STRUCT(
   bag_converter::point::PointEnXYZIT,
-  (float, x, x)(float, y, y)(float, z, z)(float, intensity, intensity)(uint32_t, t_us, t_us)(
-    uint32_t, time_stamp, time_stamp)(uint16_t, flags, flags)(uint8_t, refl_type, refl_type)(
-    uint8_t, elongation,
-    elongation)(uint8_t, lidar_status, lidar_status)(uint8_t, lidar_mode, lidar_mode)(
-    uint8_t, pkt_version_major, pkt_version_major)(uint8_t, pkt_version_minor, pkt_version_minor)(
-    uint8_t, lidar_type, lidar_type)(uint8_t, is_2nd_return, is_2nd_return)(
+  (float, x,
+   x)(float, y, y)(float, z, z)(float, intensity, intensity)(uint32_t, time_stamp, time_stamp)(
+    uint16_t, flags, flags)(uint8_t, refl_type, refl_type)(uint8_t, elongation, elongation)(
+    uint8_t, lidar_status,
+    lidar_status)(uint8_t, lidar_mode, lidar_mode)(uint8_t, pkt_version_major, pkt_version_major)(
+    uint8_t, pkt_version_minor,
+    pkt_version_minor)(uint8_t, lidar_type, lidar_type)(uint8_t, is_2nd_return, is_2nd_return)(
     uint8_t, multi_return_mode, multi_return_mode)(uint8_t, use_reflectance, use_reflectance))
 
 #endif  // BAG_CONVERTER__POINT_TYPES_HPP

src/bag_converter/src/seyond_decoder.cpp

@@ -203,12 +203,10 @@ void SeyondPCDDecoder<OutputPointT>::point_xyz_data_parse(
     // point_ptr->ts_10us is relative to the packet's ts_start_us (in 10us units)
     // pkt_offset_us_ is the packet's offset from scan start (in us)
     // point.time_stamp = (pkt_offset_us_ + ts_10us * 10) * 1000 = time from scan start in ns
-    // point.t_us = time_stamp / 1000 = time from scan start in us (deprecated)
     if constexpr (
       std::is_same_v<OutputPointT, bag_converter::point::PointXYZIT> ||
       std::is_same_v<OutputPointT, bag_converter::point::PointEnXYZIT>) {
       point.time_stamp = static_cast<uint32_t>((pkt_offset_us_ + point_ptr->ts_10us * 10) * 1000);
-      point.t_us = point.time_stamp / 1000;
     }
     if constexpr (std::is_same_v<OutputPointT, bag_converter::point::PointEnXYZIT>) {
       namespace fl = bag_converter::point::en_xyzit_flags;