3D camera recording to H5 files for offline processing

You captured 3D depth data — or you are about to — and the analysis has to happen offline, in Python, on a PC nowhere near the line. The capture tool that came with your 3D camera can write two very different files, and choosing the wrong one is the difference between a dataset you can open for years and a file that refuses to load without the camera on your bench. This guide gives you the format decision, the recording steps, the h5py code to read the take, the disk-space math, and the recovery path when only the wrong file exists. It applies to ToF, structured-light and laser-profiler recording alike; the 3D sensors category shows the cameras these workflows serve.

Which file format should you record for offline processing?

Record HDF5 — the .h5 file your capture tool writes from its monitor's record options — because HDF5 is an exchange format any library opens offline, while the application-snapshot file the same tool writes for tuning opens only with a matching camera connected.

A 3D camera's capture tool typically writes two artifacts. The application snapshot copies the camera's current application — its settings and internal state — into one file, so you can fine-tune detection parameters against a recorded scene without re-triggering the real part presentation. That is a tuning convenience tied to the camera, and it is deliberately not an interchange format: the data inside is arranged for the tool-plus-camera pair, not for a library.

The HDF5 file is the opposite. It stores the recorded stream data — depth, and where offered, amplitude or confidence — in an openly documented container that h5py and every language with an HDF5 binding can read on a camera-less PC.

So the rule: when data leaves the station — to a customer, a data scientist or your own office PC — send HDF5, and keep snapshots on the tuning laptop that made them. For the storage side of long-term archives, the guide on recording depth data losslessly for offline analysis continues from here, and when you record depth together with color, the same format-first logic explains why a multi-stream bag file beats a plain AVI. More capture-side decisions sit on the 3D topic page.

Why does an application snapshot refuse to open without the camera?

The snapshot stores one camera application together with the sensor's internal state, and the capture tool replays that pair only against a live, matching camera, so on a camera-less PC the tool cannot even load the file.

It exists for a specific job: you triggered a part once, manually, on a production line, and now you want to adjust the application's parameters against that exact scene again and again. Replaying the snapshot reproduces the camera's internal processing on the stored scene, so no new trigger is needed for tuning. But the file's structure and buffers are meaningful only to the tool when it can talk to the matching camera, which is why the tool's replay function opens recorded data files while it leaves snapshots locked to a live connection.

The frames are in there — wrapped in a form the tool never exported. No library reads the layout, and the tool itself offers no convert-or-save-as path for it offline. Treat snapshot and dataset as different objects from the first day: a snapshot proves what the camera's application did; an H5 file is the dataset.

How do you record an H5 file from the capture tool?

Open the tool's live monitor view, set the record options there to HDF5, choose a duration, run the take, and the tool writes one .h5 file that any PC opens later with no camera attached.

You need the camera connected and live in the monitor view, the record options dialog reachable from that view (the one that sets format and duration), disk headroom per the math below, and the scene running or triggerable.

1. Connect the sensor and open the live monitor view. Confirm the depth image shows the scene in position.
2. Open the record options in that monitor window. Choose HDF5 as the format. Deselect streams you will not use — depth alone halves the file versus depth plus amplitude.
3. Set the duration. Sixty seconds proves the pipeline; scale to your cycle count afterwards. For a ToF sensor, set the unambiguous range first so far background does not wrap into the working band — the ToF unambiguous range guide walks that choice.
4. Run the scene and start the recording. Keep presentation, exposure and mounting untouched for the whole window.
5. Stop, then rename the file with station, scene and take length before it leaves the tuning PC: station3_sceneA_60s.h5 beats recording_final.h5 six months later.

The workflow is identical across sensor families in the camera finder. Static, high-detail scenes suit a projected structured-light camera, and larger scenes scanned line by line suit a laser galvanometer stereo camera:

What does the Python code to read the H5 file look like?

Use h5py: open the file in read mode, list the dataset names your capture tool wrote, read the depth dataset into a NumPy array, then check its frame count against the duration and rate you set.

import h5py                      # pip install h5py
import numpy as np

path = "station3_sceneA_60s.h5"  # file name example: use yours
frames_expected = 600            # int: 60 s duration x 10 fps set in the record options

with h5py.File(path, "r") as f:
    print(list(f.keys()))        # run this first: the names come from your tool
    depth = np.asarray(f["depth"])   # use a key the print shows; shape (frames, rows, cols)

print(depth.shape, depth.dtype)  # expect about (600, 480, 640) uint16
assert depth.shape[0] >= frames_expected - 2   # the take really holds the full window
print("depth min/max:", int(depth.min()), int(depth.max()))

The dataset names are the capture tool's choice and follow the streams you ticked, so the print statement is not optional: list, then read. Depth from most sensors arrives as unsigned 16-bit values scaled in millimetres, so min and max read directly in mm against your working distance. Exposure, timestamps and similar metadata appear as attributes on the file or the datasets — print f.attrs to see them.

From the depth array to coordinates, the 2.5D height map to 3D point cloud guide continues — pixels to XYZ using the sensor's intrinsics.

How much disk space does a depth recording need?

Budget rows × columns × 2 bytes per frame for each 16-bit stream: a 640 × 480 depth take at 10 fps needs about 0.61 MB per frame, roughly 369 MB for a 60 s take and about 22 GB per hour.

The arithmetic, step by step: 640 × 480 pixels × 2 bytes = 614,400 bytes ≈ 0.61 MB per frame. At 10 fps that is 6.14 MB/s. A 60 s take: 6.14 MB/s × 60 s ≈ 369 MB. An hour: 6.14 MB/s × 3,600 s ≈ 22 GB.

Tick a second 16-bit stream (amplitude or confidence) and every figure doubles. gzip inside HDF5 shrinks smooth depth maps typically by 2× or more, because neighbouring pixels rarely differ much; measure once by comparing your file's size with the raw product above before you count on the saving. The guide on shrinking depth recordings without losing usable data lists further cuts.

Rate decides size more than anything else: record at the slowest fps your algorithms accept. For inline stations a ToF sensing camera such as the model below streams depth continuously, and the duration field, not the sensor's top speed, sets the take's size.

Long unattended takes need a capture PC with storage headroom and no desktop software churning in the background — this is where fanless industrial mini PCs earn their place on the cell.

What can you do when all you have is the snapshot file?

There is no offline conversion: the documented tooling loads a snapshot only together with a matching camera, so the fix is a re-record as HDF5, guided by a written scene sheet that reproduces the original take.

Confirm the limit once if you like: install the capture tool on the office PC and try to open the snapshot — the load fails without the camera, and the tool offers no export from it afterwards. The snapshot is not editable either. That makes the scene sheet the real deliverable, sent with every request:

• Scene and part presentation: part numbers, fixture, orientation, any stacking or covering.
• Sensor geometry: mounting position and orientation relative to the scene, working-distance band.
• Capture settings: exposure or integration, ToF unambiguous range, frame rate, streams requested.
• Timing: duration, trigger source and trigger timing.
• Environment: lighting, enclosing fixtures, anything that moves in the background.
• Tool version, so the provider reproduces the take with the same software.

If you own the camera, this takes minutes: reconnect, load the application, record the H5 as in the recording section above. If the provider owns it, send the sheet. A one-off scene that physically cannot be rebuilt is genuinely unrecoverable — say so in the request before the file arrives, and have the provider record live data through the SDK during the window instead.

How do you verify a recording before you trust it?

Open the file on a PC with no camera installed, confirm the frame count equals duration × rate within a frame or two, print depth minimum and maximum against your working band, and render three frames as images.

Work the checklist in order:

• Opens read-only with h5py on a camera-less PC — this proves it is the exchange file, not another snapshot.
• Frame count: 600 ± 2 for the 60 s, 10 fps take — a short count means the scene stalled mid-window.
• Depth min and max inside your working band: in the example station, parts at 800 mm should read roughly 760-840 mm.
• Three frames rendered as images: part present, no dropout bands, background where expected.
• If depth and color are both recorded, timestamps advance together — the depth-color timestamp drift guide explains what grows over a take and why.
• Folder carries the scene sheet and tool version, so the take can be reproduced or audited later.

The failures seen most often: the duration typed as 6 s instead of 60, the second stream ticked out of habit so the file doubled, and the scene moved mid-window. All three show up in the checks above.

If you are choosing the sensor as well as the format, build the station end to end in the system configurator, or contact the applications team for a format and storage review of a specific cell.