Add hardware timestamp reporting

[C-Achard]

Summary

Adds frame capture metadata and recording timestamp support, with best-effort Basler hardware timestamp integration.

This PR refactors camera reads to allow returning extra objects alongside the frame, such as the existing host-side software timestamp, as well as optional backend-provided timestamp metadata.
The software timestamp remains the primary source, while hardware timestamps are added only when the backend can report them.

Main changes

• Introduces a CapturedFrame wrapper for camera backends
• Adds generic timestamp metadata support
  • Supports hardware camera-clock timestamps, raw device ticks, optional wall-clock timestamps, and backend-specific extras
• Adds best-effort Basler hardware timestamp support
  • Reads device ticks count reported by Basler grab results when available
  • Falls back to an assumed one gigahertz tick frequency when the camera does not report one, and records that assumption in metadata. See Basler docs, generally devices which cannot report tick frequency operate at 1GHz, hence the fallback.
  • Treats zero-valued Basler timestamps as unavailable, which handles cases such as pylon emulation or cameras that expose the API but do not provide usable timestamps, as per Basler docs.
• Updates non-Basler backends to return the new captured-frame object.
  • Aravis, GenTL, and OpenCV currently preserve software timestamps and do not provide hardware timestamp metadata for now.
• Threads timestamp metadata through the recording path.
  • RecordingManager forwards timestamp metadata into VideoRecorder.
• Updates recorder timestamp sidecar output.
  • Timestamp sidecars now use schema version 2.
  • Per-recording timestamp source metadata is stored once.
  • Hardware timestamp fields are omitted when unavailable.
• Improves Basler exposure compatibility
  • Sets both ExposureTime and ExposureTimeAbs when writable as they both control the same property on different devices

What this does not do yet

• Hardware timestamps are best effort and backend-dependent.
• This does not change recording throughput or move recorder enqueueing off the GUI thread.

Testing

Added and updated tests accordingly; tested and confirmed to work as intended with 1x a2A1920-160umPRO.

[Copilot]

Pull request overview

This PR adds optional per-frame timestamp metadata (including best-effort Basler hardware timestamps) and threads that metadata through capture, controller signals, recording, and the timestamp sidecar output format.

Changes:

• Introduces CapturedFrame as the standard return type for camera backend read() calls, carrying software timestamp plus optional timestamp metadata.
• Adds FrameTimestampMetadata and integrates Basler tick-based timestamps (with tick-frequency discovery/fallback) into capture and recording.
• Updates VideoRecorder timestamp sidecar JSON to schema v2 with per-recording timestamp source metadata and per-frame timestamp records.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/utils/test_timestamps.py	Adds unit tests for FrameTimestampMetadata dict splitting and default selection behavior.
tests/services/test_video_recorder.py	Updates/extends tests for schema v2 timestamp sidecar output and hardware metadata inclusion.
tests/services/test_multicam_controller.py	Adjusts signal handler signatures and adds coverage for forwarding timestamp metadata.
tests/gui/test_rec_manager.py	Adds coverage ensuring RecordingManager.write_frame() forwards timestamp metadata to recorder.
tests/conftest.py	Updates test backend and recorder fakes to use CapturedFrame and pass through timestamp metadata.
tests/cameras/backends/test_opencv_backend.py	Updates OpenCV backend tests for CapturedFrame return type.
tests/cameras/backends/test_gentl_trigger.py	Updates GenTL trigger test to read .frame from CapturedFrame.
tests/cameras/backends/test_gentl_backend.py	Updates GenTL backend tests for CapturedFrame return type.
tests/cameras/backends/test_basler_backend.py	Updates Basler backend tests and adds coverage for Basler timestamp metadata.
tests/cameras/backends/test_aravis_backend.py	Updates Aravis backend tests for CapturedFrame return type and minor unused var cleanup.
tests/cameras/backends/conftest.py	Extends fake Basler SDK objects to provide timestamp and tick-frequency nodes.
dlclivegui/utils/timestamps.py	Introduces FrameTimestampMetadata dataclass and serialization helpers.
dlclivegui/services/video_recorder.py	Threads timestamp metadata through queue/write loop and writes schema v2 timestamp sidecar JSON.
dlclivegui/services/multi_camera_controller.py	Extends capture/recording signals and internal plumbing to propagate timestamp metadata.
dlclivegui/gui/recording_manager.py	Forwards timestamp metadata into VideoRecorder.write().
dlclivegui/gui/main_window.py	Passes timestamp metadata from controller signal into recording manager.
dlclivegui/cameras/base.py	Adds CapturedFrame, updates backend interface to return it, and extends capabilities.
dlclivegui/cameras/backends/opencv_backend.py	Updates OpenCV backend to return CapturedFrame on success/failure paths.
dlclivegui/cameras/backends/gentl_backend.py	Updates GenTL backend to return CapturedFrame.
dlclivegui/cameras/backends/basler_backend.py	Adds Basler timestamp tick-frequency handling and per-frame timestamp metadata generation.
dlclivegui/cameras/backends/aravis_backend.py	Updates Aravis backend to return CapturedFrame.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.