[](README.md)
<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>[](https://www.gnu.org/licenses/lgpl-3.0)
# DLClibrary
DLClibrary is a lightweight library supporting universal functions for the [DeepLabCut](https://github.com/DeepLabCut/DeepLabCut) ecosystem.
Supported functions (at this point):
- API for downloading model weights from [the model zoo](http://www.mackenziemathislab.org/dlc-modelzoo)
# Quick start
## Install
The package can be installed using `pip`:
```bash
pip install dlclibrary
```
:warning: warning, the closely named package `dlclib` is not an official DeepLabCut product. :warning:
## Example Usage
Downloading a pretrained model from the model zoo:
```python
from pathlib import Path
from dlclibrary import download_huggingface_model
# Creates a folder and downloads the model to it
model_dir = Path("./superanimal_quadruped_model")
model_dir.mkdir()
download_huggingface_model("superanimal_quadruped", model_dir)
```
PyTorch models available for a given dataset (compatible with DeepLabCut>=3.0) can be
listed using the `dlclibrary.get_available_detectors` and
`dlclibrary.get_available_models` methods. The datasets for which models are available
can be listed using `dlclibrary.get_available_datasets`. Example use:
```python
>>> import dlclibrary
>>> dlclibrary.get_available_datasets()
['superanimal_bird', 'superanimal_topviewmouse', 'superanimal_quadruped']
>>> dlclibrary.get_available_detectors("superanimal_bird")
['fasterrcnn_mobilenet_v3_large_fpn', 'ssdlite']
>>> dlclibrary.get_available_models("superanimal_bird")
['resnet_50']
```
## How to add a new model?
### TensorFlow models
Pick a good model_name. Follow the (novel) naming convention (modeltype_species), e.g. ```superanimal_topviewmouse```.
1. Add the model_name with path and commit ID to: https://github.com/DeepLabCut/DLClibrary/blob/main/dlclibrary/dlcmodelzoo/modelzoo_urls.yaml
2. Add the model name to the constant: MODELOPTIONS
https://github.com/DeepLabCut/DLClibrary/blob/main/dlclibrary/dlcmodelzoo/modelzoo_download.py#L15
3. For superanimal models also fill in the configs!
### PyTorch models (for `deeplabcut >= 3.0.0`)
PyTorch models are listed in [`dlclibrary/dlcmodelzoo/modelzoo_urls_pytorch.yaml`](
https://github.com/DeepLabCut/DLClibrary/blob/main/dlclibrary/dlcmodelzoo/modelzoo_urls_pytorch.yaml
). The file is organized as:
```yaml
my_cool_dataset: # name of the dataset used to train the model
detectors:
detector_name: path/to/huggingface-detector.pt # add detectors under `detector`
pose_models:
pose_model_name: path/to/huggingface-pose-model.pt # add pose models under `pose_models`
other_pose_model_name: path/to/huggingface-other-pose-model.pt
```
This will allow users to download the models using the format `datatsetName_modelName`,
i.e. for this example 3 models would be available: `my_cool_dataset_detector_name`,
`my_cool_dataset_pose_model_name` and `my_cool_dataset_other_pose_model_name`.
To add a new model for `deeplabcut >= 3.0.0`, simply:
- add a new line under detectors or pose models if the dataset is already defined
- add the structure if the model was trained on a new dataset
The models will then be listed when calling `dlclibrary.get_available_detectors` or
`dlclibrary.get_available_models`! You can list the datasets for which models are
available using `dlclibrary.get_available_datasets`.
Raw data
{
"_id": null,
"home_page": "https://github.com/DeepLabCut/DLClib",
"name": "dlclibrary",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "A. & M. Mathis Labs",
"author_email": "alexander@deeplabcut.org",
"download_url": "https://files.pythonhosted.org/packages/75/e1/e57d379ee40777834332ed6577d267ad2563db2f3542b7d016b91078358b/dlclibrary-0.0.11.tar.gz",
"platform": null,
"description": "[](README.md)\n<a href=\"https://github.com/psf/black\"><img alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"></a>[](https://www.gnu.org/licenses/lgpl-3.0)\n\n# DLClibrary\n\nDLClibrary is a lightweight library supporting universal functions for the [DeepLabCut](https://github.com/DeepLabCut/DeepLabCut) ecosystem.\n\nSupported functions (at this point):\n\n- API for downloading model weights from [the model zoo](http://www.mackenziemathislab.org/dlc-modelzoo)\n\n# Quick start\n\n## Install\n\nThe package can be installed using `pip`:\n\n```bash\npip install dlclibrary\n```\n\n:warning: warning, the closely named package `dlclib` is not an official DeepLabCut product. :warning:\n\n## Example Usage\n\nDownloading a pretrained model from the model zoo:\n\n```python\nfrom pathlib import Path\nfrom dlclibrary import download_huggingface_model\n\n# Creates a folder and downloads the model to it\nmodel_dir = Path(\"./superanimal_quadruped_model\")\nmodel_dir.mkdir()\ndownload_huggingface_model(\"superanimal_quadruped\", model_dir)\n```\n\nPyTorch models available for a given dataset (compatible with DeepLabCut>=3.0) can be \nlisted using the `dlclibrary.get_available_detectors` and \n`dlclibrary.get_available_models` methods. The datasets for which models are available\ncan be listed using `dlclibrary.get_available_datasets`. Example use:\n\n```python\n>>> import dlclibrary\n>>> dlclibrary.get_available_datasets()\n['superanimal_bird', 'superanimal_topviewmouse', 'superanimal_quadruped']\n\n>>> dlclibrary.get_available_detectors(\"superanimal_bird\")\n['fasterrcnn_mobilenet_v3_large_fpn', 'ssdlite']\n\n>>> dlclibrary.get_available_models(\"superanimal_bird\")\n['resnet_50']\n```\n\n\n## How to add a new model?\n\n### TensorFlow models\n\nPick a good model_name. Follow the (novel) naming convention (modeltype_species), e.g. ```superanimal_topviewmouse```. \n\n1. Add the model_name with path and commit ID to: https://github.com/DeepLabCut/DLClibrary/blob/main/dlclibrary/dlcmodelzoo/modelzoo_urls.yaml\n\n2. Add the model name to the constant: MODELOPTIONS\nhttps://github.com/DeepLabCut/DLClibrary/blob/main/dlclibrary/dlcmodelzoo/modelzoo_download.py#L15\n\n3. For superanimal models also fill in the configs!\n\n### PyTorch models (for `deeplabcut >= 3.0.0`)\n\nPyTorch models are listed in [`dlclibrary/dlcmodelzoo/modelzoo_urls_pytorch.yaml`](\nhttps://github.com/DeepLabCut/DLClibrary/blob/main/dlclibrary/dlcmodelzoo/modelzoo_urls_pytorch.yaml\n). The file is organized as:\n\n```yaml\nmy_cool_dataset: # name of the dataset used to train the model\n detectors:\n detector_name: path/to/huggingface-detector.pt # add detectors under `detector`\n pose_models:\n pose_model_name: path/to/huggingface-pose-model.pt # add pose models under `pose_models`\n other_pose_model_name: path/to/huggingface-other-pose-model.pt\n```\n\nThis will allow users to download the models using the format `datatsetName_modelName`,\ni.e. for this example 3 models would be available: `my_cool_dataset_detector_name`,\n`my_cool_dataset_pose_model_name` and `my_cool_dataset_other_pose_model_name`.\n\nTo add a new model for `deeplabcut >= 3.0.0`, simply:\n\n- add a new line under detectors or pose models if the dataset is already defined\n- add the structure if the model was trained on a new dataset \n\nThe models will then be listed when calling `dlclibrary.get_available_detectors` or\n`dlclibrary.get_available_models`! You can list the datasets for which models are \navailable using `dlclibrary.get_available_datasets`.\n",
"bugtrack_url": null,
"license": null,
"summary": "Lightweight library supporting universal functions for the DeepLabCut ecosystem",
"version": "0.0.11",
"project_urls": {
"Homepage": "https://github.com/DeepLabCut/DLClib"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "55f4618b7c088e6c07ff4d64621fa4ee45a02ca766b81698625f6888e4ce3de0",
"md5": "3a112d61941a6678cabd475509ce4865",
"sha256": "b1a774d8e4ba54e87c0b6041983c1c3babf69ad02b8f8f4801392637e5553da4"
},
"downloads": -1,
"filename": "dlclibrary-0.0.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3a112d61941a6678cabd475509ce4865",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 17450,
"upload_time": "2025-09-04T15:33:45",
"upload_time_iso_8601": "2025-09-04T15:33:45.910369Z",
"url": "https://files.pythonhosted.org/packages/55/f4/618b7c088e6c07ff4d64621fa4ee45a02ca766b81698625f6888e4ce3de0/dlclibrary-0.0.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "75e1e57d379ee40777834332ed6577d267ad2563db2f3542b7d016b91078358b",
"md5": "d0f36373e0813869040d2c0f81db1f26",
"sha256": "2483a8c2c0cefb1c6defd1c4afd0095bf9bd956204241d102231101f08f21d98"
},
"downloads": -1,
"filename": "dlclibrary-0.0.11.tar.gz",
"has_sig": false,
"md5_digest": "d0f36373e0813869040d2c0f81db1f26",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12036,
"upload_time": "2025-09-04T15:33:46",
"upload_time_iso_8601": "2025-09-04T15:33:46.969662Z",
"url": "https://files.pythonhosted.org/packages/75/e1/e57d379ee40777834332ed6577d267ad2563db2f3542b7d016b91078358b/dlclibrary-0.0.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-04 15:33:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DeepLabCut",
"github_project": "DLClib",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "huggingface_hub",
"specs": [
[
"==",
"0.11.1"
]
]
},
{
"name": "ruamel.yaml",
"specs": [
[
"==",
"0.17.21"
]
]
}
],
"lcname": "dlclibrary"
}
JSON
