API: Realtime Package
Realtime contracts decouple live preview producers from UI refresh loops. They are suitable for Streamlit, web sockets, MJPEG endpoints, notebook widgets, and future native viewers.
FrameColorSpace
module-attribute
FrameColorSpace = Literal['BGR', 'RGB', 'GRAY']
RealtimeFrame
dataclass
Immutable handoff object for realtime image previews.
The frame carries pixels plus enough metadata for UI adapters to render it without depending on pipeline-specific data classes.
Mutability
The image array is validated but not copied at construction time. Sinks that cross thread boundaries should copy pixels before storing or sharing them.
Attributes:
| Name | Type | Description |
|---|---|---|
image |
ndarray
|
Source image array. |
color_space |
FrameColorSpace
|
Color interpretation of |
frame_index |
int | None
|
Optional source frame index. |
timestamp_seconds |
float | None
|
Optional source timestamp. |
produced_at |
datetime
|
UTC timestamp for when the realtime frame value was created. |
metadata |
Mapping[str, Any]
|
Adapter-specific metadata such as preview stage and priority. |
as_rgb
as_rgb() -> np.ndarray
Return an RGB copy suitable for browser-oriented renderers.
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
IRealtimeFrameSink
Bases: Protocol
Output port for realtime visualization frames.
Sinks decouple frame producers from UI refresh loops. Implementations should avoid blocking the pipeline for slow viewers; copy frames when crossing thread or process boundaries.
publish
publish(frame: RealtimeFrame) -> None
Publish a rendered frame to a realtime consumer.
close
close() -> None
Notify consumers that no more frames will be published.
RealtimeFrameSnapshot
dataclass
Point-in-time view of a realtime frame store.
Snapshots are safe for UI polling. The contained frame, when present, is a
copy made by LatestRealtimeFrameStore.snapshot().
LatestRealtimeFrameStore
Bases: IRealtimeFrameSink
Thread-safe sink that keeps only the newest realtime frame.
This implements a drop-oldest preview policy: UI consumers never block the pipeline, and slow refresh rates simply skip stale frames.
publish
publish(frame: RealtimeFrame) -> None
Store a copy of the newest accepted realtime frame.
Lower-priority raw frames do not replace higher-priority annotated previews. This keeps live viewers from flickering between unmatched raw and rendered layers.
close
close() -> None
Mark the store inactive while keeping the latest frame available.
reset
reset() -> None
Clear any previous preview before a new run starts.
snapshot
snapshot() -> RealtimeFrameSnapshot
Return a copy-safe snapshot for UI rendering.
NullRealtimeFrameSink
Bases: IRealtimeFrameSink
No-op realtime sink.
Use this sink when a component accepts realtime publication but the current application has no viewer attached.