API: PoseKit

hydra_suite.posekit

Pose labeling subpackage.

main(*args, **kwargs)

Lazy entry point for the PoseKit labeler UI.

hydra_suite.posekit.core

hydra_suite.posekit.core.extensions

Extensions for PoseKit Labeler: - Crash-safe recovery with temp files - Versioned label backups - Per-frame metadata/tags - Cluster-stratified dataset splitting - Embedding/clustering utilities - YOLO pose I/O

FrameMetadata dataclass

Metadata for a single frame.

to_json()

Serialize frame metadata to a JSON-safe dictionary.

from_json(data) staticmethod

Build a FrameMetadata object from serialized JSON data.

MetadataManager

Manages per-frame metadata.

load()

Load metadata from disk.

save()

Save metadata to disk.

get_metadata(image_path)

Get metadata for a frame, creating if needed.

CrashSafeWriter

Writes labels atomically using temp files.

write_label(label_path, content) staticmethod

Write label file atomically using temp file + rename.

LabelVersioning

Manages versioned backups of labels.

backup_label(label_path)

Create a versioned backup of a label file.

Keypoint dataclass

Represents a single keypoint with pixel coordinates and visibility.

EmbeddingWorker

Bases: QObject

Worker thread for computing embeddings.

cancel()

Signal the worker loop to stop at the next safe checkpoint.

run()

Compute/load embeddings and emit final embedding matrix for eligible frames.

IncrementalEmbeddingCache

Manages incremental embedding computation and caching.

get_metadata()

Get cache metadata.

set_metadata(meta)

Save cache metadata.

needs_update(image_paths)

Check which images need embedding computation. Returns: (needs_compute_indices, cached_indices)

get_embeddings(image_paths)

Get embeddings for given paths (if all are cached).

add_embeddings(image_paths, embeddings)

Add new embeddings to cache.

update_embeddings(image_paths, embeddings)

Update or add embeddings for given paths.

remove_paths(paths)

Remove embeddings for deleted paths. Returns number removed.

clear()

Clear all cached embeddings.

cluster_stratified_split(image_paths, cluster_ids, train_frac=0.7, val_frac=0.15, test_frac=0.15, min_per_cluster=1, seed=0)

Split frames into train/val/test preserving cluster distribution.

Returns: (train_indices, val_indices, test_indices)

cluster_embeddings_cosine(emb, k, method='hierarchical', seed=0, hierarchical_limit=2500)

Cluster embeddings using cosine similarity. Returns cluster labels in [0..k-1].

pick_frames_stratified(emb, cluster_id, want_n, eligible_indices, min_per_cluster=1, seed=0, strategy='centroid_then_diverse')

Select frames stratified by cluster. emb: embeddings for eligible_indices (same order) cluster_id: cluster labels for eligible_indices returns: selected global indices (from eligible_indices mapping)

load_yolo_pose_label(label_path, k)

Load YOLO pose label from .txt file.

save_yolo_pose_label(label_path, cls, img_w, img_h, kpts_px, bbox_xyxy_px, pad_frac, create_backup=True)

Save YOLO pose label with crash-safe writing and optional backup.

migrate_labels_keypoints(labels_dir, old_kpt_names, new_kpt_names, mode='name')

Update all .txt labels in labels_dir to match new keypoint list length/order.

mode="name": map by unique keypoint names, fallback to 0 if missing mode="index": preserve positions by old index (truncate/extend) Returns: (files_modified, files_total)

list_labeled_indices(image_paths, labels_dir)

Return indices of images that have non-empty label files.

build_yolo_pose_dataset(image_paths, labels_dir, output_dir, train_frac, seed, class_names, keypoint_names, extra_datasets=None, extra_items=None, train_items=None, val_items=None, ignore_occluded_train=True, ignore_occluded_val=False)

Build a YOLO Pose dataset with copied images/labels under output_dir.

Returns dict with paths and counts.

build_coco_keypoints_dataset(image_paths, labels_dir, output_dir, class_names, keypoint_names, skeleton_edges, extra_datasets=None, extra_items=None)

Build a COCO keypoints dataset under output_dir.

Copies labeled frames into output_dir/images and writes annotations.json.

filter_near_duplicates(embeddings, indices, threshold=0.95)

Remove near-duplicate frames based on cosine similarity. Returns filtered indices.

Args: embeddings: All embeddings (N x D) indices: List of frame indices to filter threshold: Cosine similarity threshold (0-1). Higher = more strict filtering.

Returns: Filtered list of indices with near-duplicates removed

hydra_suite.posekit.inference

hydra_suite.posekit.inference.worker

Run SLEAP exported-model inference for a batch of images.

Executed inside the selected SLEAP conda environment. Input: JSON path passed as argv[1] Output: writes {"preds": {...}} JSON to cfg["out_json"].

hydra_suite.posekit.ui

hydra_suite.posekit.ui.canvas

PoseCanvas

Bases: QGraphicsView

Interactive graphics canvas for keypoint editing and prediction overlays.

set_callbacks(on_place, on_move, on_select=None)

Register callbacks for placement, drag movement, and optional selection.

set_current_keypoint(idx)

Set the active keypoint index used for click placement.

set_kpt_radius(r)

Update rendered keypoint radius.

set_label_font_size(size)

Update keypoint label font size.

set_kpt_opacity(opacity)

Update keypoint alpha channel used for overlay drawing.

set_edge_opacity(opacity)

Update skeleton edge alpha channel used for overlay drawing.

set_edge_width(width)

Update skeleton edge width used for annotation and prediction edges.

fit_to_view()

Fit the image to the view.

set_image(img_bgr)

Load a BGR image into the canvas and fit it to the current viewport.

rebuild_overlays(kpts, kpt_names, edges, pred_kpts=None, pred_confs=None, show_pred_conf=False)

Rebuild all keypoint/skeleton and optional prediction overlay items.

wheelEvent(event)

Zoom in/out around cursor while clamping to sane zoom bounds.

mousePressEvent(event)

Handle placement, selection, visibility toggle, and drag-start behavior.

mouseMoveEvent(event)

Update dragged keypoint/prediction position during pointer motion.

mouseReleaseEvent(event)

Commit drag interactions and optional prediction adoption on release.

FrameListDelegate

Bases: QStyledItemDelegate

Render frame name with right-aligned prediction confidence.

paint(painter, option, index)

Render frame row with elided name plus confidence and label counters.

hydra_suite.posekit.ui.main_window

MainWindow

Bases: QMainWindow

MainWindow API surface documentation.

apply_stylesheet()

Apply the PoseKit dark theme to the entire window.

new_project_wizard()

Run the New Project wizard and switch to the created project.

closeEvent(event)

Save UI settings when window closes.

keyPressEvent(event)

Handle arrow key nudging of keypoints with modifier keys.

save_project()

save_project method documentation.

load_frame(idx)

load_frame method documentation.

fit_to_view()

Fit image to view.

undo_last()

undo_last method documentation.

on_place_kpt(kpt_idx, x, y, v)

on_place_kpt method documentation.

on_move_kpt(kpt_idx, x, y)

on_move_kpt method documentation.

on_select_kpt(idx)

Called when user clicks on an existing keypoint - make it current.

clear_current_keypoint()

clear_current_keypoint method documentation.

clear_all_keypoints()

Clear all keypoints from the current frame.

prev_frame()

prev_frame method documentation.

next_frame(prefer_missing=False)

next_frame method documentation.

prev_keypoint()

prev_keypoint method documentation.

next_keypoint()

next_keypoint method documentation.

next_unlabeled()

next_unlabeled method documentation.

save_current(refresh_ui=True)

save_current method documentation.

save_all_labeling_frames()

Save all labeling frames to disk using current in-memory state.

open_skeleton_editor()

open_skeleton_editor method documentation.

open_project_settings()

open_project_settings method documentation.

open_project()

Open an existing PoseKit project.

The user may select either: • A PoseKit project JSON file (standalone or legacy). • A dataset root folder that contains a posekit_project/ sub-dir (legacy dataset-anchored layout).

export_dataset_dialog()

export_dataset_dialog method documentation.

open_smart_select()

open_smart_select method documentation.

predict_current_frame()

predict_current_frame method documentation.

apply_predictions_current()

apply_predictions_current method documentation.

predict_dataset()

predict_dataset method documentation.

open_training_runner()

open_training_runner method documentation.

open_evaluation_dashboard()

open_evaluation_dashboard method documentation.

open_active_learning()

open_active_learning method documentation.

hydra_suite.posekit.ui.models

Keypoint dataclass

Single keypoint annotation in pixel space.

FrameAnn dataclass

Single-frame annotation containing class, box, and keypoints.

DataSource dataclass

A single source dataset ingested into a multi-source PoseKit project.

Project dataclass

Persistent PoseKit project configuration and UI/session state.

to_json()

Serialize project state to a JSON-compatible dictionary.

from_json(project_path) staticmethod

Load project configuration from disk.

compute_bbox_from_kpts(kpts, pad_frac, w, h)

Compute bounding box from visible keypoints with minimum size guarantee.

hydra_suite.posekit.ui.project

resolve_dataset_paths(dataset_dir)

Resolve canonical dataset structure paths.

Expected structure: dataset_dir/ images/ posekit_project/ pose_project.json labels/

find_project(dataset_dir)

Find an existing project for a dataset root.

Primary location: dataset_dir/posekit_project/pose_project.json

The primary location is trusted by virtue of its path — if the file exists there it belongs to this dataset even if the stored images_dir is stale (e.g. after moving between machines). load_project_with_repairs will fix the paths afterwards.

Legacy fallback paths are only accepted when the stored images_dir matches, to avoid accidentally loading an unrelated project.

load_project_with_repairs(project_path, dataset_dir)

Load a project and repair any stale paths for the current machine.

create_project_via_wizard(dataset_dir)

Run the ProjectWizard dialog and create a new project from user input.

create_standalone_project_via_wizard(parent_widget=None)

Run NewProjectDialog and build a standalone multi-source project.

Unlike create_project_via_wizard(), the project file lives at a user-chosen location independent of any dataset folder, and one or more sources are added during creation rather than as an afterthought.

open_project_from_path(project_path)

Load a project directly from its .json path (no dataset_dir required).

Used when the user browses to a standalone project file. Path repairs are skipped because the project location is trusted as-is.

build_image_list(project)

Return all image paths for project, spanning every registered source.

Multi-source projects aggregate images from all project.sources in registration order. Legacy single-source projects fall back to the top-level project.images_dir.

add_source_to_project(project, dataset_dir, description='')

Ingest a new source dataset into project and persist the change.

If the project is currently in legacy single-source mode (sources=[]) the existing images_dir / labels_dir is first promoted to source_0 so that routing remains consistent.

Returns the newly created :class:DataSource.

create_empty_startup_project()

Create a minimal placeholder project for startup-without-dataset mode.

hydra_suite.posekit.ui.workers

PosePredictWorker

Bases: QObject

Background worker for one-image pose prediction.

run()

Run inference and emit either predicted keypoints or an error.

BulkPosePredictWorker

Bases: QObject

Background worker for multi-image pose prediction.

cancel()

Request cancellation for the running prediction batch.

run()

Run batch inference and stream progress updates.

SleapServiceWorker

Bases: QObject

Worker that starts and validates the SLEAP backend service.

run()

Start SLEAP service and emit status tuple.