RayCloudTools & TreeTools Documentation

This repository provides comprehensive documentation, examples, and best practices for using RayCloudTools and TreeTools - powerful command-line tools for point cloud processing and tree structure analysis.

🚀 Quick Start

The documentation is structured in 2 parts: tools and workflows. Tools contains usage documentation for each tool in raycloudtools and treetools. Workflows contains start-to-end examples of typical workflows (e.g. extracting individual tree structural information).

• Installation: See Installation Guide
• Workflows: Check Common Workflows
• Tool Reference: Browse tools by category below

📚 Documentation Structure

RayCloudTools

Advanced point cloud processing and analysis tools for LiDAR data.

🔄 Import & Export

• rayimport - Import point clouds and trajectories into raycloud format
• rayexport - Export rayclouds to standard point cloud formats

⚙️ Processing & Manipulation

• raydenoise - Remove noise from ray cloud data
• raysmooth - Smooth ray clouds by moving off-surface points
• raydecimate - Reduce ray cloud density spatially or temporally
• rayrestore - Apply decimated changes back to full resolution
• raycombine - Combine multiple ray clouds using various strategies
• raysplit - Split ray clouds using geometric and attribute criteria

🔍 Analysis & Extraction

• rayextract - Extract natural features (terrain, trees, forest structure)
• rayinfo - Get comprehensive ray cloud statistics and information
• raytransients - Separate transient objects from fixed geometry
• raywrap - Extract ground/surface meshes by wrapping point data

🎨 Visualization & Rendering

• raycolour - Color and shade ray clouds using various methods
• rayrender - Render ray clouds as 2D images from specified viewpoints

🔧 Transformation

• rayalign - Align ray clouds rigidly or non-rigidly
• rayrotate - Rotate ray clouds about the origin
• raytranslate - Translate ray clouds in 3D space and time

🎲 Generation

• raycreate - Generate synthetic ray clouds for testing

---

TreeTools

Specialized tools for processing and analyzing tree structure data.

📊 Analysis & Information

• treeinfo - Extract comprehensive tree statistics and forest inventory
• treediff - Compare tree files and analyze growth/changes
• treefoliage - Add foliage density attributes from point cloud analysis

⚙️ Processing & Manipulation

• treecombine - Merge multiple tree files by structure or attributes
• treedecimate - Reduce tree complexity while preserving topology
• treegrow - Simulate tree growth using linear models

🎨 Visualization

• treecolour - Color tree branches based on attributes or images

🎲 Generation

• treecreate - Generate synthetic trees and forests procedurally

🔗 Common Workflows

Basic Point Cloud Processing

1. Import data: rayimport → Convert point cloud to raycloud format
2. Clean data: raydenoise → Remove noise and artifacts
3. Extract features: rayextract → Extract terrain, trees, or other features
4. Visualize: raycolour + rayrender → Create colored visualizations

Forest Analysis Pipeline

1. Extract terrain: rayextract terrain → Generate ground DTM as a 3D mesh from point cloud
2. Extract trees: rayextract trees → Generate tree structures from point cloud and ground mesh
3. Analyze forest: treeinfo → Get comprehensive forest statistics
4. Visualize results: treecolour + treemesh → Create colored 3D tree models
5. Monitor changes: treediff → Compare forests over time

Large Dataset Processing

1. Optimize data: raydecimate → Reduce data size for processing
2. Process efficiently: Apply tools to decimated data
3. Restore quality: rayrestore → Apply results back to full resolution

📖 Key Concepts

Ray Cloud Format

RayCloudTools uses a specialized format that stores both ray start and end points, enabling:

• Full ray information: Complete sensor-to-surface ray paths
• Temporal data: Time-stamped measurements for change detection
• Intensity data: LiDAR intensity and surface properties
• Geometric analysis: Advanced processing using full ray geometry

Tree File Format

TreeTools processes tree structure files containing:

• Branch Structure Graph: Hierarchical tree representation
• Cylindrical segments: Each branch as connected cylinders
• Flexible attributes: Custom measurements and properties
• Parent-child relationships: Complete tree topology

🛠️ Installation & Setup

See the detailed Installation Guide for:

• Docker installation (recommended for all platforms)
• Building from source (Linux)
• Optional dependencies for advanced features
• Unit testing setup

📝 File Format Support

RayCloudTools Input/Output

• PLY (binary) - Point cloud and ray cloud format
• LAZ/LAS 1.2 - Compressed LiDAR data
• RXP - RIEGL scanner data (with RiVLib)
• Text formats - CSV, XYZ coordinate files
• Images - PNG, TIF, HDR for visualization

TreeTools Input/Output

• Text format - Comma-separated tree structure files
• PLY meshes - 3D tree visualizations
• Images - Rendered tree visualizations

🤝 Contributing

We welcome contributions to improve documentation and examples:

Submitting Issues

1. Check existing issues
2. Create detailed issue reports
3. Provide example data when possible

Contributing Documentation

1. Fork this repository
2. Make improvements or add content
3. Submit pull request with clear description

Documentation Guidelines

• Use clear, concise language
• Include practical examples
• Reference source code locations
• Follow existing formatting patterns

📄 License

This documentation follows the same license terms as the underlying RayCloudTools and TreeTools libraries. See individual repositories for details.

🔗 Related Resources

• RayCloudTools: GitHub Repository
• TreeTools: GitHub Repository
• CSIRO Robotics: Research Group

---