Why exported point clouds differ from the viewer render

You export a point cloud from the 3D camera's viewer, open the PLY in a mesh editor such as MeshLab, and it looks nothing like the render: streaks of wrong color reaching in from the left and right edges, a dense spike at the origin, and thousands of points you never saw on screen. The camera did not change and the file is not corrupt. The viewer shows you less than the exporter writes: it draws only the region where depth and color overlap and drops invalid points, while the export path writes every depth pixel it is handed. This guide walks the three causes in order of likelihood, the test that isolates each one, the filter that makes the file match the render, and the checks to run before you trust any export.

The render and the export are two pipelines

Nothing in your set-up broke. A depth-plus-color camera is two sensors behind two lenses, and the viewer and the exporter treat their footprints differently. The viewer's GPU path rasterizes each depth point and discards any fragment whose color lookup lands outside the color image, so what you see on screen is the depth–color intersection — a narrower field of view with clean texture. The exporter walks the depth frame and writes one vertex per pixel, using software that samples the color image with ordinary addressing rules. Where the depth pixel has no color counterpart, those rules still return a color: the edge pixel, repeated. Same camera, same frames, two different results. Three differences follow, ranked by how often they explain the file you are looking at.

Cause 1: the color camera sees less than the depth sensor

In a stereo or structured-light module the depth field of view is usually wider than the color one; a common split is 90° × 58° for depth against 70° × 42° for color. Sensor pixels are linear in the tangent of the angle, not the angle itself, so the fraction of the depth frame the color image covers is:

Run the numbers for that split:

• Width: tan(70° / 2) / tan(90° / 2) = 0.700 / 1.000 = 0.700, so 70% of the columns.
• Height: tan(42° / 2) / tan(58° / 2) = 0.384 / 0.554 = 0.693, so 69% of the rows.
• Area: 0.700 × 0.693 = 0.485 — under half the depth pixels have a real color source.

On a 1280 × 720 depth frame that is 896 of 1,280 columns, blind for 192 columns on each side, and 499 of 720 rows. Every depth pixel in that blind rim still receives a color in the PLY: with clamped texture addressing the sampler returns the last valid column forever, which paints the stretched streaks; with wrapped addressing you get a band of unrelated colors. The viewer discards those fragments before they reach the screen, so the artifact waited for you in the file.

Test: count the vertices the viewer never drew

Load the PLY anywhere you can script it — Python with numpy, or the filtering tools of a mesh editor — and count two things. First, vertices whose normalized texture coordinates u/w and v/h fall outside the range 0 to 1; with the split above, that is about 51% of the points, concentrated on the left and right margins. Second, vertices where x = y = z = 0. If the out-of-range texture count runs to tens of percent and sits on the margins, cause 1 is confirmed and you can stop hunting for calibration errors.

The fix: discard the rim, or crop to the intersection

The filter itself is one line per coordinate:

u = uv[:, 0] / color_w        # normalized texture column
v = uv[:, 1] / color_h        # normalized texture row
in_frame = (u >= 0) & (u <= 1) & (v >= 0) & (v <= 1)
not_zero = ~np.all(xyz == 0, axis=1)
cloud, colors = xyz[in_frame & not_zero], rgb[in_frame & not_zero]

For the mechanics of hunting bad texture coordinates in large clouds, see filtering invalid texture coordinates in a point cloud; for the registration math that produces u and v in the first place, registering RGB and depth images for a colored point cloud works through it.

Then decide what the file is for. To match the render, keep the filter: with the numbers above you keep 447,104 of 921,600 pixels (896 × 499), which is the intersection the viewer was showing you all along. To keep the full depth footprint, the rim has no color source — write it black or flag it, and never let the sampler clamp without reporting it, because streaks of repeated border pixels poison color-based segmentation far more than honest black does.

Cause 2: zero-depth pixels exported at the origin

Depth the sensor could not resolve — glare, out-of-range surfaces, dark or mirror-like parts — arrives as the value 0, and a raw exporter deprojects it anyway, producing a vertex at (0, 0, 0). The viewer discards invalid depth before drawing, so the mesh editor is the first place you see the resulting ball or spike at the origin, often the densest cluster in the file. A frame with 5% invalid depth carries about 46,000 of these vertices. The test is one count; the fix is the not_zero mask above. If the holes themselves matter to the inspection, missing points in a 3D camera point cloud attacks the capture-side causes, and depth pixel deprojection zero traces how the zero vertices arise.

Cause 3: the filters ran on screen but not in the file

Viewers apply decimation, spatial and temporal filters to what they draw; a raw export path often writes the untouched frame. The tell is the vertex count: a 1280 × 720 frame exported raw carries exactly 921,600 vertices, while the 2 × 2 decimation you watched on screen corresponds to about 230,400. Run the same filter chain on the frames, then export from that block.

Writing several hundred thousand vertices has its own cost on embedded boards; speeding up slow PLY point cloud export covers the buffered writer.

Match your symptom in one minute

When it is not the rim

If the whole cloud is wrong — geometry shifted by the mounting, axes mirrored, color offset everywhere rather than at the margins — the field-of-view explanation does not apply. First check whether the depth stream is aligned to color before export: is depth image_raw aligned to RGB? covers the check. Depth points arrive in the depth sensor's optical frame, so a tool that assumes the camera frame applies the wrong rotation; transforming depth point clouds between the optical and camera frame shows the fix. And if the viewer and your export script run different SDK versions, align them first — 3D camera header version mismatch lists the failure signs.

Hardware that removes the mismatch at the source

If every point needs true color, the color camera's field of view must be at least as wide as the depth one. For a rectilinear lens that sets a ceiling on focal length:

Covering a 90° depth field of view takes f ≤ 3.2 mm on a 1/2-inch sensor (6.4 mm wide) and f ≤ 4.4 mm on a 2/3-inch sensor (8.8 mm wide). The lens focal length calculator runs the same arithmetic for whatever sensor you mount.

A C-mount color body accepts the lens that number calls for, and the area scan cameras finder filters by mount, sensor format and interface.

On a 1-inch sensor, 12.8 mm across, the same 90° coverage needs f ≤ 6.4 mm — wide, but available in C-mount.

The other route is to stop building a two-sensor rig. Projected structured-light and ToF units in 3D sensors deliver the cloud from one housing on one optical axis, so there is no second footprint to reconcile and one specification states the coverage. When a full station is on the table, 3D camera working distance and positioning settles where that axis sits.

If the unit you choose carries a laser-classed emitter, treat it as a laser product: block the beam whenever a person is in the scanning plane, and never look into the aperture.

Checks before you trust any export

• The vertex count equals the pixel count times your decimation, not the raw pixel count by accident.
• No vertices remain at (0, 0, 0) after filtering.
• The out-of-range texture count matches one minus the area coverage from the field-of-view numbers.
• The file's bounding box matches the render, with no origin spike pulling a corner to zero.
• Colors in the outermost columns differ from their neighbours rather than copying the last valid column.
• Keep one known-good PLY and diff new exports against it after every SDK update.

Planning a new capture station rather than repairing an export? The system configurator walks camera, lens, light and controller in order, and the contact page puts the odd cases in front of an applications engineer.