Metadata-Version: 2.1
Name: awc_helpers
Version: 0.2.1
Summary: Australian Wildlife Conservancy's Wildlife detection and species classification inference tools
Author: Quan Tran
License: CC-BY-NC-SA-4.0
Project-URL: Homepage, https://github.com/Australian-Wildlife-Conservancy-AWC/awc_inference
Project-URL: Repository, https://github.com/Australian-Wildlife-Conservancy-AWC/awc_inference
Project-URL: Issues, https://github.com/Australian-Wildlife-Conservancy-AWC/awc_inference/issues
Keywords: wildlife,detection,classification,megadetector,camera-trap,ecology
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch<=2.9.1
Requires-Dist: torchvision<=0.24.1
Requires-Dist: megadetector<=10.0.17
Requires-Dist: ultralytics<=8.4.7
Requires-Dist: timm<=1.0.24

# AWC Helpers

Wildlife detection and species classification inference tools combining MegaDetector with custom species classifiers.

## Installation

### 1. Install PyTorch

**Windows (with CUDA GPU):**
```bash
pip install "torch<=2.9.1" "torchvision<=0.24.1" --index-url https://download.pytorch.org/whl/cu128
```

**Linux / Mac / Windows with CPU:**
```bash
pip install "torch<=2.9.1" "torchvision<=0.24.1"
```

### 2. Install AWC Helpers

**From PyPI:**
```bash
pip install awc-helpers
```

## Usage

```python
from awc_helpers import DetectAndClassify

# Initialize the pipeline
pipeline = DetectAndClassify(
    detector_path="models/md_v1000.0.0-redwood.pt",
    classifier_path="models/awc-135-v1.pth",
    label_names=["species_a", "species_b", "species_c"],
    detection_threshold=0.1,
    clas_threshold=0.5,
)

# Run inference on image paths
results = pipeline.predict(
    inp=["path/to/image1.jpg", "path/to/image2.jpg"],
    clas_bs=4
)

for result in results:
    print(result)
# print example:
# AWCResult(identifier='"path/to/image1.jpg"', bbox=(0.1, 0.2, 0.3, 0.4), bbox_label='animal', bbox_conf=0.95, labels_probs=(('kangaroo', 0.87),))

```

## Documenntation
Refer to [this](DOCUMENTATION.md) for more details

## License

This project is licensed under the [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](LICENSE) (CC BY-NC-SA 4.0).

**Non-commercial use only. Derivative works must use the same license.**
