Import BaseExternalDetector and add a DetectorModel type alias combining BaseDetector and BaseExternalDetector. Update DetectorInferenceRunner typing and constructor to accept DetectorModel so external detector implementations can be used for inference without changing runtime behavior.

Register a simple MockExternalDetector and add an end-to-end test for external detector inference. __init__.py now imports the mock to populate the EXTERNAL_DETECTORS registry; mock.py implements a lightweight detector that returns a centered box per image. The new test verifies building the detector from the registry, preprocessing/postprocessing, running the DetectorInferenceRunner, and basic output shape/score sanity.

Update docstring for external detectors to state they are inference-oriented and usually not trained (though a pose estimation model may be trained on top of them). Note that external detectors may lack a training loop, optimizer, snapshot loading, or target generation, clarifying expected behavior for integrators and maintainers.

Add logging and defensive checks when building external detectors. Import logging and create a module logger, then attempt to freeze model parameters (requires_grad=False) while catching AttributeError/RuntimeError and warning if the detector has no parameters; also wrap detector.eval() in a try/except to warn if eval() is missing. These changes help avoid accidental training and provide clearer messages for detectors that don't expose standard APIs.

Introduce BBoxComputationMethod enum and DetectorRunnerLike protocol; add logging and required imports. Make Loader.create_dataset accept an optional detector_runner and avoid mutating cached annotations by deep-copying them. Add logic to resolve bbox source for top-down tasks and extend _compute_bboxes to handle detection-based matching (with optional fallback to GT), keypoints-based boxes, and a placeholder for segmentation masks. Implement IoU computation, xywh->xyxy conversion, and Hungarian matching (scipy.linear_sum_assignment) to associate detector boxes to GT, plus small validation and informative logging. Overall this enables using external detector outputs to populate top-down bounding boxes robustly.

Import BBoxComputationMethod and use it in COCOLoader (replace literal "gt" with BBoxComputationMethod.GT). In DLCLoader remove the call that recomputed/overwrote annotation bboxes and add a comment explaining that create_dataset(...) now owns bbox source selection (e.g. gt, keypoints, detection), so loaders should not recompute/overwrite bboxes. Small import adjustments to support the enum.

Introduce a default_bbox_method hook on Loader to centralize legacy bbox source behavior and fall back when model_cfg has no bbox_source. ground_truth_keypoints now reads bbox_source from model_cfg and falls back to Loader.default_bbox_method(task). _resolve_bbox_method's signature and returns were updated to use the BBoxComputationMethod enum (DETECTION_BBOX / GT). DLCLoader overrides default_bbox_method to preserve historical behavior (use KEYPOINTS for TOP_DOWN and DETECT). Also updated imports to bring in BBoxComputationMethod and Task.

Introduce a new deeplabcut.pose_estimation_pytorch.data.bboxes module that defines typed DetectorContext, BBoxEntry and BBoxes models (Pydantic) with helpers to convert between xyxy/xywh, serialize/deserialize JSON, and produce DLC-style detector contexts. Update base external detector to import these types and add PrecomputedDetectorRunner: an adapter that serves precomputed BBoxEntry lists as detector outputs (supports optional image-path validation and target bbox format). This enables using saved detector outputs for top-down training/inference and simplifies bbox format handling and persistence.

Add unit tests covering bbox-source behavior and precomputed detector runner integration. New tests verify DLCLoader's backward-compatible default_bbox_method (keypoints for TOP_DOWN/DETECT), that create_dataset() derives keypoint-based bboxes by default, and that explicit bbox_source='gt' or a provided detector_runner override this behavior. They also test BBoxEntry round-trip conversion, PrecomputedDetectorRunner inference contract, and a live integration path using the MockExternalDetector -> inference runner -> BBoxEntry -> PrecomputedDetectorRunner -> create_dataset(). Several regression guards ensure create_dataset() deep-copies annotations and does not mutate cached load_data() payloads. Tests use small FakeDLCLoader/DummyDetectorRunner fixtures and patch PoseDataset to a lightweight DummyPoseDataset for focused loader logic testing.

Move the BBoxComputationMethod enum out of deeplabcut/pose_estimation_pytorch/data/base.py into a new deeplabcut/pose_estimation_pytorch/data/bboxes.py to centralize bbox-related types. Update imports in cocoloader.py, dlcloader.py and base.py to reference the new module, and adjust tests to assert against the enum members instead of string literals. Also remove the now-unused Enum import from base.py.

Call _resolve_bbox_method for TOP_DOWN and DETECT tasks (passing task and detector_runner) and avoid mutating cached annotations; shorten the related comment. Replace BBoxComputationMethod members to explicit string values instead of using auto() (and remove the unused auto import) so enum values are deterministic/serializable.

Add PrecomputedDetectorRunner to deeplabcut.pose_estimation_pytorch.models.detectors.external exports and update the test to import it from the external detectors package (instead of from data.bboxes). This centralizes the runner in the external detectors public API and keeps imports consistent in tests.

Update test config generation to use ruamel.yaml SingleQuotedScalarString for the video path key and set yaml width to avoid wrapping long paths. Use .as_posix() for project_path and video keys to ensure consistent POSIX-style strings, and open the config file with explicit utf-8 encoding. These changes make the generated YAML more robust for long or special-character paths.

Replace incorrect tuple comparison (task == (Task.TOP_DOWN, Task.DETECT)) with a single enum check (task == Task.TOP_DOWN) in tests/pose_estimation_pytorch/apis/test_apis_export.py. This restores the detector-related test branches so detector snapshots/data are properly created and validated for TOP_DOWN tasks (three occurrences updated).

Handle the common single-animal case by trusting the detector output instead of performing IoU matching. When only one candidate annotation is present, pick the highest-scoring predicted bbox (or the first if scores are unavailable), copy it into the annotation, update the area, and increment the total count. This avoids matching against stale placeholder bboxes and simplifies assignment for single-animal frames.

Add Loader._get_reference_bbox_for_matching to prefer deriving a reference bbox from visible keypoints (with margin) and fall back to annotation['bbox'], raising if neither exists. Update _compute_bboxes to coerce the bbox method earlier and to use this helper when building gt_bboxes for detection-to-annotation matching. Change BBoxComputationMethod to a str Enum so methods carry string values.

Normalize path comparison and add helpers for precomputed bboxes.

- Import Loader and DetectorRunnerLike types.
- Add PrecomputedDetectorRunner._normalize_path_for_compare to compare paths using Path.as_posix(), and use it when validating image paths to avoid mismatches across OS path styles.
- Add precompute_detector_bboxes(loader, detector_runner, output_file, modes=(...), bbox_format) to run a detector over dataset image paths, save results to a BBoxes JSON, and return the BBoxes object. Validates output length against image count.
- Add build_precomputed_detector_runner_from_config(model_cfg, mode, ...) to load a BBoxes file from model_cfg['data']['precomputed_bboxes'] and construct a PrecomputedDetectorRunner, returning None if not configured.

These changes enable caching detector outputs to reuse for top-down pose training without rerunning detectors.

Build precomputed detector runners for Task.TOP_DOWN and pass them to dataset creation so top-down training/validation use precomputed detections. Also tighten optimizer construction: resolve optimizer class earlier, use only parameters with requires_grad, raise if there are no trainable parameters, and instantiate the optimizer with those params (uses optimizer_config[type] and params).

Introduce support for precomputed detector boxes and external detector metadata in PyTorch pose configs. Adds new parameters (precomputed_bboxes, bbox_source, external_detector_metadata) to make_pytorch_pose_config, imports BBoxComputationMethod and Enum, and implements logic to set data.bbox_source, store precomputed_bboxes path, and apply safe defaults for matching/validation. Adds _yaml_safe_value helper to convert Enums, Paths, and nested containers to YAML-safe types and applies it to the final pose_config before saving.

Introduce an end-to-end test that verifies the offline / precomputed detector workflow for multi-animal top-down training. The test adds a FakeMultiAnimalDLCLoader, a PrecomputedDetectorRunner-loaded BBoxes artifact, and asserts that create_dataset correctly matches detector boxes to annotations even when detector outputs are reordered. It also builds minimal TinyTrainDataset and TinyPoseModel, runs a short training cycle via build_training_runner, ensures the detector is not invoked during training, confirms only pose model params are optimized, and checks that model parameters are updated.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Introduce DetectorToPoseInferenceRunner to compose a detector runner with a top-down pose runner, enabling detector-first -> pose inference flows. Adds DetectorRunnerLike import, implements input/context normalization, detector output normalization (bboxes, bbox_scores), and injects these into the pose runner inputs. Update build_inference_runner to accept an optional detector_runner and return the composed runner for Task.TOP_DOWN. Also tidy a one-line dict lookup formatting in training.py.

Import PrecomputedDetectorRunner in existing build tests and add a unit to ensure build_inference_runner wraps a top-down runner when a detector_runner is provided. Add a new test module tests/pose_estimation_pytorch/models/external_detectors/test_inference_wrapper.py containing comprehensive unit and integration tests for DetectorThenPoseInferenceRunner. The new tests include stubs (DummyDetectorRunner, RecordingPoseRunner, PreprocessingPoseRunner) and cover: injection of bboxes into pose runner context, defaulting bbox scores, handling of no detections, error cases (output count mismatch and invalid bbox_score length), passing shelf_writer through, and an integration check with the real top-down preprocessor to validate crop shapes. These tests ensure correct composition and data flow from external detectors to top-down pose inference.

Introduce explicit detector mode handling and demo inference.

- Add DetectorMode enum and detector_mode parameter to make_pytorch_pose_config, with coercion and validation logic for 'native' vs 'external' modes.
- Enforce/validate interactions between detector_mode, precomputed_bboxes, detector_type, bbox_source, external_detector_metadata, and top_down/backbone net types; raise clear errors for invalid combos.
- Preserve legacy behavior when detector_mode is None (infer from precomputed_bboxes), and default net_type from project config with a warning and type check.
- Serialize external detector metadata under pose_config['metadata']['detector'] when using external mode and ensure precomputed_bboxes/bbox_source are set appropriately.
- Add logger import and minor YAML-safe value typing.

- Update examples/detector_test_full_api.py to exercise external detector workflows:
  - Set detector_mode='external' in the demo pose config and require precomputed boxes.
  - Lower eval_interval for the demo, tidy docstring bullets, and add end-to-end video inference demo helpers (write_synthetic_video, build_video_context_from_detector, run_video_inference_demo).
  - Wire inference into main() via a run_inference flag and a new --no-inference CLI option; adjust progress prints accordingly.

These changes enable explicit external/precomputed detector support in top-down workflows and extend the example to demonstrate video inference using saved detector contexts.

Rewrite and clarify the detector_test_full_api example: add detailed docs, type annotations, and focused helper classes (IdentityTopDownTransform, tiny detector/model). Update pose-config handling to produce a lightweight, CPU-friendly demo (set net_type to resnet_50, colormode RGB, raise eval_interval, and add detector.train_settings.epochs stub). Ensure DLCLoader compatibility (get_image_paths fallback), serialize precomputed bboxes as JSON, and add video-inference helpers that build per-frame contexts. Switch video APIs to videos_api and improve snapshot lookup, and adjust CLI (rename script usage and add --no-inference flag). Miscellaneous formatting and import grouping for readability.

Add example script external_detector_workflow.py demonstrating an external-detector driven top-down DeepLabCut PyTorch workflow. The script provides a replaceable MyExternalDetector adapter, precomputes and saves detector boxes (precomputed_bboxes.json), generates/updates pytorch_config.yaml for external detector mode, trains pose models via train_network, and runs inference on videos or image folders (with optional per-frame cache). Includes CLI, UserSettings, and helper functions (prepare_external_topdown_pose_config, save_external_detector_bboxes, train_external_topdown_pose_model, analyze_video_with_external_boxes, analyze_image_folder_with_external_boxes). Requires an existing DLC project/config.yaml and a user-supplied detector implementation.

Expand bbox format handling and improve annotation parsing when COCO metadata is missing. Changes:

- Add "cxcywh" to BBoxFormat and implement _cxcywh_to_xyxy conversion.
- Add docstrings to xyxy<->xywh conversion helpers clarifying top-left origin assumptions.
- Update _extract_keypoints_and_bboxes signature/formatting and make it robust to missing COCO fields by:
  - Computing a default area from bbox or visible keypoints when "area" is absent.
  - Building arrays for area, category_id, iscrowd, and individual_id with sensible defaults.
  - Applying the visibility mask to the merged annotation fields instead of raising on missing area.

These changes allow training on DLC-style annotations that may lack some COCO metadata and add support for center-based bbox inputs.

Introduce DetectorToPoseInferenceRunner with options for max_individuals, num_joints, num_unique_bodyparts and fill_value. Implement selection/ordering of detector boxes, padding utilities, and prediction normalization (_select_and_order_boxes, _pad_first_dim, _empty_prediction, _normalize_prediction). Refactor inference flow to run detector first, enrich contexts, call pose runner, and return normalized fixed-shape predictions (or write via shelf_writer). Expose new kwargs in build_inference_runner. Update training GPU reporting to check the runner device string for CUDA before querying CUDA memory. Update external_detector_workflow to use the new composite runner and initialize limits from model metadata.

Update documentation in scripts/external_detector_workflow.py: insert a reminder to create a training shuffle using DLC, adjust the numbering of subsequent steps and minor spacing. This is a non-functional README-style change to clarify setup steps for external detectors.

Change the default behavior to not fall back to ground-truth bboxes (bbox_fallback_to_gt=False) across config generation, loader defaults, example/script settings, and tests. Add a warning when bbox_fallback_to_gt is set but not applicable (only valid for detection bboxes), and log an error if detector matching leaves annotations unmatched while fallback is disabled, advising users to either improve detector performance or enable GT fallback. This prevents silently substituting GT boxes and makes unmatched-detector cases more visible to users.

Expose bbox margin as a configurable parameter and thread it through DLCLoader: read bbox_margin from model_cfg["data"], pass it into to_coco/load_ground_truth, and forward it into _add_bbox_annotations (default 20). Adds explanatory comments clarifying that to_coco initializes keypoint-derived GT bboxes for compatibility and that create_dataset still owns the effective bbox source.

Update DetectorToPoseInferenceRunner to accept None for max_individuals, num_joints, and num_unique_bodyparts by widening type hints to int | None. Initialization logic now preserves None for max_individuals, defaults num_joints to 17 if None, and defaults num_unique_bodyparts to 0 if None; when numeric values are provided the previous minimum constraints (via max(...)) are still enforced. This makes it possible to explicitly leave max_individuals unset while keeping sensible defaults/constraints for provided values.

Parse detector dicts explicitly: read 'bboxes' and optional 'bbox_scores' (defaulting to ones) and raise on length mismatch. Enforce deterministic ordering by descending bbox score, apply max_individuals only when set (don't implicitly truncate), and return arrays as float32 without unnecessary copies. Adjust empty/normalized prediction behavior: _empty_prediction emits zero rows when max_individuals is unspecified and fixed-size padded outputs when it is set; _normalize_prediction only pads bodyparts when max_individuals is provided.

Refactor DetectorToPoseInferenceRunner.inference to simplify flow and delegate responsibilities to the pose runner. Inputs are split into raw_images and incoming_contexts using clearer comprehensions; the detector now receives raw images only. Incoming context dictionaries are copied to avoid mutating caller-owned data. Error formatting was improved. Removed the wrapper's internal normalization, empty-prediction handling, and shelf_writer logic; the wrapper now returns pose_runner.inference(enriched_inputs, shelf_writer=shelf_writer) and relies on the pose runner for preprocessing, prediction, postprocessing, and shelf writing.

Update test to clarify that the detector should receive raw image inputs only while incoming context is preserved and forwarded to the pose runner after bbox injection. Adjust the assertion to expect the specific image list (including a Path for the second image) and update the explanatory comment.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Minor style cleanup with no behavioral changes.

- Removed a stray trailing blank line in deeplabcut/pose_estimation_pytorch/data/dlcloader.py.
- Reflowed multi-line f-strings and the long type annotation in deeplabcut/pose_estimation_pytorch/runners/inference.py into single-line statements to improve readability and satisfy linters.

These edits are purely formatting and do not change runtime logic.

Index precomputed bbox entries by normalized image path for fast lookup and detect duplicate entries. Normalize paths using POSIX form and lowercase for comparison, and add a suffix-based fallback matcher that errors on ambiguous matches. Add helpers to extract image paths from inputs and to find matches by suffix. Update inference to prefer path-based matching (with informative errors and an order-only fallback for ndarray inputs) and adjust target_format typing from str to BBoxFormat.

Add unit tests for PrecomputedDetectorRunner to verify path-based subset lookup, that inference preserves the requested image order, and that a ValueError is raised when a requested path is missing. Tests construct BBoxes/BBoxEntry fixtures with image_path values and call PrecomputedDetectorRunner.from_bboxes(...), then assert returned bboxes and bbox_scores match expected values and ordering.

Improve TrainingRunner._gpu_usage_str by checking torch.cuda.is_available() and passing the current device to torch.cuda.memory_reserved and torch.cuda.get_device_properties. This avoids querying GPU 0 implicitly and prevents errors on non-CUDA or multi-GPU setups; also removes leftover commented-out code.

Extract data config and add explicit handling for precomputed detector bboxes. When training a TOP_DOWN task with data.bbox_source='detection_bbox', require data.precomputed_bboxes to be configured (raise ValueError if missing) and use bbox_validate_image_paths as before. If precomputed_bboxes are present but bbox_source is not 'detection_bbox', emit an info log that the precomputed boxes will be ignored. This avoids silent misconfiguration and clarifies expected config fields.