Skip to main content

CLI Commands Reference

Complete reference for all command-line interface commands in the IGN LiDAR HD Processing Library.

Command Structure​

All commands follow this structure:

ign-lidar-hd COMMAND [options]

# Or using the installed command (if in PATH)
ign-lidar-hd COMMAND [options]

Available Commands​

  • download - Download LiDAR tiles from IGN servers
  • enrich - Add building features to LAZ files
  • verify - Verify features in enriched LAZ files
  • patch - Extract patches from enriched tiles (renamed from process)
  • process - ⚠️ Deprecated alias for patch
  • pipeline - Execute complete workflows from YAML configuration

download​

Download LiDAR tiles for a specified area.

Syntax​

ign-lidar-hd download \
  --bbox MIN_LON,MIN_LAT,MAX_LON,MAX_LAT \
  --output OUTPUT_DIR \
  [--max-tiles MAX_TILES] \
  [--force]

Parameters​

ParameterTypeRequiredDescription
--bboxfloat,float,float,floatYesBounding box as min_lon,min_lat,max_lon,max_lat
--outputstringYesOutput directory for downloaded tiles
--max-tilesintegerNoMaximum number of tiles to download
--forceflagNoForce re-download existing tiles

Examples​

# Download tiles for Paris center (up to 10 tiles)
ign-lidar-hd download \
  --bbox 2.25,48.82,2.42,48.90 \
  --output /data/raw_tiles/ \
  --max-tiles 10

# Download all available tiles in area
ign-lidar-hd download \
  --bbox 2.25,48.82,2.42,48.90 \
  --output /data/raw_tiles/

# Force re-download existing tiles
ign-lidar-hd download \
  --bbox 2.25,48.82,2.42,48.90 \
  --output /data/raw_tiles/ \
  --force

Output​

Downloads LAZ files named with IGN conventions:

raw_tiles/
├── LIDARHD_FXX_0123_4567_LA93_IGN69_2020.laz
├── LIDARHD_FXX_0124_4567_LA93_IGN69_2020.laz
└── ...

Notes​

  • Coordinates must be in WGS84 (longitude/latitude)
  • Valid range for France: longitude 1-8°, latitude 42-51°
  • Files are typically 200-300 MB each
  • Smart skip detection avoids re-downloading existing files

enrich​

Add building component features to LiDAR point clouds.

Syntax​

ign-lidar-hd enrich \
  --input-dir INPUT_DIR \
  --output OUTPUT_DIR \
  --mode MODE \
  [--num-workers WORKERS] \
  [--force]

Parameters​

ParameterTypeRequiredDescription
--input-dirstringYesDirectory containing raw LAZ tiles
--outputstringYesOutput directory for enriched tiles
--modestringYesFeature extraction mode: core or full
--num-workersintegerNoNumber of parallel workers (default: 4)
--forceflagNoForce re-enrichment of existing files
--preprocessflagNo🆕 Enable preprocessing for artifact mitigation
--sor-kintegerNo🆕 SOR: number of neighbors (default: 12)
--sor-stdfloatNo🆕 SOR: std multiplier (default: 2.0)
--ror-radiusfloatNo🆕 ROR: search radius in meters (default: 1.0)
--ror-neighborsintegerNo🆕 ROR: min neighbors required (default: 4)
--voxel-sizefloatNo🆕 Voxel downsampling size in meters (optional)

Examples​

# Enrich tiles with all features
ign-lidar-hd enrich \
  --input-dir /data/raw_tiles/ \
  --output /data/enriched_tiles/ \
  --mode full

# Use 8 parallel workers
ign-lidar-hd enrich \
  --input-dir /data/raw_tiles/ \
  --output /data/enriched_tiles/ \
  --mode full \
  --num-workers 8

# Force re-enrichment
ign-lidar-hd enrich \
  --input-dir /data/raw_tiles/ \
  --output /data/enriched_tiles/ \
  --mode full \
  --force

# 🆕 With preprocessing (artifact mitigation)
ign-lidar-hd enrich \
  --input-dir /data/raw_tiles/ \
  --output /data/enriched_tiles/ \
  --mode full \
  --preprocess

# 🆕 Conservative preprocessing (preserve detail)
ign-lidar-hd enrich \
  --input-dir /data/raw_tiles/ \
  --output /data/enriched_tiles/ \
  --mode full \
  --preprocess \
  --sor-k 15 \
  --sor-std 3.0 \
  --ror-radius 1.5 \
  --ror-neighbors 3

# 🆕 Aggressive preprocessing (maximum artifact removal)
ign-lidar-hd enrich \
  --input-dir /data/raw_tiles/ \
  --output /data/enriched_tiles/ \
  --mode full \
  --preprocess \
  --sor-k 10 \
  --sor-std 1.5 \
  --ror-radius 0.8 \
  --ror-neighbors 5 \
  --voxel-size 0.3

Output​

Creates enriched LAZ files with additional point attributes:

enriched_tiles/
├── LIDARHD_FXX_0123_4567_LA93_IGN69_2020.laz  # +30 geometric features
├── LIDARHD_FXX_0124_4567_LA93_IGN69_2020.laz
└── ...

Features Added​

The enrichment process adds 30+ geometric features per point:

  • Normal vectors (nx, ny, nz)
  • Curvature (mean, gaussian)
  • Planarity and sphericity
  • Verticality and eigenvalues
  • Density measures
  • Height statistics
  • And more...

🆕 Preprocessing for Artifact Mitigation​

The --preprocess flag enables point cloud preprocessing before feature computation to reduce LiDAR scan line artifacts and improve geometric feature quality.

Techniques Applied:

  1. Statistical Outlier Removal (SOR)

    • Removes points with abnormal distances to k-nearest neighbors
    • Configurable with --sor-k (neighbors) and --sor-std (threshold)
    • Eliminates measurement errors, atmospheric noise, birds

  2. Radius Outlier Removal (ROR)

    • Removes isolated points without sufficient neighbors in radius
    • Configurable with --ror-radius (meters) and --ror-neighbors (count)
    • Reduces scan line artifacts and edge noise

  3. Voxel Downsampling (Optional)

    • Homogenizes point density using voxel grid
    • Enabled with --voxel-size parameter (e.g., 0.5 for 0.5m voxels)
    • Reduces memory usage and processing time

Expected Impact:

  • 🎯 60-80% reduction in scan line artifacts
  • 📊 40-60% cleaner surface normals
  • 🔧 30-50% smoother edge features
  • ⚡ 15-30% processing overhead (when enabled)

Recommended Presets:

# Conservative (preserve maximum detail)
--preprocess --sor-k 15 --sor-std 3.0 --ror-radius 1.5 --ror-neighbors 3

# Standard (balanced quality/speed)
--preprocess --sor-k 12 --sor-std 2.0 --ror-radius 1.0 --ror-neighbors 4

# Aggressive (maximum artifact removal)
--preprocess --sor-k 10 --sor-std 1.5 --ror-radius 0.8 --ror-neighbors 5 --voxel-size 0.3

See the Preprocessing Guide for detailed information.

Notes​

  • Only building mode is currently supported
  • Processing time: ~2-5 minutes per tile (depends on point density)
  • Processing time with preprocessing: +15-30% overhead
  • Memory usage: ~2-4 GB per worker
  • Smart skip detection avoids re-enriching existing files

verify​

Verify features in enriched LAZ files to ensure quality and correctness.

Syntax​

ign-lidar-hd verify \
  --input INPUT_FILE \
  [--show-samples] \
  [--quiet]

# Or verify multiple files
ign-lidar-hd verify \
  --input-dir INPUT_DIR \
  [--max-files MAX_FILES] \
  [--show-samples] \
  [--quiet]

Parameters​

ParameterTypeRequiredDescription
--inputstring*Single LAZ file to verify
--input-dirstring*Directory of LAZ files to verify
--max-filesintegerNoMaximum number of files to verify
--show-samplesflagNoDisplay sample points from each file
--quietflagNoSuppress detailed output, show only summary

* Either --input or --input-dir must be specified

Examples​

# Verify a single file
ign-lidar-hd verify --input enriched/file.laz

# Verify all files in directory
ign-lidar-hd verify --input-dir enriched/

# Quick check with samples
ign-lidar-hd verify --input enriched/file.laz --show-samples

# Batch verification (first 10 files)
ign-lidar-hd verify --input-dir enriched/ --max-files 10

# Quiet mode (summary only)
ign-lidar-hd verify --input-dir enriched/ --quiet

What Gets Verified​

The verify command checks:

  • RGB Values
    • Presence of red, green, blue channels
    • Value ranges (0-255)
    • Color diversity and anomaly detection
  • NIR (Infrared) Values
    • Presence of NIR channel
    • Value distribution
    • Default value detection
  • Geometric Features
    • Linearity, planarity, sphericity
    • Anisotropy, roughness
    • Value range validation [0, 1]
  • Quality Checks
    • Out-of-range value detection
    • Missing feature warnings
    • Statistical distributions

Output​

Detailed analysis per file:

================================================================================
Analyzing: LHD_FXX_0473_6916.laz
================================================================================
Total points: 6,579,534

1. RGB VALUES CHECK
--------------------------------------------------------------------------------
✓ RGB channels present
  Red:   min= 64, max=255, mean=151.34, std= 39.22
  ...
  ✓ RGB values look good

2. NIR (INFRARED) VALUES CHECK
--------------------------------------------------------------------------------
✓ NIR channel present
  Range: 1 - 253
  ...

3. LINEARITY CHECK
--------------------------------------------------------------------------------
✓ Linearity present
  Range: 0.000073 - 0.999326
  ✓ Linearity values in valid range [0, 1]
...

Summary for multiple files:

================================================================================
VERIFICATION SUMMARY
================================================================================
Files verified: 10

Feature presence:
  ✓ rgb         : 10/10 files (100.0%)
  ✓ nir         : 10/10 files (100.0%)
  ✓ linearity   : 10/10 files (100.0%)
  ...

✓ No warnings detected
================================================================================

Notes​

  • Use after enrichment to validate processing
  • Helps debug RGB/NIR fetch issues
  • Detects feature computation errors
  • See CLI Reference - Verify for detailed documentation

patch​

Extract machine learning patches from enriched tiles with optional RGB augmentation.

Syntax​

ign-lidar-hd patch \
  --input INPUT_PATH \
  --output OUTPUT_DIR \
  --lod-level LOD_LEVEL \
  [--patch-size PATCH_SIZE] \
  [--num-workers WORKERS] \
  [--include-rgb] \
  [--rgb-cache-dir CACHE_DIR] \
  [--force]

Parameters​

ParameterTypeRequiredDescription
--inputstringYesPath to enriched LAZ file or directory
--outputstringYesOutput directory for patches
--lod-levelstringYesClassification level: LOD2 or LOD3
--patch-sizefloatNoPatch size in meters (default: 10.0)
--num-workersintegerNoNumber of parallel workers (default: 4)
--include-rgbflagNoAdd RGB colors from IGN orthophotos
--rgb-cache-dirstringNoCache directory for orthophoto downloads
--forceflagNoForce reprocessing existing patches

Examples​

# Create patches for LOD2 (geometry only)
ign-lidar-hd patch \
  --input /data/enriched_tiles/tile.laz \
  --output /data/patches/ \
  --lod-level LOD2

# Create patches with RGB augmentation from IGN orthophotos
ign-lidar-hd patch \
  --input /data/enriched_tiles/ \
  --output /data/patches/ \
  --lod-level LOD2 \
  --include-rgb \
  --rgb-cache-dir /data/cache/

# Process entire directory for LOD3 with RGB
ign-lidar-hd patch \
  --input /data/enriched_tiles/ \
  --output /data/patches/ \
  --lod-level LOD3 \
  --patch-size 15.0 \
  --num-workers 6 \
  --include-rgb

# Force reprocessing with RGB
ign-lidar-hd patch \
  --input /data/enriched_tiles/ \
  --output /data/patches/ \
  --lod-level LOD2 \
  --include-rgb \
  --force

Output​

Creates NPZ patch files organized by source tile:

patches/
├── tile_0123_4567/
│   ├── patch_0001.npz
│   ├── patch_0002.npz
│   └── ...
├── tile_0124_4567/
│   ├── patch_0001.npz
│   └── ...

Patch Contents​

Each NPZ file contains:

  • points: Point coordinates (N×3 array)
  • features: Geometric features (N×30+ array)
  • labels: Building component labels (N×1 array)
  • rgb: RGB colors (N×3 array, normalized 0-1) - only if --include-rgb is used
  • metadata: Patch information (dict)

RGB Augmentation​

When using --include-rgb, the library automatically:

  1. Fetches orthophotos from IGN BD ORTHO® service (20cm resolution)
  2. Maps each 3D point to its corresponding 2D orthophoto pixel
  3. Extracts RGB colors and normalizes them to [0, 1] range
  4. Caches downloaded orthophotos for performance

Benefits:

  • Multi-modal learning (geometry + photometry)
  • Enhanced ML model accuracy
  • Better visualization capabilities
  • Automatic - no manual orthophoto downloads needed

Requirements:

pip install requests Pillow

See the RGB Augmentation Guide for detailed information.

Classification Levels​

LOD2 (15 classes): Basic building components

  • Wall, Roof, Ground, Vegetation, Window, Door, etc.

LOD3 (30 classes): Detailed building components

  • All LOD2 classes plus roof details, facade elements, etc.

Notes​

  • Patch size affects the number of points per patch
  • Smaller patches = more patches, fewer points each
  • Larger patches = fewer patches, more points each
  • Processing time: ~1-3 minutes per tile (geometry only), ~2-5 minutes with RGB
  • RGB augmentation adds ~196KB per patch (16384 points × 3 × 4 bytes)
  • Smart skip detection avoids reprocessing existing patches

process (Deprecated)​

Deprecated Command

The process command has been renamed to patch for clarity. While process still works for backwards compatibility, it will be removed in a future major version. Please use patch instead.

Migration​

Simply replace process with patch in your commands:

# Old (deprecated)
ign-lidar-hd process --input tiles/ --output patches/

# New (recommended)
ign-lidar-hd patch --input tiles/ --output patches/

All parameters and functionality remain identical. See the patch command documentation above.

Global Options​

Logging​

Control output verbosity:

# Default logging
ign-lidar-hd command [args]

# Verbose output (debug level)
ign-lidar-hd command [args] --verbose

# Quiet mode (errors only)
ign-lidar-hd command [args] --quiet

Help​

Get help for any command:

# General help
ign-lidar-hd --help

# Command-specific help
ign-lidar-hd download --help
ign-lidar-hd enrich --help
ign-lidar-hd process --help

Common Workflows​

Full Pipeline​

Complete processing workflow:

# 1. Download
ign-lidar-hd download \
  --bbox 2.25,48.82,2.42,48.90 \
  --output raw_tiles/ \
  --max-tiles 5

# 2. Enrich
ign-lidar-hd enrich \
  --input-dir raw_tiles/ \
  --output enriched_tiles/ \
  --mode full \
  --num-workers 4

# 3. Process
ign-lidar-hd process \
  --input enriched_tiles/ \
  --output patches/ \
  --lod-level LOD2 \
  --num-workers 4

Resume Interrupted Work​

Thanks to smart skip detection, you can safely re-run commands:

# If download was interrupted, just re-run
ign-lidar-hd download --bbox ... --output raw_tiles/
# Will skip existing files and download only missing ones

# Same for processing
ign-lidar-hd process --input enriched/ --output patches/ --lod-level LOD2
# Will skip tiles that already have patches

Force Reprocessing​

Override smart skip when needed:

# Force re-download
ign-lidar-hd download --bbox ... --output raw_tiles/ --force

# Force re-enrichment
ign-lidar-hd enrich --input-dir raw/ --output enriched/ --mode full --force

# Force reprocessing
ign-lidar-hd process --input enriched/ --output patches/ --lod-level LOD2 --force

Performance Tips​

Worker Configuration​

Choose worker count based on your system:

# For 8-core CPU with 16GB RAM
--num-workers 4

# For 16-core CPU with 32GB RAM
--num-workers 8

# For systems with limited memory
--num-workers 2

Memory Management​

Monitor memory usage:

# Check memory during processing
htop

# If memory is limited, reduce workers
ign-lidar-hd process --input tiles/ --output patches/ --num-workers 1

See the Memory Optimization Guide for detailed strategies.

Troubleshooting​

Command Not Found​

If ign-lidar-hd doesn't work:

# Check if package is installed
pip list | grep ign-lidar

# Reinstall if needed
pip install -e .

# Try the installed command name
ign-lidar-hd --help

Permission Errors​

# Check directory permissions
ls -la /path/to/output/

# Create directories if needed
mkdir -p /path/to/output/

Network Issues​

# Test connectivity for downloads
ping geoservices.ign.fr

# Check firewall/proxy settings
curl -I https://geoservices.ign.fr/

Processing Errors​

# Verify LAZ file integrity
lasinfo tile.laz

# Check available disk space
df -h /path/to/output/

# Reduce workers if getting memory errors
--num-workers 1

See Also​