API: GUI

Stable GUI-facing modules for the tracking app.

hydra_suite.tracker.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.

CNNClassifierRow

Bases: QWidget

Self-contained widget for one CNN classifier configuration row.

to_config()

Return config dict or None if no model selected.

load_from_config(cfg)

Populate from a config dict entry.

__init__()

Initialize the main application window and UI components.

init_ui()

Build the structured UI using Splitter and Tabs.

setup_setup_ui()

Tab 1: Setup - Files, Video, Display & Debug.

setup_detection_ui()

Tab 2: Detection - Method, Image Proc, Algo specific.

setup_tracking_ui()

Tab 3: Tracking Logic.

setup_data_ui()

Tab 4: Post-Processing.

setup_dataset_ui()

Tab 6: Dataset Generation for Active Learning.

setup_individual_analysis_ui()

Tab 7: Individual Analysis - Real-time Identity & Post-hoc Pose Analysis.

closeEvent(event)

Persist MAT-specific UI layout state on close.

select_file()

Select video file via file dialog.

select_csv()

select_csv method documentation.

select_video_output()

select_video_output method documentation.

record_roi_click(evt)

record_roi_click method documentation.

update_roi_preview()

update_roi_preview method documentation.

start_roi_selection()

start_roi_selection method documentation.

finish_roi_selection()

finish_roi_selection method documentation.

undo_last_roi_shape()

Remove the last added ROI shape.

clear_roi()

clear_roi method documentation.

keyPressEvent(event)

keyPressEvent method documentation.

on_detection_method_changed(index)

on_detection_method_changed method documentation.

on_pose_model_changed(index)

Handle selection change in the pose model combo.

on_yolo_model_changed(index)

Handle direct OBB model selection — triggers import when 'Add New' chosen.

toggle_preview(checked)

toggle_preview method documentation.

toggle_tracking(checked)

toggle_tracking method documentation.

toggle_debug_logging(checked)

toggle_debug_logging method documentation.

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.tracker.gui.main_window

Main application window for the HYDRA.

Refactored for improved UX with Tabbed interface and logical grouping.

CurrentPageStackedWidget

Bases: QStackedWidget

A stacked widget whose size hint tracks the active page.

MergeWorker

Bases: QThread

Worker thread for merging trajectories without blocking the UI.

stop()

Request cooperative cancellation.

run()

run method documentation.

InterpolatedCropsWorker

Bases: QThread

Worker thread for interpolating occluded crops without blocking the UI.

stop()

Request cooperative cancellation.

run()

run method documentation.

OrientedTrackVideoWorker

Bases: QThread

Worker thread for exporting orientation-fixed per-track videos.

stop()

Request cooperative cancellation.

run()

run method documentation.

DatasetGenerationWorker

Bases: QThread

Worker thread for generating training datasets without blocking the UI.

stop()

Request cooperative cancellation.

run()

run method documentation.

PreviewDetectionWorker

Bases: QThread

Worker thread for non-blocking preview detection.

ImmediateTooltipButton

Bases: QToolButton

Tool button that shows its tooltip immediately on hover, focus, or click.

CollapsibleGroupBox

Bases: QWidget

A collapsible group box widget that can expand/collapse its content. Used for advanced settings that don't need to be visible all the time.

setContentLayout(layout)

Set the content layout for the collapsible section.

addWidget(widget)

Add a widget to the content area.

addLayout(layout)

Add a layout to the content area.

setAccordionGroup(accordion)

Set the accordion group this collapsible belongs to.

setExpanded(expanded)

Set the expanded state of the collapsible.

isExpanded()

Check if the collapsible is expanded.

title()

Get the title of the collapsible.

setHelpToolTip(text)

Attach a compact help button to the collapsible header.

AccordionContainer

Manages a group of CollapsibleGroupBox widgets to ensure only one is expanded at a time.

addCollapsible(collapsible)

Add a collapsible to this accordion group.

collapseAllExcept(keep_expanded)

Collapse all collapsibles except the specified one.

CompactHelpLabel

Bases: QWidget

Compact inline help affordance that keeps full guidance in an explicit icon.

MainWindow

Bases: QMainWindow

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

CNNClassifierRow

Bases: QWidget

Self-contained widget for one CNN classifier configuration row.

to_config()

Return config dict or None if no model selected.

load_from_config(cfg)

Populate from a config dict entry.

__init__()

Initialize the main application window and UI components.

init_ui()

Build the structured UI using Splitter and Tabs.

setup_setup_ui()

Tab 1: Setup - Files, Video, Display & Debug.

setup_detection_ui()

Tab 2: Detection - Method, Image Proc, Algo specific.

setup_tracking_ui()

Tab 3: Tracking Logic.

setup_data_ui()

Tab 4: Post-Processing.

setup_dataset_ui()

Tab 6: Dataset Generation for Active Learning.

setup_individual_analysis_ui()

Tab 7: Individual Analysis - Real-time Identity & Post-hoc Pose Analysis.

closeEvent(event)

Persist MAT-specific UI layout state on close.

select_file()

Select video file via file dialog.

select_csv()

select_csv method documentation.

select_video_output()

select_video_output method documentation.

record_roi_click(evt)

record_roi_click method documentation.

update_roi_preview()

update_roi_preview method documentation.

start_roi_selection()

start_roi_selection method documentation.

finish_roi_selection()

finish_roi_selection method documentation.

undo_last_roi_shape()

Remove the last added ROI shape.

clear_roi()

clear_roi method documentation.

keyPressEvent(event)

keyPressEvent method documentation.

on_detection_method_changed(index)

on_detection_method_changed method documentation.

on_pose_model_changed(index)

Handle selection change in the pose model combo.

on_yolo_model_changed(index)

Handle direct OBB model selection — triggers import when 'Add New' chosen.

toggle_preview(checked)

toggle_preview method documentation.

toggle_tracking(checked)

toggle_tracking method documentation.

toggle_debug_logging(checked)

toggle_debug_logging method documentation.

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.

get_models_directory()

Get the path to the default YOLO OBB model repository.

Returns models/obb (direct OBB models). Creates the directory if it doesn't exist.

get_models_root_directory()

Return user-local models/ root and create it when missing.

get_yolo_model_repository_directory(task_family=None, usage_role=None)

Return repository directory for a YOLO model role.

get_pose_models_directory(backend=None)

Get the local pose-model repository directory.

Layout: models/pose/YOLO/ models/pose/SLEAP/ models/pose/ViTPose/

resolve_pose_model_path(model_path, backend=None)

Resolve a pose model path (relative or absolute) to an absolute path when possible.

make_pose_model_path_relative(model_path)

Convert absolute pose-model paths under models/ into relative paths.

resolve_model_path(model_path)

Resolve a model path to an absolute path.

If the path is relative, look for it in the models directory. If absolute and exists, return as-is.

Args: model_path: Relative or absolute model path

Returns: Absolute path to the model file, or original path if not found

make_model_path_relative(model_path)

Convert an absolute model path to relative if it's in the models directory.

This allows presets to be portable across devices.

Args: model_path: Absolute or relative model path

Returns: Relative path if model is in archive, otherwise absolute path

get_yolo_model_registry_path()

Return path to the local YOLO model metadata registry JSON.

load_yolo_model_registry()

Load YOLO model metadata registry (path -> metadata).

save_yolo_model_registry(registry)

Persist YOLO model metadata registry JSON.

get_yolo_model_metadata(model_path)

Get metadata for a model path if registered.

register_yolo_model(model_path, metadata)

Register/overwrite metadata entry for a model path.

hydra_suite.tracker.gui.dialogs.train_yolo_dialog

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

RoleTrainingWorker

Bases: QThread

Run selected role trainings sequentially in a background thread.

TrainYoloDialog

Bases: QDialog

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