Trace Visualization¶

Draw trajectory paths for tracked objects, visualizing their movement history by connecting recent positions with colored lines to show object movement patterns, paths, and tracking behavior over time.

How This Block Works¶

This block takes an image and tracked predictions (with tracker IDs) and draws trajectory paths showing the recent movement history of each tracked object. The block:

1. Takes an image and tracked predictions as input (predictions must include tracker_id data from a tracking block)
2. Extracts tracking IDs and position history for each tracked object
3. Determines the reference point for drawing traces based on the selected position anchor (center, corners, edges, or center of mass)
4. Applies color styling based on the selected color palette, with colors assigned by class, index, or track ID
5. Draws trajectory lines connecting the recent positions (up to trace_length positions) for each tracked object using Supervision's TraceAnnotator
6. Connects historical positions sequentially, creating path traces that show object movement direction and patterns
7. Returns an annotated image with trajectory paths overlaid on the original image

The block visualizes object tracking by drawing the path that each tracked object has taken over recent frames. Each tracked object gets a unique trace line (colored by track ID, class, or index) that connects its recent positions, creating a visual trail that shows movement direction, speed, and trajectory patterns. The trace_length parameter controls how many historical positions are included in each trace (longer traces show more movement history, shorter traces show recent movement only). This visualization requires predictions with tracker IDs from tracking blocks (like Byte Tracker), as it needs the tracking information to connect positions across frames. The traces help visualize object movement, identify tracking patterns, and understand object behavior over time.

Common Use Cases¶

• Object Trajectory Visualization: Visualize movement paths and trajectories of tracked objects to understand object behavior, movement patterns, or navigation routes for applications like vehicle tracking, pedestrian flow analysis, or object movement monitoring
• Tracking Performance Validation: Validate tracking performance by visualizing object paths to ensure tracking consistency, identify tracking errors or ID switches, or verify that objects maintain consistent trajectories
• Movement Pattern Analysis: Analyze movement patterns, speeds, or direction changes by visualizing trajectory traces to understand object behavior, detect anomalies, or identify movement trends in surveillance, security, or traffic monitoring workflows
• Path Deviation Detection: Visualize object paths to detect deviations from expected routes, identify unusual movement patterns, or monitor object trajectories for safety, security, or compliance workflows
• Real-Time Tracking Monitoring: Display trajectory traces in real-time monitoring interfaces, dashboards, or live video feeds to visualize object movement and tracking behavior as it happens
• Video Analysis and Post-Processing: Create trajectory visualizations for video analysis, post-processing workflows, or forensic analysis where understanding object movement paths and patterns is critical

Connecting to Other Blocks¶

The annotated image from this block can be connected to:

• Tracking blocks (e.g., Byte Tracker) to receive tracked predictions with tracker IDs that are required for trace visualization
• Other visualization blocks (e.g., Bounding Box Visualization, Label Visualization, Dot Visualization) to combine trajectory traces with additional annotations for comprehensive tracking visualization
• Data storage blocks (e.g., Local File Sink, CSV Formatter, Roboflow Dataset Upload) to save images with trajectory traces for documentation, reporting, or analysis
• Webhook blocks to send visualized results with trajectory traces to external systems, APIs, or web applications for display in dashboards or monitoring tools
• Notification blocks (e.g., Email Notification, Slack Notification) to send annotated images with trajectory traces as visual evidence in alerts or reports
• Video output blocks to create annotated video streams or recordings with trajectory traces for live monitoring, tracking visualization, or post-processing analysis

Type identifier¶

Use the following identifier in step "type" field: roboflow_core/trace_visualization@v1to add the block as as step in your workflow.

Properties¶

The Refs column marks possibility to parametrise the property with dynamic values available in workflow runtime. See Bindings for more info.

Runtime compatibility¶

soft — runtime hosted_serverless, dedicated_deployment; execution remote; input video

Trajectory history is stored inside a cached TraceAnnotator in process memory. With remote step execution on stateless or multi-replica HTTP runtimes, successive frames may be served by different worker processes, so traces reset or split across workers. Use local step execution in an InferencePipeline for stable cross-frame visualizations.

soft — input image

Block depends on temporal context from video or repeated-frame workflows. With a still image/photo, there is no meaningful history to track, compare, aggregate, or visualize, so the block provides little or no benefit.

Available Connections¶

Input and Output Bindings¶

The available connections depend on its binding kinds. Check what binding kinds Trace Visualization in version v1 has.

{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/trace_visualization@v1",
    "image": "$inputs.image",
    "copy_image": true,
    "predictions": "$steps.object_detection_model.predictions",
    "color_palette": "DEFAULT",
    "palette_size": 10,
    "custom_colors": [
        "#FF0000",
        "#00FF00",
        "#0000FF"
    ],
    "color_axis": "CLASS",
    "position": "CENTER",
    "trace_length": 30,
    "thickness": 1
}