links-ads/perform-models

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

git clone <repository-url>
cd perform-models

2. Set up environment

# 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

# 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

# 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

# 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

# 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:

UID=1000
GID=1000

GPU Support

For GPU acceleration, use the GPU compose override:

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

# 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 file for details.