Cambridge Arboreal Modelling Panoptic 3D (CAMP3D)

Pipeline and Dataset From Paper: Scaling Up Forest Vision with Synthetic Data (Yihang She, Andrew Blake, David Coomes, Srinivasan Keshav, 2025)

A reproducible pipeline to go from Unreal Engine exports → Blender (4.2) → HELIOS++ LiDAR simulation → ML-ready point clouds, including optional leaf/wood semantics, UAV flight planning, survey execution, and post-processing for machine learning.

Python package: camp3d
CLI entry point: camp3d
Dataset: Download here
Preprint: arXiv:2509.11201
Citation: See Citation section below

Features

Scene Creation: Convert Unreal Engine FBX exports to Blender scenes
Semantic Labeling: Automatic tree/leaf/ground classification with customizable keywords
HELIOS Integration: Export scenes to HELIOS++ format for LiDAR simulation
UAV Planning: Generate survey flight paths with configurable parameters
LiDAR Simulation: Run HELIOS++ surveys to generate point cloud data
ML Post-processing: Convert simulation output to ML-ready PLY format with tiling
Environment Management: Built-in dependency checking and setup validation

Prerequisites

Before installing CAMP3D, ensure you have:

Python 3.8+ installed
Blender 4.2 installed and accessible from command line
HELIOS++ installed (see HELIOS++ installation guide)
pyhelios Python package installed (pip install pyhelios)

Required Dependencies

CAMP3D requires several external dependencies that must be installed separately:

HELIOS++ LiDAR Simulator:
- Download from: https://github.com/3dgeo-heidelberg/helios
- Follow the installation guide for your operating system
- Ensure the helios executable is in your PATH
pyhelios Python Package:
```
pip install pyhelios
```
- This provides Python bindings for HELIOS++
- Required for survey planning and execution
Blender 4.2:
- Download from: https://www.blender.org/download/
- Ensure blender command is accessible from terminal
- Required for 3D scene processing and export

Note: These dependencies are not automatically installed with CAMP3D and must be set up manually before use.

Installation

Option 1: Install from GitHub (Recommended)

# Clone the repository
git clone https://github.com/yihshe/CAMP3D.git
cd CAMP3D

# Install in development mode
pip install -e ./camp3d-0.1.0

Option 2: Install from PyPI (when available)

pip install camp3d

Setup

After installation, set up the required components:

# Install Blender addon (automatic)
camp3d tools write-addon ~/.config/blender/4.2/scripts/addons/

# Or install manually if automatic installation fails:
# 1. Copy examples/addons/Blender2Helios.py to your Blender addons directory
# 2. Enable it in Blender: Edit → Preferences → Add-ons → search 'Blender2Helios'

# Install example materials and scenes
camp3d tools install-materials
camp3d tools install-examples

Quick Start

1. Test Your Setup

# Check if everything is installed correctly
camp3d doctor all

2. Run the Quick Demo

The quick demo contains a single tree extracted from the original Deciduous4 scene for fast testing:

# Run the complete pipeline
camp3d run -c camp3d-0.1.0/examples/quickdemo_config.yaml

This will:

Create a Blender scene from FBX files
Add semantic labels (leaf/wood classification)
Export to HELIOS++ format
Plan UAV survey flight path
Simulate LiDAR scanning
Post-process results to ML-ready format

Expected Output: A point cloud dataset obtained by virtual UAV laser scans, semantically labeled with ground/wood/leaf classifications and instance labels, ready for machine learning tasks.

3. View Results

After completion, you'll find:

Blender scene: ./scene/quickdemo/quickdemo.blend
HELIOS data: ./helios/data/quickdemo/
Point clouds: ./ml_data/quickdemo/

Example Scenes

quickdemo (Quick Test)

Purpose: Fast validation and testing
Size: Minimal (single tree from Deciduous4 scene)
Installation: camp3d tools install-examples
Processing time: ~1-2 minutes

Deciduous4 (Full Demo)

Purpose: Complete pipeline demonstration
Size: Full forest scene with procedural foliage
Source: Quixel assets from Unreal Marketplace
Installation: Download separately from GitHub repository
Processing time: ~40-60 minutes

Note: A detailed documentation on Unreal Engine procedural foliage generation and scene export will be provided later. For now, we provide exported scene files from Unreal Engine as examples.

Command Reference

Environment & Setup

# Check if everything is installed correctly
camp3d doctor all

# Install Blender2Helios addon (or install manually - see "Setup" section)
camp3d tools write-addon ~/.config/blender/4.2/scripts/addons/

# Install example materials
camp3d tools install-materials

# Install example scenes
camp3d tools install-examples

Scene Creation

# Create blend file from Unreal FBX exports
camp3d create-blend --create-new-scene \
  --landscape-fbx ./scene/quickdemo/quickdemo_landscape.fbx \
  --trees-fbx ./scene/quickdemo/quickdemo_trees.fbx \
  --blend-path ./scene/quickdemo/quickdemo.blend

# Get scene statistics
camp3d stats-blend --blend ./scene/quickdemo/quickdemo.blend

Semantic Labeling

# Add leaf/wood semantics to trees
camp3d semantics-blend \
  --blend ./scene/quickdemo/quickdemo.blend \
  --trees-collection Trees \
  --leaf-keywords "Leaves,Needles,MTL_RW_Needles,MI_birch_branch,MI_pine_branch,MI_Leaves,leaf,MI_Pine_Tree_Needles,MI_Scots_Pine_Sheet_Sick,MI_Scots_Pine_Sheet,MI_Pine_Mountain_Ash_Sheet,TwoSided" \
  --write-csv

HELIOS++ Export

# Export scene for HELIOS++ simulation
camp3d export-helios \
  --blend ./scene/quickdemo/quickdemo_leafwood.blend \
  --materials-dir ./materials \
  --output-dir ./helios \
  --scene-name quickdemo \
  --use-own-materials \
  --materials-name spread_leafwood \
  --save-scene-bbox \
  --save-survey-file

UAV Path Planning

# Plan survey flight path
camp3d plan-path \
  --scene-name quickdemo \
  --survey-mode ULS \
  --spacing 20 \
  --rotate-deg 0 \
  --relative-altitude 60 \
  --speed 5 \
  --pulse-freq-hz 200000 \
  --pattern criss-cross

LiDAR Simulation

# Run HELIOS++ simulation
camp3d survey-run \
  --survey-file ./helios/data/quickdemo/surveys/quickdemo_ULS.xml \
  --output-dir ./helios/output/

ML Post-processing

# Convert simulation output to ML-ready format. Process the last timestamp directory by default
camp3d postprocess-ml \
  --input-root ./helios/output/quickdemo_ULS \
  --output-root ./ml_data \
  --tile-size 50.0 \
  --leafwood

# Process specific timestamp directory
camp3d postprocess-ml \
  --input-root ./helios/output/quickdemo_ULS/2025-09-11_20-35-12 \
  --output-root ./ml_data \
  --leafwood

# Merge all timestamps
camp3d postprocess-ml \
  --input-root ./helios/output/quickdemo_ULS \
  --output-root ./ml_data \
  --leafwood \
  --merge-all-ts

Full Pipeline

# Run complete pipeline with config file
camp3d run -c camp3d-0.1.0/examples/quickdemo_config.yaml

# Run with custom parameters
camp3d run \
  --blend ./scene/quickdemo/quickdemo.blend \
  --materials-dir ./materials \
  --output-dir ./helios \
  --scene-name quickdemo \
  --skip-semantics

Materials: Using Ours or Your Own

Where: put .mtl files under your project materials/.
How to reference: use --materials-name <basename> (no .mtl), e.g. spread_leafwood.

You can add any number of .mtl files here. The important keys are:

helios_classification (integer label),
helios_isGround (0/1),
newmtl <CollectionName> (e.g., Landscape, Trees, Trees_Wood, Trees_Leaves).

The export script copies materials/<name>.mtl to HELIOS: helios/data/<Scene>/sceneparts/materials.mtl.

Post-processing for Machine Learning

The camp3d postprocess-ml command converts HELIOS simulation output into ML-ready format:

Features:

Format conversion: Converts .xyz point cloud files to .ply format
Tiling: Splits large scenes into manageable tiles (default: 50m × 50m)
Semantic labels: Preserves ground/vegetation classifications
Tree ID tracking: Maintains individual tree identifiers for segmentation tasks
Flexible labeling: Supports both simplified (ground/vegetation) and detailed (ground/wood/leaf) modes

Usage:

# Basic post-processing (uses latest timestamp if multiple exist)
camp3d postprocess-ml --input-root ./helios/output/quickdemo_ULS --output-root ./ml_data

# Or specify the directory which contains the XYZ files to process
camp3d postprocess-ml --input-root ./helios/output/quickdemo_ULS/2025-09-11_20-35-12 \
                --output-root ./ml_data 

# Merge all timestamps into single scene
camp3d postprocess-ml --input-root ./helios/output/quickdemo_ULS \
                --output-root ./ml_data \
                --merge-all-ts

# Advanced options with leafwood mode (used when the scene file has been converted into leaf wood semantics)
camp3d postprocess-ml --input-root ./helios/output/quickdemo_ULS \
                --output-root ./ml_data \
                --tile-size 50.0 \
                --leafwood

Output Structure:

ml_data/
└─ quickdemo/
    └─2025-09-11_20-35-12/       # Single timestamp or latest timestamp
      ├─ quickdemo_plot_0_annotated.ply
      ├─ quickdemo_plot_1_annotated.ply
      └─ ...

Each .ply file contains:

x, y, z: 3D coordinates
intensity: LiDAR return intensity
semantic_seg: Ground (1) or vegetation (2), or detailed labels (2/3/4)
treeID: Individual tree identifier (-1 for ground points)

Configuration

The pipeline uses YAML configuration files. See examples/quickdemo_config.yaml for a complete example:

camp3d:
  materials_dir: ./materials

helios:
  output_dir: ./helios

scene:
  name: quickdemo
  scene_dir: ./scene
  blend: ./scene/quickdemo/quickdemo.blend
  semantics:
    trees_collection: Trees
    leaf_keywords: ["Leaves", "MTL_RW_Needles", "MI_birch_branch", "MI_pine_branch", "MI_Leaves", "leaf", "MI_Pine_Tree_Needles", "MI_Scots_Pine_Sheet_Sick", "MI_Scots_Pine_Sheet", "MI_Pine_Mountain_Ash_Sheet", "TwoSided"]
    write_csv: false

export:
  use_own_materials: true
  materials_name: spread_leafwood
  save_scene_bbox: true
  save_survey_file: true

planning:
  rotate_deg: 0
  survey_mode: ULS
  spacing: 20.0
  relative_altitude: 60.0
  speed: 5.0
  pulse_freq_hz: 200000
  pattern: criss-cross

survey:
  callback_frequency: 10000
  output_dir: ./helios/output

postprocess:
  tile_size: 50.0
  merge_all_ts: false
  ground_label: 2
  wood_label: 3
  leaf_label: 4
  leafwood: true

Contributing

We welcome contributions to CAMP3D! Here are some ways you can contribute:

1. Adding Your Own Scenes

You can contribute by adding your own forest scenes generated using Unreal Engine's procedural foliage system:

Export from Unreal Engine:
- Split foliage into individual trees
- Export trees to FBX file with _trees suffix
- Export landscape to FBX file with _landscape suffix
- Important: Don't select LOD (Level of Details) when exporting
Create scene folder:
- Create a folder under scene/ to store your files
- Place both FBX files in this folder
Customize leaf keywords (if needed):
- CAMP3D automatically detects leaf materials using keywords in material names
- Default keywords include: Leaves, MTL_RW_Needles, MI_birch_branch, MI_pine_branch, MI_Leaves, leaf, MI_Pine_Tree_Needles, MI_Scots_Pine_Sheet_Sick, MI_Scots_Pine_Sheet, MI_Pine_Mountain_Ash_Sheet, TwoSided
- If your materials use different naming conventions, update the leaf_keywords in your config file:
```
scene:
  semantics:
    leaf_keywords: ["YourLeafKeyword1", "YourLeafKeyword2", ...]
```
Test your scene:
- Run camp3d run -c your_config.yaml to test your scene
- Share your results and any issues you encounter

Note: A detailed tutorial on Unreal Engine procedural foliage generation and scene export will be added later.

2. Expanding Survey Modes

Currently, CAMP3D supports UAV laser scanning (ULS). You can contribute by expanding to other survey modes:

MLS (Mobile Laser Scanning)
TLS (Terrestrial Laser Scanning)
ALS (Airborne Laser Scanning)

These modes are supported by the HELIOS simulator, but the path planning and survey file generation would need to be developed in this package.

3. Other Contributions

Bug fixes and improvements
Documentation improvements
Additional post-processing features
Integration with other LiDAR simulation tools

Testing

For detailed testing instructions, see TESTING.md.

Quick Test

Install and setup:

pip install -e .
camp3d tools write-addon ~/.config/blender/4.2/scripts/addons/  # or install manually
camp3d tools install-materials
camp3d tools install-examples

Run tests:

# Check environment
camp3d doctor all

# Unit tests
python test_camp3d.py

# Quick pipeline test
camp3d run -c camp3d-0.1.0/examples/quickdemo_config.yaml

Full pipeline test:
```
bash test_pipeline.sh
```

Blender Addon Script: `Blender2Helios.py` (adapted)

Base project: https://github.com/neumicha/Blender2Helios (GPLv3)

Differences vs upstream:

Uses per-object helios_part_id for <part id="..."> in the scene XML.
Emits relative OBJ paths under data/<scene>/sceneparts.
Survey generation is decoupled (we build UAV-LS surveys via plan_path).
Uses wm.obj_export with modifiers; materials via materials.mtl when useOwnMaterials=True.
Guarded directory creation inside HELIOS base dir.

Notes & Tips

Blender target: 4.2. Decimation (optional): UI → Decimate modifier on tree meshes.
Unreal export: two FBX per scene (*_landscape.fbx and *_trees.fbx), with trees separated per object.
Export writes into <output_dir>/data/<SceneName>/....
survey-run defaults outputs to <output_dir>/output/<SceneName>; override with --output-dir.

Citation

If you find CAMP3D useful in your research, please consider to cite our paper:

@misc{she2025scalingforestvisionsynthetic,
      title={Scaling Up Forest Vision with Synthetic Data}, 
      author={Yihang She and Andrew Blake and David Coomes and Srinivasan Keshav},
      year={2025},
      eprint={2509.11201},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2509.11201}, 
}

License

Python package: MIT License
Example adapted Blender2Helios add-on: GPLv3 (inherits upstream's license)

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
camp3d-0.1.0		camp3d-0.1.0
figures		figures
.gitignore		.gitignore
README.md		README.md
TESTING.md		TESTING.md
run_full_pipeline.sh		run_full_pipeline.sh
test_camp3d.py		test_camp3d.py
test_pipeline.sh		test_pipeline.sh

Folders and files

Latest commit

History

Repository files navigation

Cambridge Arboreal Modelling Panoptic 3D (CAMP3D)

Table of Contents

Features

Prerequisites

Required Dependencies

Installation

Option 1: Install from GitHub (Recommended)

Option 2: Install from PyPI (when available)

Setup

Quick Start

1. Test Your Setup

2. Run the Quick Demo

3. View Results

Example Scenes

quickdemo (Quick Test)

Deciduous4 (Full Demo)

Command Reference

Environment & Setup

Scene Creation

Semantic Labeling

HELIOS++ Export

UAV Path Planning

LiDAR Simulation

ML Post-processing

Full Pipeline

Materials: Using Ours or Your Own

Post-processing for Machine Learning

Features:

Usage:

Output Structure:

Configuration

Contributing

1. Adding Your Own Scenes

2. Expanding Survey Modes

3. Other Contributions

Testing

Quick Test

Blender Addon Script: Blender2Helios.py (adapted)

Notes & Tips

Citation

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Blender Addon Script: `Blender2Helios.py` (adapted)

Packages