Skip to content

Quick Start

Get CulicidaeLab Server up and running in minutes with this quick start guide.

Prerequisites

Before starting, ensure you have completed the installation process.

Starting the Application

CulicidaeLab Server consists of two main components that need to be running:

1. Start the Backend API Server

Open a terminal and navigate to your project directory:

cd culicidaelab-server
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uvicorn backend.main:app --port 8000 --host 127.0.0.1

The backend API will be available at: - API Base: http://localhost:8000 - Interactive API Documentation (Swagger): http://localhost:8000/docs - Alternative API Documentation (ReDoc): http://localhost:8000/redoc

2. Start the Frontend Application

Open a new terminal and navigate to your project directory:

cd culicidaelab-server
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
solara run frontend.main

The frontend application will be available at http://localhost:8765 (or the port shown in your terminal).

First Steps

1. Explore the Web Interface

  1. Open your browser and go to http://localhost:8765
  2. You'll see the CulicidaeLab Server homepage with navigation to different features
  3. Explore the main sections:
  4. Species Prediction: Upload mosquito images for AI-powered identification
  5. Interactive Map: View mosquito observations and distribution data
  6. Species Gallery: Browse information about different mosquito species
  7. Disease Information: Learn about mosquito-borne diseases

2. Test Species Prediction

  1. Navigate to the Species Prediction page
  2. Upload a mosquito image (JPEG, PNG formats supported)
  3. Wait for the AI model to process the image
  4. Review the prediction results with confidence scores

3. Explore the Interactive Map

  1. Go to the Map Visualization page
  2. View sample observation data plotted on the interactive map
  3. Click on markers to see detailed observation information
  4. Use map controls to zoom and pan around different regions

4. Browse the API Documentation

  1. Visit http://localhost:8000/docs for interactive API documentation
  2. Explore available endpoints:
  3. /predict/species - Species prediction from images
  4. /observations - Mosquito observation data
  5. /species - Species information
  6. /diseases - Disease information
  7. Try out API endpoints directly from the documentation interface

Basic Usage Examples

Making API Calls

You can interact with the API using curl, Python requests, or any HTTP client:

# Get all species
curl http://localhost:8000/species

# Get observations with limit
curl http://localhost:8000/observations?limit=10

# Get disease information
curl http://localhost:8000/diseases

Python API Usage

import requests

# Get species data
response = requests.get("http://localhost:8000/species")
species_data = response.json()

# Upload image for prediction (example)
with open("mosquito_image.jpg", "rb") as f:
    files = {"file": f}
    response = requests.post("http://localhost:8000/predict/species", files=files)
    prediction = response.json()

Configuration

Basic Configuration

The application uses default settings that work for most development scenarios. For custom configuration:

  1. Backend Configuration: Edit backend/.env file
  2. Frontend Configuration: Modify frontend/config.py

Common Configuration Options

  • API Port: Change the backend port by modifying the uvicorn command
  • Frontend Port: Solara will automatically select an available port
  • Database Path: Configure LanceDB path in backend configuration
  • Model Settings: Adjust AI model parameters in the backend configuration

Troubleshooting

Application Won't Start

  1. Check Python Environment: 

    python --version  # Should show Python 3.11.x
which python      # Should point to your virtual environment

  2. Verify Dependencies: 

    pip list | grep fastapi
pip list | grep solara

  3. Check Port Availability:

  4. Ensure ports 8000 and 8765 are not in use by other applications
  5. Use different ports if needed: uvicorn backend.main:app --port 8001

Performance Issues

  1. GPU Not Detected:
  2. Check NVIDIA drivers and CUDA installation

  3. The application will fall back to CPU processing automatically

  4. Slow Predictions:

  5. Ensure GPU is properly configured for faster inference

  6. Consider using smaller image sizes for faster processing

  7. Memory Issues:

  8. Reduce batch sizes in model configuration
  9. Close other memory-intensive applications

Common Error Messages

  • "Module not found": Ensure virtual environment is activated and dependencies are installed
  • "Port already in use": Change the port number or stop the conflicting process
  • "Database not found": Run the database initialization script again

Next Steps

Now that you have CulicidaeLab Server running:

  1. Learn More: Read the User Guide for detailed feature documentation
  2. Develop: Check the Developer Guide for development information
  3. Deploy: See the Deployment Guide for production deployment
  4. Contribute: Review the Contributing Guidelines to contribute to the project

Getting Help

If you encounter issues: