Getting Started with IGN LiDAR HD

Welcome to IGN LiDAR HD! This comprehensive guide will help you get started with processing French National Geographic Institute LiDAR data.

What is IGN LiDAR HD?

IGN LiDAR HD is a Python library designed to process high-density LiDAR data from the French National Geographic Institute (IGN) into machine learning-ready datasets. It provides tools for:

• Data Download: Automated downloading of IGN LiDAR tiles
• Feature Extraction: Building detection, vegetation classification, ground analysis
• RGB Augmentation: Color enrichment from orthophotos
• Data Export: Multiple output formats for different applications
• GPU Acceleration: High-performance processing for large datasets

Prerequisites

System Requirements

Minimum Requirements:

• Python 3.8 or higher
• 8GB RAM
• 10GB free disk space
• Internet connection for data download

Recommended Requirements:

• Python 3.11
• 16GB+ RAM
• SSD storage with 50GB+ free space
• NVIDIA GPU with 8GB+ VRAM (optional)

Python Environment

We strongly recommend using a virtual environment:

# Create virtual environment
python -m venv ign_lidar_env

# Activate environment
# Linux/macOS:
source ign_lidar_env/bin/activate
# Windows:
ign_lidar_env\Scripts\activate

Installation

Standard Installation

# Install from PyPI
pip install ign-lidar-hd

# Verify installation
ign-lidar-hd --version

Development Installation

# Clone repository
git clone https://github.com/sducournau/IGN_LIDAR_HD_DATASET.git
cd IGN_LIDAR_HD_DATASET

# Install in development mode
pip install -e .

# Install with optional dependencies
pip install -e .[gpu,dev,docs]

GPU Support (Optional)

For GPU acceleration:

# Install with GPU support
pip install ign-lidar-hd[gpu]

# Verify GPU setup
python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}')"

First Steps

1. System Information

Check your system configuration:

# Display system information
ign-lidar-hd system-info

# Expected output:
# IGN LiDAR HD v2.0.2
# Python: 3.11.5
# Platform: Linux-6.2.0-39-generic
# CPU Cores: 16
# Available RAM: 31.3 GB
# GPU Available: True (NVIDIA RTX 4090)

2. Configuration Setup

Create your first configuration file:

# Generate default configuration
ign-lidar-hd config --template > my_config.yaml

Edit the configuration:

# my_config.yaml
processing:
  chunk_size: 1000000
  n_jobs: -1 # Use all CPU cores
  use_gpu: false # Set to true if GPU available

output:
  format: "laz" # Output format
  compression: 7

features:
  buildings: true
  vegetation: true
  ground: true

quality:
  validation: true
  generate_reports: true

3. Your First Download

Download your first LiDAR tile:

# Download a sample tile (Paris area)
ign-lidar-hd download --tiles 0631_6275 --output-dir ./data

# Check downloaded files
ls -la ./data/
# Expected: 0631_6275.las (or .laz)

4. Basic Processing

Process the downloaded tile:

# Basic enrichment
ign-lidar-hd enrich \
  --input ./data/0631_6275.las \
  --output ./data/enriched_0631_6275.laz \
  --features buildings vegetation

# Check the results
ign-lidar-hd info ./data/enriched_0631_6275.laz

Understanding Your Data

LiDAR File Structure

IGN LiDAR files contain point cloud data with these attributes:

# Basic point attributes
point_attributes = {
    'X': 'Easting coordinate (Lambert 93)',
    'Y': 'Northing coordinate (Lambert 93)',
    'Z': 'Elevation (NGF-IGN69)',
    'Intensity': 'Return intensity value',
    'Return_Number': 'Return sequence (1st, 2nd, etc.)',
    'Number_of_Returns': 'Total returns per pulse',
    'Classification': 'Point classification code',
    'Scanner_Channel': 'Scanner channel ID',
    'User_Data': 'Additional user data',
    'Point_Source_ID': 'Source identifier',
    'GPS_Time': 'GPS timestamp'
}

# After enrichment, additional attributes:
enriched_attributes = {
    'Building_ID': 'Building instance identifier',
    'Vegetation_Type': 'Vegetation classification',
    'Red': 'RGB color - Red channel',
    'Green': 'RGB color - Green channel',
    'Blue': 'RGB color - Blue channel'
}

Coordinate System

IGN LiDAR data uses the French coordinate system:

• Projection: Lambert 93 (EPSG:2154)
• Vertical Datum: NGF-IGN69
• Units: Meters

Data Quality

Check data quality with:

# Validate LiDAR file
ign-lidar-hd validate ./data/0631_6275.las

# Get detailed statistics
ign-lidar-hd stats ./data/0631_6275.las --detailed

Basic Workflows

Workflow 1: Simple Enrichment

Download, process, and export a single tile:

#!/bin/bash
# simple_workflow.sh

# 1. Download data
echo "Downloading LiDAR data..."
ign-lidar-hd download --tiles 0631_6275 --output-dir ./data

# 2. Enrich with features
echo "Enriching with building features..."
ign-lidar-hd enrich \
  --input ./data/0631_6275.las \
  --output ./data/enriched_0631_6275.laz \
  --config my_config.yaml

# 3. Generate report
echo "Generating processing report..."
ign-lidar-hd report ./data/enriched_0631_6275.laz --output ./reports/

echo "Workflow complete!"

Workflow 2: Batch Processing

Process multiple tiles:

#!/bin/bash
# batch_workflow.sh

# List of tiles to process
TILES=("0631_6275" "0631_6276" "0632_6275")

for TILE in "${TILES[@]}"; do
    echo "Processing tile: $TILE"

    # Download
    ign-lidar-hd download --tiles $TILE --output-dir ./data

    # Process
    ign-lidar-hd enrich \
      --input ./data/${TILE}.las \
      --output ./data/enriched_${TILE}.laz \
      --features buildings vegetation ground \
      --parallel
done

echo "Batch processing complete!"

Workflow 3: RGB Augmentation

Add color information from orthophotos:

# Download orthophoto (if available)
ign-lidar-hd download-orthophoto \
  --tile 0631_6275 \
  --output-dir ./orthophotos

# Enrich with RGB colors
ign-lidar-hd enrich \
  --input ./data/0631_6275.las \
  --output ./data/rgb_enriched_0631_6275.laz \
  --rgb-source ./orthophotos/0631_6275.tif \
  --features buildings vegetation

Python API Basics

Using the Python API

from ign_lidar import Processor, Config

# Create configuration
config = Config(
    chunk_size=500000,
    use_gpu=False,
    features={
        'buildings': True,
        'vegetation': True,
        'ground': False
    }
)

# Initialize processor
processor = Processor(config=config)

# Process a file
result = processor.process_file(
    input_path="data/0631_6275.las",
    output_path="data/processed_0631_6275.laz"
)

# Check results
print(f"Points processed: {result.points_count:,}")
print(f"Buildings detected: {result.buildings_count}")
print(f"Processing time: {result.processing_time:.2f}s")

Working with Point Clouds

import numpy as np
from ign_lidar import PointCloud

# Load point cloud
pc = PointCloud.from_file("data/0631_6275.las")

# Basic information
print(f"Number of points: {len(pc):,}")
print(f"Bounds: {pc.bounds}")
print(f"Point density: {pc.density:.1f} pts/m²")

# Access point data
points = pc.points  # (N, 3) array of XYZ coordinates
colors = pc.colors  # (N, 3) array of RGB values
classifications = pc.classifications  # (N,) array of class labels

# Filter points
buildings = pc.filter_by_classification([6])  # Building points
vegetation = pc.filter_by_classification([3, 4, 5])  # Vegetation points

# Export filtered data
buildings.save("buildings_only.laz")
vegetation.save("vegetation_only.laz")

Feature Extraction

from ign_lidar.features import BuildingDetector, VegetationClassifier

# Initialize feature extractors
building_detector = BuildingDetector(
    min_points=100,
    min_height=2.0,
    planarity_threshold=0.1
)

vegetation_classifier = VegetationClassifier(
    height_threshold=0.5,
    density_threshold=1.0
)

# Extract buildings
buildings = building_detector.extract_buildings(pc)

# Classify vegetation
vegetation_types = vegetation_classifier.classify_vegetation(pc)

print(f"Detected {len(buildings)} buildings")
print(f"Vegetation coverage: {vegetation_types.coverage:.1%}")

Common Tasks

Task 1: Convert File Formats

# Convert LAS to LAZ (compressed)
ign-lidar-hd convert \
  --input data/input.las \
  --output data/output.laz \
  --format laz

# Convert to ASCII format
ign-lidar-hd convert \
  --input data/input.las \
  --output data/output.txt \
  --format ascii \
  --fields "x,y,z,classification,intensity"

Task 2: Extract Specific Features

# Extract only buildings
ign-lidar-hd extract \
  --input data/tile.las \
  --output data/buildings.laz \
  --feature buildings \
  --min-height 2.0

# Extract ground points
ign-lidar-hd extract \
  --input data/tile.las \
  --output data/ground.laz \
  --feature ground \
  --method cloth_simulation

Task 3: Quality Analysis

# Check data completeness
ign-lidar-hd quality \
  --input data/tile.las \
  --checks completeness,density,accuracy \
  --report quality_report.html

# Validate against standards
ign-lidar-hd validate \
  --input data/tile.las \
  --standard ign_hd \
  --output validation_report.json

Troubleshooting Common Issues

Issue 1: Out of Memory Errors

# Reduce chunk size
ign-lidar-hd enrich \
  --input large_file.las \
  --output processed.laz \
  --chunk-size 500000  # Smaller chunks

# Use streaming processing
ign-lidar-hd enrich \
  --input large_file.las \
  --output processed.laz \
  --streaming \
  --max-memory 4GB

Issue 2: Slow Processing

# Enable parallel processing
ign-lidar-hd enrich \
  --input file.las \
  --output processed.laz \
  --parallel \
  --workers 8

# Use GPU acceleration (if available)
ign-lidar-hd enrich \
  --input file.las \
  --output processed.laz \
  --gpu \
  --batch-size 50000

Issue 3: Download Failures

# Retry with different settings
ign-lidar-hd download \
  --tiles 0631_6275 \
  --output-dir ./data \
  --retry 3 \
  --timeout 300 \
  --verify-checksums

# Use alternative download method
ign-lidar-hd download \
  --tiles 0631_6275 \
  --output-dir ./data \
  --method direct \
  --mirror alternative

Next Steps

Learning Path

1. 📖 Read the Documentation

   • Basic Usage Guide
   • CLI Commands Reference
   • API Documentation

2. 🔧 Try Advanced Features

   • GPU Acceleration
   • Pipeline Configuration
   • RGB Augmentation

3. 🎯 Explore Use Cases

   • QGIS Integration
   • Custom Features
   • Regional Processing

Community and Support

• 📚 Documentation: Complete guides and API reference
• 🐛 Issue Tracker: Report bugs and request features
• 💬 Discussions: Community support and examples
• 📧 Contact: Direct support for users

Example Projects

Get inspired by these example projects:

# Clone examples repository
git clone https://github.com/sducournau/ign-lidar-examples.git
cd ign-lidar-examples

# Try the examples
python examples/building_extraction.py
python examples/vegetation_analysis.py
python examples/urban_planning_workflow.py

Configuration Reference

Basic Configuration Options

# Complete configuration example
processing:
  chunk_size: 1000000 # Points per processing chunk
  n_jobs: -1 # CPU cores (-1 = all)
  use_gpu: false # Enable GPU acceleration
  memory_limit: "8GB" # Maximum memory usage

input:
  coordinate_system: "EPSG:2154" # Lambert 93
  validation: true # Validate input files

output:
  format: "laz" # Output format
  compression: 7 # Compression level (1-9)
  precision: 0.01 # Coordinate precision

features:
  buildings:
    enabled: true
    min_points: 100
    min_height: 2.0

  vegetation:
    enabled: true
    height_threshold: 0.5

  ground:
    enabled: false
    method: "cloth_simulation"

quality:
  validation: true # Validate outputs
  generate_reports: true # Create quality reports
  error_threshold: 0.1 # Maximum acceptable error

Related Documentation

• Installation Guide
• Basic Usage
• CLI Commands
• Configuration API