If a LiDAR cloud looks correct in one application but becomes scrambled in a custom decoder, inspect its binary layout before changing sensor calibration. A PointCloud2 message describes its fields, byte order, point spacing and row spacing. Treat those values as the decoding contract. A convenient assumption that every point is three adjacent floating-point values can produce plausible-looking but incorrect coordinates.
Preserve one unchanged message and its complete metadata. Compare the same bytes through the original viewer and the failing reader. The LiDAR output-format guide explains the broader choice of outputs; this workflow addresses a narrower problem inside an already selected PointCloud2 interface.
The Jazzy PointCloud2 definition identifies the binary buffer and its layout metadata. It also distinguishes organized clouds from unordered clouds. Record the installed package revision because a reader’s supported layouts can differ even when the message definition remains familiar.
Freeze the bytes before investigating geometry
Save the original buffer, width, height, fields, point_step, row_step, is_bigendian, is_dense, header timestamp and frame identifier together. Keep the topic name, driver version and capture method in the same record. A text export containing only XYZ loses precisely the layout information needed to investigate a decoder.
Identify whether corruption appears immediately, only after a format change, only on a different computer, or only for organized data. Those boundaries suggest different hypotheses. A change after a driver update deserves a schema comparison, whereas a change between architectures deserves a byte-order check. Neither observation alone proves the cause.
Confirm that both applications receive the intended publisher. Use the remote ROS discovery workflow when the second application never receives the message. An absent input is a different failure from interpreting received bytes incorrectly.
Build the field dictionary explicitly
For every field, list its name, offset, datatype and count. The PointField definition distinguishes the datatype identifier from the number of elements. The count belongs to that field, not to the total number of points. Preserve unfamiliar fields even if the current application does not use them.
For a candidate field, calculate its occupied byte interval from its offset and the size of its declared elements. Check that the interval fits within point_step. Reject inconsistent metadata with a clear diagnostic rather than reading beyond the point boundary. Do not silently reinterpret integer intensity, packed color or time fields as floating-point coordinates.
Names and offsets answer separate questions. A reader may locate x by name while still requiring its declared datatype and offset. Likewise, a field named intensity does not establish a universal physical scale. Keep decoding separate from any application-specific interpretation of measured values.
| Observed symptom | First layout check | Evidence to retain |
|---|---|---|
| Every point is displaced or nonsensical | Field offsets and declared types | Dictionary plus selected raw bytes |
| First row works, later rows fail | Row stride and trailing padding | Width, height and row boundaries |
| Only another architecture fails | Byte order and numeric conversion | Original bytes and host byte order |
| Coordinates survive but channels disappear | Requested field selection | Input and output schemas |
Use both point spacing and row spacing
A point’s field address is derived from the row index multiplied by row_step, the column index multiplied by point_step, and the field offset. This is a direct consequence of the layout definition. Validate indices against width and height before calculating the address, and validate the resulting interval against the available buffer.
Point spacing can include padding or additional channels. Row spacing can also exceed the packed width multiplied by point_step. A custom reader that flattens an organized buffer without considering row boundaries can interpret row padding as points. The resulting image may appear to shear or repeat rather than fail with an obvious exception.
The C++ iterator interface provides a useful reference for supported traversal operations. Read its documented assumptions alongside the installed implementation. A helper intended for one arrangement should not be treated as proof that every arbitrary producer layout is handled.
Construct a small synthetic message for the decoder test with explicitly known coordinates and deliberate padding. This is a software fixture, not a sensor-performance result. Verify the first and last point of each row and a point near each boundary. Include an invalid metadata fixture to establish that the reader stops safely instead of returning corrupted values.
Handle byte order without changing the original
Compare message byte order with the reader’s numeric conversion rules. If conversion is needed, apply it exactly once to the intended values. Preserve the captured buffer so a diagnostic operation cannot modify the reference used for the second comparison. Record whether the decoder creates a copy or returns a view of the input storage.
The versioned sensor_msgs_py implementation is useful for understanding how that revision constructs field datatypes and handles byte order. It is source evidence about a particular helper, not a guarantee for every padded organized layout. Inspect the installed code before selecting it as the independent oracle.
Check numerical validity after conversion. Distinguish a malformed byte interpretation from a correctly decoded non-finite value. Keep the original point count and the count after validity filtering separate. Dropping invalid values during the first comparison can hide whether both readers started from the same locations.
Prove the repair with the same message
Compare selected point indices and named fields against an independent bounded reader. Use a documented numeric tolerance suitable for the declared type and conversion path. Do not select a tolerance by observing how much error the failing decoder happens to produce. Preserve both expected and actual values in the test record.
The iterator implementation can help trace exact field traversal for the C++ revision under investigation. Keep the conclusions limited to inspected behavior. A successful packed-cloud test does not establish correct handling of row padding or every supported field datatype.
Once bytes agree, investigate coordinate frames and timestamps separately. The TF timing diagnostic addresses transform availability; the calibration workflow addresses physical alignment. Changing an extrinsic transform to compensate for a decoding defect produces a fragile and misleading repair.
Retain the original message, synthetic fixtures, schema, package revisions, failing output and corrected output in a reproducible support bundle. Explain which assumption failed and which layouts remain unsupported. That boundary is more useful than reporting that the cloud now looks reasonable.
Make regression coverage part of the handoff. Test an empty cloud, a single point, a packed row, multiple padded rows, and each field type the application claims to support. Preserve explicit expected behavior when a required coordinate is missing. The reader should identify an unsupported schema rather than quietly substituting zeros, because those zeros can create a false obstacle at the origin.
Repeat the comparison after changing the producer revision. A stable topic name does not establish a stable field dictionary. Store the schema alongside the fixture and require a deliberate review when it changes. This gives a future maintainer a concrete compatibility check instead of relying on a screenshot from a previous deployment.
Frequently asked questions
Can I assume XYZ occupies the first twelve bytes?
No. Read the actual field offsets and datatypes. Additional channels and padding can change the arrangement without changing the message type.
Does a correct viewer prove my decoder is wrong?
It is useful comparative evidence, but confirm that both applications use identical bytes and that the viewer is not applying a different conversion or filter.
Should I remove padding from the producer?
First establish the interface contract. Repacking can be a deliberate conversion, but it must update the metadata consistently and preserve every channel required downstream.
