| Name | wildlife-tools JSON |
| Version |
0.0.9
JSON |
| download |
| home_page | |
| Summary | Tools for using wildlife re-identification datasets. |
| upload_time | 2024-01-26 08:30:13 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2023 Vojtěch Čermák Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
wildlife
re-identification
datasets
machine learning
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<a href="https://github.com/WildlifeDatasets/wildlife-tools/issues"><img src="https://img.shields.io/github/issues/WildlifeDatasets/wildlife-tools" alt="GitHub issues"></a>
<a href="https://github.com/WildlifeDatasets/wildlife-tools/pulls"><img src="https://img.shields.io/github/issues-pr/WildlifeDatasets/wildlife-tools" alt="GitHub pull requests"></a>
<a href="https://github.com/WildlifeDatasets/wildlife-tools/graphs/contributors"><img src="https://img.shields.io/github/contributors/WildlifeDatasets/wildlife-tools" alt="GitHub contributors"></a>
<a href="https://github.com/WildlifeDatasets/wildlife-tools/network/members"><img src="https://img.shields.io/github/forks/WildlifeDatasets/wildlife-tools" alt="GitHub forks"></a>
<a href="https://github.com/WildlifeDatasets/wildlife-tools/stargazers"><img src="https://img.shields.io/github/stars/WildlifeDatasets/wildlife-tools" alt="GitHub stars"></a>
<a href="https://github.com/WildlifeDatasets/wildlife-tools/watchers"><img src="https://img.shields.io/github/watchers/WildlifeDatasets/wildlife-tools" alt="GitHub watchers"></a>
<a href="https://github.com/WildlifeDatasets/wildlife-tools/blob/main/LICENSE"><img src="https://img.shields.io/github/license/WildlifeDatasets/wildlife-tools" alt="License"></a>
</p>
<div align="center">
<img src="resources/logo-transparent.png" alt="Project logo" width="300">
<p align="center">A tool-kit for Wildlife Individual Identification that provides a wide variety of pre-trained models for inference and fine-tuning.</p>
<a href="https://wildlifedatasets.github.io/wildlife-tools/">Documentation</a>
·
<a href="https://github.com/WildlifeDatasets/wildlife-tools/issues/new?assignees=aerodynamic-sauce-pan&labels=bug&projects=&template=bug_report.md&title=%5BBUG%5D">Report Bug</a>
·
<a href="https://github.com/WildlifeDatasets/wildlife-tools/issues/new?assignees=aerodynamic-sauce-pan&labels=enhancement&projects=&template=enhancement.md&title=%5BEnhancement%5D">Request Feature</a>
</div>
</br >
## Our other projects
<div align="center">
<div style="display: flex; justify-content: center">
<div style="margin-right: 50px;">
<img src="resources/megadescriptor-logo.png" alt="Image 1" width="200" style="margin-bottom: 5px;">
<p><a href="https://huggingface.co/BVRA/MegaDescriptor-L-384">MegaDescriptor</a></p>
</div>
<div>
<img src="resources/datasets-logo.png" alt="Image 2" width="200" style="margin-bottom: 5px;"> <!-- Adjust margin as needed -->
<p><a href="https://huggingface.co/BVRA/MegaDescriptor-L-384">Wildlife Datasets</a></p>
</div>
</div>
</div>
<h1></h1>
# Introduction
The `wildlife-tools` library offers a simple interface for various tasks in the Wildlife Re-Identification domain. It covers use cases such as training, feature extraction, similarity calculation, image retrieval, and classification. It complements the `wildlife-datasets` library, which acts as dataset repository. All datasets there can be used in combination with `WildlifeDataset` component, which serves for loading extracting images and image tensors other tasks.
More information can be found in [Documentation](https://wildlifedatasets.github.io/wildlife-tools/)
## Installation
To install `wildlife-tools`, you can build it from scratch or use pre-build Pypi package.
### Using Pypi
```script
pip install wildlife-tools
```
### Building from scratch
Clone the repository using `git` and install it.
```script
git clone git@github.com:WildlifeDatasets/wildlife-tools.git
cd wildlife-tools
pip install -e .
```
## Modules in the in the `wildlife-tools`
- The `data` module provides tools for creating instances of the `WildlifeDataset`.
- The `train` module offers tools for fine-tuning feature extractors on the `WildlifeDataset`.
- The `features` module provides tools for extracting features from the `WildlifeDataset` using various extractors.
- The `similarity` module provides tools for constructing a similarity matrix from query and database features.
- The `inference` module offers tools for creating predictions using the similarity matrix.
## Relations between modules:
```mermaid
graph TD;
A[Data]-->|WildlifeDataset|B[Features]
A-->|WildlifeDataset|C;
C[Train]-->|finetuned extractor|B;
B-->|query and database features|D[Similarity]
D-->|similarity matrix|E[Inference]
```
## Example
### 1. Create `WildlifeDataset`
Using metadata from `wildlife-datasets`, create `WildlifeDataset` object for the MacaqueFaces dataset.
```Python
from wildlife_datasets.datasets import MacaqueFaces
from wildlife_tools.data import WildlifeDataset
import torchvision.transforms as T
metadata = MacaqueFaces('datasets/MacaqueFaces')
transform = T.Compose([T.Resize([224, 224]), T.ToTensor(), T.Normalize(mean=(0.485, 0.456, 0.406), std=(0.229, 0.224, 0.225))])
dataset = WildlifeDataset(metadata.df, metadata.root, transform=transform)
```
Optionally, split metadata into subsets. In this example, query is first 100 images and rest are in database.
```Python
dataset_database = WildlifeDataset(metadata.df.iloc[100:,:], metadata.root, transform=transform)
dataset_query = WildlifeDataset(metadata.df.iloc[:100,:], metadata.root, transform=transform)
```
### 2. Extract features
Extract features using MegaDescriptor Tiny, downloaded from HuggingFace hub.
```Python
from wildlife_tools.features import DeepFeatures
name = 'hf-hub:BVRA/MegaDescriptor-T-224'
extractor = DeepFeatures(timm.create_model(name, num_classes=0, pretrained=True))
query, database = extractor(dataset_query), extractor(dataset_database)
```
### 3. Calculate similarity
Calculate cosine similarity between query and database deep features.
```Python
from wildlife_tools.similarity import CosineSimilarity
similarity_function = CosineSimilarity()
similarity = similarity_function(query, database)
```
### 4. Evaluate
Use the cosine similarity in nearest neigbour classifier and get predictions.
```Python
classifier = KnnClassifier(k=1, database_labels=dataset_database.labels_string)
predictions = classifier(similarity['cosine'])
accuracy = np.mean(dataset_database.labels_string == predictions)
```
## Citation
If you like our package, please cite us.
```
@InProceedings{Cermak_2024_WACV,
author = {\v{C}erm\'ak, Vojt\v{e}ch and Picek, Luk\'a\v{s} and Adam, Luk\'a\v{s} and Papafitsoros, Kostas},
title = {{WildlifeDatasets: An Open-Source Toolkit for Animal Re-Identification}},
booktitle = {Proceedings of the IEEE/CVF Winter Conference on Applications of Computer Vision (WACV)},
month = {January},
year = {2024},
pages = {5953-5963}
}
```
Raw data
{
"_id": null,
"home_page": "",
"name": "wildlife-tools",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Vojt\u011bch \u010cerm\u00e1k <cermak.vojtech@seznam.cz>",
"keywords": "wildlife,re-identification,datasets,machine learning",
"author": "",
"author_email": "Vojt\u011bch \u010cerm\u00e1k <cermak.vojtech@seznam.cz>",
"download_url": "https://files.pythonhosted.org/packages/4d/71/09a64ca02da9d4f4cbd75a02ec934904ea1a69aa5cbf26e9e5f53f37e2da/wildlife-tools-0.0.9.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <a href=\"https://github.com/WildlifeDatasets/wildlife-tools/issues\"><img src=\"https://img.shields.io/github/issues/WildlifeDatasets/wildlife-tools\" alt=\"GitHub issues\"></a>\n <a href=\"https://github.com/WildlifeDatasets/wildlife-tools/pulls\"><img src=\"https://img.shields.io/github/issues-pr/WildlifeDatasets/wildlife-tools\" alt=\"GitHub pull requests\"></a>\n <a href=\"https://github.com/WildlifeDatasets/wildlife-tools/graphs/contributors\"><img src=\"https://img.shields.io/github/contributors/WildlifeDatasets/wildlife-tools\" alt=\"GitHub contributors\"></a>\n <a href=\"https://github.com/WildlifeDatasets/wildlife-tools/network/members\"><img src=\"https://img.shields.io/github/forks/WildlifeDatasets/wildlife-tools\" alt=\"GitHub forks\"></a>\n <a href=\"https://github.com/WildlifeDatasets/wildlife-tools/stargazers\"><img src=\"https://img.shields.io/github/stars/WildlifeDatasets/wildlife-tools\" alt=\"GitHub stars\"></a>\n <a href=\"https://github.com/WildlifeDatasets/wildlife-tools/watchers\"><img src=\"https://img.shields.io/github/watchers/WildlifeDatasets/wildlife-tools\" alt=\"GitHub watchers\"></a>\n <a href=\"https://github.com/WildlifeDatasets/wildlife-tools/blob/main/LICENSE\"><img src=\"https://img.shields.io/github/license/WildlifeDatasets/wildlife-tools\" alt=\"License\"></a>\n</p>\n\n<div align=\"center\">\n <img src=\"resources/logo-transparent.png\" alt=\"Project logo\" width=\"300\">\n <p align=\"center\">A tool-kit for Wildlife Individual Identification that provides a wide variety of pre-trained models for inference and fine-tuning.</p>\n <a href=\"https://wildlifedatasets.github.io/wildlife-tools/\">Documentation</a>\n \u00b7\n <a href=\"https://github.com/WildlifeDatasets/wildlife-tools/issues/new?assignees=aerodynamic-sauce-pan&labels=bug&projects=&template=bug_report.md&title=%5BBUG%5D\">Report Bug</a>\n \u00b7\n <a href=\"https://github.com/WildlifeDatasets/wildlife-tools/issues/new?assignees=aerodynamic-sauce-pan&labels=enhancement&projects=&template=enhancement.md&title=%5BEnhancement%5D\">Request Feature</a>\n</div>\n\n</br >\n\n## Our other projects\n\n\n<div align=\"center\">\n<div style=\"display: flex; justify-content: center\">\n <div style=\"margin-right: 50px;\">\n <img src=\"resources/megadescriptor-logo.png\" alt=\"Image 1\" width=\"200\" style=\"margin-bottom: 5px;\">\n <p><a href=\"https://huggingface.co/BVRA/MegaDescriptor-L-384\">MegaDescriptor</a></p>\n </div>\n\n <div>\n <img src=\"resources/datasets-logo.png\" alt=\"Image 2\" width=\"200\" style=\"margin-bottom: 5px;\"> <!-- Adjust margin as needed -->\n <p><a href=\"https://huggingface.co/BVRA/MegaDescriptor-L-384\">Wildlife Datasets</a></p>\n </div>\n</div>\n</div>\n\n\n<h1></h1>\n\n# Introduction\nThe `wildlife-tools` library offers a simple interface for various tasks in the Wildlife Re-Identification domain. It covers use cases such as training, feature extraction, similarity calculation, image retrieval, and classification. It complements the `wildlife-datasets` library, which acts as dataset repository. All datasets there can be used in combination with `WildlifeDataset` component, which serves for loading extracting images and image tensors other tasks. \n\nMore information can be found in [Documentation](https://wildlifedatasets.github.io/wildlife-tools/)\n\n## Installation\n\nTo install `wildlife-tools`, you can build it from scratch or use pre-build Pypi package.\n\n\n### Using Pypi\n\n```script\npip install wildlife-tools\n\n```\n\n### Building from scratch\n\nClone the repository using `git` and install it.\n```script\ngit clone git@github.com:WildlifeDatasets/wildlife-tools.git\n\ncd wildlife-tools\npip install -e .\n```\n\n\n## Modules in the in the `wildlife-tools`\n\n- The `data` module provides tools for creating instances of the `WildlifeDataset`.\n- The `train` module offers tools for fine-tuning feature extractors on the `WildlifeDataset`.\n- The `features` module provides tools for extracting features from the `WildlifeDataset` using various extractors.\n- The `similarity` module provides tools for constructing a similarity matrix from query and database features.\n- The `inference` module offers tools for creating predictions using the similarity matrix.\n\n\n\n## Relations between modules:\n\n```mermaid\n graph TD;\n A[Data]-->|WildlifeDataset|B[Features]\n A-->|WildlifeDataset|C;\n C[Train]-->|finetuned extractor|B;\n B-->|query and database features|D[Similarity]\n D-->|similarity matrix|E[Inference]\n```\n\n\n\n## Example\n### 1. Create `WildlifeDataset` \nUsing metadata from `wildlife-datasets`, create `WildlifeDataset` object for the MacaqueFaces dataset.\n\n```Python\nfrom wildlife_datasets.datasets import MacaqueFaces\nfrom wildlife_tools.data import WildlifeDataset\nimport torchvision.transforms as T\n\nmetadata = MacaqueFaces('datasets/MacaqueFaces')\ntransform = T.Compose([T.Resize([224, 224]), T.ToTensor(), T.Normalize(mean=(0.485, 0.456, 0.406), std=(0.229, 0.224, 0.225))])\ndataset = WildlifeDataset(metadata.df, metadata.root, transform=transform)\n```\n\nOptionally, split metadata into subsets. In this example, query is first 100 images and rest are in database.\n\n```Python\ndataset_database = WildlifeDataset(metadata.df.iloc[100:,:], metadata.root, transform=transform)\ndataset_query = WildlifeDataset(metadata.df.iloc[:100,:], metadata.root, transform=transform)\n```\n\n### 2. Extract features\nExtract features using MegaDescriptor Tiny, downloaded from HuggingFace hub.\n\n```Python\nfrom wildlife_tools.features import DeepFeatures\n\nname = 'hf-hub:BVRA/MegaDescriptor-T-224'\nextractor = DeepFeatures(timm.create_model(name, num_classes=0, pretrained=True))\nquery, database = extractor(dataset_query), extractor(dataset_database)\n```\n\n### 3. Calculate similarity\nCalculate cosine similarity between query and database deep features.\n\n```Python\nfrom wildlife_tools.similarity import CosineSimilarity\n\nsimilarity_function = CosineSimilarity()\nsimilarity = similarity_function(query, database)\n```\n\n\n### 4. Evaluate\nUse the cosine similarity in nearest neigbour classifier and get predictions.\n\n```Python\nclassifier = KnnClassifier(k=1, database_labels=dataset_database.labels_string)\npredictions = classifier(similarity['cosine'])\naccuracy = np.mean(dataset_database.labels_string == predictions)\n```\n\n## Citation\n\nIf you like our package, please cite us.\n\n```\n@InProceedings{Cermak_2024_WACV,\n author = {\\v{C}erm\\'ak, Vojt\\v{e}ch and Picek, Luk\\'a\\v{s} and Adam, Luk\\'a\\v{s} and Papafitsoros, Kostas},\n title = {{WildlifeDatasets: An Open-Source Toolkit for Animal Re-Identification}},\n booktitle = {Proceedings of the IEEE/CVF Winter Conference on Applications of Computer Vision (WACV)},\n month = {January},\n year = {2024},\n pages = {5953-5963}\n}\n```\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 Vojt\u011bch \u010cerm\u00e1k Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "Tools for using wildlife re-identification datasets.",
"version": "0.0.9",
"project_urls": {
"Bug Tracker": "https://github.com/WildlifeDatasets/wildlife-tools/issues",
"Documentation": "https://wildlifedatasets.github.io/wildlife-tools/",
"Homepage": "https://github.com/WildlifeDatasets/wildlife-tools"
},
"split_keywords": [
"wildlife",
"re-identification",
"datasets",
"machine learning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "18af623183cbca07bc009cec54c58a0e840fe99cf4937176bc5cc3eefeed4f73",
"md5": "f6fb2c11791dda4ac33b637eee689112",
"sha256": "b9913bddc9c497e9e0616cce0ac7a794d467c891515cd15abb2e5a8d262f54b0"
},
"downloads": -1,
"filename": "wildlife_tools-0.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f6fb2c11791dda4ac33b637eee689112",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 25551,
"upload_time": "2024-01-26T08:30:10",
"upload_time_iso_8601": "2024-01-26T08:30:10.540100Z",
"url": "https://files.pythonhosted.org/packages/18/af/623183cbca07bc009cec54c58a0e840fe99cf4937176bc5cc3eefeed4f73/wildlife_tools-0.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4d7109a64ca02da9d4f4cbd75a02ec934904ea1a69aa5cbf26e9e5f53f37e2da",
"md5": "68126186db61799bf6d0750f46419c06",
"sha256": "6800b8282149a6af75c07d8ddae339ac4b5cbc2e82790bc5893bcf5f5fb61e82"
},
"downloads": -1,
"filename": "wildlife-tools-0.0.9.tar.gz",
"has_sig": false,
"md5_digest": "68126186db61799bf6d0750f46419c06",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22259,
"upload_time": "2024-01-26T08:30:13",
"upload_time_iso_8601": "2024-01-26T08:30:13.087869Z",
"url": "https://files.pythonhosted.org/packages/4d/71/09a64ca02da9d4f4cbd75a02ec934904ea1a69aa5cbf26e9e5f53f37e2da/wildlife-tools-0.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-26 08:30:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "WildlifeDatasets",
"github_project": "wildlife-tools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "wildlife-tools"
}
