Troubleshooting Guide

Solutions to common issues encountered when processing LiDAR data with IGN LiDAR HD.

Installation Issues

Dependency Installation Failure

Problem: Python package installation fails

ERROR: Failed building wheel for some-package

Solutions:

1. Update pip

   pip install --upgrade pip setuptools wheel

2. Install with conda

   conda install -c conda-forge ign-lidar-hd

3. Manual dependency installation

   pip install numpy scipy laspy pdal
   pip install ign-lidar-hd

CUDA/GPU Issues

Problem: CUDA not detected

CUDA not available, falling back to CPU processing

Diagnosis:

# Check CUDA
nvidia-smi
python -c "import torch; print(torch.cuda.is_available())"

Solutions:

1. Install NVIDIA drivers
2. Install CUDA Toolkit
3. Install PyTorch with CUDA support

Processing Issues

Memory Errors

Problem: Insufficient memory

MemoryError: Unable to allocate array

Solutions:

1. Reduce chunk size

   processor = Processor(chunk_size=100000)

2. Process in small batches

   for batch in split_large_file(input_file, max_points=500000):
       process_batch(batch)

3. Use pagination

   processor = Processor(use_pagination=True, page_size=50000)

GPU Out of Memory

Problem: Insufficient VRAM

CUDA out of memory. Tried to allocate 2.00 GiB

Solutions:

1. Limit GPU memory

   processor = Processor(gpu_memory_limit=0.5)

2. Clear GPU cache

   import torch
   torch.cuda.empty_cache()

3. Hybrid CPU/GPU processing

   processor = Processor(
       use_gpu=True,
       fallback_to_cpu=True
   )

File Errors

Problem: Corrupted LAS file

LASError: Invalid LAS file header

Diagnosis:

# Verify with PDAL
pdal info input.las

# Validate with laspy
python -c "import laspy; f=laspy.read('input.las'); print('OK')"

Solutions:

1. Repair with PDAL

   pdal translate input.las output_fixed.las --writers.las.forward=all

2. Validate and clean

   from ign_lidar.utils import validate_and_clean
   clean_file = validate_and_clean("input.las")

Performance Issues

Slow Processing

Problem: Very poor performance

Diagnosis:

from ign_lidar import Profiler

with Profiler() as prof:
    result = processor.process_tile("input.las")
prof.print_bottlenecks()

Solutions:

1. Optimize parameters

   processor = Processor(
       n_jobs=-1,  # All cores
       chunk_size=1000000,
       use_gpu=True
   )

2. Check disk speed

   # Test disk speed
   dd if=/dev/zero of=test_file bs=1M count=1000

3. Monitor resources

   htop  # CPU and RAM
   iotop  # Disk I/O
   nvidia-smi  # GPU

I/O Bottlenecks

Problem: Slow read/write

Solutions:

1. Optimize buffers

   processor = Processor(
       read_buffer_size='128MB',
       write_buffer_size='128MB',
       io_threads=4
   )

2. Use fast storage

   • Prefer NVMe SSDs
   • Avoid network drives for processing

3. Adaptive compression

   # Balance compression/speed
   processor = Processor(
       output_format='laz',
       compression_level=1
   )

Configuration Issues

Invalid Configuration

Problem: Parameter errors

ConfigurationError: Invalid feature configuration

Solutions:

1. Validate configuration

   from ign_lidar import Config
   
   config = Config.from_file("config.yaml")
   config.validate()

2. Use default configuration

   config = Config.get_default()
   config.features = ['buildings', 'vegetation']

3. Generate configuration templates

   # Generate template
   ign-lidar-hd config --template > config.yaml

Path Issues

Problem: Files not found

FileNotFoundError: No such file or directory

Solutions:

1. Verify paths

   import os
   assert os.path.exists("input.las"), "File not found"

2. Use absolute paths

   input_path = os.path.abspath("input.las")

3. Check permissions

   ls -la input.las
   chmod 644 input.las

Specific Issues

RGB Augmentation

Problem: Color augmentation failure

OrthophotoError: Cannot read orthophoto file

Solutions:

1. Verify format

   gdalinfo orthophoto.tif

2. Convert format

   gdal_translate -of GTiff input.jp2 output.tif

3. Check georeferencing

   from ign_lidar.utils import check_crs_match
   match = check_crs_match("input.las", "orthophoto.tif")

Building Detection

Problem: Poor building detection

Solutions:

1. Adjust parameters

   config = Config(
       building_detection={
           'min_points': 100,
           'height_threshold': 2.0,
           'planarity_threshold': 0.1
       }
   )

2. Adaptive preprocessing

   processor = Processor(
       ground_classification=True,
       noise_removal=True
   )

Logging and Debugging

Enable Detailed Logging

import logging

logging.basicConfig(level=logging.DEBUG)
processor = Processor(verbose=True)

Save Logs

import logging

logging.basicConfig(
    filename='ign_lidar.log',
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)

Debug Mode

# Debug execution
IGN_LIDAR_DEBUG=1 python script.py

# Detailed profiling
IGN_LIDAR_PROFILE=1 python script.py

Support and Help

Documentation

• Performance Guide
• GPU Guide
• API Reference

Diagnostic Tools

# System information
ign-lidar-hd system-info

# Configuration test
ign-lidar-hd config-test

# Data validation
ign-lidar-hd validate input.las

Bug Reporting

1. Collect information

   ign-lidar-hd system-info > system_info.txt

2. Minimal example

   # Minimal code reproducing the issue
   from ign_lidar import Processor
   processor = Processor()
   # Error here...

3. Test files

   • Provide small test LAS file if possible
   • Include configuration used

Useful Resources

• GitHub Repository: Issues and discussions
• Documentation: Detailed guides and API
• Examples: Sample scripts
• Community: Discussion forums

Quick Solutions

General Checklist

1. ✅ Python 3.8+ installed
2. ✅ Dependencies correctly installed
3. ✅ Valid input files
4. ✅ Read/write permissions
5. ✅ Sufficient disk space
6. ✅ Available RAM for chunks
7. ✅ Updated GPU drivers (if used)

Useful Commands

# Quick diagnostics
ign-lidar-hd doctor

# Clear cache
ign-lidar-hd cache --clear

# Reset configuration
ign-lidar-hd config --reset

# Performance test
ign-lidar-hd benchmark --quick