deeplabcut.modelzoo.utils

Functions:

Name	Description
create_conversion_table	Creates a conversion table mapping bodyparts defined for a DeepLabCut project to
dlc_modelzoo_path	Returns: the path to the modelzoo folder in the DeepLabCut installation
get_conversion_table	Gets the conversion table from a project to a SuperAnimal model.
get_super_animal_project_cfg	Gets the project configuration file for a SuperAnimal model.
get_super_animal_scorer	Args:
parse_project_model_name	Parses model zoo model names for SuperAnimal models.

create_conversion_table

create_conversion_table(
    config: str | Path, super_animal: str, project_to_super_animal: dict[str, str]
) -> ConversionTable

Creates a conversion table mapping bodyparts defined for a DeepLabCut project to bodyparts defined for a SuperAnimal model. This allows to fine-tune SuperAnimal weights instead of transfer learning from ImageNet. The conversion table is directly added to the project's configuration file.

Parameters:

Name	Type	Description	Default
config	str | Path	The path to the project configuration for which the conversion table should be created.	required
super_animal	str	The SuperAnimal model for the conversion table	required
project_to_super_animal	dict[str, str]	The conversion table mapping each project bodypart to the corresponding SuperAnimal bodypart.	required

Returns:

Type	Description
ConversionTable	The conversion table that was added to the project config.

Raises:

Type	Description
ValueError	If the conversion table is misconfigured (e.g., if there are misnamed bodyparts in the table). See ConversionTable for more.

Source code in deeplabcut/modelzoo/utils.py

def create_conversion_table(
    config: str | Path,
    super_animal: str,
    project_to_super_animal: dict[str, str],
) -> ConversionTable:
    """Creates a conversion table mapping bodyparts defined for a DeepLabCut project to
    bodyparts defined for a SuperAnimal model. This allows to fine-tune SuperAnimal
    weights instead of transfer learning from ImageNet. The conversion table is directly
    added to the project's configuration file.

    Args:
        config: The path to the project configuration for which the conversion table
            should be created.
        super_animal: The SuperAnimal model for the conversion table
        project_to_super_animal: The conversion table mapping each project bodypart
            to the corresponding SuperAnimal bodypart.

    Returns:
        The conversion table that was added to the project config.

    Raises:
         ValueError: If the conversion table is misconfigured (e.g., if there are
            misnamed bodyparts in the table). See ConversionTable for more.
    """
    cfg = read_config(str(config))
    sa_cfg = get_super_animal_project_cfg(super_animal)
    conversion_table = ConversionTable(
        super_animal=super_animal,
        project_bodyparts=get_bodyparts(cfg),
        super_animal_bodyparts=sa_cfg["bodyparts"],
        table=project_to_super_animal,
    )

    conversion_tables = cfg.get("SuperAnimalConversionTables")
    if conversion_tables is None:
        conversion_tables = {}

    conversion_tables[super_animal] = conversion_table.table
    cfg["SuperAnimalConversionTables"] = conversion_tables
    write_config(str(config), cfg)
    return conversion_table

dlc_modelzoo_path

dlc_modelzoo_path() -> Path

Returns: the path to the modelzoo folder in the DeepLabCut installation

Source code in deeplabcut/modelzoo/utils.py

def dlc_modelzoo_path() -> Path:
    """Returns: the path to the `modelzoo` folder in the DeepLabCut installation"""
    dlc_root_path = Path(get_deeplabcut_path())
    return dlc_root_path / "modelzoo"

get_conversion_table

get_conversion_table(cfg: dict | str | Path, super_animal: str) -> ConversionTable

Gets the conversion table from a project to a SuperAnimal model.

Parameters:

Name	Type	Description	Default
cfg	dict | str | Path	The path to a project configuration file, or directly the project config.	required
super_animal	str	The SuperAnimal for which to get the configuration file.	required

Returns:

Type	Description
ConversionTable	A dictionary mapping {project_bodypart: super_animal_bodypart}

Raises:

Type	Description
ValueError	If the conversion table is misconfigured (e.g., if there are misnamed bodyparts in the table). See ConversionTable for more.

Source code in deeplabcut/modelzoo/utils.py

def get_conversion_table(cfg: dict | str | Path, super_animal: str) -> ConversionTable:
    """Gets the conversion table from a project to a SuperAnimal model.

    Args:
        cfg: The path to a project configuration file, or directly the project config.
        super_animal: The SuperAnimal for which to get the configuration file.

    Returns:
        A dictionary mapping {project_bodypart: super_animal_bodypart}

    Raises:
        ValueError: If the conversion table is misconfigured (e.g., if there are
            misnamed bodyparts in the table). See ConversionTable for more.
    """
    if isinstance(cfg, (str, Path)):
        cfg = read_config(str(cfg))

    conversion_tables = cfg.get("SuperAnimalConversionTables", {})
    if conversion_tables is None or super_animal not in conversion_tables:
        raise ValueError(
            f"No conversion table defined in the project config for {super_animal}."
            "Call deeplabcut.modelzoo.create_conversion_table to create one."
        )

    sa_cfg = get_super_animal_project_cfg(super_animal)
    conversion_table = ConversionTable(
        super_animal=super_animal,
        project_bodyparts=get_bodyparts(cfg),
        super_animal_bodyparts=sa_cfg["bodyparts"],
        table=conversion_tables[super_animal],
    )
    return conversion_table

get_super_animal_project_cfg

get_super_animal_project_cfg(super_animal: str) -> dict

Gets the project configuration file for a SuperAnimal model.

Parameters:

Name	Type	Description	Default
super_animal	str	the name of the SuperAnimal model for which to load the project configuration	required

Returns:

Type	Description
dict	the project configuration for the given SuperAnimal model

Source code in deeplabcut/modelzoo/utils.py

def get_super_animal_project_cfg(super_animal: str) -> dict:
    """Gets the project configuration file for a SuperAnimal model.

    Args:
        super_animal: the name of the SuperAnimal model for which to load the project
            configuration

    Returns:
        the project configuration for the given SuperAnimal model

    Raises:
        ValueError if no such SuperAnimal is found
    """
    project_configs_dir = dlc_modelzoo_path() / "project_configs"
    super_animal_projects = {p.stem: p for p in project_configs_dir.iterdir()}
    if super_animal not in super_animal_projects:
        raise ValueError(
            f"No such SuperAnimal model: {super_animal}. Available SuperAnimal models "
            f"are {', '.join(super_animal_projects.keys())}."
        )

    return read_config_as_dict(super_animal_projects[super_animal])

get_super_animal_scorer

get_super_animal_scorer(
    super_animal: str,
    model_snapshot_path: Path | str,
    detector_snapshot_path: Path | str | None,
    torchvision_detector_name: str | None = None,
) -> str

Parameters:

Name	Type	Description	Default
super_animal	str	The SuperAnimal dataset on which the models were trained	required
model_snapshot_path	Path | str	The path for the SuperAnimal pose model snapshot	required
detector_snapshot_path	Path | str | None	The path for the SuperAnimal detector snapshot, if a detector is being used.	required
torchvision_detector_name	str | None	The name of a pretrained COCO detector from torchvision, if such a detector is used instead of a snapshot.	None

Returns:

Type	Description
str	The DLC scorer name to use for the given SuperAnimal models.

Source code in deeplabcut/modelzoo/utils.py

def get_super_animal_scorer(
    super_animal: str,
    model_snapshot_path: Path | str,
    detector_snapshot_path: Path | str | None,
    torchvision_detector_name: str | None = None,
) -> str:
    """
    Args:
        super_animal: The SuperAnimal dataset on which the models were trained
        model_snapshot_path: The path for the SuperAnimal pose model snapshot
        detector_snapshot_path: The path for the SuperAnimal detector snapshot, if a
            detector is being used.
        torchvision_detector_name: The name of a pretrained COCO detector from torchvision,
            if such a detector is used instead of a snapshot.

    Returns:
        The DLC scorer name to use for the given SuperAnimal models.
    """
    if detector_snapshot_path is not None and torchvision_detector_name is not None:
        raise ValueError("Provide only one of `detector_snapshot_path` or `torchvision_detector_name`, not both.")
    super_animal_prefix = super_animal + "_"
    # Always use model name first
    model_name = Path(model_snapshot_path).stem
    if model_name.startswith(super_animal_prefix):
        model_name = model_name[len(super_animal_prefix) :]
    dlc_scorer = f"{super_animal_prefix}{model_name}"

    # Then add detector name if provided
    if detector_snapshot_path is not None:
        detector_name = Path(detector_snapshot_path).stem
        if detector_name.startswith(super_animal_prefix):
            detector_name = detector_name[len(super_animal_prefix) :]
        dlc_scorer += f"_{detector_name}"
    elif torchvision_detector_name is not None:
        dlc_scorer += f"_{torchvision_detector_name}"

    return dlc_scorer

parse_project_model_name

parse_project_model_name(superanimal_name: str) -> tuple[str, str]

Parses model zoo model names for SuperAnimal models.

Parameters:

Name	Type	Description	Default
superanimal_name	str	the name of the SuperAnimal model name to parse	required

Returns:

Name	Type	Description
project_name	tuple[str, str]	the parsed SuperAnimal model name model_name: the model architecture (e.g., dlcrnet, hrnetw32)

Source code in deeplabcut/modelzoo/utils.py

def parse_project_model_name(superanimal_name: str) -> tuple[str, str]:
    """Parses model zoo model names for SuperAnimal models.

    Args:
        superanimal_name: the name of the SuperAnimal model name to parse

    Returns:
        project_name: the parsed SuperAnimal model name
        model_name: the model architecture (e.g., dlcrnet, hrnetw32)
    """

    if superanimal_name == "superanimal_quadruped":
        warnings.warn(
            f"{superanimal_name} is deprecated and will be removed in a future version. Use"
            f"{superanimal_name}_model_suffix instead.",
            DeprecationWarning,
            stacklevel=2,
        )
        superanimal_name = "superanimal_quadruped_hrnetw32"

    if superanimal_name == "superanimal_topviewmouse":
        warnings.warn(
            f"{superanimal_name} is deprecated and will be removed in a future version. Use"
            f"{superanimal_name}_model_suffix instead.",
            DeprecationWarning,
            stacklevel=2,
        )
        superanimal_name = "superanimal_topviewmouse_dlcrnet"

    model_name = superanimal_name.split("_")[-1]
    project_name = superanimal_name.replace(f"_{model_name}", "")

    dlc_root_path = get_deeplabcut_path()
    modelzoo_path = os.path.join(dlc_root_path, "modelzoo")

    available_model_configs = glob(os.path.join(modelzoo_path, "model_configs", "*.yaml"))
    available_models = [os.path.splitext(os.path.basename(path))[0] for path in available_model_configs]

    if model_name not in available_models:
        raise ValueError(f"Model {model_name} not found. Available models are: {available_models}")

    available_project_configs = glob(os.path.join(modelzoo_path, "project_configs", "*.yaml"))
    [os.path.splitext(os.path.basename(path))[0] for path in available_project_configs]

    return project_name, model_name