culicidaelab 0.3.1

A Python library for mosquito detection, segmentation, and classification in images

CulicidaeLab 🦟

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

---

culicidaeLab python library 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. culicidaelab library is part of the is a part of the CulicidaeLab Ecosystem.

CulicidaeLab Ecosystem Architecture

flowchart TD

    %% Define layers with subgraphs
    subgraph L1 ["Data Layer"]
        DS1["🦟 mosquito_dataset_46_3139<br/>Base Diversity Dataset<br/>(46 species, 3139 unique images)<br/>📄 CC-BY-SA-4.0"]
        DS2["📊 mosquito-species-<br/>classification-dataset<br/>📄 CC-BY-SA-4.0"]
        DS3["🔍 mosquito-species-<br/>detection-dataset<br/>📄 CC-BY-SA-4.0"]
        DS4["✂️ mosquito-species-<br/>segmentation-dataset<br/>📄 CC-BY-SA-4.0"]
    end

    subgraph L2 ["AI Model Layer"]
        subgraph M_COLLECTION ["Top-5 Model Collection"]
            M4["📊 exp_7_new_bg_simple-subs_1_v_5<br/>pvt_v2_b0.in1k_ep_60<br/>(Classification)<br/>📄 Apache 2.0"]
        end
        subgraph M_DEFAULT ["Top-1 Models used as default in 'culicidaelab'"]
            M1["📊 culico-net-cls-v1<br/>(Classification)<br/>📄 Apache 2.0"]
            M2["🔍 culico-net-det-v1<br/>(Detection)<br/>📄 AGPL-3.0"]
            M3["✂️ culico-net-segm-v1-nano<br/>(Segmentation)<br/>📄 Apache 2.0"]
        end
    end

    subgraph L3 ["Application Layer"]
        APP1["🐍 culicidaelab<br/>Python Library<br/>(Core ML functionality) <br/>📄 AGPL-3.0"]
        APP2["🌐 culicidaelab-server<br/>Web Application<br/>(API services)<br/>📄 AGPL-3.0"]
        APP3["📸 culicidaelab-mobile<br/>Mobile Application<br/><br/>📄 AGPL-3.0"]
    end

    subgraph L4 ["API Service Layer"]
        S1["🗲 Prediction Service<br/>(ML inference)"]
        S2["💾 Observation Service<br/>(Data storage & retrieval)"]
        S3["🗺️ Map Service<br/>(Geospatial visualization)"]
        S4["🦟 Mosquito Gallery Service<br/>"]
        S5["💊 Diseases Gallery Service<br/>"]
    end

    %% Dataset derivation and training flows
    DS1 -.->|"derives"| DS2
    DS1 -.->|"derives"| DS3
    DS1 -.->|"derives"| DS4
    DS2 -->|"used for train"| M1
    DS3 -->|"used for train"| M2
    DS4 -->|"used for train"| M3
    DS2 -->|"used for train"| M4

    %% Model integration
    M1 -->|"integrated into"| APP1
    M2 -->|"integrated into"| APP1
    M3 -->|"integrated into"| APP1
    M4 -->|"integrated into"| APP3

    %% Data source for gallery
    DS1 -->|"provides photos"| APP2
    DS1 -->|"provides photos"| APP3

    %% Library to server integration
    APP1 -->|"powers"| APP2

    %% Service provisioning
    APP2 -->|"hosts"| S1
    APP2 -->|"hosts"| S2
    APP2 -->|"hosts"| S3
    APP2 -->|"hosts"| S4
    APP2 -->|"hosts"| S5

    %% Mobile app service consumption
    APP3 <-->|"API calls"| S1
    APP3 <-->|"API calls"| S2
    APP3 -->|"WebView"| S3

    %% Styling
    classDef dataLayer fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    classDef modelLayer fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    classDef appLayer fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
    classDef serviceLayer fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    classDef collections fill:#f4dbf8,stroke:#9b3ac5,stroke-width:1px,stroke-dasharray:5,5

    classDef dataset fill:#bbdefb,stroke:#1565c0,stroke-width:2px
    classDef model fill:#e1bee7,stroke:#8e24aa,stroke-width:2px
    classDef application fill:#c8e6c9,stroke:#43a047,stroke-width:2px
    classDef service fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px

    class L1 dataLayer
    class L2 modelLayer
    class L3 appLayer
    class L4 serviceLayer

    class DS1,DS2,DS3,DS4 dataset
    class M1,M2,M3,M4 model
    class APP1,APP2,APP3 application
    class S1,S2,S3,S4,S5 service
    class M_DEFAULT,M_COLLECTION collections
   

An open-source system for mosquito research and analysis includes components:

• Data:

  • Base diversity dataset (46 species, 3139 images under CC-BY-SA-4.0 license.
  • Specialized derivatives: classification, detection, and segmentation datasets under CC-BY-SA-4.0 licenses.

• Models:

  • Top-1 models (see reports), used as default by culicidaelab library: classification (Apache 2.0), detection (AGPL-3.0), segmentation (Apache 2.0)
  • Top-5 classification models collection with accuracy >90% for 17 mosquito species.

• Protocols: All training parameters and metrics available at:

  • Detection model reports
  • Segmentation model reports
  • Classification experiment reports - 1st round
  • Classification experiment reports -2nd round

• Applications:

  • Python library (AGPL-3.0) providing core ML functionality
  • Web server (AGPL-3.0) hosting API services
  • Mobile app (AGPL-3.0) for field use with optimized models

These components form a cohesive ecosystem where datasets used for training models that power applications, the Python library provides core functionality to the web server, and the server exposes services consumed by the mobile application. All components are openly licensed, promoting transparency and collaboration.

This integrated approach enables comprehensive mosquito research, from data collection to analysis and visualization, supporting both scientific research and public health initiatives.

Key Features of the culicidaelab library

• 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.

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.

Requirements

Hardware Requirements

Processor (CPU): Any modern x86-64 CPU.

Memory (RAM): Minimum 2 GB. 8 GB or more is recommended for processing large datasets or using more complex models.

Graphics Card (GPU): An NVIDIA GPU with CUDA support is highly recommended for a significant performance increase in deep learning model operations, especially for detection and segmentation but not essential for classification (see performance logs ang notebook). For the SAM model, a GPU is virtually essential for acceptable performance. Minimum video memory is 2 GB; 4 GB or more is recommended. For serve-gpu installation profile, CUDA 12.X is required, for CUDA 11.X use installation instructions below.

pip install onnxruntime-gpu --extra-index-url https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/onnxruntime-cuda-11/pypi/simple/
pip install culicidaelab

Hard Drive: At least 10 GB of free space to install the library, dependencies, download pre-trained models, and store processed data.

Software Requirements

Operating Systems (tested):

• Windows 10/11
• Linux 22.04+

Software:

• for Linux needed libgl1 package to be installed
• Git
• Python 3.11
• uv 0.8.13

Python packages:

• PyTorch 2.3.1+
• FastAI 2.7.0 - 2.8.0
• Ultralytics 8.3.0+
• HuggingFace Hub 0.16.0+
• Datasets 4.0.0
• Pillow 9.4.0
• Pydantic 2.0.0+

For full list of dependencies, see the pyproject.toml file.

Installation

Basic Installation

For most users, the default installation provides full inference capabilities:

pip install culicidaelab

This includes CPU-based inference using ONNX Runtime, giving you everything needed for fast lightweight mosquito classification inference, and includes all core functionality without heavy ML frameworks, such as configuration management, resource handling, and model downloading capabilities.

Installation Profiles

Choose an installation profile based on your use case:

For Production/Serving (Lightweight Inference)

GPU-accelerated inference:

pip install culicidaelab[serve-gpu]

Lightweight serve alias (equivalent to default):

pip install culicidaelab[serve]

For Research/Development

CPU-based development (includes PyTorch, FastAI, Ultralytics, and ONNX):

pip install culicidaelab[full] --extra-index-url https://download.pytorch.org/whl/cpu

GPU-accelerated development (includes PyTorch GPU, FastAI, Ultralytics, and ONNX GPU):

pip install culicidaelab[full-gpu]

Additional Options

Run example notebooks locally:

pip install culicidaelab[full,examples] --extra-index-url https://download.pytorch.org/whl/cpu
# Or for GPU development:
pip install culicidaelab[full-gpu,examples]

Build documentation locally:

pip install culicidaelab[full,docs] --extra-index-url https://download.pytorch.org/whl/cpu
# Or for GPU development:
pip install culicidaelab[full-gpu,docs]

Run tests:

pip install culicidaelab[full,test] --extra-index-url https://download.pytorch.org/whl/cpu
# Or for GPU development:
pip install culicidaelab[full-gpu,test]

Development Setup

To set up a development environment with all tools:

1. Clone the repository:

git clone https://github.com/iloncka-ds/culicidaelab.git
cd culicidaelab

2. Install dependencies with uv (recommended):

uv venv -p 3.11
source .venv/bin/activate

# On Windows: .venv\Scripts\activate
uv sync -p 3.11
uv cache clean
# This installs the library in editable mode with all dev tools (CPU version)
uv pip install -e .[dev]

# For GPU development, use:
# uv pip install -e .[full-gpu,docs,test]

Or with pip:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -e .[dev]
pip cache purge

3. Set up pre-commit hooks:

pre-commit install

This will run linters and formatters automatically on each commit to ensure code quality and consistency.

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.

from culicidaelab import MosquitoClassifier, 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 = MosquitoClassifier(settings, load_model=True)

# 3. Make a prediction
# The model is lazy-loaded (downloaded and loaded into memory) here.
result = classifier.predict("path/to/your/image.jpg")

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

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

Documentation

For complete guides, tutorials, and the full API reference, visit the documentation site.

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 for details on our code of conduct, development setup, and the pull request process.

Acknowledgments

CulicidaeLab development is supported by a grant from the Foundation for Assistance to Small Innovative Enterprises (FASIE)

License

This project is distributed under the AGPL-3.0 License. See the LICENSE file for more information.

Citation

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

@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.
• Email: [e-mail]