Skip to content

Commit 4034d19

Browse files
rain-Brianrain-Brian
committed
feat: repo infrastructure, docs site, and packaging for PyTorch-Wildlife launch
- README.md: full content with quick start, model table, ecosystem table, badges - .gitignore: standard template matching other ecosystem repos - pyproject.toml: PytorchWildlife package with full metadata and dependency list - citation.cff: title, repository-code, version 1.3.0, date-released, keywords - SECURITY.md: Microsoft standard security policy - docs-requirements.txt: lightweight MkDocs-only deps for CI - mkdocs.yml: Material theme (green/deep orange, paw icons) matching Biodiversity/MegaDetector - docs/index.md: overview, quick start, ecosystem table - docs/installation.md: pip, conda, GPU, Docker, Jupyter - docs/model_zoo.md: detection + classification + bioacoustic models with code examples - docs/cite.md: BibTeX for PyTorch-Wildlife and MegaDetector papers - docs/tags.md: material/tags directive - docs/build_mkdocs.md: developer guide for building docs locally - .github/workflows/deploy-docs.yml: auto-deploy on push to main - .github/ISSUE_TEMPLATE/: bug report, feature request, question templates
1 parent 86eecf1 commit 4034d19

17 files changed

Lines changed: 995 additions & 2 deletions

‎.github/ISSUE_TEMPLATE/bug-report.yml‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
name: Bug Report
2+
description: Problems with PyTorch-Wildlife
3+
labels: [bug]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Thank you for submitting a Bug Report!
9+
10+
- type: checkboxes
11+
attributes:
12+
label: Search before asking
13+
description: >
14+
Please search the [issues](https://github.com/microsoft/Pytorch-Wildlife/issues) to see if a similar bug report already exists.
15+
options:
16+
- label: >
17+
I have searched the PyTorch-Wildlife [issues](https://github.com/microsoft/Pytorch-Wildlife/issues) and found no similar bug report.
18+
required: true
19+
20+
- type: textarea
21+
attributes:
22+
label: Bug
23+
description: Provide console output with error messages and/or screenshots of the bug.
24+
placeholder: |
25+
💡 ProTip! Include as much information as possible (error messages, screenshots, logs, tracebacks, etc.) to receive the most helpful response.
26+
validations:
27+
required: true
28+
29+
- type: textarea
30+
attributes:
31+
label: Environment
32+
description: Please specify the software and hardware you used to produce the bug.
33+
placeholder: |
34+
- PytorchWildlife: 1.3.0
35+
- OS: Ubuntu 22.04
36+
- Python: 3.10.0
37+
validations:
38+
required: false
39+
40+
- type: textarea
41+
attributes:
42+
label: Minimal Reproducible Example
43+
description: >
44+
This is referred to by community members as creating a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example).
45+
placeholder: |
46+
```
47+
# Code to reproduce your issue here
48+
```
49+
validations:
50+
required: false
51+
52+
- type: textarea
53+
attributes:
54+
label: Additional
55+
description: Anything else you would like to share?
56+
57+
- type: checkboxes
58+
attributes:
59+
label: Are you willing to submit a PR?
60+
description: >
61+
(Optional) We encourage you to submit a [Pull Request](https://github.com/microsoft/Pytorch-Wildlife/pulls) (PR) to help contribute to PyTorch-Wildlife for everyone, especially if you have a good understanding of how to implement a fix or feature.
62+
options:
63+
- label: Yes I'd like to help by submitting a PR!

‎.github/ISSUE_TEMPLATE/feature-request.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: Feature Request
2+
description: Suggest an enhancement for PyTorch-Wildlife
3+
labels: [enhancement]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Thank you for submitting a PyTorch-Wildlife Feature Request!
9+
10+
- type: checkboxes
11+
attributes:
12+
label: Search before asking
13+
description: >
14+
Please search the [issues](https://github.com/microsoft/Pytorch-Wildlife/issues) to see if a similar feature request already exists.
15+
options:
16+
- label: >
17+
I have searched the PyTorch-Wildlife [issues](https://github.com/microsoft/Pytorch-Wildlife/issues) and found no similar feature request.
18+
required: true
19+
20+
- type: textarea
21+
attributes:
22+
label: Description
23+
description: A short description of your feature.
24+
placeholder: |
25+
What new feature would you like to see in PyTorch-Wildlife?
26+
validations:
27+
required: true
28+
29+
- type: textarea
30+
attributes:
31+
label: Use case
32+
description: |
33+
Describe the use case of your feature request. It will help us understand and prioritize the feature request.
34+
placeholder: |
35+
How would this feature be used, and who would use it?
36+
37+
- type: textarea
38+
attributes:
39+
label: Additional
40+
description: Anything else you would like to share?
41+
42+
- type: checkboxes
43+
attributes:
44+
label: Are you willing to submit a PR?
45+
description: >
46+
(Optional) We encourage you to submit a [Pull Request](https://github.com/microsoft/Pytorch-Wildlife/pulls) (PR) to help contribute to PyTorch-Wildlife for everyone, especially if you have a good understanding of how to implement a fix or feature.
47+
options:
48+
- label: Yes I'd like to help by submitting a PR!

‎.github/ISSUE_TEMPLATE/question.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: Question
2+
description: Ask a PyTorch-Wildlife question
3+
labels: [question]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Thank you for asking a general question!
9+
10+
- type: checkboxes
11+
attributes:
12+
label: Search before asking
13+
description: >
14+
Please search the [issues](https://github.com/microsoft/Pytorch-Wildlife/issues) to see if a similar question already exists.
15+
options:
16+
- label: >
17+
I have searched the PyTorch-Wildlife [issues](https://github.com/microsoft/Pytorch-Wildlife/issues) and found no similar question.
18+
required: true
19+
20+
- type: textarea
21+
attributes:
22+
label: Question
23+
description: What is your question?
24+
placeholder: |
25+
💡 ProTip! Include as much information as possible to receive the most helpful response.
26+
validations:
27+
required: true
28+
29+
- type: textarea
30+
attributes:
31+
label: Additional
32+
description: Anything else you would like to share?

‎.github/workflows/deploy-docs.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: Deploy MkDocs site
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- 'docs/**'
9+
- 'mkdocs.yml'
10+
- 'docs-requirements.txt'
11+
12+
jobs:
13+
deploy:
14+
runs-on: ubuntu-latest
15+
permissions:
16+
contents: write
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- uses: actions/setup-python@v5
21+
with:
22+
python-version: '3.10'
23+
24+
- name: Install MkDocs dependencies
25+
run: pip install -r docs-requirements.txt
26+
27+
- name: Deploy to GitHub Pages
28+
run: mkdocs gh-deploy --force

‎.gitignore‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
__pycache__/
2+
*.py[cod]
3+
*$py.class
4+
*.egg-info/
5+
dist/
6+
build/
7+
*.egg
8+
.eggs/
9+
*.so
10+
.env
11+
.venv
12+
env/
13+
venv/
14+
.tox/
15+
.coverage
16+
htmlcov/
17+
.pytest_cache/
18+
*.log
19+
.DS_Store
20+
Thumbs.db
21+
Brewfile
22+
site/
23+
archive/
24+
*.code-workspace
25+
*.pt
26+
*.pth
27+
*.ckpt
28+
*.cache

‎README.md‎

Lines changed: 86 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,86 @@
1-
# MegaDetector-Camera
2-
An open-source, modular PyTorch framework for scalable wildlife detection and classification in images and videos.
1+
![A colorful banner illustrating various species of animals and plants in a natural environment, symbolizing biodiversity and the use of AI for conservation purposes.](https://zenodo.org/records/20044680/files/Biodiversity_Banner.png)
2+
3+
# PyTorch-Wildlife
4+
5+
**Unified open-source AI framework for wildlife monitoring and conservation.**
6+
Microsoft AI for Good Lab — camera-trap detection, species classification, bioacoustic analysis, and more.
7+
8+
<div align="center">
9+
<br>
10+
<a href="https://github.com/microsoft/Pytorch-Wildlife/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue" /></a>
11+
<a href="https://pypi.org/project/PytorchWildlife"><img src="https://img.shields.io/pypi/v/PytorchWildlife?color=limegreen" /></a>
12+
<a href="https://pypi.org/project/PytorchWildlife"><img src="https://static.pepy.tech/badge/pytorchwildlife" /></a>
13+
<a href="https://pypi.org/project/PytorchWildlife"><img src="https://img.shields.io/pypi/pyversions/PytorchWildlife" /></a>
14+
<a href="https://huggingface.co/spaces/ai-for-good-lab/pytorch-wildlife"><img src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Demo-blue" /></a>
15+
<a href="https://discord.gg/TeEVxzaYtm"><img src="https://img.shields.io/badge/Discord-Join_us-5865F2?logo=discord&logoColor=white" /></a>
16+
<a href="https://microsoft.github.io/Pytorch-Wildlife/"><img src="https://img.shields.io/badge/Docs-526CFE?logo=MaterialForMkDocs&logoColor=white" /></a>
17+
<br><br>
18+
</div>
19+
20+
PyTorch-Wildlife is the collaborative deep learning framework that powers the [Microsoft AI for Good Lab](https://www.microsoft.com/en-us/ai/ai-for-good)'s biodiversity work. It hosts detection models, species classifiers, and the tools needed to run them — from single-image inference to large-scale batch processing.
21+
22+
**MegaDetector**, the most widely used camera-trap detection model in conservation, is invoked through PyTorch-Wildlife. So are the species classifiers for Amazon Rainforest, Snapshot Serengeti, and European ecosystems.
23+
24+
25+
## Quick Start
26+
27+
```bash
28+
pip install PytorchWildlife
29+
```
30+
31+
```python
32+
import numpy as np
33+
from PytorchWildlife.models import detection as pw_detection
34+
from PytorchWildlife.models import classification as pw_classification
35+
36+
# Detection — weights download automatically
37+
detection_model = pw_detection.MegaDetectorV6()
38+
detection_result = detection_model.single_image_detection("path/to/image.jpg")
39+
40+
# Classification
41+
classification_model = pw_classification.AI4GAmazonRainforest()
42+
classification_result = classification_model.single_image_classification("path/to/image.jpg")
43+
```
44+
45+
**Try without installing anything:**
46+
- [Hugging Face demo](https://huggingface.co/spaces/ai-for-good-lab/pytorch-wildlife) — upload images in your browser
47+
- [Google Colab notebook](https://colab.research.google.com/drive/1rjqHrTMzEHkMualr4vB55dQWCsCKMNXi?usp=sharing) — free cloud GPU
48+
49+
50+
## Available Models
51+
52+
### Detection
53+
| Model | Architecture | Description |
54+
|---|---|---|
55+
| `MegaDetectorV6` | YOLOv10 / YOLOv9 / RT-DETR | Animal detection in camera-trap images |
56+
| `MegaDetectorV5` | YOLOv5 | Previous generation, widely deployed |
57+
| `DeepfauneDetector` | YOLOv8 | European ecosystem detection |
58+
| `HerdNet` | CNN localization | Point-based detection for aerial imagery |
59+
60+
### Classification
61+
| Model | Description |
62+
|---|---|
63+
| `AI4GAmazonRainforest` | Species classification for Amazon Rainforest |
64+
| `AI4GSnapshotSerengeti` | Species classification for African savanna |
65+
| `AI4GOpossum` | Opossum vs. non-opossum classifier |
66+
| `DeepfauneClassifier` | European ecosystem species classifier |
67+
| `DFNE` | Deepfaune fine-tuned for Northeastern North America |
68+
69+
See the [Model Zoo](https://microsoft.github.io/Pytorch-Wildlife/model_zoo/) for full details, performance benchmarks, and version history.
70+
71+
72+
## Part of the Biodiversity Ecosystem
73+
74+
PyTorch-Wildlife is part of the larger open-source ecosystem from the Microsoft AI for Good Lab:
75+
76+
| Repo | Purpose |
77+
|---|---|
78+
| [microsoft/Biodiversity](https://github.com/microsoft/Biodiversity) | The umbrella repository — documentation hub for the AI for Good Lab's biodiversity work |
79+
| [microsoft/Pytorch-Wildlife](https://github.com/microsoft/Pytorch-Wildlife) | This repo — the unified deep learning framework |
80+
| [microsoft/MegaDetector](https://github.com/microsoft/MegaDetector) | Animal detection in camera-trap imagery |
81+
| [microsoft/SPARROW](https://github.com/microsoft/SPARROW) | Solar-Powered Acoustic and Remote Recording Observation Watch — AI-enabled edge device |
82+
| [microsoft/MegaDetector-Acoustic](https://github.com/microsoft/MegaDetector-Acoustic) | Bioacoustic models for audio-based wildlife monitoring |
83+
| [microsoft/MegaDetector-Overhead](https://github.com/microsoft/MegaDetector-Overhead) | Point-based detection for overhead and aerial imagery |
84+
| [SPARROW Studio](https://github.com/microsoft/Biodiversity/tree/main/SPARROW-Studio) | Desktop application for running all models with a graphical interface |
85+
86+
> Questions? [Email us](mailto:zhongqimiao@microsoft.com) or join the [![Discord](https://img.shields.io/badge/any_text-Join_us!-blue?logo=discord&label=Discord)](https://discord.gg/TeEVxzaYtm)

‎SECURITY.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<!-- BEGIN MICROSOFT SECURITY.MD V0.0.9 BLOCK -->
2+
3+
## Security
4+
5+
Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet) and [Xamarin](https://github.com/xamarin).
6+
7+
If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/security.md/definition), please report it to us as described below.
8+
9+
## Reporting Security Issues
10+
11+
**Please do not report security vulnerabilities through public GitHub issues.**
12+
13+
Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/security.md/msrc/create-report).
14+
15+
If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/security.md/msrc/pgp).
16+
17+
You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc).
18+
19+
Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
20+
21+
* Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
22+
* Full paths of source file(s) related to the manifestation of the issue
23+
* The location of the affected source code (tag/branch/commit or direct URL)
24+
* Any special configuration required to reproduce the issue
25+
* Step-by-step instructions to reproduce the issue
26+
* Proof-of-concept or exploit code (if possible)
27+
* Impact of the issue, including how an attacker might exploit the issue
28+
29+
This information will help us triage your report more quickly.
30+
31+
If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/security.md/msrc/bounty) page for more details about our active programs.
32+
33+
## Preferred Languages
34+
35+
We prefer all communications to be in English.
36+
37+
## Policy
38+
39+
Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/security.md/cvd).
40+
41+
<!-- END MICROSOFT SECURITY.MD BLOCK -->

‎citation.cff‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
cff-version: 1.2.0
2+
title: PyTorch-Wildlife
3+
message: "If you use PyTorch-Wildlife, please cite it using the metadata from this file."
4+
type: software
5+
version: "1.3.0"
6+
date-released: "2026-05-14"
7+
authors:
8+
- given-names: Andres
9+
family-names: Hernandez
10+
- given-names: Zhongqi
11+
family-names: Miao
12+
- given-names: Luisa
13+
family-names: Vargas
14+
- given-names: Sara
15+
family-names: Beery
16+
- given-names: Rahul
17+
family-names: Dodhia
18+
- given-names: Juan
19+
family-names: Lavista
20+
- name: "Microsoft AI for Good Lab"
21+
identifiers:
22+
- type: url
23+
value: "https://arxiv.org/abs/2405.12930"
24+
description: "Pytorch-Wildlife: A Collaborative Deep Learning Framework for Conservation"
25+
- type: url
26+
value: "https://arxiv.org/abs/1907.06772"
27+
description: "Efficient Pipeline for Camera Trap Image Review"
28+
repository-code: "https://github.com/microsoft/Pytorch-Wildlife"
29+
url: "https://microsoft.github.io/Pytorch-Wildlife/"
30+
keywords:
31+
- PyTorch-Wildlife
32+
- MegaDetector
33+
- camera traps
34+
- wildlife detection
35+
- animal detection
36+
- species classification
37+
- conservation
38+
- computer vision
39+
- bioacoustics
40+
- ai-for-good
41+
license: MIT

‎docs-requirements.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
mkdocs
2+
mkdocs-get-deps
3+
mkdocs-material
4+
mkdocs-material-extensions
5+
pymdown-extensions
6+
mkdocstrings
7+
mkdocstrings-python

0 commit comments

Comments
 (0)