Struct StageOutput 

pub struct StageOutput {
    pub detections: Option<DetectionSet>,
    pub tracks: Option<Vec<Track>>,
    pub signals: Vec<DerivedSignal>,
    pub scene_features: Vec<SceneFeature>,
    pub artifacts: TypedMetadata,
}

Output returned by a stage’s process() method.

Each field is optional — a stage only sets the fields it produces. The pipeline executor merges this into the PerceptionArtifacts accumulator.

Joint-model and direct-track-emitter patterns

A stage is not limited to producing a single artifact type. Common patterns beyond classical detection:

• Joint det+track model: set both detections and tracks in a single StageOutput. The executor merges both into the accumulator. Tracks produced this way can carry per-observation metadata via TrackObservation::metadata.
• Direct track emitter: set only tracks (leave detections as None). No intermediate DetectionSet is required. Set TrackObservation::detection_id to None since there are no upstream detections to reference.
• Richer observations: stages that produce typed artifacts (embeddings, feature maps, attention weights) can store them in TrackObservation::metadata (per-observation) or Track::metadata (per-track), or pass them as artifacts (per-frame typed metadata) for downstream stage consumption.

Fields

detections: Option<DetectionSet>

New or updated detection set.

If Some, replaces the current detection set in the accumulator. If None, the previous detection set is kept.

tracks: Option<Vec<Track>>

New or updated track set.

Some(Vec<Track>) is authoritative for this frame: it replaces the current track set in the accumulator and marks the output as authoritative. Previously-known tracks absent from this set are treated as normally ended (TrackEnded) by the temporal store.

None means this stage does not produce tracks — the previous track set is kept and authoritativeness is unchanged.

signals: Vec<DerivedSignal>

Derived signals — always appended to the accumulator.

scene_features: Vec<SceneFeature>

Scene-level features — always appended to the accumulator.

artifacts: TypedMetadata

Typed artifacts for downstream stages — merged (last-writer-wins by TypeId).

This is the primary extension seam for inter-stage communication beyond the built-in fields. Any Clone + Send + Sync + 'static value can be stored here by type, and downstream stages retrieve it from StageContext::artifacts.stage_artifacts.

Example uses:

• Feature maps or embeddings from a detector for a downstream classifier.
• Prepared multi-frame input tensors for a temporal/clip-based model.
• Confidence calibration metadata from an upstream stage.

Implementations

impl StageOutput

pub fn empty() -> Self

Create an empty stage output (no detections, tracks, signals, or artifacts).

pub fn with_detections(detections: DetectionSet) -> Self

Create a stage output containing only detections.

pub fn with_tracks(tracks: Vec<Track>) -> Self

Create a stage output containing only tracks.

pub fn with_signals(signals: Vec<DerivedSignal>) -> Self

Create a stage output containing only signals.

pub fn with_signal(signal: DerivedSignal) -> Self

Create a stage output containing a single signal.

pub fn with_scene_features(features: Vec<SceneFeature>) -> Self

Create a stage output containing only scene features.

pub fn with_artifact<T: Clone + Send + Sync + 'static>(value: T) -> Self

Create a stage output containing a single typed artifact.

This is useful for stages that produce a single custom artifact type for downstream consumption.

pub fn build() -> StageOutputBuilder

Start building a StageOutput incrementally.

Example

use nv_perception::StageOutput;

let output = StageOutput::build()
    .detections(Default::default())
    .artifact(42_u32)
    .finish();

Trait Implementations

impl Clone for StageOutput

fn clone(&self) -> StageOutput

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StageOutput

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for StageOutput

fn default() -> StageOutput

Returns the “default value” for a type.