A compressed image topic can publish correctly while its codec controls remain absent from a parameter GUI. The camera driver, transport publisher and decoder may expose different settings, sometimes under different nodes. This troubleshooting procedure helps you locate the owner of image transport compression parameters, distinguish missing controls from rejected updates, and verify a change without altering the camera's capture format.
Separate capture format from transport encoding
Start by identifying which layer you actually need to change. A parameter containing the word format is not necessarily a compression setting.
| Layer | What its format describes | Where to investigate |
|---|---|---|
| Camera acquisition | The pixels delivered by the device, including packing or color arrangement | Camera feature interface and driver configuration |
| Published raw image | The encoding, dimensions and layout of the application image | Publisher configuration and raw message metadata |
| Compressed color transport | The codec and options used to encode a published image | The active color transport publisher plugin |
| Compressed depth transport | The depth-specific representation and supported codec options | The active depth transport publisher plugin |
| Subscriber | The transport selected and the decoded image interpretation | Subscriber configuration and decoder support |
A camera pixel-format change can affect acquisition, conversion and every downstream subscriber. A transport codec change normally targets the published representation instead. However, a particular plugin can restrict which input image encodings it accepts.
If the raw or depth stream itself is unavailable, begin with missing-stream and unknown-pixel-format diagnostics. Compression troubleshooting assumes the underlying image stream already works.
Find the publisher that owns the parameters
Inspect the live graph rather than relying only on the node selected in a GUI. In a sourced ROS 2 environment, begin with:
ros2 node list
ros2 topic list -t
Then inspect the compressed topic's publishers. These example paths are illustrative; substitute the names reported by your running system:
ros2 topic info /inspection/image/compressed -v
ros2 param list /inspection/image_publisher
ros2 param dump /inspection/image_publisher
The topic information identifies publisher endpoints. Query the corresponding node, then look for parameters associated with the image topic and transport plugin. Do not derive a parameter path simply by appending .compressed.format to the raw topic name.
Topic namespaces and parameter names serve different purposes. A fully qualified topic path does not establish the spelling of its configuration keys. Different package versions can also organize plugin parameters differently.
For composed systems, a process can contain several component nodes. The process or component-container name alone does not identify the parameter owner. Inspect the actual publisher endpoint and its node namespace.
If the expected controls are absent, check these possibilities in order:
- You queried the camera node rather than a separate transport or republisher node.
- You selected another instance with a similar name in a different namespace.
- The intended publisher has not been instantiated because of lazy initialization or disabled stream configuration.
- The plugin is unavailable, failed to load, or differs from the installed documentation.
- The GUI has not refreshed its parameter list.
Keep a real subscriber connected during testing when the publisher uses lazy activation. Treat that as a diagnostic condition, not a universal requirement for parameter discovery.
Distinguish missing, read-only and rejected settings
An absent parameter and a rejected update require different fixes. First list the parameters through the command line, then inspect the descriptor for the exact key you discovered.
The command structure is ros2 param describe, followed by the owning node and its parameter name. Use ros2 param get to record the current value before attempting a change.
| Observation | Likely explanation | Next test |
|---|---|---|
| CLI lists the parameter, but the GUI does not | GUI discovery, refresh or presentation issue | Read and describe it through the CLI |
| Neither interface lists it | Wrong owner, inactive publisher, absent plugin or version difference | Inspect endpoints, startup logs and installed package versions |
| Descriptor marks it read-only | Runtime updates are not supported through that parameter | Check documented startup configuration |
| Update returns an unsuccessful result | A validation callback rejected the request | Read the returned reason and inspect node logs |
| Update succeeds but output does not change | Wrong stream, deferred application or an inactive publisher instance | Inspect newly generated messages from the intended endpoint |
A descriptor is useful evidence, but it is not the whole update policy. A node can reject a write through its parameter callback even when the descriptor does not mark the parameter read-only.
Similarly, an accepted parameter value is not proof that an active encoder has changed. Verify the output as a separate step.
For camera-owned controls rather than transport settings, the distinction is explained in color stream exposure control diagnostics. Device feature discovery is covered separately in GenICam feature-access diagnostics.
Choose color and depth compression separately
Color and depth transports are not interchangeable wrappers around the same data. Their encoding choices must preserve the information required by downstream processing.
| Requirement | Practical starting point | What to verify |
|---|---|---|
| Color preview with constrained bandwidth | JPEG, where the plugin supports it | Artifacts, latency and acceptable visual quality |
| Exact reconstruction of the supported integer color image | PNG, where supported | Decoded pixel equality and processing cost |
| Depth for measurement | A documented depth-specific transport | Units, invalid values and reconstruction error |
| Existing application with a fixed decoder | A mutually supported transport configuration | Decoder compatibility and message interpretation |
JPEG is lossy and can alter edges, fine texture and small color differences. PNG provides lossless reconstruction of supported image samples, but a plugin may perform conversion before encoding. Compare the decoded result against the actual raw publisher output, not an assumed camera buffer.
Depth requires extra care. Encodings such as 16UC1 and 32FC1 describe storage types; they do not independently establish distance units or invalid-value conventions. A depth transport may transform or quantize floating-point values before compressing them. A PNG payload therefore does not automatically mean that the original floating-point depth values survive unchanged.
Do not send a depth image through an ordinary lossy color codec for measurement. Confirm the depth plugin's supported inputs, reconstruction behavior and decoder requirements.
After decoding, retain the correct geometry metadata. The guide to intrinsic parameters for depth and texture images explains why image dimensions and calibration must remain consistent.
Estimate the bandwidth before changing codecs
Use a bandwidth estimate to establish whether compression is addressing the actual bottleneck. The following equations describe image payload only; they exclude middleware, network and container overhead.
Consider a hypothetical color stream measuring 1280 × 720 pixels, with 3 bytes per pixel at 30 frames per second:
- Raw frame size: 1280 × 720 × 3 = 2,764,800 bytes.
- Raw payload rate: 2,764,800 × 30 = 82,944,000 bytes per second.
- Using decimal units, that is about 82.9 MB/s, or 663.6 Mbit/s.
Suppose measurements show an average compressed frame size of 160,000 bytes:
- Compressed payload rate: 160,000 × 30 = 4,800,000 bytes per second.
- That is 4.8 MB/s, or 38.4 Mbit/s.
- Compression ratio: 2,764,800 / 160,000 = about 17.3:1.
These are application examples, not promised codec results. Encoded size varies with scene content, noise, codec settings and image encoding. Measure peak frame sizes as well as averages.
Compression also consumes processing time. At 30 frames per second, the nominal frame interval is 1000 / 30 = about 33.3 ms. Compare that interval with measured processing throughput and end-to-end latency; asynchronous pipelines can overlap work while still accumulating queues.
If the raw stream already misses its target rate, investigate camera frame-rate, pixel-format and exposure limits before attributing the problem to compression.
Make one controlled change and verify the result
Use a fixed scene or repeatable recording wherever practical. Changing illumination, motion and codec settings together makes the result difficult to interpret.
- Record the baseline. Save node names, topic types, raw image encoding, current parameter values and package versions. Record delivered frame rate and latency.
- Confirm the subscriber's transport. A viewer using the raw topic will not demonstrate a compressed codec change. Check its actual subscription endpoint.
-
Check the exact parameter. Read its descriptor, current value, accepted type and documented constraints. Do not assume that every
formatkey accepts JPEG or PNG strings. - Attempt the supported runtime update. Use the owning node's parameter interface. Read the complete success or failure response and relevant logs.
- Inspect newly generated messages. Check the compressed message's format metadata and decode its payload with a compatible subscriber. Metadata alone is not a sufficient test.
- Compare the decoded output. For supported lossless integer color paths, test pixel equality. For depth, evaluate valid-value counts, units and error against a suitable reference.
- Test persistence separately. Put an accepted setting into the documented launch or parameter configuration, restart the affected publisher and repeat the checks.
For a runtime-rejected parameter, startup configuration is appropriate only when the documentation supports that setting at initialization. Restarting does not create a parameter that the installed plugin never declares.
Use a controlled stop and restart of the documented component or pipeline. Do not assume a camera power cycle is necessary for a software encoder setting.
Check the supported software combination
If the correct plugin is present but its controls remain absent, collect the complete software combination before replacing packages:
- ROS 2 distribution and operating-system release.
- Camera wrapper or driver version.
- Camera SDK version, where applicable.
- Image transport core and plugin package versions.
- Subscriber or decoder version.
- Workspace overlays and container image identity, if used.
Use the manufacturer's documented support matrix for the acquisition stack and the plugin project's release documentation for transport behavior. A feature described for another release is not evidence that the installed package exposes it.
Do not remove distribution checks or force unsupported dependency combinations as a production remedy. Use a documented supported release combination. A container can help reproduce that combination, but it does not by itself establish camera access, driver compatibility or plugin functionality.
Check which workspace the running process actually uses. Updating one installation while launching another can leave the old plugin active. Restart the relevant process after deploying the supported change, then repeat parameter discovery.
If acquisition also fails after a software change, separate that fault using SDK build-mismatch and frame-timeout diagnostics.
Check acquisition requirements before ordering hardware
Missing transport controls usually call for software investigation, not a replacement camera. If you are also specifying a new acquisition system, treat hardware selection and transport compatibility as separate decisions.
For conventional image capture, compare interface and image requirements in area scan cameras. For depth acquisition, start with 3D sensors. The camera finder helps narrow acquisition hardware; it does not establish support for a particular middleware plugin.
The LS-CMR-0166 is a USB3 area scan camera. It is an acquisition reference, not a claimed solution for missing transport parameters.
- Sensor format
- 1/1.7"
- Interface
- USB3
- Resolution
- 12 MP
- Shutter
- Rolling
The MV-DPS200P-02 is a projected structured-light camera. Its catalog entry does not establish compatibility with the transport stack discussed here.
- Type
- Stereo / structured light
Before ordering, document the required raw image encoding, driver support, calibration output and downstream decoder. Request confirmation of the complete integration rather than inferring software compatibility from the camera interface.
Prevention checklist and next step
Keep a short commissioning record for each published stream:
- Publisher identity: record the node, namespace and topic so another instance cannot be mistaken for it.
- Parameter ownership: distinguish device controls, raw-image settings and transport plugin controls.
- Update behavior: document whether each setting is runtime-configurable or startup-only.
- Encoding contract: record color ordering, depth units, invalid-value handling and calibration association.
- Performance evidence: retain encoded size, throughput, latency and image-quality measurements.
- Restart test: confirm that the intended configuration returns after a normal restart.
- Release record: retain the supported package combination and active workspace configuration.
The immediate next step is to identify the compressed topic's actual publisher and compare its declared parameters with documentation for the installed release. If hardware selection is also part of the project, use the camera configurator or contact applications support with your acquisition requirements and software version record.
Questions
Why does a compressed topic work when its compression parameters are missing?
The GUI may be querying the camera driver while a different node owns the encoder controls. Parameters can also be absent because the relevant publisher is inactive, the plugin failed to load, or the installed release does not expose them. Inspect the topic's publisher endpoints and query their parameters directly.
Should I change the camera pixel format to select JPEG or PNG?
Do not assume that a camera format control selects a transport codec. Device pixel formats describe acquisition data, while JPEG and PNG are downstream encoding choices. Find the active transport publisher's documented codec setting and confirm that the subscriber can decode the selected output.
Does PNG compression preserve floating-point depth exactly?
Not necessarily. PNG can preserve the integer samples presented to its encoder, but a depth plugin may transform or quantize floating-point depth before encoding. Check the transport's reconstruction rules, distance units and invalid-value handling, then compare decoded measurements against an appropriate reference.
When does a compression setting require a restart?
Restart when the installed component documents the setting as startup-only or requires encoder reinitialization. First confirm that the parameter exists and is supported. A restart cannot add a missing feature, and a software transport change does not automatically require a camera power cycle.
How can I prove that a codec change took effect?
Measure newly generated messages from the intended publisher, confirm the subscriber's transport, and decode the payload. Compare image quality or depth error as well as bandwidth and latency. A successful parameter response proves acceptance of the request, not necessarily that the intended active stream changed.