Skip to content

DL Optical Flow (f8.dl.optflow)

ONNXRuntime NeuFlowV2 dense optical flow service (flow SHM output).

  • Service class: f8.dl.optflow
  • Version: 0.0.1
  • Source directory: f8/dl/optflow
  • Tags: onnx, vision, optical_flow, flow_shm

When to Use

  • Use f8.dl.optflow when you need higher-quality motion estimation than simpler flow approaches provide.
  • It is most useful in scenes where motion vectors materially affect later logic and traditional flow is not good enough.
  • Choose it when flow quality matters more than absolute runtime cost.

Common Wiring Patterns

  • Feed it from a video source and route the result into f8.pyengine, summary logic, or visualization.
  • If cvkit.denseoptflow is already in use, compare both approaches in parallel before committing to the DL path.
  • Reserve it for places where the graph actually benefits from better motion quality.

Pitfalls / Gotchas

  • DL flow tends to be significantly more compute-heavy.
  • If the downstream logic only needs a rough activity score, this module may be overkill.
  • Validate on known sample footage before dropping it into a large live graph.

Service Reference

How to Run

pixi run -e onnx f8pydl_optflow
  • Workdir: ../../../../
  • Environment overrides: none

Typical Inputs / Outputs

  • Data inputs: none
  • Data outputs: monitor
  • Commands: none

Service State Fields

Name Access Required On Node Schema Description
inputShmName rw true true string / default= Input SHM name (e.g. shm.xxx.video).
computeEveryNFrames rw true false integer / default=2 Compute optical flow once per N new frames.
weightsDir rw true false string / default=services/f8/dl/weights Directory containing .yaml + .onnx model files. Reset to the default relative path when exporting publish JSON.
modelId rw true false string / default= Model id selected from weightsDir (ignored if modelYamlPath is set).
modelYamlPath rw true false string / default= Optional explicit model yaml path (overrides modelId). Cleared when exporting publish JSON.
ortProvider rw true false string / enum[auto, cuda, cpu] / default=auto auto prefers CUDAExecutionProvider when available.
autoDownloadWeights rw true false boolean / default=True When model file is missing, download from onnxUrl in model yaml.
availableModels ro true false array[string] List of model ids discovered from weightsDir.
loadedModel ro true false string / default= Current loaded model id/task.
ortActiveProviders ro true false string / default= JSON list of active ONNX Runtime providers for this session.
flowShmName ro true true string / default= Output flow SHM name.
flowShmFormat ro true false string / default=flow2_f16 Flow payload format. Fixed to flow2_f16.
lastError ro true false string / default= Last runtime error string (best-effort).
active rw true false boolean / default=True Service lifecycle state (activate/deactivate).
svcId ro true false string Readonly: current service instance id (svcId).

Key Fields That Matter

  • inputShmName (Input Video SHM, rw): Input SHM name (e.g. shm.xxx.video). Schema: string / default=.
  • computeEveryNFrames (Compute Every N Frames, rw): Compute optical flow once per N new frames. Schema: integer / default=2.
  • weightsDir (Weights Dir, rw): Directory containing .yaml + .onnx model files. Reset to the default relative path when exporting publish JSON. Schema: string / default=services/f8/dl/weights.
  • modelId (Model Id, rw): Model id selected from weightsDir (ignored if modelYamlPath is set). Schema: string / default=.
  • modelYamlPath (Model YAML Path, rw): Optional explicit model yaml path (overrides modelId). Cleared when exporting publish JSON. Schema: string / default=.
  • ortProvider (ONNX Runtime Provider, rw): auto prefers CUDAExecutionProvider when available. Schema: string / enum[auto, cuda, cpu] / default=auto.
  • autoDownloadWeights (Auto Download Weights, rw): When model file is missing, download from onnxUrl in model yaml. Schema: boolean / default=True.
  • availableModels (Available Models, ro): List of model ids discovered from weightsDir. Schema: array[string].

Service Commands

None

Service Data Input Ports

None

Service Data Output Ports

Name Required On Node Schema Description
monitor true false object{active, alive, cpu, error, ...} Unified runtime monitor snapshots (health/resource/perf/error).

Operators

None

  • No bundled scenario references this node yet.