Trace Visualization

Class: TraceVisualizationBlockV1

Source: inference.core.workflows.core_steps.visualizations.trace.v1.TraceVisualizationBlockV1

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

Name	Type	Description	Refs
name	str	Enter a unique identifier for this step..	❌
copy_image	bool	Enable this option to create a copy of the input image for visualization, preserving the original. Use this when stacking multiple visualizations..	✅
color_palette	str	Select a color palette for the visualised elements..	✅
palette_size	int	Specify the number of colors in the palette. This applies when using custom or Matplotlib palettes..	✅
custom_colors	List[str]	Define a list of custom colors for bounding boxes in HEX format..	✅
color_axis	str	Choose how bounding box colors are assigned..	✅
position	str	Anchor position for drawing trajectory traces relative to each detection's bounding box. Options include: CENTER (center of box), corners (TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT), edge midpoints (TOP_CENTER, CENTER_LEFT, CENTER_RIGHT, BOTTOM_CENTER), or CENTER_OF_MASS (center of mass of the object). The trace path is drawn connecting positions at this anchor point across recent frames..	✅
trace_length	int	Maximum number of historical tracked object positions to include in each trajectory trace. Controls how long the movement trail appears. Higher values create longer traces showing more movement history, while lower values create shorter traces showing only recent movement. Must be at least 1. Typical values range from 10 to 50 frames depending on the desired trail length and frame rate..	✅
thickness	int	Thickness of the trajectory trace lines in pixels. Controls how thick the path lines appear. Higher values create thicker, more visible traces, while lower values create thinner, more subtle traces. Must be at least 1. Typical values range from 1 to 5 pixels..	✅

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

Available Connections

Compatible Blocks

Check what blocks you can connect to Trace Visualization in version v1.

• inputs: Trace Visualization, Detections Consensus, Background Color Visualization, VLM As Classifier, Florence-2 Model, Reference Path Visualization, Corner Visualization, Bounding Rectangle, SAM 3, Pixel Color Count, Seg Preview, Perspective Correction, Roboflow Dataset Upload, Detection Offset, OpenAI, Model Monitoring Inference Aggregator, Image Threshold, Pixelate Visualization, Object Detection Model, Dimension Collapse, Email Notification, Label Visualization, Image Slicer, Object Detection Model, Bounding Box Visualization, Google Vision OCR, Crop Visualization, VLM As Detector, Time in Zone, Image Blur, Path Deviation, Clip Comparison, Anthropic Claude, SIFT, Triangle Visualization, Detection Event Log, Instance Segmentation Model, Gaze Detection, Stitch Images, SIFT Comparison, Heatmap Visualization, SAM 3, Time in Zone, Mask Visualization, Detections Stitch, Email Notification, Stability AI Outpainting, Time in Zone, LMM For Classification, Segment Anything 2 Model, Google Gemini, Velocity, Anthropic Claude, Google Gemini, Dynamic Zone, Template Matching, Google Gemini, Twilio SMS Notification, Keypoint Detection Model, Byte Tracker, Roboflow Dataset Upload, Stability AI Image Generation, SIFT Comparison, Polygon Zone Visualization, Distance Measurement, YOLO-World Model, Line Counter, Depth Estimation, Dot Visualization, Llama 3.2 Vision, PTZ Tracking (ONVIF).md), Dynamic Crop, Detections Merge, Contrast Equalization, Circle Visualization, Size Measurement, Slack Notification, Color Visualization, Image Slicer, Stability AI Inpainting, OpenAI, Clip Comparison, Local File Sink, Byte Tracker, Detections Transformation, JSON Parser, Relative Static Crop, Detections Filter, Instance Segmentation Model, Polygon Visualization, Ellipse Visualization, OCR Model, CogVLM, VLM As Detector, SAM 3, Stitch OCR Detections, Twilio SMS/MMS Notification, Stitch OCR Detections, Moondream2, Halo Visualization, Icon Visualization, Anthropic Claude, Image Contours, Morphological Transformation, Motion Detection, Line Counter, Blur Visualization, Detections List Roll-Up, Detections Combine, OpenAI, Polygon Visualization, CSV Formatter, Detections Stabilizer, Camera Calibration, Detections Classes Replacement, Single-Label Classification Model, Line Counter Visualization, Camera Focus, OpenAI, Webhook Sink, Image Convert Grayscale, LMM, Multi-Label Classification Model, Camera Focus, Classification Label Visualization, Model Comparison Visualization, EasyOCR, Image Preprocessing, VLM As Classifier, Grid Visualization, Background Subtraction, Halo Visualization, Overlap Filter, Keypoint Visualization, QR Code Generator, Identify Outliers, Florence-2 Model, Buffer, Text Display, Identify Changes, Roboflow Custom Metadata, Byte Tracker, Mask Area Measurement, Keypoint Detection Model, Path Deviation, Absolute Static Crop
• outputs: Trace Visualization, Contrast Equalization, CLIP Embedding Model, Circle Visualization, Background Color Visualization, SmolVLM2, Perception Encoder Embedding Model, VLM As Classifier, Color Visualization, Florence-2 Model, Image Slicer, Stability AI Inpainting, Reference Path Visualization, OpenAI, Corner Visualization, Pixel Color Count, SAM 3, Clip Comparison, Seg Preview, Relative Static Crop, Perspective Correction, Roboflow Dataset Upload, OpenAI, Instance Segmentation Model, Image Threshold, Pixelate Visualization, Object Detection Model, Multi-Label Classification Model, Polygon Visualization, Ellipse Visualization, OCR Model, CogVLM, Label Visualization, VLM As Detector, Image Slicer, Dominant Color, Object Detection Model, Bounding Box Visualization, Google Vision OCR, Crop Visualization, Barcode Detection, SAM 3, Twilio SMS/MMS Notification, VLM As Detector, Image Blur, Qwen2.5-VL, Moondream2, Halo Visualization, Clip Comparison, Anthropic Claude, Icon Visualization, SIFT, QR Code Detection, Triangle Visualization, Anthropic Claude, Image Contours, Morphological Transformation, Motion Detection, Instance Segmentation Model, Gaze Detection, Stitch Images, Heatmap Visualization, Blur Visualization, SAM 3, OpenAI, Polygon Visualization, Mask Visualization, Detections Stabilizer, Detections Stitch, Email Notification, Stability AI Outpainting, Time in Zone, Google Gemini, Segment Anything 2 Model, LMM For Classification, Camera Calibration, Anthropic Claude, Google Gemini, Single-Label Classification Model, Google Gemini, Template Matching, Line Counter Visualization, OpenAI, Camera Focus, Image Convert Grayscale, Keypoint Detection Model, LMM, Byte Tracker, Multi-Label Classification Model, Camera Focus, Model Comparison Visualization, Classification Label Visualization, Roboflow Dataset Upload, Stability AI Image Generation, EasyOCR, SIFT Comparison, Qwen3-VL, Polygon Zone Visualization, YOLO-World Model, VLM As Classifier, Background Subtraction, Halo Visualization, Buffer, Keypoint Visualization, Florence-2 Model, Depth Estimation, Text Display, Single-Label Classification Model, Dot Visualization, Llama 3.2 Vision, Dynamic Crop, Image Preprocessing, Keypoint Detection Model, Absolute Static Crop

Input and Output Bindings

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

Bindings

• input

  • image (image): The image to visualize on..
  • copy_image (boolean): Enable this option to create a copy of the input image for visualization, preserving the original. Use this when stacking multiple visualizations..
  • predictions (Union[rle_instance_segmentation_prediction, keypoint_detection_prediction, object_detection_prediction, instance_segmentation_prediction]): Model predictions to visualize..
  • color_palette (string): Select a color palette for the visualised elements..
  • palette_size (integer): Specify the number of colors in the palette. This applies when using custom or Matplotlib palettes..
  • custom_colors (list_of_values): Define a list of custom colors for bounding boxes in HEX format..
  • color_axis (string): Choose how bounding box colors are assigned..
  • position (string): Anchor position for drawing trajectory traces relative to each detection's bounding box. Options include: CENTER (center of box), corners (TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT), edge midpoints (TOP_CENTER, CENTER_LEFT, CENTER_RIGHT, BOTTOM_CENTER), or CENTER_OF_MASS (center of mass of the object). The trace path is drawn connecting positions at this anchor point across recent frames..
  • trace_length (integer): Maximum number of historical tracked object positions to include in each trajectory trace. Controls how long the movement trail appears. Higher values create longer traces showing more movement history, while lower values create shorter traces showing only recent movement. Must be at least 1. Typical values range from 10 to 50 frames depending on the desired trail length and frame rate..
  • thickness (integer): Thickness of the trajectory trace lines in pixels. Controls how thick the path lines appear. Higher values create thicker, more visible traces, while lower values create thinner, more subtle traces. Must be at least 1. Typical values range from 1 to 5 pixels..

• output

  • image (image): Image in workflows.

Example JSON definition of step Trace Visualization in version v1

{
    "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
}