Camera frame timestamp vs system time: why clocks differ

You print the frame timestamp next to the host clock and get 13,905,354,715,900 beside 1,729,090,310.31. Nothing is broken: the first value counts ticks of the camera's own hardware counter, the second counts seconds since 1970-01-01 UTC. The units differ and the origins differ, so subtracting one from the other produces a number with no meaning. Work through this once and the pairing behaves: read the camera clock's unit and origin, decode both printed values, latch a single offset that puts every frame on the host time base, and run three tests that prove the mapping. The same method correlates frames with PLC events, log entries or a second camera.

Why the two numbers can never match

The frame timestamp is a free-running counter driven by the camera's own crystal. It counts up only, ignores leap seconds, daylight saving and NTP corrections, and starts from an origin of its own: power-up, or zero after a reset command. time.time() returns seconds since 1970-01-01 UTC on the host wall clock, which NTP steps back and forth. Two counters with different units and origins do not subtract. When a mapped time looks wrong, the cause is one of these five, roughly in order of how often it is the culprit:

1. Unit. The value is ticks, not seconds. The same digits, 13,905,354,715,900, mean 13,905.35 s at 1 ns per tick but 92,702.36 s at 150 MHz. Test: read the tick frequency before interpreting anything.
2. Epoch. The origin is camera boot or the last reset, not 1970. Test: power-cycle the camera. A boot-relative counter restarts near zero; Unix time would survive.
3. Anchor. The value is latched when exposure starts, on some models when exposure ends, never when your callback runs.
4. Arrival. A GigE or USB3 frame reaches your callback tens of milliseconds after capture. The host arrival time is a different measurement; see the buffer timestamp latency guide.
5. Drift, reset or wrap. The two crystals drift apart by milliseconds per hour, a reset zeroes the counter, and narrow counters wrap.

Read the unit, origin and anchor from the camera

On GigE Vision cameras the feature GevTimestampTickFrequency reports the counter rate in ticks per second (Hz). A camera reporting 150,000,000 has ticks of 1/150,000,000 s ≈ 6.67 ns. Non-GigE cameras expose an equivalent clock-frequency control or document a fixed rate. The value is model-specific, so read it instead of assuming nanoseconds.

The origin follows the same rule: the counter runs from power-up, and the documented TimestampReset control sets it back to zero. GenICam SFNC defines the frame timestamp as the instant exposure starts; some models latch at exposure end instead. How that value travels into your buffer is the subject of the chunk data timestamp guide.

Worked example: decode the two printed values

Take the pair from the introduction. Host value first: subtract the 2024-01-01 00:00:00 UTC anchor of 1,704,067,200 s. 1,729,090,310 - 1,704,067,200 = 25,023,110 s, which is 289 days plus 53,510 s, and 53,510 s = 14 h 51 min 50 s. The log line was written on 16 October 2024 at 14:51:50 UTC.

The camera value stays ambiguous until the tick rate is read. Two plausible readings of the same 13,905,354,715,900:

Both are believable uptimes, which is the point. The naive subtraction 1,729,090,310.31 - 13,905.35 = 1,729,076,404.96 decodes to 11:00:05 UTC on the same day: plausible-looking, and wrong by exactly the uptime you misread. Read the frequency first; never guess the unit.

Map both clocks onto one time base

One offset latches the counters together. Read the camera counter and the host monotonic clock at the same instant, scale ticks to seconds, and the difference is your offset. Every frame then maps with one addition:

Worked through: at latch, the host monotonic clock reads 5,000.000 s and the camera counter reads 13,905,354,715,900 at 1 GHz, i.e. 13,905.3547159 s. The offset is 5,000.000 - 13,905.3547159 = -8,905.3547159 s. A frame with 13,906,354,715,900 ticks maps to 13,906.3547159 - 8,905.3547159 = 5,001.0000000 s, exactly 1.0000000 s after the latch, as timed.

In Python the pattern is four lines. The feature name comes from the camera; the variable names are illustrative:

import time

tick_frequency = 150_000_000    # from GevTimestampTickFrequency, Hz (illustrative value)
ticks_now = 13_905_354_715_900  # int, camera counter read now
host_now = time.monotonic()     # float, seconds on the host monotonic clock

offset = host_now - ticks_now / tick_frequency  # float, seconds

def frame_time(ticks: int) -> float:
    return ticks / tick_frequency + offset

Latch against the monotonic clock, not time.time(): NTP can step wall time backwards, and a step corrupts the offset. The two crystals then drift apart at the tolerance of the camera's crystal, typically ±20-50 ppm. That is 1.2-3 ms per minute (50 ppm × 60 s = 3 ms) and up to 180 ms per hour (50 ppm × 3,600 s = 0.18 s). Re-latch every 60 s and clock error stays at or below 3 ms; if 0.1 s accuracy is enough, an hourly re-latch does.

Three tests before you trust the mapping

1. Round trip. Acquire two frames 1,000 ms apart, paced by the host timer. The mapped delta must read 1.000 s within your drift budget; with a fresh offset and 6.67 ns resolution, an error above single-digit milliseconds is a bug, not clock physics.
2. Hardware event. Pulse the camera's trigger line from an output the host also time-stamps. The mapped timestamp must land at trigger-plus-latency, and repeated pulses should scatter by microseconds — wired trigger jitter, well under a millisecond.
3. Cross-camera. Fire two cameras from one trigger. Their mapped times must agree within wiring skew. A camera that reads consistently late by about one exposure duration has an anchor mismatch, exposure end instead of start, not a clock fault.

Other epochs you will meet

FILETIME catches people because the scale is 100 ns: 132,702,865,451,985,472 × 100 ns = 13,270,286,545.2 s after 1601-01-01, which is 9 July 2021. Convert by dividing by 10^7, never by 10^9.

PTP is the clean exit: a camera disciplined to a network grandmaster reports genuine epoch time and the offset step disappears. When it misbehaves, the camera PTP timestamps guide lists the checks that restore Unix time. Host runtimes carry their own traps: real-time controllers keep a separate clock domain from their Windows machines, which is why real-time timestamp strings can differ from the Windows host at the same instant.

Rolling shutter: the timestamp belongs to row 0

On a rolling-shutter sensor the latched instant is the start of row 0's exposure, and row N is exposed roughly N × t_row later. Say a 4,000-row sensor reads out in 20 ms: the per-row time is 20 ms / 4,000 = 5 µs, so the last row sees the scene about 20 ms after the timestamp. Part of an apparent clock error is simply where the object sat in the frame. If exposure changes frame to frame under auto exposure, the anchor moves with it; read the real exposure per frame from metadata and correct, as in the frame metadata exposure guide.

Keep the mapping honest across a shift

• Re-latch the offset at a fixed cadence: 60 s for millisecond-class work, per the drift numbers above.
• Log every timestamp reset and power cycle. Each starts a new time base and invalidates stored offsets.
• Mind counter width. 64 bits at 1 GHz wraps after about 584 years (2^64 × 1 ns = 1.845 × 10^10 s), so wrap is rarely the bug; a 32-bit counter at 150 MHz wraps every 28.6 s. The clock rollover and monotonic mapping guide shows the reconstruction.
• Keep the latch, the conversion and the drift check in one tested module, not scattered through the application.

What this means when you pick hardware

The decision: never compare the raw numbers. Read GevTimestampTickFrequency, latch one offset against the host monotonic clock, re-latch every 60 s for millisecond work, and prove the mapping with the three tests above. GigE Vision cameras report the tick rate directly; models with PTP or a hardware trigger input remove most of the mapping work in multi-camera cells, where every camera needs the same time base.

Shortlist with the camera finder; more timing guides sit on the cameras topic page.

If the timing options look like a maze, contact the applications team and bring your drift budget.