| Name | birder JSON |
| Version |
0.0.5a7
JSON |
| download |
| home_page | None |
| Summary | A computer vision framework for wildlife image analysis, focusing on avian species. |
| upload_time | 2024-07-08 16:40:13 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | Apache-2.0 |
| keywords |
computer-vision
image-classification
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Birder
Birder is an open-source computer vision framework for bird species classification and detection in wildlife imagery.
* [Introduction](#introduction)
* [Setup](#setup)
* [Getting Started](#getting-started)
* [Pre-trained Models](#pre-trained-models)
* [Detection](#detection)
* [Licenses](#licenses)
* [Acknowledgments](#acknowledgments)
## Introduction
Birder is an open-source computer vision framework designed for wildlife imagery, specifically focused on bird species classification and detection. This project leverages deep neural networks to provide robust models that can handle real-world data challenges.
For comprehensive documentation, tutorials, and more visit the main documentation at [docs/README.md](docs/README.md).
The project features:
* A diverse collection of classification and detection models
* Support for self-supervised pre-training
* Knowledge distillation training (teacher-student)
* Custom utilities and data augmentation techniques
* Comprehensive training scripts
* Advanced error analysis tools
* Extensive documentation and tutorials (hopefully...)
Unlike projects that aim to reproduce ImageNet training results from common papers, Birder is tailored specifically for practical applications in ornithology, conservation, and wildlife photography.
For a complete list of supported bird species, please refer to the [docs/classes.md](docs/classes.md) file in the docs folder.
As Ross Wightman eloquently stated in the [timm README](https://github.com/huggingface/pytorch-image-models#introduction):
> The work of many others is present here. I've tried to make sure all source material is acknowledged via links to github, arXiv papers, etc. in the README, documentation, and code docstrings. Please let me know if I missed anything.
The same principle applies to Birder. We stand on the shoulders of giants in the fields of computer vision, machine learning, and ornithology. We've made every effort to acknowledge and credit the work that has influenced and contributed to this project. If you believe we've missed any attributions, please let us know by opening an issue.
## Setup
Birder can be installed either as a package or cloned from Git.
### Option 1: Package Installation (Recommended for Users)
1. Set up and activate a virtual environment:
```sh
python -m venv .venv
source .venv/bin/activate # On Windows, use .venv\Scripts\activate
```
1. Update pip and wheel in your virtual environment:
```sh
pip install --upgrade pip wheel
```
1. Install PyTorch 2.3 or above suitable for your hardware and drivers (see [https://pytorch.org/get-started/locally/](https://pytorch.org/get-started/locally/)).
1. Install the `birder` package
```sh
pip install birder
```
### Option 2: Cloning from Git (Recommended for Contributors or Advanced Users)
1. Clone the repository:
```sh
git clone https://gitlab.com/birder/birder.git
cd birder
```
1. Set up and activate a virtual environment:
```sh
python -m venv .venv
source .venv/bin/activate # On Windows, use .venv\Scripts\activate
```
1. Update pip and install wheel
```sh
pip install --upgrade pip wheel
```
1. Install PyTorch 2.3 or above suitable for your hardware and drivers (see [https://pytorch.org/get-started/locally/](https://pytorch.org/get-started/locally/)).
```sh
# For CUDA
pip install --upgrade -r requirements/requirements-pytorch-gpu.txt
# For CPU
pip install --upgrade -r requirements/requirements-pytorch-cpu.txt
```
1. Install development requirements:
```sh
pip install --upgrade -r requirements/requirements-dev.txt
```
### Verifying the Installation
To verify that Birder is installed correctly, run:
```sh
python -c "import birder; print(birder.__version__)"
```
This should print the version of Birder.
## Getting Started
Once Birder is installed, you can start exploring its capabilities.
Birder provides pre-trained models that you can download using the `fetch-model` tool.
To download a model, use the following command:
```sh
python -m birder.tools fetch-model mobilenet_v3_1_0
```
To classify bird images, use the `birder-predict` script as follows:
```sh
birder-predict -n mobilenet_v3 -p 1 -e 0 --show bird.jpeg
```
For more options and detailed usage of the prediction tool, run:
```sh
birder-predict --help
```
For more detailed usage instructions and examples, please refer to our [documentation](docs/README.md).
## Pre-trained Models
Birder provides a comprehensive suite of pre-trained models for bird species classification.
To explore the full range of available pre-trained models, use the `list-models` tool:
```sh
python -m birder.tools list-models --pretrained
```
This command displays a catalog of models ready for download.
### Model Nomenclature
The naming convention for Birder models encapsulates key information about their architecture and training approach.
Architecture: The first part of the model name indicates the core neural network structure (e.g., MobileNet, ResNet).
Training indicators:
* intermediate: Signifies models that underwent a two-stage training process, beginning with a large-scale weakly labeled dataset before fine-tuning on the primary dataset
* pretrained: Indicates models that leveraged self-supervised pre-training techniques, primarily Masked Autoencoder (MAE), prior to supervised training
Other tags:
* quantized: Model that has been quantized to reduce the computational and memory costs of running inference
Net Param: The number following the model name (e.g., 50, 1.0, 0.5), called the `net_param`, represents a specific configuration choice for the network. It represents a specific configuration choice for the network, which can affect aspects such as model size or complexity.
For instance, *convnext_v2_5_pretrained-intermediate_0* represents a ConvNeXt v2 model with a `net_param` of 5 that underwent both pre-training and intermediate training.
### Self-supervised Image Pre-training
Our pre-training process utilizes a diverse collection of image datasets.
This approach allows our models to learn rich, general-purpose visual representations before fine-tuning on specific bird classification tasks.
The pre-training dataset comprises:
* iNaturalist 2021 (~3.3M)
* WebVision-2.0 (~1.5M random subset)
* imagenet-w21-webp-wds (~1M random subset)
* SA-1B (~220K random subset of 20 chunks)
* NABirds (~48K)
* Birdsnap v1.1 (~44K)
* CUB-200 2011 (~18K)
* The Birder dataset (~1.5M)
Total: ~7.5M images
This carefully curated mix of datasets balances general visual knowledge with domain-specific bird imagery, enhancing the model's overall performance.
For detailed information about these datasets, including descriptions, citations, and licensing details, please refer to [docs/public_datasets.md](docs/public_datasets.md).
## Detection
Detection features are currently under development and will be available in future releases.
For annotation, run the following command:
```sh
labelme --labels ../birder/data/detection_data/classes.txt --nodata --output ../birder/data/detection_data/training_annotations --flags unknown ../birder/data/detection_data/training
```
## Project Status and Contributions
Birder is currently a personal project in active development. As the sole developer, I am focused on building and refining the core functionalities of the framework. At this time, I am not actively seeking external contributors.
However, I greatly appreciate the interest and support from the community. If you have suggestions, find bugs, or want to provide feedback, please feel free to:
* Open an issue in the project's issue tracker
* Use the project and share your experiences
* Star the repository if you find it useful
While I may not be able to incorporate external contributions at this stage, your input is valuable and helps shape the direction of Birder. I'll update this section if the contribution policy changes in the future.
Thank you for your understanding and interest in Birder!
## Licenses
### Code
The code in this project is licensed under Apache 2.0. See [LICENSE](LICENSE) for details.
Some code is adapted from other projects.
There are notices with links to the references at the top of the file or at the specific class/function.
It is your responsibility to ensure compliance with licenses here and conditions of any dependent licenses.
If you think we've missed a reference or a license, please create an issue.
### Pretrained Weights
Some of the pretrained weights available here are pretrained on ImageNet. ImageNet was released for non-commercial research purposes only (<https://image-net.org/download>). It's not clear what the implications of that are for the use of pretrained weights from that dataset. It's best to seek legal advice if you intend to use the pretrained weights in a commercial product.
### Disclaimer
If you intend to use Birder, its pretrained weights, or any associated datasets in a commercial product, we strongly recommend seeking legal advice to ensure compliance with all relevant licenses and terms of use.
It's the user's responsibility to ensure that their use of this project, including any pretrained weights or datasets, complies with all applicable licenses and legal requirements.
## Acknowledgments
Birder owes much to the work of others in computer vision, machine learning, and ornithology.
Special thanks to:
* **Ross Wightman**: His work on [PyTorch Image Models (timm)](https://github.com/huggingface/pytorch-image-models) greatly inspired the design and approach of Birder.
* **Image Contributors**:
* Yaron Schmid - from [YS Wildlife](https://www.yswildlifephotography.com/who-we-are)
for their generous donations of bird photographs.
This project also benefits from numerous open-source libraries and ornithological resources.
If any attribution is missing, please open an issue to let us know.
Raw data
{
"_id": null,
"home_page": null,
"name": "birder",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "computer-vision, image-classification",
"author": null,
"author_email": "Ofer Hasson <author@example.com>",
"download_url": "https://files.pythonhosted.org/packages/a2/34/ad63494b3524a9208e89c81688ae992b70da80d9e5dd0311c92649628da2/birder-0.0.5a7.tar.gz",
"platform": null,
"description": "# Birder\n\nBirder is an open-source computer vision framework for bird species classification and detection in wildlife imagery.\n\n* [Introduction](#introduction)\n* [Setup](#setup)\n* [Getting Started](#getting-started)\n* [Pre-trained Models](#pre-trained-models)\n* [Detection](#detection)\n* [Licenses](#licenses)\n* [Acknowledgments](#acknowledgments)\n\n## Introduction\n\nBirder is an open-source computer vision framework designed for wildlife imagery, specifically focused on bird species classification and detection. This project leverages deep neural networks to provide robust models that can handle real-world data challenges.\n\nFor comprehensive documentation, tutorials, and more visit the main documentation at [docs/README.md](docs/README.md).\n\nThe project features:\n\n* A diverse collection of classification and detection models\n* Support for self-supervised pre-training\n* Knowledge distillation training (teacher-student)\n* Custom utilities and data augmentation techniques\n* Comprehensive training scripts\n* Advanced error analysis tools\n* Extensive documentation and tutorials (hopefully...)\n\nUnlike projects that aim to reproduce ImageNet training results from common papers, Birder is tailored specifically for practical applications in ornithology, conservation, and wildlife photography.\n\nFor a complete list of supported bird species, please refer to the [docs/classes.md](docs/classes.md) file in the docs folder.\n\nAs Ross Wightman eloquently stated in the [timm README](https://github.com/huggingface/pytorch-image-models#introduction):\n\n> The work of many others is present here. I've tried to make sure all source material is acknowledged via links to github, arXiv papers, etc. in the README, documentation, and code docstrings. Please let me know if I missed anything.\n\nThe same principle applies to Birder. We stand on the shoulders of giants in the fields of computer vision, machine learning, and ornithology. We've made every effort to acknowledge and credit the work that has influenced and contributed to this project. If you believe we've missed any attributions, please let us know by opening an issue.\n\n## Setup\n\nBirder can be installed either as a package or cloned from Git.\n\n### Option 1: Package Installation (Recommended for Users)\n\n1. Set up and activate a virtual environment:\n\n ```sh\n python -m venv .venv\n source .venv/bin/activate # On Windows, use .venv\\Scripts\\activate\n ```\n\n1. Update pip and wheel in your virtual environment:\n\n ```sh\n pip install --upgrade pip wheel\n ```\n\n1. Install PyTorch 2.3 or above suitable for your hardware and drivers (see [https://pytorch.org/get-started/locally/](https://pytorch.org/get-started/locally/)).\n\n1. Install the `birder` package\n\n ```sh\n pip install birder\n ```\n\n### Option 2: Cloning from Git (Recommended for Contributors or Advanced Users)\n\n1. Clone the repository:\n\n ```sh\n git clone https://gitlab.com/birder/birder.git\n cd birder\n ```\n\n1. Set up and activate a virtual environment:\n\n ```sh\n python -m venv .venv\n source .venv/bin/activate # On Windows, use .venv\\Scripts\\activate\n ```\n\n1. Update pip and install wheel\n\n ```sh\n pip install --upgrade pip wheel\n ```\n\n1. Install PyTorch 2.3 or above suitable for your hardware and drivers (see [https://pytorch.org/get-started/locally/](https://pytorch.org/get-started/locally/)).\n\n ```sh\n # For CUDA\n pip install --upgrade -r requirements/requirements-pytorch-gpu.txt\n\n # For CPU\n pip install --upgrade -r requirements/requirements-pytorch-cpu.txt\n ```\n\n1. Install development requirements:\n\n ```sh\n pip install --upgrade -r requirements/requirements-dev.txt\n ```\n\n### Verifying the Installation\n\nTo verify that Birder is installed correctly, run:\n\n```sh\npython -c \"import birder; print(birder.__version__)\"\n```\n\nThis should print the version of Birder.\n\n## Getting Started\n\nOnce Birder is installed, you can start exploring its capabilities.\n\nBirder provides pre-trained models that you can download using the `fetch-model` tool.\nTo download a model, use the following command:\n\n```sh\npython -m birder.tools fetch-model mobilenet_v3_1_0\n```\n\nTo classify bird images, use the `birder-predict` script as follows:\n\n```sh\nbirder-predict -n mobilenet_v3 -p 1 -e 0 --show bird.jpeg\n```\n\nFor more options and detailed usage of the prediction tool, run:\n\n```sh\nbirder-predict --help\n```\n\nFor more detailed usage instructions and examples, please refer to our [documentation](docs/README.md).\n\n## Pre-trained Models\n\nBirder provides a comprehensive suite of pre-trained models for bird species classification.\n\nTo explore the full range of available pre-trained models, use the `list-models` tool:\n\n```sh\npython -m birder.tools list-models --pretrained\n```\n\nThis command displays a catalog of models ready for download.\n\n### Model Nomenclature\n\nThe naming convention for Birder models encapsulates key information about their architecture and training approach.\n\nArchitecture: The first part of the model name indicates the core neural network structure (e.g., MobileNet, ResNet).\n\nTraining indicators:\n\n* intermediate: Signifies models that underwent a two-stage training process, beginning with a large-scale weakly labeled dataset before fine-tuning on the primary dataset\n* pretrained: Indicates models that leveraged self-supervised pre-training techniques, primarily Masked Autoencoder (MAE), prior to supervised training\n\nOther tags:\n\n* quantized: Model that has been quantized to reduce the computational and memory costs of running inference\n\nNet Param: The number following the model name (e.g., 50, 1.0, 0.5), called the `net_param`, represents a specific configuration choice for the network. It represents a specific configuration choice for the network, which can affect aspects such as model size or complexity.\n\nFor instance, *convnext_v2_5_pretrained-intermediate_0* represents a ConvNeXt v2 model with a `net_param` of 5 that underwent both pre-training and intermediate training.\n\n### Self-supervised Image Pre-training\n\nOur pre-training process utilizes a diverse collection of image datasets.\nThis approach allows our models to learn rich, general-purpose visual representations before fine-tuning on specific bird classification tasks.\n\nThe pre-training dataset comprises:\n\n* iNaturalist 2021 (~3.3M)\n* WebVision-2.0 (~1.5M random subset)\n* imagenet-w21-webp-wds (~1M random subset)\n* SA-1B (~220K random subset of 20 chunks)\n* NABirds (~48K)\n* Birdsnap v1.1 (~44K)\n* CUB-200 2011 (~18K)\n* The Birder dataset (~1.5M)\n\nTotal: ~7.5M images\n\nThis carefully curated mix of datasets balances general visual knowledge with domain-specific bird imagery, enhancing the model's overall performance.\n\nFor detailed information about these datasets, including descriptions, citations, and licensing details, please refer to [docs/public_datasets.md](docs/public_datasets.md).\n\n## Detection\n\nDetection features are currently under development and will be available in future releases.\n\nFor annotation, run the following command:\n\n```sh\nlabelme --labels ../birder/data/detection_data/classes.txt --nodata --output ../birder/data/detection_data/training_annotations --flags unknown ../birder/data/detection_data/training\n```\n\n## Project Status and Contributions\n\nBirder is currently a personal project in active development. As the sole developer, I am focused on building and refining the core functionalities of the framework. At this time, I am not actively seeking external contributors.\n\nHowever, I greatly appreciate the interest and support from the community. If you have suggestions, find bugs, or want to provide feedback, please feel free to:\n\n* Open an issue in the project's issue tracker\n* Use the project and share your experiences\n* Star the repository if you find it useful\n\nWhile I may not be able to incorporate external contributions at this stage, your input is valuable and helps shape the direction of Birder. I'll update this section if the contribution policy changes in the future.\n\nThank you for your understanding and interest in Birder!\n\n## Licenses\n\n### Code\n\nThe code in this project is licensed under Apache 2.0. See [LICENSE](LICENSE) for details.\nSome code is adapted from other projects.\nThere are notices with links to the references at the top of the file or at the specific class/function.\nIt is your responsibility to ensure compliance with licenses here and conditions of any dependent licenses.\n\nIf you think we've missed a reference or a license, please create an issue.\n\n### Pretrained Weights\n\nSome of the pretrained weights available here are pretrained on ImageNet. ImageNet was released for non-commercial research purposes only (<https://image-net.org/download>). It's not clear what the implications of that are for the use of pretrained weights from that dataset. It's best to seek legal advice if you intend to use the pretrained weights in a commercial product.\n\n### Disclaimer\n\nIf you intend to use Birder, its pretrained weights, or any associated datasets in a commercial product, we strongly recommend seeking legal advice to ensure compliance with all relevant licenses and terms of use.\n\nIt's the user's responsibility to ensure that their use of this project, including any pretrained weights or datasets, complies with all applicable licenses and legal requirements.\n\n## Acknowledgments\n\nBirder owes much to the work of others in computer vision, machine learning, and ornithology.\n\nSpecial thanks to:\n\n* **Ross Wightman**: His work on [PyTorch Image Models (timm)](https://github.com/huggingface/pytorch-image-models) greatly inspired the design and approach of Birder.\n\n* **Image Contributors**:\n * Yaron Schmid - from [YS Wildlife](https://www.yswildlifephotography.com/who-we-are)\n\n for their generous donations of bird photographs.\n\nThis project also benefits from numerous open-source libraries and ornithological resources.\n\nIf any attribution is missing, please open an issue to let us know.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A computer vision framework for wildlife image analysis, focusing on avian species.",
"version": "0.0.5a7",
"project_urls": {
"Homepage": "https://gitlab.com/birder/birder",
"Issues": "https://gitlab.com/birder/birder/-/issues"
},
"split_keywords": [
"computer-vision",
" image-classification"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "251c7ac1505877dfcd8b79fcf75fdcdb0f7363277e97c7a1d611ae1a0c99bc97",
"md5": "311b55118dbe1183f7945d801c42850d",
"sha256": "d75fe40535fb0eff6cfcad3fe9e292491c19baf401e9e643cd6314f1229c4b7f"
},
"downloads": -1,
"filename": "birder-0.0.5a7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "311b55118dbe1183f7945d801c42850d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 238863,
"upload_time": "2024-07-08T16:40:10",
"upload_time_iso_8601": "2024-07-08T16:40:10.781430Z",
"url": "https://files.pythonhosted.org/packages/25/1c/7ac1505877dfcd8b79fcf75fdcdb0f7363277e97c7a1d611ae1a0c99bc97/birder-0.0.5a7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a234ad63494b3524a9208e89c81688ae992b70da80d9e5dd0311c92649628da2",
"md5": "99aabbaf6b08ad39008b57d3dc503cc2",
"sha256": "da6c4bc1a1896e00f9cb5b062d06c5fa480149803c2e7bfe9b015b864967e0a6"
},
"downloads": -1,
"filename": "birder-0.0.5a7.tar.gz",
"has_sig": false,
"md5_digest": "99aabbaf6b08ad39008b57d3dc503cc2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 157809,
"upload_time": "2024-07-08T16:40:13",
"upload_time_iso_8601": "2024-07-08T16:40:13.205657Z",
"url": "https://files.pythonhosted.org/packages/a2/34/ad63494b3524a9208e89c81688ae992b70da80d9e5dd0311c92649628da2/birder-0.0.5a7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-08 16:40:13",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "birder",
"gitlab_project": "birder",
"lcname": "birder"
}
