🎬 SimBA visualization methods

This document consolidates all SimBA visualization methods from the scenario-based tutorials. Use it as a single reference for creating videos, plots, heatmaps, and other outputs.

Tooltips: Many menu items and dialog options in SimBA have tooltips. Hover over a label or control to see a short description.

---

📖 Overview

This document serves as a central location documenting many pose-dependent visualization methods in SimBA. SimBA provides tools to visualize pose-estimation data, classifier predictions, movement metrics, blob tracking, YOLO model results, and egocentric alignment—available in the [Visualizations] tab, [ROI] tab, [Label behavior] tab, and Tools menu.

Tab	Visualization context
[Visualizations]	Most tools: classifications, Gantt, probability, path, distance, classification heatmaps, data tables, merge
[ROI]	ROI tracking — Time in/entries per ROI; ROI features — Distances, inside/outside, directionality towards ROIs; Heatmap locations — Time per arena region; Directionality — Animals directing towards each other; Create path plots — Simple single-body-part path plots (quick, minimal options)
[Label behavior]	Visualize annotations — Extract frames where behavior was annotated as present; Visualize annotation bouts — Create per-bout videos from behavior annotations
Process Videos	Blob tracking… → Visualize blob tracking — Overlay blob shapes on videos; YOLO tracking… → Visualize YOLO model results — Overlay YOLO pose keypoints on videos
Tools menu	Visualize pose-estimation in folder — Overlay pose keypoints on videos; Create path plot — Simple single-body-part path plots (no project required); Egocentrically align pose and video — Rotate poses and videos to a fixed egocentric view; Concatenate (stack) videos → Concatenate two videos — Join two videos horizontally or vertically

Note — Data sources and output locations:
SimBA uses a project folder (the main folder you created when setting up your SimBA project; it contains subfolders such as csv, videos, logs).

Where SimBA reads input data from:

• Classifier predictions (behavior labels from your trained model) are read from the directory project_folder/csv/machine_results/.

• Videos are read from the directory project_folder/videos/.

• Pose data (tracked body-part x,y coordinates after outlier correction) are read from the directory project_folder/csv/outlier_corrected_movement_location/. Path plots, distance plots, data tables, and location heatmaps use this data.

Where SimBA saves output to: Visualization outputs from the [Visualizations] and [ROI] tabs are saved under project_folder/frames/output/ in type-specific subfolders. See Where visualization outputs are saved at the end of this document for the full list.

No project required: The following do not require a SimBA project—you choose the input and output folders yourself: Visualize blob tracking and Visualize YOLO model results (under Process Videos → Blob tracking… / YOLO tracking…); Visualize pose-estimation in folder and Egocentrically align pose and video (under Tools).

Note: SimBA also provides menu video editing tools (e.g. rotate, crop, change resolution, merge image directories) that operate on videos independent of tracking. Those tools are documented elsewhere (see Tools and Video processing).

---

🗺️ Quick reference (all visualization methods)

• Validate model: Interactive probability plot (Scenario 1)

• Validate model: Validation video (Scenario 1)

• Visualize classifications

• Visualize Gantt charts

• Visualize probability plots

• Visualize path plots

• Visualize distance plots

• Visualize classification heatmaps

• Visualize ROI tracking (ROI tab)

• Visualize ROI features (ROI tab)

• Visualize heatmap locations (ROI tab)

• Visualize directionality (ROI tab)

• Visualize ROI directionality (ROI tab)

• Visualize data tables

• Merge (concatenate) multiple videos

• Post-classification validation (Scenario 4)

• Visualize annotations (Label behavior tab)

• Visualize annotation bouts (Label behavior tab)

• Visualize pose-estimation in folder (Tools menu)

• Visualize blob tracking (Process Videos menu)

• Visualize YOLO model results (Process Videos menu)

• Egocentrically align pose and video (Tools menu)

• Create path plots (ROI tab)

• Concatenate two videos (Tools menu)

---

Validate model: Interactive probability plot (Scenario 1)

Used when validating a classifier on a single held-out video before running on experimental data. See Scenario 1 — Step 8.

Inspect frame-by-frame probabilities alongside the video. The window shows two panels: on the left is the video; on the right is the probability plot.

Prerequisites: A trained classifier (.sav file, e.g. in project_folder/models/generated_models/); one feature file from project_folder/csv/features_extracted/ that was not used for training (held-out validation file); and the matching video in project_folder/videos/. You select the feature file and model in the validation pop-up; SimBA runs the classifier on that file and displays probabilities alongside the video.

The x-axis is frame number, the y-axis is classifier probability (0–1). The main line (blue) traces predicted probability. Threshold lines (75%, 50%, 25%) appear as dashed horizontals. A red vertical line and circle mark the current frame. Double-click a point on the plot to jump the video to that frame. Keyboard shortcuts (focus the plot): ← → navigate frames, Space play/pause.

---

Validate model: Validation video (Scenario 1)

Creates a video with classifier predictions overlaid on each frame. See Scenario 1 — Step 8.

Prerequisites: A trained classifier (.sav file); one feature file from project_folder/csv/features_extracted/ (typically a held-out file not used in training); and the matching video in project_folder/videos/. You select the feature file and model in the validation pop-up; SimBA runs the classifier and generates a video with predictions overlaid on each frame.

Pop-up options:

Option	Description
FONT SIZE	Size of behavior labels and other text overlays. AUTO scales from video resolution; or pick 1–100 for fixed size. Use larger values for high-res or distant viewing.
TEXT SPACING	Space between stacked text lines (e.g. behavior name and probability). AUTO adjusts to video; or 1–100. Reduces overlap when multiple labels appear.
CIRCLE SIZE	Size of dots at each pose keypoint (nose, tail, etc.). AUTO scales with video; or 1–100. Larger circles make keypoints easier to see on small previews.
TEXT OPACITY	Transparency of text overlays (0.1–1.0). Lower values let more video show through; 1.0 is fully opaque. Useful when overlays obscure behavior.
TEXT THICKNESS	Boldness of text strokes. Thicker text (higher values) stays readable on busy or low-contrast frames.
BODY-PART PALETTE	Color scheme for pose dots—one color per animal. Examples: Pastel1, spring, Set1. Pick a palette that contrasts with your arena and animals.
SHOW POSE	TRUE = draw keypoints and skeleton on the video; FALSE = video only. Turn off for cleaner output if pose is not needed for validation.
SHOW ANIMAL NAMES	TRUE = labels like “Animal_1” near each animal; FALSE = no names. Helps when tracking identity or explaining videos to others.
SHOW BOUNDING BOX	TRUE = draw a box around each animal; FALSE = no boxes. Boxes clarify location and overlap; turn off for minimal overlay.
SHOW CONFIDENCE	TRUE = display the classifier probability (e.g. 0–100%) for each frame; FALSE = hide it. Essential for threshold tuning; optional for presentation.
CPU COUNT	Number of CPU cores for encoding. More cores speed up video creation when processing many or long videos. Use 2–4+ if available.
GANTT TYPE	None = no Gantt bar chart. Final frame only = one static Gantt at the end (faster). Video = Gantt updates per frame (shows timing over video). Use CPU count > 1 for Gantt videos.

Where output is saved: project_folder/frames/output/validation/

---

VISUALIZE CLASSIFICATIONS

Creates videos (or frame sequences) with classification overlays: the video plays while the current behavior predictions and probabilities are shown (e.g. text overlay, highlighted pose). Use this to quickly review predictions or to create presentation videos. See this example.

The pop-up offers the following options:

Prerequisites:

• Classifier predictions — You must have already run the classifier (e.g. from the Run machine model tab) so that CSVs with predictions and probabilities exist in project_folder/csv/machine_results/. Each file should match a video (same base name).

• Videos — Source videos must be in project_folder/videos/ with filenames matching the machine_results CSVs (excluding extension). SimBA overlays the classification labels on these videos.

BODY-PART VISUALIZATION THRESHOLD

Option	Description
BODY-PART PROBABILITY THRESHOLD	Minimum pose-estimation confidence (0.0–1.0) for body parts to be drawn. Use 0.0 to show all; use 1.0 to show only 100% certain detections. Body parts below this threshold are hidden.

TEXT SETTINGS

Option	Description
FONT	Font used for the behavior labels, timers, and probability text drawn on the video. Options are the fonts bundled with SimBA (in simba/assets/fonts). Pick a clean, legible font (e.g. Poppins Regular) for small overlay text.
TEXT SIZE	Size of behavior labels on the video. AUTO = SimBA picks based on video resolution; or choose 1–100.
TEXT SPACING	Space between label text and other drawn elements. AUTO = SimBA picks; or 1–100.
TEXT THICKNESS	How bold the behavior labels are. AUTO or 1–100; higher = thicker text.
CIRCLE SIZE	Size of dots drawn at each body part (pose visualization). AUTO = SimBA picks; or 1–100.
TEXT OPACITY	Transparency of labels (0.1–1.0). Lower = more transparent.
TEXT COLOR	Color of the behavior name text (e.g. White, Red).
TEXT BACKGROUND COLOR	Color of the box behind the text. Helps labels stand out on busy frames.
TRACKING COLOR PALETTE	Color scheme for pose dots (one color per animal). Options include Set1, Set2, etc.

Preview of the fonts bundled with SimBA (the FONT option) — each row renders the same sample so you can compare legibility before choosing.

TIME SEGMENT

Option	Description
PLOT SPECIFIC TIME SEGMENT	If checked, START TIME (HH:MM:SS) and END TIME (HH:MM:SS) become active. Only the selected time window of the video is used for the output (e.g. 00:01:30 to 00:05:00). Use for long videos when you only need a clip.

VISUALIZATION SETTINGS

Option	Description
CPU CORES	Number of CPU cores for parallel processing when creating multiple videos (2 to max).
USE GPU	If TRUE and a compatible NVIDIA GPU is available, use it to speed up video creation. Disabled if no compatible GPU is detected.
SHOW GANTT PLOT	NO GANTT = no bar chart. Static Gantt (final frame, faster) = one bar chart at the end. Dynamic Gantt (updated per frame) = bar chart updates as the video plays.
SHOW TRACKING (POSE)	If checked, draws tracked body parts (dots and skeleton) on the video.
SHOW ANIMAL BOUNDING BOXES	FALSE = no bounding box. axis-aligned = axis-aligned bounding box (aligned with video axes). animal-aligned = minimum rotated rectangle that aligns with the animal’s orientation. Helps see location and overlap.
SHOW CLASSIFICATION PROBABILITY	If checked, displays the model’s confidence (0–100%) for the predicted behavior on each frame.
SHOW ANIMAL NAME(S)	If checked, displays labels like “Animal_1” so you can tell animals apart.
CREATE VIDEO	If checked, generates an .mp4 with behavior labels and optional overlays.
CREATE FRAMES	If checked, saves one .png image per frame. At least one of CREATE VIDEO or CREATE FRAMES must be checked.
INCLUDE TIMERS OVERLAY	If checked, shows a timer (time or frame number) on each frame. Handy for presentations or matching other data.
ROTATE VIDEO 90°	If checked, rotates the output 90°. Use for portrait (vertical) recordings.

SINGLE VIDEO — Select one video from the VIDEO dropdown (or use the file browser) and click Create single video. MULTIPLE VIDEOS — Click Create multiple videos (N found) to process all videos that have classification results.

Where output is saved: Videos and frames are saved to the project_folder/frames/output/sklearn_results/ directory.

---

VISUALIZE GANTT CHARTS

Gantt charts are horizontal bar charts: one row per classifier, with bars indicating when each behavior occurred and for how long. Use them to compare timing and duration across behaviors or videos. They can be static (one image for the whole video) or dynamic (a video where the chart updates over time). Select at least one behavior and at least one output type (frames, videos, or last frame), then run.

Prerequisites:

• Classifier predictions — Machine results must exist in project_folder/csv/machine_results/ (one CSV per video, with prediction and probability columns for each classifier). Run the classifier first if this folder is empty.

• Videos — Optional for static/last-frame output; required if you create Gantt videos. Videos in project_folder/videos/ must match machine_results filenames so the dynamic chart can be synced to video length.

STYLE SETTINGS:

Option	Description
GANTT PLOT RESOLUTION	Size of the output image or video (width×height in pixels). Options include 640×480, 1280×720, etc. Bigger = sharper but slower and larger files.
TEXT SIZE	Font size for behavior names on the y-axis (1–25). Bigger = easier to read; too big can overlap if you have many behaviors.
TEXT ROTATION (°)	Rotation of the behavior labels on the y-axis (0–180°, step 2). Use 45° or 90° when you have many behaviors to reduce overlap.
COLOR PALETTE	Color scheme for the behavior bars (e.g. Set1, Set2, viridis). Each behavior gets its own color.
BAR OPACITY (%)	Transparency of the bars (5%–100% in 5% steps). Lower = more transparent; useful when bars overlap. Default: 85%.
X-AXIS TIME FORMAT	SECONDS = numeric (e.g. 120). HH:MM:SS = clock style (e.g. 00:02:00). Use HH:MM:SS for long videos or presentations.
FONT	Font for behavior names. AUTO = SimBA picks; or choose a font (e.g. Arial).
CPU CORES	Number of CPU cores for parallel processing of dynamic Gantt outputs (CREATE FRAMES and/or CREATE VIDEOS). Applies to both SINGLE VIDEO and MULTIPLE VIDEO(S) runs; not used when creating only the static last frame.

BEHAVIORS — Check which classifier(s) to show on the chart. At least one must be selected. Each behavior gets its own row of colored bars.

VISUALIZATION SETTINGS — Choose at least one output type:

Option	Description
CREATE FRAMES	If checked, saves one .png image per frame. Use if you need to step through frame by frame as individual files.
CREATE VIDEOS	If checked, creates a .mp4 where the Gantt chart builds over time, frame by frame.
CREATE LAST FRAME	If checked, saves one .png with the full Gantt chart for the entire video. Good for a quick summary. Default: on.
LAST FRAME AS SVG	If checked, saves the final static Gantt as .svg (vector format) instead of .png. Useful for manuscripts and scalable figures.
VIDEO (Single Video panel)	Choose which single video to process when clicking the VIDEO button under SINGLE VIDEO.

SINGLE VIDEO — Select one video from the VIDEO dropdown and click Create single video. MULTIPLE VIDEO(S) — Click Create multiple videos to process all videos that have classification results.

Where output is saved: Videos, frames, and final images are saved to the project_folder/frames/output/gantt_plots/ directory. Per-video outputs: {video_name}.mp4, {video_name}_final_image.png (or {video_name}_final_image.svg if LAST FRAME AS SVG is checked), and (if CREATE FRAMES) a subfolder {video_name}/ with frame images.

TIP: Create GIFs from frames via Tools → Generate gifs. Prefer WebM over GIF: Tools → Convert file formats → Convert videos to WEBM.

---

VISUALIZE PROBABILITY PLOTS

Line plots showing the classifier’s predicted probability (0–1) for one behavior across the video timeline. The x-axis is time (or frame), the y-axis is probability. Use these to see when the model was confident vs uncertain and to tune the discrimination threshold. Select at least one output type (frames, videos, or final frame), then run.

Prerequisites:

• Classifier predictions — CSVs in project_folder/csv/machine_results/ must contain probability columns (e.g. Probability_BtWGaNP) for the selected classifier(s). Run the classifier first if needed.

• Videos — Required only if you create probability videos (chart animates over time). Videos in project_folder/videos/ must match machine_results filenames. Not required for static or last-frame image output.

STYLE SETTINGS:

Option	Description
RESOLUTION	Size of the output image or video (width×height in pixels). Options include 640×480, 1280×720, etc.
LINE COLOR	Color of the probability line (e.g. Red, Blue, Green). Default: Red.
TEXT SIZE	Font size for axis labels (1–25). Bigger = easier to read. Default: 10.
LINE WIDTH	Thickness of the probability line (1–25). Thicker = more visible. Default: 2.
MAX Y-AXIS	Maximum value on the y-axis. AUTO = SimBA sets to 1.0 (100%). Or choose 10–100 (representing 0.1–1.0) to zoom in on lower probabilities.
LINE OPACITY	Transparency of the line (0.1–1.0 in 0.1 steps). Lower = more transparent. Default: 1.0.
SHOW THRESHOLD LINES	TRUE = draws horizontal lines at the discrimination threshold(s) so you can see when the model crosses above/below. FALSE = no threshold lines. Default: TRUE. Useful for tuning thresholds.

VISUALIZATION SETTINGS — Choose at least one output type:

Option	Description
CLASSIFIER	Select which classifier to plot (e.g. BtWGaNP). One classifier per plot.
CPU CORE COUNT	Number of CPU cores for parallel processing (1 to max). Used for multiple videos.
CREATE FRAMES	If checked, saves one .png per frame. Use for animation or to create a GIF.
CREATE VIDEOS	If checked, creates an .mp4 where the probability line builds over time.
CREATE FINAL FRAME	If checked, saves one .png with the full probability plot for the entire video. Default: on.

SINGLE VIDEO — Select one video from the VIDEO dropdown and click CREATE SINGLE VIDEO. MULTIPLE VIDEO — Click Create multiple videos to process all videos that have classification results.

Where output is saved: Videos, frames, and final images are saved to the project_folder/frames/output/probability_plots/ directory. Per-video outputs: {video_name}_{classifier_name}.mp4, {video_name}_{classifier_name}_final_frm_{datetime}.png, and (if CREATE FRAMES) a subfolder {video_name}_{classifier_name}/ with frame images.

---

VISUALIZE PATH PLOTS

Path plots show where each animal moved over time (trajectory lines) and, optionally, where classified behaviors occurred (colored markers). Use them to see spatial patterns (e.g. where in the arena behaviors tended to occur) and to combine movement with classification in one visualization. See Scenario 2 — Part 5.

Prerequisites:

• Pose data — Tracking data must be in project_folder/csv/outlier_corrected_movement_location/ (one CSV per video). SimBA uses this to draw the path of the selected body part(s). If you overlay classification, it also reads from project_folder/csv/machine_results/ (same base filenames).

• Videos — Source videos in project_folder/videos/ with filenames matching the pose (and, if used, machine_results) CSVs. Required for video output or when drawing the path on video frames.

Note — Simpler path plots: For quick, single-body-part trajectory plots with minimal options, see Create path plots (ROI tab) (under the [ROI] tab or Tools → Create path plot; the Tools version requires no project). Those tools produce simpler path plots without classification markers, multiple animals, ROI overlays, or time-segment controls.

STYLE SETTINGS

Option	Description
MAX PRIOR LINES (S)	How much of the path to show. ENTIRE VIDEO = full trajectory. Or choose 1–60 seconds so only the last N seconds of movement are drawn (shorter = “trailing” path, longer = more history).
RESOLUTION	Output image/video size. AUTO = use video resolution. Or pick a preset (e.g. 640×480, 1280×720) in WIDTH×HEIGHT format.
BACKGROUND	Solid color (e.g. White, Black). Video - static frame = use one video frame as background (then set SELECT FRAME INDEX). Video - moving frames = paths overlaid on the video as it plays.
SELECT FRAME INDEX	Shown only when BACKGROUND = Video - static frame. Frame number (1 = first frame) to use as the static background.
BACKGROUND OPACITY (%)	Only when BACKGROUND is a video option. 10–100% in steps of 10. 100% = fully opaque; lower = more transparent so paths stand out.
LINE WIDTH	Thickness of the path lines in pixels. AUTO = SimBA chooses; or 1–25.
CIRCLE SIZE	Size of the circle drawn at the current (end) position of each path. AUTO or 1–25 pixels.
FONT SIZE	Size of text (e.g. animal names). AUTO or 1–25.
FONT THICKNESS	Boldness of text. AUTO or 1–25.
SHOW ANIMAL NAMES	TRUE = label the end of each path with the animal name. FALSE = no labels.

CHOOSE BODY-PARTS

Option	Description
# ANIMALS	Number of animals (paths) to plot (1 up to your project’s animal count). Sets how many body-part/color rows appear.
BODY-PART 1, 2, …	For each animal, choose which body part to track (e.g. Nose, Center, Tail_base). Typically use Center or Nose.
COLOR/PALETTE	For each animal: a named color (e.g. Red, Blue), a palette (e.g. viridis, plasma) for a time-based color gradient along the path, or CUSTOM to enter RGB (e.g. 255,0,0).

SEGMENTS (time window)

Option	Description
Plot ONLY defined time-segment	If checked, the path is drawn only for the selected time range. Uncheck to use the full video.
START TIME	Start of the segment. Format HH:MM:SS (e.g. 00:00:10). Enabled when the time-segment checkbox is checked.
END TIME	End of the segment. Format HH:MM:SS (e.g. 00:01:30). Must be after START TIME.

CLASSIFICATION VISUALIZATION

Option	Description
INCLUDE CLASSIFICATION LOCATIONS	If checked, dots/markers are drawn on the path where the selected behaviors were detected. Requires classifier prediction data in project_folder/csv/machine_results/.
Classifier 1, 2, …	Which classifier to show (e.g. Attack, Sniffing). One row per classifier when classification is included.
Color (per classifier)	Color of the markers for that behavior.
Size (per classifier)	Marker size in pixels (1–50). Larger = more visible but can obscure the path.

ROI VISUALIZATION

Option	Description
INCLUDE ROIs	If checked, ROI shapes are drawn on the plot. Requires ROI definitions in the project. If the option is disabled, no ROI data was found.

VISUALIZATION SETTINGS (output type)

Option	Description
CPU CORE COUNT	Number of CPU cores for parallel processing when creating multiple videos (2 up to your system max). Not used for single video.
CREATE FRAMES	If checked, saves one .png per frame. Use for stepping through frame-by-frame or to build a GIF.
CREATE VIDEOS	If checked, creates an .mp4 where the path grows frame by frame over time.
CREATE LAST FRAME	If checked, saves one .png with the full path up to the last frame. Default: on.

SINGLE VIDEO — Choose a video from the Video dropdown, then click CREATE SINGLE VIDEO. MULTIPLE VIDEO — Click Create multiple videos to process all videos that have data in project_folder/csv/outlier_corrected_movement_location/ (and, if classification markers are used, also in project_folder/csv/machine_results/).

Where output is saved: project_folder/frames/output/path_plots/. For each video: {video_name}.mp4 (if CREATE VIDEOS), {video_name}_final_frame.png (if CREATE LAST FRAME), and if CREATE FRAMES is checked, a subfolder {video_name}/ containing one .png per frame.

---

VISUALIZE DISTANCE PLOTS

Line plots of the distance between pairs of body parts (or animals) over time. Use these to visualize approach/retreat, proximity, or other distance-based measures (e.g. nose-to-nose distance between two animals). See Scenario 2 — Part 5. The pop-up offers the following options:

Prerequisites:

• Pose data — Tracking data must be in project_folder/csv/outlier_corrected_movement_location/ (one CSV per video). SimBA computes distances between the body-part pairs you select from this data. Calibration (pixels per mm) must be set so distances are in cm. Run outlier correction (and video parameters) first if this folder is empty.

• Videos — Source videos in project_folder/videos/ with filenames matching the pose CSVs. Required for video or frame output so the plot can be synced to video length.

Option	Description
RESOLUTION	Output image/video size (width×height in pixels). Options include 640×480, 1280×720, etc.
FONT SIZE	Font size for axis labels (1–32).
LINE WIDTH	Thickness of the distance line (1–32).
LINE OPACITY	Transparency of the line (0.0–1.0). Lower = more transparent.
MAX Y-AXIS	Maximum value on the y-axis (cm). AUTO = SimBA sets from data; or 10–1000 in steps of 10 to fix the scale.
# DISTANCES	Number of distance curves to plot (1 to a maximum based on body parts). Each curve shows distance between one pair of body parts.
DISTANCE 1, 2, …	For each distance: select body part 1 and body part 2 (the two must differ; e.g. Nose_1 and Nose_2 for inter-animal distance) and a line color.
CREATE FRAMES	If checked, saves one .png per frame.
CREATE VIDEOS	If checked, creates .mp4 with the distance line building over time.
CREATE LAST FRAME	If checked, saves one .png with the full distance plot for the entire video. At least one of CREATE FRAMES, CREATE VIDEOS, or CREATE LAST FRAME must be checked.
CPU CORE COUNT	Number of CPU cores for parallel processing when creating multiple videos.

SINGLE VIDEO — Select one video and click Create single video. MULTIPLE VIDEO — Click Create multiple videos to process all videos that have data in project_folder/csv/outlier_corrected_movement_location/.

Where output is saved: project_folder/frames/output/line_plot/. Per-video: {video_name}.mp4 (or .avi for single-core), {video_name}_final_distances.png, and (if CREATE FRAMES) subfolder {video_name}/ with frame images.

---

VISUALIZE CLASSIFICATION HEATMAPS

Heatmaps show where in the arena (or frame) classified behaviors tended to occur. Warmer colors indicate more time or more events at that location. Use them to identify spatial hotspots (e.g. corners where attacks occurred). See this video and Scenario 2 — Part 5.

The pop-up offers the following options:

Prerequisites:

• Classifier predictions — Machine results must exist in project_folder/csv/machine_results/ (one CSV per video) with prediction and probability columns for the chosen classifier. SimBA uses the selected body part’s location when the behavior is predicted to build the spatial heatmap. Run the classifier first if needed.

• Videos — Required if HEATMAP BACKGROUND is VIDEO or VIDEO FRAME (to overlay the heatmap on video). Videos in project_folder/videos/ must match machine_results filenames. Not required for heatmap-only (NONE) output.

• Calibration — Video parameters (pixels per mm) must be set so that bin size in mm and arena coordinates are meaningful; see project_folder/logs/video_info.csv.

Option	Description
PALETTE	Colormap for the heatmap (e.g. jet, viridis, magma, plasma). See Matplotlib colormaps.
SHADING	Gouraud = smooth gradients between bins. Flat = solid colors per bin.
CLASSIFIER	Which behavior to plot. The heatmap shows where this behavior occurs in the arena over time.
BODY-PART	Body part used to pinpoint location. When the classifier detects the behavior, SimBA records where this body part is.
MAX TIME SCALE (S)	Maximum value for the color scale (seconds of behavior per bin). AUTO = SimBA uses max from data; or 5–100 in steps of 5.
BIN SIZE (MM)	Size of each spatial bin in mm (e.g. 20×20). Smaller = finer detail but noisier; larger = smoother heatmap.
MINIMUM SECONDS	Hide bins with very low behavior duration. Bins below this (seconds) appear empty. NONE = show all bins.
SHOW TIME COLOR LEGEND	If TRUE, displays the color bar explaining the heatmap scale.
LINE COLOR	Color for contour/boundary lines. NONE = no lines.
HEATMAP BACKGROUND	NONE = plain. VIDEO = overlay on full video. VIDEO FRAME = overlay on one frame. When VIDEO/VIDEO FRAME: HEATMAP OPACITY (%) (5–100). When VIDEO: SHOW KEYPOINT (draw body-part position). When VIDEO FRAME: FRAME NUMBER (0 = first).
PLOT SELECT TIME-PERIOD	If checked, only plots between START TIME and END TIME (HH:MM:SS).
CPU CORE COUNT	CPU cores for parallel processing.
CREATE FRAMES	If checked, saves one .png per frame.
CREATE VIDEOS	If checked, creates .mp4 with heatmap building over time.
CREATE LAST FRAME	If checked, saves one .png with the final cumulative heatmap. At least one output type must be checked.

SINGLE VIDEO — Select one video and click Create single heatmap. MULTIPLE VIDEO — Click Create multiple heatmaps to process all videos that have data in project_folder/csv/machine_results/.

Where output is saved: project_folder/frames/output/heatmaps_classifier_locations/. Per-video: {video_name}.mp4, {video_name}_final_frm.png, and (if CREATE FRAMES) subfolder {video_name}/ with frame images.

---

VISUALIZE ROI TRACKING (ROI tab)

Available under the [ROI] tab → VISUALIZE ROI DATA → VISUALIZE ROI TRACKING. See ROI Tutorial — Part 4.

Creates videos with ROI shapes overlaid on each frame, plus counters showing how much time animals have spent in each ROI and how many times they have entered each ROI. Use this to visualize traditional ROI metrics (time in, entries) alongside the video. Data is read from project_folder/csv/outlier_corrected_movement_location/ and ROI definitions in the project.

Prerequisites:

• ROI definitions — You must have drawn and saved at least one ROI (e.g. zones, shapes) on the videos in this project. ROI definitions are stored in the project; SimBA uses them to compute time-in and entry counts and to draw the shapes on the output video.

• Pose data — Tracking data (body-part x,y coordinates) must exist in project_folder/csv/outlier_corrected_movement_location/. Each CSV should correspond to a video in project_folder/videos/ (same base filename). If you have not yet run outlier correction and feature extraction, do that first so this folder is populated.

• Videos — Source videos must be in project_folder/videos/ with filenames matching the pose CSVs (excluding extension).

Option	Description
BODY-PART PROBABILITY THRESHOLD	Minimum pose-estimation confidence (0.0–1.0) for body parts. Frames below this are filtered. Use 0.0 to use all frames.
SHOW POSE-ESTIMATED LOCATIONS	If TRUE, draws circles at the selected body-part locations. Disables KEY-POINT SIZE and COLOR when FALSE.
SHOW ANIMAL NAMES	Display animal labels on the video.
SHOW ANIMAL BOUNDING BOXES	FALSE = no bounding box. axis-aligned = axis-aligned bounding box (aligned with video axes). animal-aligned = minimum rotated rectangle that aligns with the animal’s orientation.
SHOW CLASSIFICATION TIMERS	Controls timer format shown with ROI counters. SECONDS = numeric seconds. HH:MM:SS.SSSS = clock-style timestamp with fractional seconds.
TEXT FONT	Font used for the ROI timer/entry counters and labels drawn in the side panel. Options are the fonts bundled with SimBA (in simba/assets/fonts). Pick a clean, legible font (e.g. Poppins Regular) for small overlay text.
BORDER BACKGROUND COLOR	Color of the side panel where ROI counters are shown.
OUTSIDE ROI ZONES DATA	If TRUE, treats all areas NOT covered by an ROI as one additional ROI and shows its metrics.
NUMBER OF CPU CORES	Cores for parallel processing (1 to max).
USE GPU	Use GPU for faster processing when available.
NUMBER OF ANIMALS	How many animals to visualize (1 to project max).
BODY-PART (per animal)	Body part used as proxy for animal location (e.g. Nose, Center).
COLOR (per animal)	Color of pose circles. Shown only when SHOW POSE-ESTIMATED LOCATIONS is TRUE.
KEY-POINT SIZE (per animal)	Size of pose circles. AUTO = SimBA picks from video resolution. Shown only when pose is enabled.

Preview of the fonts bundled with SimBA (the TEXT FONT options) — each row renders the same sample so you can compare legibility before choosing.

SINGLE VIDEO — Select a video and click Create single ROI video. ALL VIDEOS — Click Create all ROI videos to process all videos that have ROI and pose data.

Where output is saved: project_folder/frames/output/ROI_analysis/. Per-video: {video_name}.mp4.

Examples:

Outside ROI zones data (treats areas not covered by an ROI as one additional zone).

---

VISUALIZE ROI FEATURES (ROI tab)

Available under the [ROI] tab → VISUALIZE ROI DATA → VISUALIZE ROI FEATURES. See ROI Tutorial — Part 5.

Creates videos showing continuous and boolean ROI features (rather than just time-in and entries): distances to ROIs, whether animals are inside ROIs, and optionally directionality towards ROIs (when the animal’s head points at an ROI). Use this to inspect ROI feature data used for machine learning or descriptive statistics.

Prerequisites:

• ROI definitions — At least one ROI must be drawn and saved in the project so SimBA can compute distances, inside/outside status, and (optionally) directionality towards ROIs.

• Pose data — Tracking data must be in project_folder/csv/outlier_corrected_movement_location/ (or equivalent), with one CSV per video. Video filenames must match.

• For directionality towards ROIs — If you want to use SHOW DIRECTIONALITY (lines or funnel), your pose configuration must include nose and left/right ear (or equivalent) body parts so SimBA can estimate head direction. If those body parts are not available, the directionality option is disabled.

Option	Description
SHOW DIRECTIONALITY	FALSE = no direction overlay. LINES = lines from head to ROI when directing. FUNNEL = funnel-style polygon. Disabled when directionality is not available.
BORDER COLOR	Color of the side panel / border.
TEXT FONT	Font used for the ROI feature text (in-zone status, distances, directionality) drawn in the side panel. Options are the fonts bundled with SimBA (in simba/assets/fonts). Pick a clean, legible font (e.g. Poppins Regular) for small overlay text.
SHOW POSE	Draw pose-estimated body parts on the video.
SHOW ROI CENTERS	Mark the center of each ROI with a circle.
SHOW ROI EAR TAGS	Show ear-tag points of each ROI shape.
SHOW ANIMAL NAMES	Display animal labels.
SHOW ANIMAL BOUNDING BOXES	Draw no box (FALSE), axis-aligned boxes, or animal-aligned boxes around each animal.
USE GPU	Use GPU for faster processing when available.
CPU CORES	Number of cores for multiprocessing.
PROBABILITY THRESHOLD	Filter body-part locations below this confidence (0.0–1.0).
NUMBER OF ANIMALS	How many animals to visualize.
BODY-PART (per animal)	Body part used as proxy for animal location.

Preview of the fonts bundled with SimBA (the TEXT FONT options) — each row renders the same sample so you can compare legibility before choosing.

SINGLE VIDEO — Select a video and click Visualize ROI features: single video. ALL VIDEOS — Click Visualize ROI features: all X video(s) to process all videos with ROI data.

Where output is saved: project_folder/frames/output/ROI_features/. Per-video: {video_name}.mp4.

---

VISUALIZE HEATMAP LOCATIONS (ROI tab)

Available under the [ROI] tab → Create heatmaps. See ROI Tutorial — Part 6: Heatmaps.

Location heatmaps visualize time spent in different regions of the arena (colour-coded by duration). Unlike classification heatmaps, this tool does not depend on user-drawn ROIs or classifier predictions: it divides the arena into square bins and shows where the selected body part spent the most time. Use it to explore spatial occupancy patterns (e.g. corners, center, edges). For an example in video format, see the SimBA YouTube playlist.

Prerequisites:

• Pose data — Tracking data (body-part coordinates) must be in project_folder/csv/outlier_corrected_movement_location/, with one CSV per video. SimBA uses this data to compute where the selected body part (e.g. Center, Nose) was in each frame and then sums time per spatial bin. Video and CSV base filenames must match.

• Videos — Source videos in project_folder/videos/ are required if you choose HEATMAP BACKGROUND = VIDEO or VIDEO FRAME (to overlay the heatmap on video). Not required for NONE (heatmap only).

• Calibration — Video parameters (pixels per mm, resolution) must be set so that bin size in mm and spatial coordinates are meaningful; see the project’s project_folder/logs/video_info.csv.

Option	Description
PALETTE	Colormap for the heatmap (e.g. jet, viridis, magma, plasma). See Matplotlib colormaps.
SHADING	Gouraud = smooth gradients between bins. Flat = solid colors per bin.
BODY-PART	Single body part used to represent location. SimBA generates heatmaps based on where this body part spends time. Typically use Center (center of mass) or Nose.
MAX TIME SCALE (S)	Maximum value for the color scale (seconds per bin). AUTO = SimBA computes the max time spent in any bin from the data. Or choose 5–100 in steps of 5.
BIN SIZE (MM)	Size of each square region in mm (e.g. 20×20). Smaller = finer detail but noisier; larger = coarser but smoother heatmaps.
SHOW TIME COLOR LEGEND	If TRUE, displays the color bar explaining the heatmap scale (seconds spent in each area).
MINIMUM SECONDS	Hide bins with very low occupancy. Bins below this value (seconds) appear empty. NONE = show all bins.
LINE COLOR	Color for contour/boundary lines between bins. NONE = no lines.
HEATMAP BACKGROUND	NONE = plain heatmap. VIDEO = overlay on full video. VIDEO FRAME = overlay on one chosen frame. When VIDEO/VIDEO FRAME: HEATMAP OPACITY (%) (5–100). When VIDEO: SHOW KEYPOINT (draw body-part position). When VIDEO FRAME: FRAME NUMBER (0 = first).
PLOT SELECT TIME-PERIOD	If checked, only plots between START TIME and END TIME (HH:MM:SS).
CPU CORES	Number of CPU cores for parallel processing when creating multiple heatmaps.
CREATE FRAMES	If checked, saves one .png per frame. Warning: for long videos this creates many files.
CREATE VIDEOS	If checked, creates .mp4 with heatmap building over time.
CREATE LAST FRAME	If checked, saves one .png with the cumulative heatmap for the entire video. Default: on.

SINGLE VIDEO — Select one video from the VIDEO dropdown and click Create single heatmap. MULTIPLE VIDEO — Click Create multiple heatmaps to process all videos that have data in project_folder/csv/outlier_corrected_movement_location/.

Where output is saved: project_folder/frames/output/heatmaps_locations/. Per-video: {video_name}.mp4, {video_name}_final_frm.png (or similar), and (if CREATE FRAMES) subfolder {video_name}/ with frame images.

---

VISUALIZE DIRECTIONALITY (ROI tab)

Available under the [ROI] tab. SimBA uses nose and ear coordinates to estimate head direction (line of sight). This is a proxy for gaze, not actual gaze tracking. Requires nose, left ear, and right ear (or equivalent) body parts. See ROI Tutorial — Part 3–5 and Directionality between animals.

Directionality towards ROIs — Use Visualize ROI Features (SHOW DIRECTIONALITY = LINES or FUNNEL) to visualize when animals are directing towards user-defined ROIs.

The tools below visualize directionality between animals, not towards ROIs:

Visualize directionality between animals

[ROI] tab → OTHER ANALYSES / VISUALIZATIONS → VISUALIZE DIRECTIONALITY BETWEEN ANIMALS

Creates videos showing when each animal is directing towards other animals (not ROIs). Draws lines or polyfills from the observer’s eye to the observed body parts.

Prerequisites:

• At least two animals — The directionality analysis and visualization are defined for one animal directing towards another; your project and pose data must include at least two tracked animals.

• Nose and ear body parts — The pose configuration must include nose, left ear, and right ear (or equivalent) for each animal so SimBA can estimate head direction (line of sight). These are used to compute when one animal is “directing” towards the other.

• Directionality data already computed — You must run ANALYZE DIRECTIONALITY BETWEEN ANIMALS (in the [ROI] tab) before using this visualization. That step writes directionality dataframes to project_folder/logs/directionality_dataframes/. This tool reads from that folder; if it is empty or missing, the visualization will have nothing to display.

Option	Description
LEFT EAR / RIGHT EAR / NOSE	Body parts used to estimate head direction. Must be unique.
SHOW POSE TRACKING	Draw pose-estimated body parts.
HIGHLIGHT DIRECTION END-POINTS	Emphasize observed body parts with salient circles.
SHOW ANIMAL NAMES	Display animal labels.
DIRECTION COLOR	Color of direction lines. Random = auto-assigned.
POSE CIRCLE SIZE	Size of pose dots. AUTO or 1–10.
LINE THICKNESS	Thickness of direction lines. AUTO or 1–10.
LINE OPACITY	Transparency of direction lines (0.1–1.0).
CPU core count	Cores for multiprocessing.

Where output is saved: project_folder/frames/output/Directing_animals/

---

VISUALIZE ROI DIRECTIONALITY (ROI tab)

Available under the [ROI] tab → OTHER ANALYSES / VISUALIZATIONS → VISUALIZE ROI DIRECTIONALITY.

Creates videos showing when each animal is directing towards user-defined ROIs. Draws lines or funnels from the animal’s eye midpoint to the ROI when the animal is directing towards it. A side panel displays the directing boolean (True/False) and cumulative total directing time for each animal-ROI combination, updating in real time per frame.

Prerequisites:

• Pose data — Tracking data in project_folder/csv/outlier_corrected_movement_location/ (one file per video).

• ROI definitions — ROIs must be drawn for the video(s) you want to visualize. SimBA reads ROI definitions from project_folder/logs/measures/ROI_definitions.h5.

• Nose and ear body parts — The pose configuration must include nose, left ear, and right ear (or equivalent) body parts so SimBA can estimate head direction.

Option	Description
LEFT EAR / RIGHT EAR / NOSE	Body parts used to estimate head direction. SimBA auto-guesses from your body-part names; adjust if needed. All three must be unique.
DIRECTION STYLE	Style of the directing indicator. LINES draws a straight line from the eye midpoint to the ROI center. FUNNEL draws a filled triangle from the eye midpoint to the ROI boundary edges.
BORDER COLOR	Background color of the text panel on the right side of the video.
DIRECTION COLOR	Color of the directing line or funnel.
SHOW POSE	If TRUE, draw pose-estimation keypoints on the video.
SHOW ROI CENTERS	If TRUE, draw the center point of each ROI.
SHOW ANIMAL NAMES	If TRUE, display animal name labels on the video.
CIRCLE SIZE	Size of pose keypoint circles. AUTO computes an optimal size based on video resolution.
DIRECTION LINE THICKNESS	Thickness of the directing line. AUTO computes an optimal thickness based on video resolution.
USE GPU	If TRUE, use GPU acceleration for video concatenation (requires compatible hardware).
CPU CORES	Number of CPU cores for multiprocessing.
Visualize ONLY defined time-segment	If checked, only the specified time window (start/end in HH:MM:SS) is visualized instead of the full video.

Where output is saved: project_folder/frames/output/ROI_directing_visualizations/

To analyze directionality towards ROIs (aggregate statistics, detailed tables), see ROI Tutorial — Directionality towards ROIs.

---

VISUALIZE DATA TABLES

Creates videos or frames where a table overlays the video, showing movement metrics (total distance traveled, current velocity) for selected body parts, updating in real time as the video plays. Useful for presentations or for checking that movement calculations look correct. See Scenario 2 — Part 5. The pop-up offers the following options:

Prerequisites:

• Pose data — Tracking data must be in project_folder/csv/outlier_corrected_movement_location/ (one CSV per video). SimBA computes total distance and velocity from the selected body part’s coordinates; calibration (pixels per mm) must be set so values are in cm and cm/s. Run outlier correction and video parameters first if this folder is empty.

• Videos — Source videos in project_folder/videos/ with filenames matching the pose CSVs. Required so the table overlay can be rendered on the correct video and synced to frame count.

Option	Description
RESOLUTION	Output image/video size (width×height in pixels). Options include 640×480, 1280×720, etc.
DECIMAL ACCURACY	Number of decimal places for movement and velocity values (0–10).
BACKGROUND COLOR	Background color of the table (e.g. White, Black). Must differ from header and text colors.
HEADER COLOR	Color of the header labels (e.g. ANIMAL, TOTAL MOVEMENT, CURRENT VELOCITY). Must differ from background.
FONT THICKNESS	Thickness of the table text (0–10). Higher = bolder.
# ANIMALS	Number of body parts (rows) to show in the table. Each row displays one body part.
BODY-PART (per row)	Which body part to track (e.g. Nose, Center, Tail_base). Must be unique per row. COLOR — Text color for that row. Must differ from background.
CREATE FRAMES	If checked, saves one .png per frame of the table overlay.
CREATE VIDEOS	If checked, creates .mp4 with the table updating as the video plays. At least one of CREATE FRAMES or CREATE VIDEOS must be checked.

Metrics displayed: For each body part, the table shows Total movement (cm) (cumulative distance up to the current frame) and Velocity (cm/s) (current frame).

SINGLE VIDEO — Select one video and click Create single video. MULTIPLE VIDEOS — Click Create multiple videos to process all videos that have data in project_folder/csv/outlier_corrected_movement_location/.

Where output is saved: project_folder/frames/output/live_data_table/. Per-video: {video_name}.mp4, and (if CREATE FRAMES) subfolder {video_name}/ with frame images.

---

MERGE (CONCATENATE) MULTIPLE VIDEOS

The merge (concatenate) multiple videos tool combines several videos into one output video by arranging them in a single multi-panel layout. Each input video becomes one panel; they are not played one after another in time, but shown side by side (or in a grid) in every frame. Typical uses include putting the original video, a classification-overlay video, a Gantt chart, and a probability or path plot into one view for figures, slides, or quick visual comparison.

Prerequisites:

• Two or more video files — You must have the videos you want to merge already on disk (e.g. from SimBA visualizations: classification video, Gantt video, path plot, probability plot, or any other exported .mp4/.avi). Each file is selected via VIDEO 1, VIDEO 2, etc. No SimBA project is required when using Tools → Concatenate multiple videos; when using the [Visualizations] tab, the project’s output folder is the typical source.

How to open it: In the [Visualizations] tab, click MERGE FRAMES. You can also use the Tools menu → Concatenate multiple videos. See Scenario 2 — Part 5.

What you set:

• Number of videos — Choose how many videos to merge (2–20). The window then shows one file selector per video (VIDEO 1, VIDEO 2, …). Order of the list determines panel position (e.g. Video 1 is top-left or first, depending on join type).

• Join type — Layout of the panels:

  • HORIZONTAL — One row; videos side by side.

  • VERTICAL — One column; videos stacked.

  • MOSAIC — Two rows of panels (videos split across the two rows). With only 2 videos, this behaves like VERTICAL.

  • MIXED MOSAIC — One large panel (Video 1) and the rest in a two-row mosaic. Requires at least 3 videos.

• Resolution — WIDTH and HEIGHT (in pixels) of each panel. Options include 480, 640, 1280, 1920, 2560. For MIXED MOSAIC, this size applies to the smaller panels.

• USE GPU — If TRUE, a compatible GPU is used to speed up encoding when available.

• OUT VIDEO QUALITY — 10–100; higher values give better quality and larger files (default 60).

Click RUN to generate the merged video.

Where output is saved: project_folder/frames/output/merged/ as merged_video_YYYYMMDDHHMMSS.mp4 (date and time with no separator, e.g. merged_video_20250212143055.mp4). When the tool is run without a project (Tools → Concatenate multiple videos), the file is saved in the same directory as the first selected video.

https://github.com/user-attachments/assets/b84364ee-3e85-4630-8955-070491f74f00

---

Post-classification validation (Scenario 4)

Generates bout-level clips for reviewing predictions and spotting false positives. See Scenario 4 — Part 7.

Creates a video for each CSV with concatenated clips of all bouts of the target behavior. Each bout is extracted and concatenated into one video so you can quickly review predictions and spot false positives.

Prerequisites:

• Classifier predictions — Machine results must exist in project_folder/csv/machine_results/ (one CSV per video) with prediction columns for the target behavior. Run the classifier first so these files exist.

• Videos — Source videos must be in project_folder/videos/ with filenames matching the machine_results CSVs. SimBA uses them to extract the bout clips and concatenate them into the validation video.

Options:

• Seconds — Duration added before and after each event (in seconds). Use to add context around each bout.

• Target — Behavior to include (e.g. Attack, Sniffing). Select the classifier you want to validate.

Where output is saved: project_folder/frames/output/classifier_validation/. Each file: {videoname}_{target}_{bout_count}.mp4.

---

VISUALIZE ANNOTATIONS (Label behavior tab)

Available under the [Label behavior] tab → LABELLING TOOLS → VISUALIZE ANNOTATIONS. See Label behavior — Visualization.

Extracts and saves frames where behavior was annotated as present (behavior-present frames). Use this to review your annotation quality, create training datasets, or verify that labels match the intended behavior. Each output image corresponds to one annotated behavior-present frame.

Prerequisites:

• Behavior annotations — The project must contain labeled behavior data: either from the SimBA [Label behavior] tab (frame or bout annotations) or from imported third-party annotations (e.g. BORIS, Solomon Coder). SimBA expects these to be stored in CSV files that include both pose/features and the behavior columns.

• Data files in the correct folder — Annotated CSVs must be in project_folder/csv/targets_inserted/ (or the project’s equivalent targets folder). Each file typically corresponds to one video and includes columns that indicate for each frame (or bout) whether the behavior was present. If you have not yet labeled or appended annotations, do that first so this folder is populated with the classifier(s) you want to visualize.

Option	Description
CHOOSE CLASSIFIERS	Tick which classifier(s) to extract. At least one must be selected. Each classifier gets its own subfolder.
DOWN-SAMPLE IMAGES	None = full resolution. 2x, 3x, 4x, 5x = reduce image dimensions by that factor.
IMAGE FORMAT	Output format: png, jpg, or webp.
GREYSCALE IMAGES	If TRUE, converts frames to grayscale.
VIDEO	ALL VIDEOS = process all annotated videos. Or select one video.

RUN — Click RUN to extract the frames. Progress appears in the main SimBA terminal.

Where output is saved: project_folder/frames/output/annotated_frames/. Hierarchy: {video_name}/{classifier_name}/{frame_number}.png. For example, My_video/Attack/28.png is frame 28 of My_video annotated as Attack present.

---

VISUALIZE ANNOTATION BOUTS (Label behavior tab)

Available under the [Label behavior] tab → LABELLING TOOLS → VISUALIZE ANNOTATION BOUTS.

Creates one video clip per annotated bout for selected classifier(s). Each clip can include optional pre/post context windows and overlays such as pose, animal names, bounding boxes, and timer text.

Prerequisites:

• Behavior annotations — Annotated target files must exist in project_folder/csv/targets_inserted/ and contain the selected classifier columns.

• Videos — Matching source videos must exist in project_folder/videos/ (same base filename as target file).

Option	Description
VIDEO	Process one selected video or ALL VIDEOS with annotation target files.
PRE-BOUT WINDOW (SECONDS)	Integer seconds to include before each detected annotation bout.
POST-BOUT WINDOW (SECONDS)	Integer seconds to include after each detected annotation bout.
TEXT SIZE / SPACING / THICKNESS	Overlay text styling. AUTO lets SimBA adapt values to video size.
CIRCLE SIZE	Size of pose keypoint circles. AUTO scales by resolution.
TEXT OPACITY / TEXT COLOR / TEXT BG COLOR	Overlay readability controls for timer and bout labels.
TRACKING COLOR PALETTE	Color palette for pose/body-part overlays.
CPU CORES	Number of CPU cores for multiprocessing clip rendering.
USE GPU	Uses GPU-enabled path when available (if supported).
SHOW ANIMAL BBOX	FALSE, axis-aligned, or animal-aligned boxes.
SHOW VIDEO TIMER	FALSE, seconds, or hh:mm:ss.ssss timer overlay format.
SHOW TRACKING (POSE)	Draw pose keypoints on the output clips.
SHOW ANIMAL NAME(S)	Draw animal labels near tracked keypoints.

Where output is saved: project_folder/frames/output/annotated_frames/videos/. Filenames follow {video_name}_{classifier}_{bout_id}.mp4.

---

VISUALIZE POSE-ESTIMATION IN FOLDER (Tools menu)

Available under Tools → Visualize pose-estimation in folder…. See Tools: Visualize pose estimation in folder.

Renders videos with pose keypoints overlaid on each frame. Use this to verify tracking quality after interpolation, smoothing, or outlier correction—or to inspect any folder of pose CSV/parquet files. The tool does not require a SimBA project: it works on any folder containing compatible tracking files.

Typical use: After importing and preprocessing pose data, select the folder (e.g. project_folder/csv/outlier_corrected_movement_location/ or project_folder/csv/input/) and choose a save directory; SimBA renders one video per tracking file.

Option	Description
KEY-POINT SIZES	Size of pose circles (AUTO, or 1–100). AUTO derives size from video resolution.
VIDEO SECTION (SECONDS)	ENTIRE VIDEO(S) = full video. Or 10, 20, … 200 to render only the first N seconds per video.
CPU COUNT	Cores for multiprocessing (2 to max minus one). More cores = faster but higher RAM/GPU use.
USE GPU	If TRUE, uses GPU for concatenation when multiprocessing.
INCLUDE BOUNDING BOX	FALSE = no bounding box. AXIS-ALIGNED = axis-aligned bounding box (aligned with video axes). ANIMAL-ALIGNED = minimum rotated rectangle that aligns with the animal’s orientation.
SHOW CENTER OF MASS	FALSE = no center dot. Or choose a color to draw the center of mass per animal (useful for verifying movement analysis).
SAVE DIRECTORY	Folder where output videos are saved. User-selectable (e.g. desktop or a project subfolder).
NUMBER OF ANIMALS	Number of tracked individuals (1–16). Must match the pose data.
ANIMAL n COLOR PALETTE	Color scheme per animal. AUTO = SimBA picks; or choose a palette (e.g. Set1, viridis).
SELECT DATA FILE (CSV/PARQUET)	Run on a single file. Pick a CSV or parquet tracking file and click RUN.
SELECT DATA DIRECTORY (CSV/PARQUET)	Batch run on all supported files in a folder. Pick a directory (e.g. project_folder/csv/outlier_corrected_movement_location/) and click RUN.

Where output is saved: The SAVE DIRECTORY you choose. Each input file produces one output video (e.g. {filename}.mp4).

---

VISUALIZE BLOB TRACKING (Process Videos menu)

Available under Process Videos → Blob tracking… → Visualize blob tracking. See Blob tracking and Blob tracking visualization notebook.

Renders videos with blob-tracking overlays: convex hulls, anterior (nose), posterior (tail), center, and optional left/right body-part points. Blob tracking uses background subtraction (no pose-estimation model) to detect animals and infer body parts from the blob shape. Use this to verify blob detection quality or create presentation videos.

Prerequisites:

• Blob tracking CSV files — You must have already run SimBA’s blob tracking pipeline (background subtraction, convex hull, anterior/posterior/center inference) so that CSV files exist with blob-derived body-part or hull data. The format and columns must match what this visualization tool expects (see Blob tracking).

• Source videos — The original videos that were used to generate the blob tracking CSVs. Each CSV filename (without extension) must match a video filename (without extension) so SimBA can overlay the blob shapes on the correct video.

• No SimBA project required — This tool runs from the Process Videos menu and does not require a SimBA project. You select the data directory (blob CSVs), video directory, and save directory manually.

Option	Description
VIDEO DIRECTORY	Folder containing source videos. Filenames must match CSV filenames (without extension).
DATA DIRECTORY	Folder containing blob tracking CSV files.
SAVE DIRECTORY	Where output videos are saved.
CPU CORE COUNT	Number of CPU cores for processing (1 to max).
SHAPE OPACITY	Opacity of drawn shapes (0.1–1.0). Lower = more transparent.
BACKGROUND OPACITY	Opacity of background video frames (0.1–1.0).
KEY-POINT SIZES	Size of circles for point markers. AUTO or 1–20.
HULL COLOR	Color for convex hull. NONE = disable hull.
ANTERIOR COLOR	Color for anterior (nose) point. NONE = disable.
POSTERIOR COLOR	Color for posterior (tail) point. NONE = disable.
CENTER COLOR	Color for center point. NONE = disable.
LEFT COLOR	Color for left body-part point. NONE = disable.
RIGHT COLOR	Color for right body-part point. NONE = disable.

RUN — Click RUN to generate annotated videos for all matching CSV/video pairs in the selected directories.

Where output is saved: The SAVE DIRECTORY you choose.

---

VISUALIZE YOLO MODEL RESULTS (Process Videos menu)

Available under Process Videos → YOLO tracking… → Visualize YOLO model results. See YOLO Pose Estimation Visualization.

Renders videos with YOLO pose-estimation overlays: keypoints, skeleton lines, optional bounding boxes, and (when PLOT TRACKS = TRUE) track IDs and consistent colors per animal. Use this to verify YOLO inference results or create presentation videos.

Prerequisites:

• YOLO pose CSV files — You must have run Predict with YOLO model (under Process Videos → YOLO tracking…) so that pose-estimation results are saved as CSV files. Each CSV contains keypoint coordinates (and optionally track IDs) per frame. The visualization reads these files and draws keypoints (and skeleton/tracks if selected) on the video.

• Source videos — The videos that were used as input to the YOLO prediction step. CSV and video base filenames must match (excluding extension) so each CSV is overlaid on the correct video.

• No SimBA project required — This tool runs from the Process Videos menu. You choose the data path/directory (YOLO CSVs), video path/directory, and save directory yourself; a SimBA project folder is not required.

Option	Description
SAVE DIRECTORY	Where annotated output videos are saved.
PLOT TRACKS	TRUE = use YOLOPoseTrackVisualizer (track IDs, consistent colors per animal; for multi-animal). FALSE = use YOLOPoseVisualizer (keypoints only; faster for single-animal).
CPU CORE COUNT	Number of CPU cores (1 to max minus one).
SHOW BOUNDING BOXES	If TRUE, draws boxes around each detected animal.
VERBOSE	If TRUE, prints progress to terminal.
THRESHOLD	Confidence threshold (0.0–1.0). Only detections above this are drawn. 0.0 = show all.
LINE THICKNESS	Thickness of skeleton lines. AUTO or 1–20.
CIRCLE SIZE	Radius of keypoint circles. AUTO or 1–20.
DATA PATH (CSV)	Single-file mode: path to one YOLO pose CSV.
VIDEO PATH	Single-file mode: path to the matching video.
DATA DIRECTORY	Batch mode: folder of YOLO pose CSV files.
VIDEO DIRECTORY	Batch mode: folder of source videos. CSV and video filenames must match (excluding extension).

CREATE SINGLE VIDEO — Use DATA PATH and VIDEO PATH, then click to process one video. CREATE MULTIPLE VIDEOS — Use DATA DIRECTORY and VIDEO DIRECTORY, then click to process all matching pairs.

Where output is saved: The SAVE DIRECTORY you choose. Output videos have the same names as the input videos with pose overlays.

---

EGOCENTRICALLY ALIGN POSE AND VIDEO (Tools menu)

Available under Tools → Egocentrically align pose and video. See Egocentric alignment notebook.

Rotates and translates pose data and video frames so one animal is centered and facing a fixed direction. Use for egocentric analysis (e.g. Straub tail classification) or visualization where orientation should be standardized. The center anchor body-part is placed at the center of each frame; the direction anchor defines the animal’s facing direction, which is rotated to the chosen direction (0–360°).

Prerequisites:

• Pose-estimation CSV files — A folder containing pose CSV (or parquet) files with body-part x,y coordinates (and optionally likelihood) per frame. For example, use project_folder/csv/outlier_corrected_movement_location/ if you have already run outlier correction in a SimBA project, or any other folder with compatible tracking files.

• Matching source videos — The videos that correspond to each tracking file. Each CSV filename (without extension) must match exactly one video filename (without extension) so SimBA can render the pose overlay on the correct video. Resolution and frame count should match the tracking data.

• No SimBA project required — This tool runs from the Tools menu. You select the data directory, video directory (or single file), and save directory yourself.

Option	Description
DATA DIRECTORY	Folder containing pose CSV files.
VIDEO DIRECTORY	Folder containing source videos.
SAVE DIRECTORY	Where aligned pose CSVs and rotated videos are saved. Cannot be the same as data or video directories.
CENTER ANCHOR	Body-part placed at the center of each frame (e.g. center of mass, tail base).
DIRECTION ANCHOR	Body-part that defines the animal’s facing direction (e.g. nose). Placed at DIRECTION degrees relative to center.
DIRECTION	Target angle in degrees (0–360). E.g. 0 = direction anchor to the east (right); 180 = to the west (left).
ROTATION COLOR	Fill color for pixels revealed when the frame is rotated (e.g. Black).
CPU COUNT	Number of CPU cores for video rotation.
USE GPU	If TRUE, uses GPU for rotation (requires NVIDIA GPU).

RUN — Processes all matching CSV/video pairs. Outputs: (1) aligned pose CSV files, (2) rotated videos with the subject centered and facing the specified direction.

Where output is saved: The SAVE DIRECTORY you choose. Aligned CSVs and rotated videos keep the same filenames as inputs.

---

CREATE PATH PLOTS (ROI tab)

*Available under the [ROI] tab → CREATE PATH PLOTS. Also under Tools → Create path plot (no project required).

Creates a simple path plot for one body part in one video. Unlike the full path plot in the Visualizations tab, this tool has minimal options—ideal for a quick trajectory visualization without classification markers, multiple animals, ROI overlays, or time segments. For more complex path plots (multiple animals, classifiers, ROI overlays, batch processing), use CREATE PATH PLOTS in the [Visualizations] tab.

Prerequisites:

• Pose data — When run from the [ROI] tab, pose data must be in project_folder/csv/outlier_corrected_movement_location/ (one CSV per video). The project must have video parameters set and outlier correction already run. When run from Tools → Create path plot, you choose the data folder yourself and no project is required.

• Videos — When using the ROI tab, source videos in project_folder/videos/ must match the pose CSVs. Required for video output (path building over time); for last-frame-only image output, the path is drawn from the pose data and video is optional depending on implementation.

Option	Description
VIDEO	Which video to plot. Dropdown lists videos that have data in the directory project_folder/csv/outlier_corrected_movement_location/.
BODY-PART	Single body part to trace (e.g. Nose, Center, Tail_base).
BACKGROUND COLOR	Background color (e.g. White, Black).
LINE COLOR	Color of the path line (e.g. Red, Blue).
LINE THICKNESS	1–10 pixels.
CIRCLE SIZE	Size of circles marking points along the path (1–10).
LAST FRAME ONLY	TRUE = save one .png with the full path. FALSE = save an .mp4 where the path builds frame by frame.

RUN — Click RUN to generate the path plot.

Where output is saved: project_folder/frames/output/path_plots/. Output: {video_name}_simple_path_plot.png (if LAST FRAME ONLY) or {video_name}_simple_path_plot.mp4.

---

CONCATENATE TWO VIDEOS (Tools menu)

Available under Tools → Concatenate (stack) videos… → Concatenate two videos. See Tools: Concatenate two videos.

Joins two videos into a single output video, either horizontally (side by side) or vertically (stacked). Unlike Concatenate multiple videos (which arranges 2–20 videos in a multi-panel mosaic), this tool produces a simple two-panel layout. No SimBA project is required.

Option	Description
FIRST VIDEO PATH	Path to the first video file.
SECOND VIDEO PATH	Path to the second video file.
RESOLUTION (ASPECT RATIO RETAINED)	VIDEO 1 = use first video’s resolution; VIDEO 2 = use second video’s resolution; or a fixed height/width (240, 320, 480, 640, 720, 800, 960, 1120, 1080, 1980). For horizontal concat, this sets height; for vertical, it sets width. Aspect ratio is preserved.
OUTPUT VIDEO QUALITY	10–100. Higher = better quality, larger file (default 60).
USE GPU	If TRUE, uses NVIDIA GPU for faster encoding when available.
HORIZONTAL concatenation	Places the two videos side by side in one row.
VERTICAL concatenation	Stacks the two videos in one column.

RUN — Click RUN to create the concatenated video.

Where output is saved: Same directory as the first video. Filename: {video1}_{video2}_concat.mp4 (e.g. Video1_Video2_concat.mp4).

---

➡️ Related tutorials

• Scenario 1 — Train classifier, validate on single video (interactive probability plot, validation video)

• Scenario 2 — Run classifier on experimental data, full visualization set (Part 5)

• Scenario 4 — Add new data to project, post-classification validation (Part 6–7)

• ROI Tutorial — ROI analysis, directionality towards ROIs (Part 3–5), location heatmaps (Part 6)

• Directionality between animals — Full tutorial for directionality between animals

• Label behavior — Labelling tools, including visualize annotations

• Tools — Visualize pose-estimation in folder, concatenate two videos, and other tools

• Blob tracking — Blob detection, tracking, and visualization

• YOLO pose visualization — Visualize YOLO model results

• Egocentric alignment notebook — Egocentrically align pose and video

---

📚 API Reference

Visualization	Class or module	Read the Docs
Classification videos	PlotSklearnResultsSingleCore, PlotSklearnResultsMultiProcess	simba.plotting
Validation video	ValidateModelOneVideo, ValidateModelOneVideoMultiprocess	simba.plotting
Gantt charts	GanttCreatorSingleProcess, GanttCreatorMultiprocess	simba.plotting
Probability plots	TresholdPlotCreatorSingleProcess, TresholdPlotCreatorMultiprocess	simba.plotting
Path plots	PathPlotterSingleCore, PathPlotterMulticore	simba.plotting
Distance plots	DistancePlotterSingleCore, DistancePlotterMultiCore	simba.plotting
Classification heatmaps	HeatMapperClfSingleCore, HeatMapperClfMultiprocess	simba.plotting
ROI tracking (ROI tab)	ROIPlotter, ROIPlotMultiprocess	simba.plotting
ROI features (ROI tab)	ROIfeatureVisualizer, ROIfeatureVisualizerMultiprocess	simba.plotting
Location heatmaps (ROI tab)	HeatmapperLocationSingleCore, HeatMapperLocationMultiprocess	simba.plotting
Directionality between animals	DirectingOtherAnimalsVisualizer, DirectingOtherAnimalsVisualizerMultiprocess	simba.plotting
Data tables	DataPlotter	simba.plotting
Merge videos	FrameMergererFFmpeg, ConcatenatorPopUp	simba.plotting, simba.ui
Annotated frames (Label behavior tab)	AnnotationFrameExtractor	simba.labelling
Annotated bout videos (Label behavior tab)	PlotAnnotatedBouts	simba.plotting
Pose visualization (Tools menu)	PosePlotter, PosePlotterMultiProcess	simba.plotting
Blob tracking (Process Videos menu)	BlobVisualizer	simba.plotting
YOLO model results (Process Videos menu)	YOLOPoseVisualizer, YOLOPoseTrackVisualizer	simba.plotting
Egocentrically align pose and video (Tools menu)	EgocentricalAligner	simba.data_processors
Create path plots (ROI tab)	EzPathPlot	simba.plotting
Concatenate two videos (Tools menu)	video_concatenator	simba.video_processors

Full API index: SimBA API Reference

---

Where visualization outputs are saved

In the paths below, project_folder means the main folder of your SimBA project (the folder that contains csv, videos, logs, etc.). Replace it with the actual path on your computer, e.g. C:\Users\YourName\MySimBAProject or /home/username/MySimBAProject.

Visualization	Output path
Classification videos	project_folder/frames/output/sklearn_results/
Gantt charts	project_folder/frames/output/gantt_plots/
Probability plots	project_folder/frames/output/probability_plots/
Path plots	project_folder/frames/output/path_plots/
Distance plots	project_folder/frames/output/line_plot/
Classification heatmaps	project_folder/frames/output/heatmaps_classifier_locations/
ROI tracking (ROI tab)	project_folder/frames/output/ROI_analysis/
ROI features (ROI tab)	project_folder/frames/output/ROI_features/
Location heatmaps (ROI tab)	project_folder/frames/output/heatmaps_locations/
Directionality between animals (ROI tab)	project_folder/frames/output/Directing_animals/
Data tables	project_folder/frames/output/live_data_table/
Merged videos	project_folder/frames/output/merged/
Validation video (Scenario 1)	project_folder/frames/output/validation/
Post-classification validation clips (Scenario 4)	project_folder/frames/output/classifier_validation/
Annotated frames (Label behavior tab)	project_folder/frames/output/annotated_frames/
Annotated bout videos (Label behavior tab)	project_folder/frames/output/annotated_frames/videos/
Create path plots (ROI tab)	project_folder/frames/output/path_plots/
Pose visualization (Tools menu)	User-selected save directory
Blob tracking (Process Videos menu)	User-selected save directory
YOLO model results (Process Videos menu)	User-selected save directory
Egocentrically align pose and video (Tools menu)	User-selected save directory
Concatenate two videos (Tools menu)	Same directory as first selected video

---

Bugs and feature requests: Please help improve SimBA by reporting bugs or suggesting features—either open an issue on GitHub or reach out on Gitter.

Author: Simon N