Refactor `ctd_conditions` / `conditions_provider` + add `ConditionsConfig` + fix `InferenceConfig` by deruyter92 · Pull Request #3387 · DeepLabCut/DeepLabCut

deruyter92 · 2026-07-10T08:34:25Z

Issues
This PR addresses two issues with the way conditions are specified for inference with a BUCTD model:

With the introduction of typed configs, the InferenceConfig was too simplified: different schemas can be used to specify the conditions, but only a plain (unvalidated) dict was supported.
The implementation of CondProvider in pose_estimation_pytorch/data/ctd.py was slightly incorrect and misleading:
- the two subclasses CondFromFile and CondFromModel serve a different thing (either a provider that can read conditions from a file, or just a config object that still needs downstream loading of the BU model).
- CondProvider was denoted as abstract base class, but both subclasses call super(). on the parent methods.
- inference API required the CondFromModel configuration or a dict, which now should be replaced with a proper DLCBaseConfig instance.

Implementation

This PR introduces a ConditionsConfiguration schema with two subclasses ConditionsFileConfig and ConditionsModelConfig to solve the oversimplified schema design.
The implementation of CondProvider is refactored: only CondFromFile is kept, as it literally provides conditions from a file. The CondFromModel configuration class is replaced with ConditionsModelConfig.
inference API is refactored to accept ConditionsConfig or their raw arguments, and normalized + validated at the beginning.

Refactor type InferenceConfig.conditions with ConditionsConfig union Replace the untyped `dict[str, Any] | None` conditions field with a proper typed hierarchy: `ConditionsConfig` base class with `ConditionsFileConfig` (filepath only) and `ConditionsModelConfig` (direct paths or DLC shuffle shorthand) subclasses. A `ConditionsConfig.build()` classmethod normalizes any raw YAML input (str, Path, dict) into the correct subtype. - Add `config/ctd_conditions.py` with the three config classes - Update `InferenceConfig.conditions` to `ConditionsModelConfig | ConditionsFileConfig | None` with a `mode="before"` field validator calling `ConditionsConfig.build()` - Refactor `get_condition_provider()` to accept `ConditionsModelConfig | dict` and use `ConditionsConfig.build()` instead of ad-hoc dict inspection - Fix bug in `CondFromModel.__init__`: `snapshot_path` was incorrectly assigned `Path(config_path)` instead of `Path(snapshot_path)`

CondProvider was denoted as abstract class, but was no abstract in practice since both subclasses call its methods. The helper is a cleaner way to achieve the same.

… if applicable

- remove CondFromModel: it was just a config. Now replaced with ConditionsModelConfig - remove get_condition_provider: it was just a wrapper to initialize CondFromModel, which is now centralized in ConditionsModelConfig

Add ConditionsConfig subtype for unresolved shuffle-references. And hook-up ModelConfig.resolve_from_conditions().

deruyter92 · 2026-07-10T13:45:15Z

Edit
now added a third schema subclass which was accepted in the original design as well: ConditionsShuffleConfig for shuffle references that are not yet resolved to a model snapshot on disk. I added a resolve_from_conditions method to do the canonical resolution to a ConditionModelConfig (which finds the snapshot on disk) for BUCTD live inference.

C-Achard

I think this is a very good start, and indeed good to harden this a bit.

There are still a few things that may be worth clarifying:

Should we wrap the old CondFromModel with a deprecated constructor that routes to the new builder? Or not worth it as internal API/too much effort for the payoff
resolve_from_conditions is very nice to expose capabilities from the schema. It may be worth making the supported capabilities of each condition source more explicit, either in the documentation or through routing in the code, to make future refactors easier

Adding tests (which might already be done or planned) would be very helpful too.

- Only when task is COND_TOP_DOWN. - falsey values "", {} etc should not silently fall back to model_cfg.inference.conditions

This function is just used internally, does not require a project config and uses resolved model snapshots etc,. Since not all ConditionsConfigurations (e.g. shuffle) can be resolved without a projectconfig, and since resolution already happens in upstream funcitons it is more clean to strictly accept ConditionsModelConfig here.

…onfig or ConditionsModelConfig, not ConditionsFileConfig.

…onfigs

C-Achard · 2026-07-14T13:22:53Z

@deruyter92 I'm fixing the fast lane in another PR, sorry for the CI fails

Correctly reflect the available subtypes of ConditionsConfig for analysis or live inference

…r assertion

- remove circular assertion - add missing tests (e.g. DLCLoader injects) - format parametrized input as pytest.param for more clarity

deruyter92 · 2026-07-15T08:02:03Z

@C-Achard thanks again for your initial review. I've addressed your comments and made some extra adjustments:

added tests
improved public API that accepts raw input forms for ConditionsModelConfig / ConditionsShuffleConfig and its raw form (dict)
improved docstrings and documentation for the distinction between ConditionsFileConfig (only used for evaluation) and ConditionsModelConfig / ConditionsShuffleConfig (used for live-inference; caches results in a file as well)

We should probably discuss whether it is worth to add the option of using precomputed conditions via ConditionsFileConfig / CondFromFile for inference as well. I completely agree with your earlier comment that this would feel natural, but I think it requires a substantial adjustment to the current implementation: now inference always assumes that unseen images can be passed and conditions are computed on the fly using the BU model (no-precomputed conditions available). The conditions are however cached, so the next time inference is run, the BU model will be skipped for existing images with the same scorer.

Let me know if you think this adjustment would still be worth it, or if you think that caching is sufficient for now.

C-Achard

Thanks for all the updates!

C-Achard · 2026-07-15T12:35:48Z

I think it requires a substantial adjustment to the current implementation: now inference always assumes that unseen images can be passed and conditions are computed on the fly using the BU model (no-precomputed conditions available)

Let's leave it out then

deruyter92 added 8 commits July 9, 2026 16:09

refactor data/ctd.py: replace get_loader_and_snapshot with helper.

d698c85

refactor data/ctd.py: remove ABC CondProvider

c13f25f

CondProvider was denoted as abstract class, but was no abstract in practice since both subclasses call its methods. The helper is a cleaner way to achieve the same.

refactor ConditionsConfig: add build from shuffle

986ac8d

refactor ConditionsConfig: clean up build constructors

73f0d77

Add affords_bu_inference property to ConditionsConfig

77807e2

refactor callers with ctd_conditions: use normalized ConditionsConfig…

67229b9

… if applicable

refactor data/ctd.py and apis/ctd.py

0660100

- remove CondFromModel: it was just a config. Now replaced with ConditionsModelConfig - remove get_condition_provider: it was just a wrapper to initialize CondFromModel, which is now centralized in ConditionsModelConfig

deruyter92 changed the title ~~Refactor ctd_conditions / conditions_provider + add ConditionsConfig + fix InferenceConfig~~ Refactor ctd_conditions / conditions_provider + add ConditionsConfig + fix InferenceConfig Jul 10, 2026

deruyter92 requested a review from C-Achard July 10, 2026 08:34

add ConditionsShuffleConfig and resolve_from_conditions()

8553294

Add ConditionsConfig subtype for unresolved shuffle-references. And hook-up ModelConfig.resolve_from_conditions().

C-Achard reviewed Jul 13, 2026

View reviewed changes

deruyter92 added 5 commits July 14, 2026 13:38

refactor analyze_images: clean normalization of ctd_conditions

3ebd7b0

- Only when task is COND_TOP_DOWN. - falsey values "", {} etc should not silently fall back to model_cfg.inference.conditions

refactor analyze_videos and analyze_images (strict ConditionsShuffleC…

35cf90a

…onfig or ConditionsModelConfig, not ConditionsFileConfig.

add missing shuffle literal

38cca93

Fix load_conditions_for_evaluation: add support for Typed ConditionsC…

b87c970

…onfigs

deruyter92 added 5 commits July 14, 2026 15:43

Improve docstrings and function signatures

3592b16

Correctly reflect the available subtypes of ConditionsConfig for analysis or live inference

add tests for ctd conditions configurations

03036d9

remove unused property "affords_bu_inference"

047dfa4

refactor tests_ctd_conditions, improve variable names and fix circula…

c37fc07

…r assertion

update test_ctd_conditions

9642add

- remove circular assertion - add missing tests (e.g. DLCLoader injects) - format parametrized input as pytest.param for more clarity

deruyter92 marked this pull request as ready for review July 15, 2026 07:53

C-Achard approved these changes Jul 15, 2026

View reviewed changes

deruyter92 mentioned this pull request Jul 15, 2026

Fix CondFromModel loading the config path as its snapshot #3402

Closed

MMathisLab self-requested a review July 17, 2026 17:20

MMathisLab approved these changes Jul 17, 2026

View reviewed changes

AlexEMG approved these changes Jul 18, 2026

View reviewed changes

Merge branch 'main' into jaap/fix_ctd_conditions_config

7a36f4a

deruyter92 merged commit 6a181fd into main Jul 20, 2026
4 of 5 checks passed

deruyter92 deleted the jaap/fix_ctd_conditions_config branch July 20, 2026 12:15

deruyter92 mentioned this pull request Jul 20, 2026

version bump 3.0.1 #3423

Merged

9 tasks

Navigation Menu

Uh oh!

Uh oh!

Refactor `ctd_conditions` / `conditions_provider` + add `ConditionsConfig` + fix `InferenceConfig` - #3387

Refactor `ctd_conditions` / `conditions_provider` + add `ConditionsConfig` + fix `InferenceConfig`#3387
deruyter92 merged 20 commits into
mainfrom
jaap/fix_ctd_conditions_config

deruyter92 commented Jul 10, 2026

Uh oh!

deruyter92 commented Jul 10, 2026 •

edited

Loading

Uh oh!

C-Achard left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

C-Achard commented Jul 14, 2026

Uh oh!

deruyter92 commented Jul 15, 2026

Uh oh!

C-Achard left a comment

Uh oh!

C-Achard commented Jul 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Uh oh!

Conversation

deruyter92 commented Jul 10, 2026

Uh oh!

deruyter92 commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

C-Achard left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

C-Achard commented Jul 14, 2026

Uh oh!

deruyter92 commented Jul 15, 2026

Uh oh!

C-Achard left a comment

Choose a reason for hiding this comment

Uh oh!

C-Achard commented Jul 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

deruyter92 commented Jul 10, 2026 •

edited

Loading

C-Achard left a comment •

edited

Loading