Pipeline

vigilo_stream.Pipeline manages hardware video capture, worker thread pools, neural inference, and temporal event evaluation.

class Pipeline:
    def __init__(
        self,
        config_path: Optional[str] = None,
        models_dir: Optional[str] = "models",
        auto_download: bool = True,
        device: str = "auto",
    ) -> None: ...

Constructor

Pipeline(...)

Initializes a new capture and inference pipeline.

• Parameters:
  • config_path (Optional[str]): Path to a custom TOML configuration file. If None, default settings are used.
  • models_dir (Optional[str]): Directory containing the ONNX model files. Defaults to "models".
  • auto_download (bool): If True, automatically downloads any missing model weights from official repositories into models_dir on first use. Defaults to True.
  • device (str): Execution target preference:
    • "auto" (default): Uses GPU acceleration if available and cached, otherwise runs on CPU.
    • "gpu": Requires GPU acceleration. Automatically downloads the platform-specific GPU runtime backend from GitHub Releases on first use if not already cached.
    • "cpu": Always uses the lightweight CPU-optimized engine with zero external downloads.
• Raises:
  • IOError: If config_path is specified but cannot be read.
  • ValueError: If the TOML configuration is malformed.
  • RuntimeError: If the neural detector cannot be built, or if device="gpu" is requested but no supported hardware or backend is available.

---

Methods

start(source_spec)

Starts the background capture and inference worker threads.

• Parameters:
  • source_spec (str): The input source specification.
    • "camera:0": Default webcam device 0.
    • "file:path/to/video.mp4": Video file for offline playback.
    • "dir:path/to/frames_folder": Directory containing an image sequence.
• Returns: None
• Raises:
  • ValueError: If source_spec is invalid or unsupported.
  • IOError: If the camera device cannot be opened or the file does not exist.
  • RuntimeError: If the pipeline is already running or the background threads fail to start.

is_running()

Checks if the background capture and inference threads are currently active.

• Returns: bool (True if active, False otherwise).

poll_frame()

Fetches the most recently captured and processed video frame without blocking.

• Returns: Optional[Frame]: A zero-copy Frame object, or None if no new frame is available yet.

snapshot()

Fetches the instantaneous detection signals evaluated on the latest frame without blocking.

• Returns: Optional[Signals]: A snapshot containing detected faces, head pose, gaze, objects, and identity similarity, or None if no frame has been processed yet.

events()

Drains and returns all new temporal violation events generated by the FusionEngine since the last call.

• Returns: List[Event]: A list of discrete events (e.g. ViolationStarted, ViolationEnded).

enrol()

Requests face identity enrollment on the next video frame that contains a clear face detection.

• Returns: None

is_enrolled()

Checks whether a reference face embedding has been successfully enrolled for ArcFace identity verification.

• Returns: bool (True if enrolled, False otherwise).

update_config(toml_str)

Hot-reloads detection thresholds, cadence intervals, and fusion rules without stopping capture.

• Parameters:
  • toml_str (str): A valid TOML string containing updated configuration keys.
• Returns: None
• Raises:
  • ValueError: If the TOML string is invalid.
  • RuntimeError: If the pipeline is uninitialized.

stop()

Stops background capture and worker threads, releasing hardware camera handles and memory pools.

• Returns: None

---

Context manager support

Pipeline implements the Python context manager protocol (__enter__ and __exit__). Exiting the with block automatically calls stop().

with vigilo_stream.Pipeline() as pipe:
    pipe.start("camera:0")
    # ...