Skip to main content

Feature Modes

Choose the right feature set for your machine learning application. IGN LiDAR HD offers predefined feature modes optimized for different use cases.

🎯 Feature Modes Overview​

ModeFeaturesSpeedUse Casev2.4.3+ Export
minimal~8⚡⚡⚡⚡Quick prototyping✅ Complete
lod2~12⚡⚡⚡Basic building classification✅ Complete
lod3~38⚡⚡Detailed architectural modeling✅ Complete
full~43⚡Research, complete analysis✅ Complete
customVariableVariableUser-defined selection✅ Complete
v2.4.3 Feature Export Fix

All computed features are now saved to disk! Previous versions (< 2.4.3) only exported 12 features even when computing 35+. Regenerate datasets for complete feature sets.

📊 Feature Set Details​

LOD2 Mode (12 features)​

Essential features for basic building classification:

features:
  mode: lod2
  k_neighbors: 20

Feature List:

  • Normals (3): normal_x, normal_y, normal_z
  • Shape (3): planarity, linearity, sphericity
  • Height (1): height_above_ground
  • Building (2): verticality, wall_score
  • Density (1): density
  • Curvature (1): curvature
  • Radiometric (Optional): RGB (3), NIR (1), NDVI (1)

Performance:

  • Processing: ~15s per 1M points (CPU)
  • Training: Fast convergence
  • Memory: ~200 MB per 1M points

Best For:

  • Building vs. non-building classification
  • LOD2 semantic segmentation
  • Baseline model development
  • Fast iteration cycles

LOD3 Mode (38 features)​

Complete feature set for detailed architectural modeling:

features:
  mode: lod3
  k_neighbors: 30
  include_extra: true

Complete Feature List:

Normals (3):

  • normal_x, normal_y, normal_z - complete normal vectors

Shape Descriptors (6):

  • planarity, linearity, sphericity
  • anisotropy, roughness, omnivariance

Curvature (2):

  • curvature, change_curvature

Eigenvalues (5):

  • eigenvalue_1, eigenvalue_2, eigenvalue_3
  • sum_eigenvalues, eigenentropy

Height Features (3):

  • height_above_ground, vertical_std, z_normalized

Building Scores (3):

  • verticality, wall_score, roof_score

Density Features (5):

  • density, local_density, num_points_2m
  • neighborhood_extent, height_extent_ratio

Architectural Features (4):

  • edge_strength, corner_likelihood
  • overhang_indicator, surface_roughness

Radiometric (Optional):

  • RGB (3): red, green, blue
  • Infrared (2): nir, ndvi

Performance:

  • Processing: ~45s per 1M points (CPU)
  • Training: Slower but more detailed
  • Memory: ~600 MB per 1M points

Best For:

  • LOD3 architectural modeling
  • Fine structure detection (edges, corners, overhangs)
  • Detailed building classification
  • Research applications

Full Mode (43+ features)​

Complete feature set for research and analysis:

features:
  mode: full
  include_extra: true
  compute_all: true

All Features (beyond LOD3):

Additional Height Variants (3):

  • z_absolute, z_from_ground, z_from_median - multiple height normalizations

Additional Geometric (2):

  • distance_to_center - radial distance from patch center
  • local_roughness - fine-scale surface variation
  • horizontality - complement to verticality

Output Format (v2.4.2+):

  • NPZ/HDF5/PyTorch: Full 43+ feature matrix
  • LAZ: All 35+ features as extra dimensions
  • Metadata: feature_names list, num_features count

Performance:

  • Processing: ~50s per 1M points (CPU)
  • Training: Complete geometric description
  • Memory: ~700 MB per 1M points
  • File Size: ~3-4x larger than LOD2 (worth it for completeness)

Best For:

  • Research and feature analysis
  • Maximum information extraction
  • Feature importance studies
  • Complete geometric characterization
  • GIS visualization (all features in LAZ)
Feature Export Guarantee

All computed features are now exported! Previous versions (< 2.4.2) only saved 12 features despite computing 43+. Upgrade and regenerate datasets for complete feature access.

🚀 Quick Start Examples​

Example 1: Fast LOD2 Training​

ign-lidar-hd process \
  --config-file examples/config_lod2_simplified_features.yaml \
  input_dir=data/raw \
  output_dir=data/patches

Configuration:

processor:
  lod_level: LOD2
  num_points: 16384

features:
  mode: lod2
  k_neighbors: 20
  use_rgb: true
  compute_ndvi: true

Expected Output:

  • 11 features per point
  • Fast training convergence
  • Good baseline accuracy

Example 2: Detailed LOD3 Modeling​

ign-lidar-hd process \
  --config-file examples/config_lod3_full_features.yaml \
  input_dir=data/raw \
  output_dir=data/patches

Configuration:

processor:
  lod_level: LOD3
  num_points: 32768

features:
  mode: lod3
  k_neighbors: 20
  include_extra: true
  compute_ndvi: true

Expected Output:

  • 38 features per point
  • Detailed architectural structures
  • Best accuracy for LOD3

Example 3: Complete Feature Set (Full Mode)​

ign-lidar-hd process \
  --config-file examples/config_complete.yaml \
  input_dir=data/raw \
  output_dir=data/patches

Configuration (v2.4.2+):

processor:
  lod_level: LOD3
  num_points: 32768

features:
  mode: full
  k_neighbors: 30
  include_extra: true
  compute_all: true
  use_rgb: true
  use_infrared: true
  compute_ndvi: true

output:
  formats: ["npz", "laz"] # LAZ for GIS visualization
  include_metadata: true

Expected Output:

  • 43+ features per point (all computed features)
  • Complete geometric characterization
  • LAZ files with all features as extra dimensions
  • Metadata with feature names and counts

Verification:

import numpy as np

# Load and check
data = np.load('patches/patch_001.npz')
meta = data['metadata'].item()

print(f"Features: {meta['num_features']}")
print(f"Names: {meta['feature_names']}")
# Expected: 43+ features with full list

Example 4: Multi-Scale Hybrid​

ign-lidar-hd process \
  --config-file examples/config_multiscale_hybrid.yaml \
  input_dir=data/raw \
  output_dir=data/patches

Configuration:

processor:
  patch_configs:
    - size: 50.0
      feature_mode: lod3 # Fine details
      num_points: 24000
    - size: 100.0
      feature_mode: lod3 # Medium context
      num_points: 32000
    - size: 150.0
      feature_mode: lod2 # Coarse generalization
      num_points: 32000

Strategy:

  • Small patches (50m): LOD3 for fine details
  • Large patches (150m): LOD2 for context
  • Adaptive feature complexity

🎓 Best Practices​

Choosing the Right Mode​

Use LOD2 (12 features) when:

  • ✅ Building basic classification models
  • ✅ Need fast training cycles
  • ✅ Limited computational resources
  • ✅ Prototyping new architectures
  • ✅ Building vs. non-building classification

Use LOD3 (38 features) when:

  • ✅ Need detailed architectural features
  • ✅ Detecting edges, corners, overhangs
  • ✅ LOD3 building modeling
  • ✅ Maximum accuracy is priority
  • ✅ Fine structure detection

Use Full (43+ features) when:

  • ✅ Research and feature analysis
  • ✅ Need all computed features
  • ✅ Feature importance studies
  • ✅ Maximum information extraction
  • ✅ GIS visualization with LAZ export

Use Custom when:

  • ✅ Specific feature requirements
  • ✅ Domain knowledge guides selection
  • ✅ Optimizing for specific architecture

Feature Selection Strategy​

Start Simple:

  1. Begin with LOD2 (11 features)
  2. Train baseline model
  3. Evaluate performance

Add Complexity:

  1. Upgrade to LOD3 if needed
  2. Monitor overfitting on validation set
  3. Compare accuracy improvement

Optimize:

  1. Remove features with low importance
  2. Custom mode with essential features only
  3. Balance accuracy vs. training time

Performance Tuning​

For Faster Processing:

features:
  mode: lod2 # Fewer features
  k_neighbors: 20 # Lower k
  use_gpu: true # GPU acceleration

For Better Accuracy:

features:
  mode: lod3 # More features
  k_neighbors: 30 # Higher k
  include_extra: true # All enhanced features
  use_radius: true # Better neighborhoods

For Memory Constraints:

features:
  mode: lod2 # Smaller feature set
  use_gpu_chunked: true
  gpu_batch_size: 500000

📈 Feature Importance Analysis​

Critical Features (Present in all modes)​

  1. planarity - Distinguishes flat surfaces (walls, roofs)
  2. height_above_ground - Separates ground from buildings
  3. verticality - Identifies vertical surfaces (walls)
  4. normals - Direct orientation indicators

LOD3+ High-Value Features​

  1. edge_strength - Building edges and corners
  2. wall_score - Direct wall classification
  3. roof_score - Direct roof classification
  4. eigenvalue_1 - Dominant structural direction
  5. corner_likelihood - Junction detection

Full Mode Additional Features​

  1. horizontality - Horizontal surface identification
  2. local_roughness - Fine-scale surface variation
  3. z_from_ground/median - Multiple height references
  4. distance_to_center - Radial position information

Radiometric Features (Optional in all modes)​

  1. ndvi - Vegetation vs. building separation
  2. rgb - Color-based classification
  3. nir - Vegetation reflectance

🔧 Python API​

Using Feature Modes​

from ign_lidar import LiDARProcessor
from ign_lidar.features import get_feature_config

# Get feature configuration
config = get_feature_config("lod3", k_neighbors=30)
print(f"Features: {config.num_features}")
print(f"Names: {config.feature_names}")

# Process with LOD3
processor = LiDARProcessor(
    lod_level="LOD3",
    use_gpu=True
)
patches = processor.process_tile("input.laz", "output/")

Custom Feature Selection​

from ign_lidar.features import get_feature_config

# Define custom features
custom_features = {
    'xyz',
    'normal_z',
    'planarity',
    'linearity',
    'height_above_ground',
    'wall_score',
    'roof_score',
    'density'
}

# Create custom configuration
config = get_feature_config(
    mode="custom",
    custom_features=custom_features,
    k_neighbors=25
)

# Use in processor
processor = LiDARProcessor(
    lod_level="LOD3",
    custom_features=custom_features
)

📊 Benchmark Results​

Processing Speed (1M points, CPU)​

ModeFeaturesTimeSpeedup vs. Full
LOD21215s3.3x faster
LOD33845s1.1x faster
Full43+50sbaseline

Memory Usage (1M points)​

ModeFeaturesRAMGPU VRAM
LOD212200 MB150 MB
LOD338600 MB400 MB
Full43+700 MB450 MB

File Sizes (per patch, 16K points)​

ModeFeaturesNPZ SizeLAZ Size
LOD212~250 KB~180 KB
LOD338~650 KB~420 KB
Full43+~750 KB~480 KB

Training Performance​

Dataset: 100K patches, PointNet++ architecture

ModeFeaturesEpochsVal AccuracyInference Time
LOD2125087.3%12ms/patch
LOD3388092.1%18ms/patch
Full43+9093.5%20ms/patch

Conclusion: LOD3 provides +4.8% accuracy over LOD2. Full mode provides additional +1.4% for research applications.

🐛 Troubleshooting​

Issue: Out of memory with LOD3​

Solution:

features:
  mode: lod2 # Use simpler mode
  # Or enable chunking:
  use_gpu_chunked: true
  gpu_batch_size: 500000

Issue: Training overfits with LOD3​

Solution:

  • Increase regularization (dropout, weight decay)
  • Add more data augmentation
  • Consider LOD2 for better generalization

Issue: Too slow processing​

Solution:

processor:
  use_gpu: true # Enable GPU
features:
  mode: lod2 # Fewer features
  k_neighbors: 20 # Lower k

📚 Related Documentation​

🔗 Example Configurations​

All example configs available in examples/ directory:

  • config_lod2_simplified_features.yaml - 12 features, fast training
  • config_lod3_full_features.yaml - 38 features, detailed modeling
  • config_complete.yaml - 43+ features, complete feature export
  • config_multiscale_hybrid.yaml - Multi-scale adaptive features
  • config_training_dataset.yaml - Production training configs

Choose wisely. Train efficiently. Build better models. 🚀