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

```bash
# 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
# 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**:
```bash
docker build -t kamlan-gradio .
docker run -p 7860:7860 -e EE="your_credentials" kamlan-gradio
```

#### Option C: Direct Server Deployment

1. **Install dependencies**:
```bash
pip install -r requirements_gradio.txt
```

2. **Set up credentials**:
```bash
export EE="your_earth_engine_credentials_json"
```

3. **Run with process manager** (e.g., PM2, supervisor):
```bash
# 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:**
```json
{
    "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:**
```json
{
    "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](https://sustainability-lab.github.io/), IIT Gandhinagar  
Supported by Gujarat Forest Department