README.md

---
license: cc-by-nc-sa-4.0
---

# PERFORM Models

This repository contains code and models implemented during the PERFORM project for automated detection and segmentation of photovoltaic panels and trees from aerial imagery using deep learning models deployed with NVIDIA Triton Inference Server.

## Prerequisites

- Docker and Docker Compose
- NVIDIA GPU with Docker GPU support (recommended)
- At least 32GB RAM for Triton server
- Input imagery in GeoTIFF format

## Installation and Usage

### 1. Clone the repository
```bash
git clone <repository-url>
cd perform-models
```

### 2. Set up environment
```bash
# Set your user ID for proper file permissions
export UID=$(id -u)
export GID=$(id -g)
```

### 3. Prepare your data
- Place input GeoTIFF files in the `inputs/` directory
- Results will be saved to the `outputs/` directory

### 4. Run inference

#### PV Panels Detection
```bash
# Basic usage
docker-compose run cli panels --model_name perform_pv_panels

# With custom resolution (default: 25cm/pixel)
docker-compose run cli panels --model_name perform_pv_panels --target_resolution 0.3

# Custom input/output paths
docker-compose run cli panels \
  --model_name perform_pv_panels \
  --input_path /app/inputs \
  --output_path /app/outputs
```

#### Rooftop Detection
```bash
# Basic usage
docker-compose run cli rooftop --model_name perform_rooftop

# With custom resolution (default: 25cm/pixel)
docker-compose run cli rooftop --model_name perform_rooftop --target_resolution 0.3

# Custom input/output paths
docker-compose run cli rooftop \
  --model_name perform_rooftop \
  --input_path /app/inputs \
  --output_path /app/outputs
```

#### Tree Segmentation
```bash
# Basic usage
docker-compose run cli trees

# With custom model
docker-compose run cli trees --model_name custom_tree_model

# Custom paths
docker-compose run cli trees \
  --input_path /app/inputs \
  --output_path /app/outputs
```

### 5. View help
```bash
# General help
docker-compose run cli --help

# Subcommand help
docker-compose run cli panels --help
docker-compose run cli trees --help
```

## Project Structure

```
├── docker/                    # Docker configuration files
│   ├── python.dockerfile     # Python CLI container
│   └── triton.dockerfile     # Triton server container
├── inputs/                   # Input GeoTIFF files (mount point)
├── outputs/                  # Output results (mount point)
├── model_repository/         # Triton model repository
│   └── ...
├── src/perform/             # Python package source
├── docker-compose.yml      # Main compose configuration
├── docker-compose.gpu.yml  # GPU-specific overrides
├── pyproject.toml          # Python package configuration
└── requirements.txt        # Python dependencies
```

## Models

### PV Panels Detection
- **Input**: RGB aerial imagery (8-10cm/pixel, automatically resampled to 25cm/pixel)
- **Output**: 
  - Segmentation masks (GeoTIFF)
  - Vectorized polygons with building regularization (Parquet)
- **Model**: `perform_pv_panels`

### Rooftop Detection
- **Input**: RGB aerial imagery (8-10cm/pixel, automatically resampled to 25cm/pixel)
- **Outputs**: 
  - Segmentation masks (GeoTIFF) with roof orientation
    0. Background
    1. Flat
    2. North
    3. East
    4. South
    5. West
  - Binary segmentation masks (GeoTIFF) with roof edges
- **Model**: `perform_rooftop`

### Tree Segmentation
- **Input**: RGB aerial imagery (TIFF format)
- **Output**: Tree polygons (Parquet format)
- **Model**: `perform_tree_crown`

## Configuration

### Environment Variables
Create a `.env` file:
```bash
UID=1000
GID=1000
```

### GPU Support
For GPU acceleration, use the GPU compose override:
```bash
docker-compose -f docker-compose.yml -f docker-compose.gpu.yml run cli panels --model_name perform_pv_panels
```

### Server Configuration
- Triton server runs on ports 8000 (HTTP), 8001 (gRPC), 8002 (metrics)
- Health check endpoint: `http://localhost:8000/v2/health/ready`
- The CLI automatically waits for Triton to be ready before starting inference

## Output Formats

- **Rasters**: GeoTIFF format with preserved georeferencing
- **Vectors**: Parquet format with geometry and attributes
- **Naming**: Output files use the same name as input files with appropriate extensions

## Development

### Local Installation
```bash
# Install in development mode
pip install -e .

# Run locally (requires Triton server)
perform panels --model_name perform_pv_panels --server_url localhost:8000
```

### Adding New Models
1. Add model to `model_repository/` following Triton format
2. Implement inference logic in `src/perform/cli.py`
3. Add new subcommand to CLI

## License

This project is licensed under CC BY-NC-SA 4.0 - see the [LICENSE](LICENSE) file for details.