Skip to content

API: TrackerKit GUI

Stable GUI-facing modules for the tracking app.

hydra_suite.trackerkit.gui

GUI module for HYDRA Suite.

This module contains the graphical user interface components including the main window.

MainWindow

Bases: QMainWindow

Main application window providing GUI interface for HYDRA configuration, model management, and execution.

__init__()

Initialize the main application window and UI components.

init_ui()

Build the structured UI using Splitter and Tabs.

closeEvent(event)

Stop active workers cleanly, then persist UI layout state on close.

select_file()

Select video file via file dialog.

select_csv()

select_csv method documentation.

record_roi_click(evt)

Record an ROI click from the video label.

update_roi_preview()

Render current ROI shapes + in-progress points onto the video label.

start_roi_selection()

Start an ROI shape selection session.

finish_roi_selection()

Finalize the current ROI shape and add it to the shape list.

undo_last_roi_shape()

Remove the last added ROI shape.

clear_roi()

Clear all ROI shapes and reset state.

keyPressEvent(event)

Handle key press events.

on_pose_model_changed(index)

Handle selection change in the pose model combo.

on_yolo_headtail_model_changed(index)

Handle head/tail classification model combo-box changes.

Handles three cases: 1. __add_new__ sentinel — opens the add-model file dialog. 2. Discovered (unannotated) classkit entry — opens the annotation dialog. 3. Normal registered entry — syncs analysis mode UI.

toggle_preview(checked)

Toggle preview mode on/off.

toggle_tracking(checked)

Toggle full tracking on/off.

toggle_debug_logging(checked)

Toggle debug logging level.

start_full()

start_full method documentation.

stop_tracking()

stop_tracking method documentation.

on_progress_update(percentage, status_text)

on_progress_update method documentation.

on_pose_exported_model_resolved(artifact_path)

Update pose exported-model UI/config when runtime resolves an artifact path.

on_tracking_warning(title, message)

Display tracking warnings in the UI.

show_gpu_info()

Display GPU and acceleration information dialog.

on_stats_update(stats)

Update real-time tracking statistics.

on_new_frame(rgb)

on_new_frame method documentation.

save_trajectories_to_csv(trajectories, output_path)

Save processed trajectories to CSV.

Args: trajectories: Either list of tuples (old format) or pandas DataFrame (new format with confidence) output_path: Path to save CSV file

merge_and_save_trajectories()

merge_and_save_trajectories method documentation.

on_merge_progress(value, message)

Update progress bar during merge.

on_merge_error(error_message)

Handle merge errors.

on_merge_finished(resolved_trajectories)

Handle completion of trajectory merging.

on_tracking_finished(finished_normally, fps_list, full_traj)

on_tracking_finished method documentation.

start_backward_tracking()

start_backward_tracking method documentation.

start_tracking(preview_mode, backward_mode=False)

start_tracking method documentation.

start_preview_on_video(video_path)

start_preview_on_video method documentation.

start_tracking_on_video(video_path, backward_mode=False)

start_tracking_on_video method documentation.

get_parameters_dict()

get_parameters_dict method documentation.

load_config()

Manually load config from file dialog.

save_config(preset_mode=False, preset_path=None, preset_name=None, preset_description=None, prompt_if_exists=True)

Save current configuration to JSON file.

Args: preset_mode: If True, skip video paths, device settings, and ROI data (for organism presets) preset_path: If provided, save directly to this path without prompting preset_name: Name for the preset (only used in preset_mode) preset_description: Description for the preset (only used in preset_mode) prompt_if_exists: If False, overwrite default config path without interactive replace dialog.

Returns: bool: True if config was saved successfully, False if cancelled or failed

on_dataset_progress(value, message)

Update progress bar during dataset generation.

on_dataset_finished(dataset_dir, num_frames)

Handle dataset generation completion.

on_dataset_error(error_message)

Handle dataset generation errors.

crop_video_to_roi()

Crop the video to the ROI bounding box and save as new file.

hydra_suite.trackerkit.gui.main_window

Main application window for the HYDRA.

Refactored for improved UX with Tabbed interface and logical grouping.

MainWindow

Bases: QMainWindow

Main application window providing GUI interface for HYDRA configuration, model management, and execution.

__init__()

Initialize the main application window and UI components.

init_ui()

Build the structured UI using Splitter and Tabs.

closeEvent(event)

Stop active workers cleanly, then persist UI layout state on close.

select_file()

Select video file via file dialog.

select_csv()

select_csv method documentation.

record_roi_click(evt)

Record an ROI click from the video label.

update_roi_preview()

Render current ROI shapes + in-progress points onto the video label.

start_roi_selection()

Start an ROI shape selection session.

finish_roi_selection()

Finalize the current ROI shape and add it to the shape list.

undo_last_roi_shape()

Remove the last added ROI shape.

clear_roi()

Clear all ROI shapes and reset state.

keyPressEvent(event)

Handle key press events.

on_pose_model_changed(index)

Handle selection change in the pose model combo.

on_yolo_headtail_model_changed(index)

Handle head/tail classification model combo-box changes.

Handles three cases: 1. __add_new__ sentinel — opens the add-model file dialog. 2. Discovered (unannotated) classkit entry — opens the annotation dialog. 3. Normal registered entry — syncs analysis mode UI.

toggle_preview(checked)

Toggle preview mode on/off.

toggle_tracking(checked)

Toggle full tracking on/off.

toggle_debug_logging(checked)

Toggle debug logging level.

start_full()

start_full method documentation.

stop_tracking()

stop_tracking method documentation.

on_progress_update(percentage, status_text)

on_progress_update method documentation.

on_pose_exported_model_resolved(artifact_path)

Update pose exported-model UI/config when runtime resolves an artifact path.

on_tracking_warning(title, message)

Display tracking warnings in the UI.

show_gpu_info()

Display GPU and acceleration information dialog.

on_stats_update(stats)

Update real-time tracking statistics.

on_new_frame(rgb)

on_new_frame method documentation.

save_trajectories_to_csv(trajectories, output_path)

Save processed trajectories to CSV.

Args: trajectories: Either list of tuples (old format) or pandas DataFrame (new format with confidence) output_path: Path to save CSV file

merge_and_save_trajectories()

merge_and_save_trajectories method documentation.

on_merge_progress(value, message)

Update progress bar during merge.

on_merge_error(error_message)

Handle merge errors.

on_merge_finished(resolved_trajectories)

Handle completion of trajectory merging.

on_tracking_finished(finished_normally, fps_list, full_traj)

on_tracking_finished method documentation.

start_backward_tracking()

start_backward_tracking method documentation.

start_tracking(preview_mode, backward_mode=False)

start_tracking method documentation.

start_preview_on_video(video_path)

start_preview_on_video method documentation.

start_tracking_on_video(video_path, backward_mode=False)

start_tracking_on_video method documentation.

get_parameters_dict()

get_parameters_dict method documentation.

load_config()

Manually load config from file dialog.

save_config(preset_mode=False, preset_path=None, preset_name=None, preset_description=None, prompt_if_exists=True)

Save current configuration to JSON file.

Args: preset_mode: If True, skip video paths, device settings, and ROI data (for organism presets) preset_path: If provided, save directly to this path without prompting preset_name: Name for the preset (only used in preset_mode) preset_description: Description for the preset (only used in preset_mode) prompt_if_exists: If False, overwrite default config path without interactive replace dialog.

Returns: bool: True if config was saved successfully, False if cancelled or failed

on_dataset_progress(value, message)

Update progress bar during dataset generation.

on_dataset_finished(dataset_dir, num_frames)

Handle dataset generation completion.

on_dataset_error(error_message)

Handle dataset generation errors.

crop_video_to_roi()

Crop the video to the ROI bounding box and save as new file.

get_video_config_path(video_path)

Get the config file path for a given video file.

hydra_suite.trackerkit.gui.orchestrators.config

ConfigOrchestrator — config load/save, presets, ROI, video setup.

ConfigOrchestrator

Manages configuration load/save, presets, ROI, and video file setup.

load_config()

Manually load config from file dialog.

save_config(preset_mode=False, preset_path=None, preset_name=None, preset_description=None, prompt_if_exists=True)

Save current configuration to JSON file.

Args: preset_mode: If True, skip video paths, device settings, and ROI data (for organism presets) preset_path: If provided, save directly to this path without prompting preset_name: Name for the preset (only used in preset_mode) preset_description: Description for the preset (only used in preset_mode) prompt_if_exists: If False, overwrite default config path without interactive replace dialog.

Returns: bool: True if config was saved successfully, False if cancelled or failed

get_parameters_dict()

get_parameters_dict method documentation.

crop_video_to_roi()

Crop the video to the ROI bounding box and save as new file.

hydra_suite.trackerkit.gui.orchestrators.session

SessionOrchestrator — logging, progress, UI state machine.

SessionOrchestrator

Manages session logging, progress display, and UI state transitions.

record_roi_click(evt)

Record an ROI click from the video label.

update_roi_preview()

Render current ROI shapes + in-progress points onto the video label.

start_roi_selection()

Start an ROI shape selection session.

finish_roi_selection()

Finalize the current ROI shape and add it to the shape list.

undo_last_roi_shape()

Remove the last added ROI shape.

clear_roi()

Clear all ROI shapes and reset state.

keyPressEvent(event)

Handle key press events - cancel ROI on Escape.

toggle_preview(checked)

Toggle preview mode on/off.

toggle_tracking(checked)

Toggle full tracking on/off.

hydra_suite.trackerkit.gui.orchestrators.tracking

TrackingOrchestrator — run→merge→export→finalize lifecycle.

TrackingOrchestrator

Owns the tracking lifecycle: start, stop, merge, export, finalize.

start_full()

start_full method documentation.

stop_tracking()

stop_tracking method documentation.

on_progress_update(percentage, status_text)

on_progress_update method documentation.

on_pose_exported_model_resolved(artifact_path)

Update pose exported-model UI/config when runtime resolves an artifact path.

on_tracking_warning(title, message)

Display tracking warnings in the UI.

show_gpu_info()

Display GPU and acceleration information dialog.

clear_detection_caches()

Delete all current-video cache files for the active video.

on_stats_update(stats)

Update real-time tracking statistics.

on_new_frame(rgb)

on_new_frame method documentation.

save_trajectories_to_csv(trajectories, output_path)

Save processed trajectories to CSV.

Args: trajectories: Either list of tuples (old format) or pandas DataFrame (new format with confidence) output_path: Path to save CSV file

merge_and_save_trajectories()

merge_and_save_trajectories method documentation.

on_merge_progress(value, message)

Update progress bar during merge.

on_merge_error(error_message)

Handle merge errors.

on_merge_finished(resolved_trajectories)

Handle completion of trajectory merging.

on_tracking_finished(finished_normally, fps_list, full_traj)

on_tracking_finished method documentation.

on_postprocess_progress(value, message)

Update progress bar during post-processing.

on_postprocess_finished(processed_trajectories)

Route processed trajectories to the appropriate pipeline stage.

on_postprocess_error(error_message)

Handle post-processing errors.

start_backward_tracking()

start_backward_tracking method documentation.

start_tracking(preview_mode, backward_mode=False)

start_tracking method documentation.

start_preview_on_video(video_path)

start_preview_on_video method documentation.

start_tracking_on_video(video_path, backward_mode=False)

start_tracking_on_video method documentation.

on_dataset_progress(value, message)

Update progress bar during dataset generation.

on_dataset_finished(dataset_dir, num_frames)

Handle dataset generation completion.

on_dataset_error(error_message)

Handle dataset generation errors.

hydra_suite.trackerkit.gui.panels.setup_panel

SetupPanel — preset selection, video files, display, and ROI configuration.

SetupPanel

Bases: QWidget

Preset picker, video/batch file selection, ROI, and display options.

apply_config(config)

Update panel widgets to reflect a new config object.

hydra_suite.trackerkit.gui.panels.detection_panel

DetectionPanel — detection method, image preprocessing, and model config.

DetectionPanel

Bases: QWidget

Detection method selector, image-processing pipeline, and YOLO config.

apply_config(config)

Update panel widgets to reflect a new config object.

on_detection_method_changed(index)

Keep compatibility hook and synchronize YOLO-only individual-analysis controls.

on_yolo_model_changed(index)

Handle direct OBB model selection.

on_yolo_detect_model_changed(index)

Handle sequential detection model combo-box changes, opening the add-model dialog when the sentinel item is selected.

on_yolo_crop_obb_model_changed(index)

Handle sequential crop OBB model combo-box changes, opening the add-model dialog when the sentinel item is selected.

hydra_suite.trackerkit.gui.panels.tracking_panel

TrackingPanel — core tracking parameters, Kalman filter, and assignment config.

TrackingPanel

Bases: QWidget

Kalman filter parameters, identity assignment, and backward pass controls.

apply_config(config)

Update panel widgets to reflect a new config object.

set_identity_section_visible(visible)

Hide the entire identity-decoder collapsible.

Called from the session orchestrator's individual-analysis-mode sync whenever identity classification is toggled in the Analyse Individuals panel. When identity classification is OFF the entire decoder section is irrelevant — hide it rather than leaving disabled controls on screen.

sync_directed_orient_posthoc_ui(posthoc_active)

Show/hide the head-tail/pose anchor note based on model presence.

hydra_suite.trackerkit.gui.dialogs.train_yolo_dialog

Role-aware MAT Training Center dialog for multi-model YOLO workflows.

RoleTrainingWorker

Bases: BaseWorker

Run selected role trainings sequentially in a background thread.

TrainYoloDialog

Bases: BaseDialog

MAT role-aware training center replacing legacy OBB-only trainer.

hydra_suite.trackerkit.gui.dialogs.parameter_helper

Parameter Selection Helper Dialog. Integrated with Main UI frame range and granular parameter control.

ParameterHelperDialog

Bases: BaseDialog

Interactive dialog for auto-tuning core tracking parameters (Kalman, YOLO thresholds, assignment weights) against a detection cache.

setup_ui()

Build the full dialog layout: left controls/results table and right live-preview panel.

get_scoring_weights()

Return the current scoring-weight spinbox values as a params dict.

get_tuning_config()

Return a mapping of tracking parameter names to whether each is selected for Optuna optimization.

run_optimization()

Start the Optuna-based tracking optimizer with the selected parameters and trial budget.

on_progress(val, msg)

Update the progress bar and status label with the optimizer's current trial progress.

on_results(results)

Populate the results table with ranked optimization trials and colour-coded sub-score badges.