Skip to content

treedecimate.md

Latest commit

 

History

History
219 lines (160 loc) · 5.4 KB

treedecimate.md

File metadata and controls

219 lines (160 loc) · 5.4 KB
Raw

TreeDecimate

TreeDecimate is a tool for reducing the complexity of tree files by decreasing the number of segments while preserving topology and essential geometric features. It maintains branch junction locations and overall tree structure.

Usage

Segment-based Decimation

treedecimate <tree_file> <factor> segments

Reduce to every Nth segment:

treedecimate forest.txt 2 segments

Ratio-based Decimation

treedecimate <tree_file> ratio <max_ratio>

Remove segments based on length-to-width ratio:

treedecimate forest.txt ratio 3

Decimation Methods

Segment Decimation

Reduces tree complexity by keeping every Nth segment:

  • Factor 2: Keeps every 2nd segment (roughly half complexity)
  • Factor 3: Keeps every 3rd segment (roughly one-third complexity)
  • Higher factors: Greater complexity reduction

Ratio Decimation

Removes segments with low length-to-width ratios:

  • Length: Distance between segment endpoints
  • Width: Segment diameter (2 × radius)
  • Ratio threshold: Minimum length/width ratio to retain segment

Topology Preservation

The tool maintains tree structure by:

  • Preserving junctions: All branch points are retained
  • Maintaining connectivity: Parent-child relationships preserved
  • Keeping terminals: End segments (leaves) are always kept
  • Preserving roots: Root segments remain unchanged

Examples

Basic Segment Decimation

Reduce complexity by half:

treedecimate detailed_trees.txt 2 segments

Reduce to one-third complexity:

treedecimate forest.txt 3 segments

High decimation for simplified structure:

treedecimate complex_tree.txt 5 segments

Ratio-based Simplification

Remove very short segments:

treedecimate noisy_trees.txt ratio 2

Keep only longer segments:

treedecimate forest.txt ratio 5

Aggressive ratio decimation:

treedecimate detailed_scan.txt ratio 10

Algorithm Details

Segment Decimation Process

  1. Start from root segment (always preserved)
  2. Count segments along each branch
  3. Keep every Nth segment based on decimation factor
  4. Force preservation at branch junctions
  5. Always preserve terminal segments

Ratio Decimation Process

  1. Calculate length and width for each segment
  2. Compute length-to-width ratio
  3. Remove segments below threshold ratio
  4. Re-parent child segments to preserved parents
  5. Reindex segment relationships

Quality Preservation

Geometric Features

  • Branch junction positions maintained exactly
  • Overall tree shape preserved
  • Terminal branch locations unchanged
  • Root position and orientation preserved

Structural Integrity

  • No disconnected segments created
  • Topology remains valid
  • Parent-child relationships consistent
  • Tree remains a connected structure

Applications

File Size Reduction

  • Reduce storage requirements for large forest datasets
  • Optimize memory usage for processing
  • Speed up analysis algorithms

Visualization

  • Create simplified models for real-time rendering
  • Generate level-of-detail (LOD) representations
  • Improve interactive visualization performance

Analysis Efficiency

  • Speed up computational algorithms
  • Reduce processing time for forest analysis
  • Create manageable datasets for statistical analysis

Data Transmission

  • Reduce file sizes for network transfer
  • Optimize datasets for remote processing
  • Create compact representations for sharing

Examples by Use Case

Visualization LOD

treedecimate forest.txt 2 segments  # Medium detail
treedecimate forest.txt 4 segments  # Low detail

Noise Removal

treedecimate reconstructed_trees.txt ratio 3

Performance Optimization

treedecimate large_forest.txt 3 segments

Analysis Simplification

treedecimate complex_trees.txt ratio 5

Quality vs. Performance Trade-offs

Low Decimation (Factor 2-3)

  • Quality: High geometric fidelity
  • Performance: Moderate improvement
  • Use case: Balanced applications

Medium Decimation (Factor 4-6)

  • Quality: Good overall structure
  • Performance: Significant improvement
  • Use case: Visualization and analysis

High Decimation (Factor 7+)

  • Quality: Basic structure preserved
  • Performance: Maximum improvement
  • Use case: Rough analysis, thumbnails

Limitations

Topology Constraints

  • Only works on full tree structures (not trunk-only files)
  • Cannot create new junctions or merge branches
  • Maintains original branching patterns

Quality Loss

  • Fine-scale geometric details may be lost
  • Some biological realism may be reduced
  • Very high decimation may oversimplify structure

Output

The tool generates:

  • <input>_decimated.txt: Simplified tree file
  • Maintains same format and attribute structure
  • Preserves all attributes for retained segments

Validation

The decimated trees maintain:

  • Valid tree topology
  • Consistent parent-child relationships
  • Proper segment indexing
  • All required attributes

Additional Information

  • Decimation respects tree hierarchy and biological structure
  • Junction detection ensures structural integrity
  • Segment counting is branch-aware for natural decimation
  • For more detailed information on decimation algorithms, refer to the TreeDecimate source code at treetools/treetools/treedecimate/treedecimate.cpp.