deployment_instructions.md

Kamlan KML Analyzer - Gradio Version Deployment Instructions

Overview

This is a Gradio-based version of the Kamlan KML Analyzer that includes API endpoints for Google Sheets integration. The app provides both a web interface and REST API endpoints for programmatic access.

Features

• Web Interface: User-friendly Gradio interface for KML analysis
• REST API: Endpoints for Google Sheets integration via Apps Script
• Geometry Analysis: Centroid, area, perimeter calculations
• Map Visualization: Interactive maps with satellite imagery
• Export Capabilities: CSV download of metrics

Quick Start

1. Local Development

# Clone and navigate to the directory
cd NDVI_PERG

# Install dependencies
pip install -r requirements_gradio.txt

# Set up Earth Engine credentials (if not already done)
# Option 1: Use existing credentials
# Option 2: Set environment variable
export EE="your_earth_engine_credentials_json"

# Run the application
python gradio_app.py

The app will be available at http://localhost:7860

2. Production Deployment

Option A: Hugging Face Spaces

1. Create a new Hugging Face Space
2. Upload these files:
   • gradio_app.py
   • functions.py
   • requirements_gradio.txt
3. Set the Earth Engine credentials in the Space secrets:

   EE = your_earth_engine_credentials_json
   

Option B: Cloud Deployment (AWS/GCP/Azure)

1. Containerized Deployment (Recommended):

# Dockerfile
FROM python:3.9-slim

WORKDIR /app

COPY requirements_gradio.txt .
RUN pip install -r requirements_gradio.txt

COPY . .

EXPOSE 7860

CMD ["python", "gradio_app.py"]

2. Build and run:

docker build -t kamlan-gradio .
docker run -p 7860:7860 -e EE="your_credentials" kamlan-gradio

Option C: Direct Server Deployment

1. Install dependencies:

pip install -r requirements_gradio.txt

2. Set up credentials:

export EE="your_earth_engine_credentials_json"

3. Run with process manager (e.g., PM2, supervisor):

# Using PM2
pm2 start gradio_app.py --name kamlan-gradio --interpreter python3

# Using nohup
nohup python gradio_app.py > app.log 2>&1 &

API Endpoints

Base URL

Replace YOUR_API_BASE_URL with your deployed app URL (e.g., https://your-space.hf.space)

Available Endpoints

1. Analyze KML

GET /api/analyze_kml?file_url=<kml_url>

Response:

{
    "success": true,
    "data": {
        "centroid_lat": 23.123456,
        "centroid_lon": 72.123456,
        "area_m2": 50000.25,
        "area_ha": 5.00,
        "perimeter_m": 894.35,
        "coordinates": [...],
        "gmaps_url": "http://maps.google.com/maps?q=23.123456,72.123456&layer=satellite"
    }
}

2. Health Check

GET /api/health

Response:

{
    "status": "healthy",
    "message": "KML Analyzer API is running"
}

Google Sheets Integration

1. Set up Apps Script

1. Open Google Sheets
2. Go to Extensions > Apps Script
3. Copy the contents of google_apps_script_example.js
4. Update the API_BASE_URL variable with your deployed app URL
5. Save the script

2. Usage in Spreadsheet

Formula-based usage:

=analyzeKML("https://example.com/your-file.kml")
=getCentroid("https://example.com/your-file.kml")
=getArea("https://example.com/your-file.kml")
=getPerimeter("https://example.com/your-file.kml")

Batch processing:

1. Put KML URLs in Column A
2. Use the custom menu: "KML Analysis" > "Analyze KMLs in Column A"

Environment Variables

Variable	Description	Required
EE	Earth Engine credentials JSON	Yes
PORT	Port to run the app (default: 7860)	No

Troubleshooting

Common Issues

1. Earth Engine Authentication Error:

   • Ensure EE credentials are properly set
   • Verify the credentials JSON format

2. Memory Issues:

   • For large KML files, increase container memory limits
   • Consider implementing file size limits

3. API Rate Limiting:

   • Implement request throttling for batch operations
   • Add caching for frequently accessed files

Logs and Monitoring

• Check application logs for debugging
• Monitor API endpoint response times
• Set up health check monitoring

Security Considerations

1. API Security:

   • Implement API rate limiting
   • Add authentication if needed
   • Validate input URLs

2. File Processing:

   • Limit file size uploads
   • Sanitize file inputs
   • Implement timeout for processing

Performance Optimization

1. Caching:

   • Cache processed KML results
   • Implement Redis for session storage

2. Scaling:

   • Use load balancers for multiple instances
   • Implement horizontal scaling

3. Earth Engine Optimization:

   • Use Earth Engine batch processing
   • Implement result caching

Support

For issues and questions:

• Check the application logs
• Review Earth Engine quotas and limits
• Contact the Sustainability Lab at IIT Gandhinagar

Credits

Developed by Sustainability Lab, IIT Gandhinagar
Supported by Gujarat Forest Department