Skip to content

treecombine.md

Latest commit

 

History

History
160 lines (117 loc) · 4.47 KB

treecombine.md

File metadata and controls

160 lines (117 loc) · 4.47 KB
Raw

TreeCombine

TreeCombine is a tool for merging multiple tree files into a single file. It can combine files by concatenating trees or by merging attributes from files with identical tree structures.

Usage

treecombine <tree_file1> <tree_file2> <tree_file3> ...
  • Takes two or more tree files as input
  • Automatically determines the appropriate combination method

Combination Methods

The tool automatically selects one of two combination approaches:

1. Concatenate Trees (Same Attributes)

When all files have the same attribute structure:

  • Combines all trees from all files into a single file
  • Preserves individual tree structures
  • Maintains consistent attribute sets

2. Merge Attributes (Same Trees)

When all files have identical tree structures but different attributes:

  • Combines attribute sets from all files
  • Maintains the same tree topology
  • Creates comprehensive attribute datasets

Requirements

For Tree Concatenation

  • All input files must have identical attribute names
  • Both segment attributes and tree-level attributes must match
  • Trees can have different structures and counts

For Attribute Merging

  • All input files must have identical tree structures:
    • Same number of trees
    • Same number of segments per tree
    • Same parent-child relationships (topology)
  • Files can have different attribute sets

Examples

Concatenate Multiple Forest Files

Combine separate forest surveys with same attributes:

treecombine plot1.txt plot2.txt plot3.txt

Merge Different Attribute Sets

Combine files with same trees but different measurements:

treecombine base_structure.txt diameter_data.txt height_data.txt

Combine Temporal Datasets

Merge different time periods with same tree structure:

treecombine trees_2020.txt trees_2021.txt trees_2022.txt

Validation

The tool performs extensive validation:

Structure Validation

  • Checks tree count consistency
  • Verifies segment count per tree
  • Validates parent-child relationships
  • Ensures topological consistency

Attribute Validation

  • Compares attribute name lists
  • Verifies tree-level attribute consistency
  • Checks segment-level attribute matching

Error Handling

Invalid Combinations

The tool will refuse to combine files when:

  • Files have different attributes AND different tree structures
  • Files have identical attributes AND identical tree structures (no benefit)

File Loading

  • Skips files that cannot be loaded
  • Reports which files are being skipped
  • Continues processing with remaining valid files

Output

Creates a combined tree file containing:

  • All trees from input files (concatenation mode)
  • OR original tree structure with merged attributes (attribute mode)
  • Comments from the first input file
  • Consistent formatting and structure

Applications

Forest Inventory

  • Combine multiple survey plots
  • Merge field measurements with remote sensing data
  • Integrate different measurement campaigns

Temporal Analysis

  • Combine multi-temporal datasets
  • Merge growth measurements over time
  • Create comprehensive forest monitoring datasets

Data Integration

  • Combine structural data with biological attributes
  • Merge LiDAR-derived and field-measured parameters
  • Integrate different data collection methods

Multi-source Analysis

  • Combine data from different sensors
  • Merge manual and automated measurements
  • Create comprehensive tree databases

Use Cases

Scenario 1: Multi-plot Survey

treecombine forest_plot_A.txt forest_plot_B.txt forest_plot_C.txt

Combines trees from different plots into single forest file.

Scenario 2: Attribute Enhancement

treecombine structure.txt biomass.txt health.txt

Adds biomass and health attributes to existing tree structure.

Scenario 3: Temporal Monitoring

treecombine baseline.txt growth_year1.txt growth_year2.txt

Creates time-series dataset with growth measurements.

Quality Assurance

The tool ensures:

  • No data loss during combination
  • Preservation of tree topology
  • Consistent attribute formatting
  • Proper error reporting for incompatible files

Additional Information

  • Comments are preserved from the first input file only
  • File processing order affects the final attribute order
  • Large datasets are handled efficiently with minimal memory usage
  • For more detailed information on combination algorithms, refer to the TreeCombine source code at treetools/treetools/treecombine/treecombine.cpp.