TreeAIBox Lite - Headless Model Runner

A Python-based headless inference engine for TreeAIBox that performs wood/leaf classification on point cloud data using deep learning models.

Features

• Headless operation - No GUI dependencies, runs on servers and clusters
• Multiple output formats - Create new fields or overwrite existing ones (e.g., alpha channel)
• PLY file support - Read and write point cloud data with colors, normals, and scalar fields

Installation

Using pip

# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Using conda

conda env create -f environment.yml
conda activate treeaibox

Usage

Basic usage

python run_models_inference.py \
  --input input.ply \
  --model-path models/woodcls_branch_tls_segformer3D_112_4cm\(GPU6GB\).pth \
  --wood-cls branch \
  --output output.ply

Note: --model-path is required and must point to a valid .pth model file.

Overwrite a field with classification results

# Write classification to alpha channel
python run_models_inference.py \
  --input forest.ply \
  --model-path models/woodcls_branch_tls_segformer3D_112_4cm\(GPU6GB\).pth \
  --wood-cls branch \
  --output-field alpha \
  --output results.ply

Force CPU processing

python run_models_inference.py \
  --input forest.ply \
  --model-path models/woodcls_branch_tls_segformer3D_112_4cm\(GPU6GB\).pth \
  --wood-cls branch \
  --no-gpu \
  --output results.ply

Short command-line options

python run_models_inference.py \
  -i input.ply \
  --model-path models/woodcls_branch_tls_segformer3D_112_4cm\(GPU6GB\).pth \
  -o output.ply \
  --wood-cls branch \
  --output-field alpha

Command-Line Arguments

Argument	Short	Type	Default	Description
--input	-i	str	required	Input PLY file path
--model-path		str	required	Path to model file (.pth)
--output	-o	str	output.ply	Output PLY file path
--wood-cls		str	branch	Classification type: branch or stem
--output-field		str	new field	Field name to overwrite with results (e.g., alpha, confidence)
--use-gpu		flag	True	Enable GPU acceleration
--no-gpu		flag	False	Force CPU-only processing

Classification Output

The model outputs two classes that are automatically remapped:

• 1 = Leaf
• 255 = Wood

These values are written to either:

• A new scalar field named {wood_type}_classification (default)
• An existing field you specify with --output-field (overwrites)

Project Structure

TreeAIBox_Lite/
├── run_models_inference.py    # Main inference script
├── mock_point_cloud.py        # Point cloud data structures
├── requirements.txt           # Pip dependencies
├── environment.yml            # Conda environment
├── README.md                  # This file
├── models/                    # Model files (.pth)
├── modules/
│   ├── filter/               # Wood classification modules
│   │   ├── componentFilter.py
│   │   ├── vox3DSegFormer.py
│   │   └── vox3DESegFormer.py
│   └── treeisonet/           # Tree isolation modules
├── forest.ply                # Sample point cloud
└── model_zoo.json            # Model configuration

Examples

Example 1: Basic classification

python run_models_inference.py \
  --input forest.ply \
  --model-path models/woodcls_branch_tls_segformer3D_112_4cm\(GPU6GB\).pth \
  --output classified.ply

Example 2: Classification with alpha channel override

python run_models_inference.py \
  --input forest.ply \
  --model-path models/woodcls_branch_tls_segformer3D_112_4cm\(GPU6GB\).pth \
  --wood-cls branch \
  --output-field alpha \
  --output forest_classified.ply

Example 3: Use distilled model on low VRAM GPU

python run_models_inference.py \
  -i forest.ply \
  --model-path "models/woodcls_branch_tls_segformer3D_112_4cm(GPU2GBDistilled).pth" \
  --use-gpu \
  -o results.ply

Example 4: Batch processing with CPU

MODEL="models/woodcls_branch_tls_segformer3D_112_4cm(GPU6GB).pth"
for file in *.ply; do
  python run_models_inference.py \
    --input "$file" \
    --model-path "$MODEL" \
    --no-gpu \
    --output "classified_${file}"
done

Available Models

The following models are included in the models/ directory:

Branch Classification (Wood/Leaf)

• woodcls_branch_tls_segformer3D_112_4cm(GPU6GB).pth - Full model (6GB VRAM)
• woodcls_branch_tls_segformer3D_112_4cm(GPU2GBDistilled).pth - Distilled model (2GB VRAM)
• woodcls_branch_tls_esegformer3D_128_2.5cm(GPU3GB).pth - Efficient model (3GB VRAM)

Stem Classification (Wood/Leaf)

• woodcls_stem_tls_segformer3D_112_4cm_GPU12GB.pth - Full model (12GB VRAM)
• woodcls_stem_tls_segformer3D_112_20cm_GPU8GB.pth - Standard model (8GB VRAM)
• woodcls_stem_tls_esegformer3D_128_10cm(GPU3GB).pth - Efficient model (3GB VRAM)

Choose the model that fits your hardware constraints and use its full filename with --model-path.

Dependencies

• torch - PyTorch for model inference
• torchvision - Vision utilities
• torchaudio - Audio utilities
• numpy - Numerical computing
• plyfile - PLY file I/O
• timm - Transformer models
• numpy-indexed - Indexed array operations

Hardware Requirements

• GPU (optional): NVIDIA GPU with CUDA 12.1 for accelerated processing
• CPU: CPU-only mode supported (slower)
• RAM: 8GB+ recommended for large point clouds

Output Format

The output PLY file includes:

• Original point coordinates (x, y, z)
• Original colors (if present)
• Original normals (if present)
• All scalar fields including classification results

Troubleshooting

Module not found errors

pip install -r requirements.txt

CUDA errors

Try forcing CPU mode:

python run_models_inference.py \
  --input file.ply \
  --model-path models/woodcls_branch_tls_segformer3D_112_4cm\(GPU6GB\).pth \
  --no-gpu \
  --output output.ply

Missing --model-path argument

Make sure to specify the full path to the model file:

python run_models_inference.py \
  --input file.ply \
  --model-path models/woodcls_branch_tls_segformer3D_112_4cm\(GPU6GB\).pth \
  --output output.ply

Available models are in the ./models/ directory.

License

See project documentation for licensing information.