Skip to main content

IGN LiDAR HD Processing Library

Version 2.4.2+ | Python 3.8+ | MIT License

PyPI version Python 3.8+ License: MIT

Transform French IGN LiDAR HD point clouds into ML-ready datasets for building classification. Features GPU acceleration, rich geometric features (all 35-45+ computed features now exported), RGB/NIR augmentation, intelligent skip system, and memory-optimized configurations for all system specs.

πŸš€ Quick Start​

# Install
pip install ign-lidar-hd

# Download sample data
ign-lidar-hd download --bbox 2.3,48.8,2.4,48.9 --output data/ --max-tiles 5

# Process with default settings
ign-lidar-hd process input_dir=data/ output_dir=patches/

For GPU acceleration (12-20x speedup), see the GPU Setup Guide.

✨ Key Features​

  • πŸ—ΊοΈ IGN Integration - Direct download from IGN WFS service
  • 🎨 Multi-modal Data - Geometry + RGB + Infrared (NDVI-ready)
  • πŸ—οΈ Building Classification - LOD2/LOD3/Full schemas (12-43+ features)
  • πŸ“Š Complete Features - All 35-45+ computed geometric features now exported to disk
  • πŸ“ Feature Tracking - Metadata includes feature names and counts for reproducibility
  • πŸš€ GPU Acceleration - 12-20x speedup with RAPIDS cuML
  • ⚑ Intelligent Skip - ~1800x faster on re-runs, automatic recovery
  • βš™οΈ YAML Configuration - Reproducible workflows with example configs

πŸ“‹ Processing Modes​

Choose the right mode for your workflow:

Patches Only (Default)​

ML-ready patches for training:

ign-lidar-hd process input_dir=data/ output_dir=patches/

Both Patches & Enriched LAZ​

Training + GIS visualization:

ign-lidar-hd process input_dir=data/ output_dir=both/ output.processing_mode=both

Enriched LAZ Only​

Fast GIS workflow:

ign-lidar-hd process input_dir=data/ output_dir=enriched/ output.processing_mode=enriched_only
tip

For ML applications, patches provide cleaner geometric features than LAZ tiles (no boundary artifacts).

πŸ“ Configuration Examples​

Production-ready configs in the examples/ directory:

# GPU-accelerated processing
ign-lidar-hd process --config-file examples/config_gpu_processing.yaml \
  input_dir=data/raw output_dir=data/enriched

# ML training with augmentation
ign-lidar-hd process --config-file examples/config_training_dataset.yaml \
  input_dir=data/raw output_dir=data/patches

# Preview configuration
ign-lidar-hd process --config-file examples/config_training_dataset.yaml --show-config

See example configs directory for complete workflows.

πŸ“¦ Output Formats​

  • NPZ - NumPy format (recommended for ML)
  • HDF5 - Hierarchical data format
  • PyTorch - .pt files for PyTorch training
  • LAZ - Point cloud visualization (CloudCompare, QGIS)
  • Multi-format - Combine formats: npz,laz, hdf5,torch

🎯 What's New​

v2.4.2 (2025-10-12) - Latest Release​

  • οΏ½ Full GPU Acceleration: Complete GPU implementation for all advanced features in "full" mode
  • ⚑ 5-10x Speedup: Massive performance boost for large point clouds (>10M points) with GPU
  • 🎯 GPU-Accelerated Features: Eigenvalue, architectural, and density features now on GPU
  • πŸ”„ Seamless Fallback: Automatic GPU/CPU switching with zero API changes
  • βœ… Same Quality: Identical output quality, same interface, better performance

Read the full release notes β†’

Previous Releases​

v2.4.1 - Full feature mode fix (all 30 features)
v2.4.0 - Enhanced feature validation, production-ready ML stability
v2.3.0 - Processing modes, YAML configs, intelligent skip system
v2.0.0 - Modular architecture, boundary-aware features

οΏ½ Common Workflows​

Download and Process​

# Download tiles for a region
ign-lidar-hd download --bbox 2.3,48.8,2.4,48.9 --output data/ --max-tiles 10

# Process with GPU acceleration
ign-lidar-hd process input_dir=data/ output_dir=patches/ processor.use_gpu=true

LOD3 with RGB and NDVI​

ign-lidar-hd process \
  input_dir=data/ \
  output_dir=patches/ \
  processor.lod_level=LOD3 \
  features.use_rgb=true \
  features.compute_ndvi=true

Python API​

from ign_lidar import LiDARProcessor, IGNLiDARDownloader

# Download tiles
downloader = IGNLiDARDownloader("downloads/")
tiles = downloader.download_by_bbox(bbox=(2.3, 48.8, 2.4, 48.9), max_tiles=5)

# Process with custom settings
processor = LiDARProcessor(lod_level="LOD3", use_gpu=True)
patches = processor.process_directory("data/", "patches/", num_workers=4)

# PyTorch integration
from torch.utils.data import DataLoader
from ign_lidar import LiDARPatchDataset

dataset = LiDARPatchDataset("patches/")
dataloader = DataLoader(dataset, batch_size=32, shuffle=True)

πŸ“¦ Output Structure​

NPZ File Contents:

{
    'points': np.ndarray,        # [N, 3] XYZ coordinates
    'normals': np.ndarray,       # [N, 3] surface normals
    'curvature': np.ndarray,     # [N] principal curvature
    'labels': np.ndarray,        # [N] building class labels
    # Optional: RGB, infrared, geometric features
}

Directory Structure:

output_dir/
β”œβ”€β”€ tile1_patch_0001.npz
β”œβ”€β”€ tile1_patch_0002.npz
β”œβ”€β”€ tile1_enriched.laz          # if processing_mode="both"
└── metadata.json

οΏ½ Learn More​

Getting Started​

Advanced Features​

Reference​

🀝 Support​

πŸ“„ License​

MIT License - See LICENSE for details.