Depth image resolution smaller than expected: check decimation first

You configure a depth camera for 1280 x 720, grab a frame, save it to PNG, and the file opens at 640 x 360. The camera did not fail and the sensor did not change mode: something between the raw stream and the file threw pixels away. In almost every case the culprit is a decimation post-processing filter left enabled in a viewer or SDK pipeline. This troubleshooting guide shows you where decimation hides, how to verify the true output resolution of a depth stream, and which pipeline and stream settings to rule out, in order of probability.

Symptom: the saved file is smaller than the configured stream

The signature is consistent. The requested stream profile is a full resolution such as 1280 x 720. The saved image measures exactly half in each axis, 640 x 360 — one quarter of the pixels. Halving in both dimensions is the fingerprint of a decimation factor of 2. Other ratios point to other causes: a factor of 4 gives 320 x 180; a completely different resolution such as 848 x 480 from a 1280 x 720 request means the stream itself was opened at a different profile.

Note the distinction that drives the whole diagnosis:

• Stream resolution is what the camera transmits. Read it from the active stream profile.
• Pipeline resolution is what your processing chain emits after filters. Read it from the frame you are about to save.

If those two numbers disagree, a filter is resizing. If they already agree at the smaller value, the stream was configured wrong from the start.

Cause 1 (most likely): a decimation filter in the viewer or pipeline

Depth processing pipelines commonly offer post-processing filters: spatial noise reduction, temporal smoothing, hole filling, and decimation. Decimation exists to cut noise and bandwidth by discarding pixels, and it reduces the image dimensions by its factor. A viewer that applies filters globally will show the reduced image in the preview and write the same reduced image to disk — so the preview looks normal and only the file size betrays the change.

The fix:

1. Open the post-processing or filter settings in the viewer or SDK pipeline.
2. Find the decimation (sometimes called downsampling) filter and check whether it is enabled.
3. Disable it, or set its factor to 1.
4. Restart the stream so the pipeline rebuilds without the filter.
5. Save a frame and confirm the file dimensions.

Cause 2: verify the true stream resolution before blaming the pipeline

Before concluding the pipeline is at fault, confirm what the stream actually delivers. Applications and viewers can silently open a different profile than the one you intended, especially after a device re-enumeration or a settings reload. The pattern is the same one behind camera startup frame rate: verify saved settings and readback: never trust the request, read back the active configuration.

How to check:

1. Query the current stream profile of the depth stream — its width, height, and frame rate.
2. Compare it against your target, for example 1280 x 720.
3. If it differs, reconfigure the stream explicitly and re-read the profile.
4. Only when the profile matches should you investigate filters.

For a mismatch that appears after every restart, apply the discipline from reset camera settings programmatically before capture: write the full stream configuration at startup rather than relying on persisted state.

Cause 3: the requested profile was rejected and a default applied

Some depth modes are mutually exclusive: a high depth resolution may be unavailable at a given frame rate, or while the color stream runs at a particular setting. When a requested profile cannot be honored, the SDK may fall back to a supported one without an obvious error. The saved file then shows a resolution you never asked for, and it is not a round fraction of your target.

Diagnose it by listing the profiles the device reports as supported for the depth stream and checking whether your target is among them at the current frame rate. If it is not, either lower the frame rate, adjust the conflicting stream, or accept the nearest supported profile. The same rejection-without-error behavior appears in color stream exposure control: diagnose rejected settings, where a value the device refuses never reaches the hardware.

Cause 4: saving code resizes the frame

If the stream profile and the pipeline output are both correct, the reduction happens at save time. Common culprits:

• A resize call inserted for preview that also runs on the save path.
• Writing the wrong buffer: a display-scaled copy instead of the source frame.
• Lossy conversion that carries a scaling parameter, such as an undistortion or remap stage with an output size separate from the input. The cropping-versus-coverage trade-off in undistortion scaling parameter: cropping versus field of view is the same class of bug: an intermediate stage silently changing image geometry.

Save the frame with no processing between acquisition and the file write. If that file is full resolution, binary-search your pipeline stages until the dimension change appears.

How to verify the fix

Work through these checks in order; each takes under a minute.

1. Read the active depth stream profile. Width and height must equal the target.
2. Read the dimensions of the frame object handed to your save function. It must equal the stream profile.
3. Open the saved file and check its pixel dimensions and bit depth. For depth data, a 16-bit PNG preserves the millimetre values; an 8-bit conversion throws away range detail, a separate loss covered in saving 12-bit camera images without losing intensity data.
4. Repeat after restarting the application, to confirm the configuration survives reconnects.

Smaller pixels versus smaller coverage

A decimated depth image keeps the same field of view: each pixel simply covers more area, so spatial resolution drops but coverage does not. That matters when you downstream tasks that depend on geometry. If you map detected regions into 3D, as in bounding box depth: mapping image pixels to 3D points, the intrinsics must match the image you actually process — a 640 x 360 depth map needs 640 x 360 intrinsics, not the 1280 x 720 set. Mixing them shifts every measurement.

Also know that on stereo and structured-light devices the depth image's coverage can legitimately be smaller than the color image's, for optical reasons rather than any filter; depth image field of view: why stereo coverage is smaller explains that geometry. Do not chase a filter when the effect you see is field of view, not resolution.

Choosing hardware when you need the resolution at the source

When your application genuinely needs more depth detail than the sensor delivers after legitimate processing, no filter setting will help — you need a sensor with more output. Two examples from our range show the choice:

The first is a time-of-flight sensing camera, which measures depth per pixel directly; the second is a laser galvanometer stereo camera for structured-light capture. Browse the full 3D sensors range or the camera finder to compare laser profilers, stereo structured-light, and ToF types. If your inspection task also needs 2D images at matching resolution, the area scan cameras category covers GigE, USB3, 10GigE, and CoaXPress options, and the system configurator walks camera, lens, and light choices together. Note that depth sensors expose fixed profile lists rather than arbitrary resolutions, so pick a model whose native profile already exceeds your measurement requirement — upsampling later recovers no detail.

When the usual answer is wrong

Three situations where disabling decimation does not fix the file:

• The stream profile itself is wrong. Readback shows the smaller size before any filter. Fix the stream configuration, not the pipeline.
• The device fell back after a restart. Settings written once did not persist. Write the configuration at every startup.
• The reduction happens at save time. Pipeline and stream are correct; your save path resizes. Test with a raw dump of the frame buffer.

Quick checklist

• [ ] Compare saved file dimensions against the target resolution; note the ratio (half on each axis means decimation).
• [ ] Read the active depth stream profile's width and height from the device.
• [ ] Disable decimation in every viewer or pipeline the frame passes through.
• [ ] Confirm the frame handed to the save function matches the stream profile.
• [ ] Save as 16-bit PNG for depth data; verify bit depth in the file.
• [ ] Restart the application and re-verify, so a filter or fallback cannot reappear silently.
• [ ] Check that downstream code uses intrinsics matching the actual image size.

If after these steps the resolution still drops, gather the requested profile, the readback profile, and the saved file dimensions, and send them to us through the contact page — with those three numbers the cause is usually identifiable in one reply.