Chunk data on camera frames: carry timestamp and exposure per image

A frame arrives at your code carrying pixels, and your logger stamps it with the host clock — then you try to measure anything faster than a few milliseconds and the numbers wobble. Chunk data moves the measurement into the camera: the timestamp, the exposure time actually used, the gain and a frame counter ride inside the image buffer itself. This guide covers what chunk data is, which values a camera can embed, what it costs in bandwidth, why an SDK sometimes hides it, and how to confirm all three layers — firmware, transport, adapter — deliver it. If you specify cameras for event timing, exposure logging or multi-camera alignment, you will leave able to test a stack for chunk support in minutes, with the arithmetic to judge its cost.

What is chunk data on a camera frame?

Chunk data is the GenICam feature in which the camera appends a block of metadata — timestamp, the exposure time it actually used, gain, a frame counter, digital-IO states — to the same buffer that carries the pixels, so the values travel with the image.

The camera packs the block alongside the pixel payload, and the SDK unpacks it and hands you one value set per frame. Both GigE Vision and USB3 Vision carry chunk blocks, and the standardized names come from GenICam's SFNC, so a chunk-enabled camera behaves the same through any conforming API. The clock behind the timestamp belongs to the camera: it free-runs from power-up, is read-only from the host side, and advances monotonically for the whole session.

The contrast is host-side sampling. A logger that reads the PC clock inside the frame callback stamps the moment the buffer reached your process, not the moment the sensor saw light; every microsecond of transfer, driver work and scheduler delay between the two lands inside your measurement. Chunk values are measured where the exposure happens, and that whole class of error leaves the data.

Which values can a camera embed in each frame?

The camera's node map lists exactly which chunks its firmware can produce, and the common set is a timestamp, the exposure time and gain applied to that frame, a frame counter and the digital-IO line states captured with the exposure.

The SFNC names follow one pattern: a master switch, ChunkModeActive, turns the feature on, and each value gets its own selector and enable — the time value is ChunkTimestamp and the others follow the same form. Values are read-only: the timestamp returns the camera's counter, and nothing written from the host changes it. Where in the frame cycle the clock is latched — exposure start or exposure end — differs between cameras, and Chunk data timestamp: camera time at exposure end and how to latch it works through that latch point.

Cameras with region support often add chunks naming the region that produced the frame. Read the node map rather than a data-sheet table: the firmware decides the list, and the list is short to check.

How much bandwidth does chunk data cost?

Almost nothing: a chunk block runs a few dozen to a few hundred bytes per frame, so a generous 128-byte block on a camera streaming 4000 × 3000 at 30 fps adds about 3.8 kB/s against roughly 360 MB/s of pixel payload — a 0.001 % share.

The arithmetic for the example stream: 4000 × 3000 = 12,000,000 pixels per frame. At 8 bit mono, one byte per pixel, that is 12,000,000 B ≈ 12.0 MB per frame, and 12.0 MB × 30 fps = 360 MB/s of pixel data. A 128-byte chunk block — illustrative, because the real size grows with the number of values you enable — adds 128 B × 30 = 3,840 B/s. The share is 3,840 / 360,000,000 = 0.0011 %. Even a 1,000-byte block would add 30 kB/s, eight times more and still invisible.

The overhead scales with frame rate and stays flat with resolution; the payload is what decides the transport. The same frame at 16 bit doubles to 24 MB and 720 MB/s, past what a USB3 link sustains, while a GigE link moves 1000 Mbit/s ÷ 8 = 125 MB/s at line rate and USB3 about three times that. If a measured stream lands far below this arithmetic, suspect the link before the software: on embedded hosts a USB3 camera stuck at a fraction of its expected rate usually traces to a fallback or driver cause, as in this USB3 camera low-speed troubleshooting guide.

The example stream is the printed spec of the camera below — 12 MP USB3, 4000 × 3000 at 30 fps:

Why is the camera timestamp different from the host timestamp?

Host time marks when the buffer reached your callback — after transfer, driver and OS scheduling delay — while the chunk timestamp is latched inside the camera at the frame's latch point, so the two differ by milliseconds that move from frame to frame.

The camera interval is the measurement; the host interval is the measurement plus jitter. On a busy host the callback lands late by a scheduling quantum or a buffer-queue hiccup, and the size of the lateness changes per frame. GigE Vision frame arrival jitter: isolate camera and host timing walks that isolation, and Camera buffer timestamp latency: interpret frame timing explains what a buffer stamp actually includes.

To place camera time on the host clock, map it once per session: capture a frame, read the arrival time A and the chunk stamp T, and carry the offset A − T as the session's conversion. The counter is monotonic and read-only, so the offset holds until you close the camera; re-map after any reconnect.

When do you need chunk data instead of logging timestamps in software?

You need chunk data whenever the number must describe the exposure rather than the arrival: frame interval and speed under jitter, exposure and gain under auto exposure, dropped-frame detection, IO-event correlation and time alignment between cameras — five jobs host-side logging does not survive.

• Frame interval and speed under jitter. The 34 % error above is the case. Any speed or timing number computed from arrival times inherits it, and the chunk stamps remove it.
• Exposure and gain under auto exposure. The exposure you wrote to the camera is not the exposure the sensor used; the per-frame chunk records what actually happened, as Read exposure time from frame metadata under auto exposure shows, and Camera exposure and gain units: interpreting raw values covers how to read those numbers.
• Dropped-frame detection. When the frame counter steps 847 → 850, two frames vanished at the source. A host-side counter can miss frames for its own reasons and cannot say where they went.
• IO correlation. The IO-line chunk records the trigger input's state at the exposure, so a frame whose trigger came from the wrong source shows up immediately.
• Multi-camera alignment. Two cameras each free-run their own counter, and per-frame stamps are the only time base the streams share — whether the cameras are two USB3 units triggered together, as in Hardware sync two USB cameras: trigger both cameras together, or a rack of CoaXPress cameras onto a frame grabber such as the MV-GX1008, with ports assigned as in Assign cameras to ports reliably in a multi-camera system.

Two hardware shapes cover that last case — cameras sharing one NIC, and cameras feeding a frame grabber:

Why doesn't chunk data show up in the SDK?

Three layers must agree: firmware that generates the chunks, a GigE Vision or USB3 Vision transport that carries them, and an SDK adapter that both exposes the GenICam chunk nodes and parses them out of each buffer — hide the nodes anywhere and supported hardware still delivers nothing.

The classic failure is the third layer. The camera's own configuration tool shows a chunk category with every value you want; enumerate the node map from your acquisition API and the chunk nodes are absent. The firmware is rarely the cause — if the vendor's tool sees the nodes, the camera produces them. For GenICam-based hosts the adapter is the GenTL producer or the vendor's API layer, and it decides what your code can reach; one that predates the feature or never maps the chunk category drops it silently.

Run this check on any camera you plan to log from:

1. Open the camera in the vendor's node browser and find the chunk category; write down the values it offers.
2. Enumerate the same node map from your own API and count the chunk nodes. A browser list your API cannot reproduce is the adapter gap, located in five minutes.
3. Enable the master switch and select the values you need; confirm the buffer length grows or the SDK exposes per-frame values.
4. Log ten frames and read them back: the counter must step by exactly 1, and the stamp must advance by roughly the frame period — 33.3 ms at 30 fps.

If your flow depends on a configuration built in the vendor's tool, the supported equivalent is the camera's user-set feature: save the settings to a user set and load that set from your API, if the adapter exposes those nodes too. Once the chunk nodes do appear, Setting camera exposure time through a GenICam API in Python shows the shape of the calls, and Access GigE camera registers at runtime from your control code covers reading the underlying registers when a feature is not exposed at all.

What should you check before specifying a camera for chunk logging?

Check four things before you order: the firmware must list the chunks you need, your SDK adapter must expose those nodes, the timestamp's tick rate must fit the interval you plan to measure, and the link must carry your payload with headroom.

• The node map lists your values. Timestamp, exposure, gain, counter, IO status — in the vendor's browser, on the exact firmware version you will run.
• Your API reproduces the list. Same nodes, same names; this is the layer that fails most often.
• The tick rate fits the interval. A microsecond tick resolves a 5 ms interval to 0.02 %; a millisecond tick resolves it to 20 % — the difference between usable and useless for the timing example above.
• The latch point is known. Exposure start or exposure end, per camera; compare two cameras only after both are written down.
• The payload fits the link. Run the bandwidth arithmetic for your resolution, bit depth and frame rate against the line rate — 125 MB/s for GigE, about three times that for USB3.
• The buffer handling survives the extra fields. If the SDK reuses buffers, copy the chunk values out before the next frame, as Torn frames in a camera callback: copy the buffer before you queue it shows for the pixels.

Shortlist the cameras in the area scan cameras category with the camera finder, run the node-map test on the shortlist, then size camera, grabber and host together in the vision system configurator. More systems-level guides sit on the systems topic page.