Metadata-Version: 2.4
Name: culicidaelab
Version: 0.1.0
Summary: A Python library for mosquito detection, segmentation, and classification in images
Author-email: Ilona Kovaleva <iloncka.ds@gmail.com>
Project-URL: Homepage, https://github.com/iloncka/culicidaelab
Project-URL: Bug Tracker, https://github.com/iloncka/culicidaelab/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.3.1
Requires-Dist: torchvision>=0.18.1
Requires-Dist: numpy>=1.24.4
Requires-Dist: tqdm>=4.66.1
Requires-Dist: hydra-core>=1.3.2
Requires-Dist: iopath>=0.1.10
Requires-Dist: pillow>=9.4.0
Requires-Dist: fastai<=2.8.0,>=2.7.0
Requires-Dist: timm>=0.9.0
Requires-Dist: ultralytics>=8.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: huggingface-hub>=0.16.0
Requires-Dist: datasets>=2.13.0
Requires-Dist: omegaconf>=2.3.0
Requires-Dist: python-dotenv>=0.21.0
Requires-Dist: pycocotools>=2.0.7
Requires-Dist: sam2>=1.1.0
Requires-Dist: dill>=0.3.8
Requires-Dist: graphviz>=0.20.3
Requires-Dist: appdirs>=1.4.4
Requires-Dist: requests>=2.25.1
Requires-Dist: toml>=0.10.2
Requires-Dist: dotenv>=0.9.9
Requires-Dist: pydantic-settings>=2.9.1
Requires-Dist: ipykernel==6.16.2
Requires-Dist: ipywidgets>=8.1.7
Requires-Dist: jupytext>=1.17.2
Requires-Dist: mkdocs[i18n]>=1.6.1
Provides-Extra: dev
Requires-Dist: black==23.3.0; extra == "dev"
Requires-Dist: mypy==1.4.1; extra == "dev"
Requires-Dist: pre-commit==2.21.0; extra == "dev"
Requires-Dist: pytest==7.4.4; extra == "dev"
Requires-Dist: pytest-cov==4.1.0; extra == "dev"
Requires-Dist: pytest-mock==3.14.1; extra == "dev"
Requires-Dist: ruff==0.8.0; extra == "dev"
Requires-Dist: twine==5.1.1; extra == "dev"
Requires-Dist: bandit==1.8.5; extra == "dev"
Requires-Dist: types-requests==2.32.4.20250611; extra == "dev"
Requires-Dist: types-pyyaml==6.0.12.20250516; extra == "dev"
Requires-Dist: types-toml==0.10.8.20240310; extra == "dev"
Requires-Dist: gputil==1.4.0; extra == "dev"
Requires-Dist: mkdocs==1.6.1; extra == "dev"
Requires-Dist: mkdocs-material==9.5.46; extra == "dev"
Requires-Dist: mkdocstrings[python]==0.27.0; extra == "dev"
Requires-Dist: mkdocs-custom-fences>=0.1.2; extra == "dev"
Requires-Dist: mkdocs-gallery>=0.10.4; extra == "dev"
Requires-Dist: mkdocs-static-i18n>=1.3.0; extra == "dev"
Dynamic: license-file

<div align="center">

# CulicidaeLab 🦟

**A configuration-driven Python library for advanced mosquito analysis, featuring pre-trained models for detection, segmentation, and species classification.**

</div>

<p align="center">
  <a href="https://pypi.org/project/culicidaelab/"><img alt="PyPI" src="https://img.shields.io/pypi/v/culicidaelab?color=blue"></a>

  <a href="#">
  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff" /></a>
</p>

---

`CulicidaeLab` provides a robust, extensible framework designed to streamline the pipeline of mosquito image analysis. Built on a powerful configuration system, it allows researchers and developers to easily manage datasets, experiment with models, and process images for classification, detection, and segmentation tasks.

## Key Features

- **Configuration-Driven Workflow**: Manage all settings—from file paths to model parameters—through simple YAML files. Override defaults easily for custom experiments.
- **Ready-to-Use Models**: Leverage pre-trained models for:
    - **Species Classification**: Identify mosquito species using a high-accuracy classifier.
    - **Mosquito Detection**: Localize mosquitoes in images with a YOLO-based detector.
    - **Instance Segmentation**: Generate precise pixel-level masks with a SAM-based segmenter.
- **Unified API**: All predictors share a consistent interface (`.predict()`, `.visualize()`, `.evaluate()`) for a predictable user experience.
- **Automatic Resource Management**: The library intelligently manages local storage, automatically downloading and caching model weights and datasets on first use.
- **Extensible Provider System**: Seamlessly connect to data sources. A `HuggingFaceProvider` is built-in, with an easy-to-implement interface for adding more providers.
- **Powerful Visualization**: Instantly visualize model outputs with built-in, configurable methods for drawing bounding boxes, classification labels, and segmentation masks.

## Installation

It is recommended to use a modern package manager like `uv` or `pip`.

```bash
# Using uv
uv add culicidaelab

# Or using pip
pip install culicidaelab
```

## Quick Start

Here's how to classify the species of a mosquito in just a few lines of code. The library will automatically download the necessary model on the first run.

```python
import cv2
from culicidaelab.core import get_settings

# 1. Get the central settings object
# This loads all default configurations for the library.
settings = get_settings()

# 2. Instantiate the classifier
# The settings object knows how to configure the classifier.
classifier = settings.instantiate_from_config("predictors.classifier")

# 3. Load an image
# (Ensure you have an image file at 'path/to/your/image.jpg')
try:
    image = cv2.imread("path/to/your/image.jpg")
    image_rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
except (cv2.error, AttributeError):
    print("Error: Could not load image. Please check the file path.")
    exit()

# 4. Make a prediction
# The model is lazy-loaded (downloaded and loaded into memory) here.
with classifier.model_context():
    predictions = classifier.predict(image_rgb)

# 5. Print the results
# The output is a list of (species_name, confidence_score) tuples.
print("Top 3 Predictions:")
for species, confidence in predictions[:3]:
    print(f"- {species}: {confidence:.4f}")

# Example Output:
# Top 3 Predictions:
# - Aedes aegypti: 0.9876
# - Aedes albopictus: 0.0112
# - Culex quinquefasciatus: 0.0009
```

## Going Deeper

`CulicidaeLab` can do much more. You can easily chain predictors, run batch predictions, and visualize results.

```python
# --- Continuing from the Quick Start ---

# Use the detector to find the mosquito first
detector = settings.instantiate_from_config("predictors.detector")
with detector.model_context():
    detections = detector.predict(image_rgb) # Returns [(x, y, w, h, conf)]

# Visualize the detection results
with detector.model_context():
    viz_image = detector.visualize(image_rgb, detections)
    cv2.imwrite("detection_result.png", cv2.cvtColor(viz_image, cv2.COLOR_RGB2BGR))
```

## Practical Applications

`CulicidaeLab` is more than just a set of models; it's a powerful engine for building real-world solutions. Here are some of the ways it can be applied:

-   **Automation in Scientific Laboratories:**
    -   **Bulk Data Processing:** Automatically analyze thousands of images from camera traps or microscopes to assess mosquito populations without manual intervention.
    -   **Reproducible Research:** Standardize the data analysis process, allowing other scientists to easily reproduce and verify research results published using the library.

-   **Integration into Governmental and Commercial Systems:**
    -   **Epidemiological Surveillance:** Use the library as the core "engine" for national or regional monitoring systems to track vector-borne disease risks.
    -   **Custom Solution Development:** Rapidly prototype and create specialized software products for pest control services, agro-industrial companies, or environmental organizations.

-   **Advanced Analytics and Data Science:**
    -   **Geospatial Analysis:** Write scripts to build disease vector distribution maps by processing geotagged images.
    -   **Predictive Modeling:** Use the library's outputs as features for larger models that forecast disease outbreaks based on vector presence and density.

## Documentation

For complete guides, tutorials, and the full API reference, **[visit the documentation site](https://iloncka-ds.github.io/culicidaelab/)**.

The documentation includes:
- In-depth installation and configuration guides.
- Detailed tutorials for each predictor.
- Architectural deep-dives for contributors.
- A full, auto-generated API reference.

## Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.

Please see our **[Contributing Guide](https://github.com/iloncka-ds/culicidaelab/blob/main/CONTRIBUTING.md)** for details on our code of conduct, development setup, and the pull request process.

## Development Setup

To get a development environment running:

1.  **Clone the repository**:
    ```bash
    git clone https://github.com/iloncka-ds/culicidaelab.git
    cd culicidaelab
    ```

2.  **Install dependencies with `uv` or `pip`**:
    ```bash
    # This installs the library in editable mode and includes all dev tools
    uv pip install -e ".[dev]"
    ```

3.  **Set up pre-commit hooks**:
    ```bash
    pre-commit install
    ```
    This will run linters and formatters automatically on each commit to ensure code quality and consistency.

## Acknowledgments

CulicidaeLab development is  supported by a grant from the **Foundation for Assistance to Small Innovative Enterprises (FASIE)**.
[https://fasie.ru/](https://fasie.ru/)

## License

This project is distributed under the MIT License. See the [LICENSE](https://github.com/iloncka-ds/culicidaelab/blob/main/LICENSE) file for more information.

## Citation

If you use `CulicidaeLab` in your research, please cite it as follows:

```bibtex
@software{culicidaelab2024,
  author = {Ilona Kovaleva},
  title = {{CulicidaeLab: A Configuration-Driven Python Library for Mosquito Analysis}},
  year = {2024},
  publisher = {GitHub},
  journal = {GitHub repository},
  url = {https://github.com/iloncka-ds/culicidaelab}
}
```

## Contact

- **Issues**: Please use the [GitHub issue tracker](https://github.com/iloncka-ds/culicidaelab/issues).
- **Email**: [iloncka.ds@gmail.com](mailto:iloncka.ds@gmail.com)
