-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathREADME.Rmd
187 lines (159 loc) · 7.88 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
<p align="center">
<img src="man/figures/ITSMe_logo_RGB.jpg" height="200" >
</p>
## Goal
The goal of the ITSMe (Individual Tree Structural Metrics) R-package is to
provide easy to use functions to quickly obtain structural metrics from
individual tree point clouds and their respective quantitative structure models
(QSMs).
## Installation
You can install the development version of ITSMe from
[GitHub](https://github.com/) with:
``` r
# install.packages("devtools")
devtools::install_github("lmterryn/ITSMe", build_vignettes = TRUE)
```
## Input
The functions are developed for tree point clouds obtained with TLS and QSMs
obtained with [TreeQSM](https://github.com/InverseTampere/TreeQSM). The
functions can, however, also be used on tree point clouds obtained
from UAV-LS or MLS. You always need to keep in mind that the accuracy of
the metric measurements will depend on the quality of the data.
## Individual tree structural metrics
Structural metrics that can be calculated with the ITSMe package are
summarised in the tables below.
### Basic structural metrics
| structural metric | function name | input |
| ------------------------------|:---------------------------------:|-------------------:|
| diameter at breast height (m) | dbh_pc, dbh_qsm | point cloud, QSM |
| diameter above buttresses (m) | dab_pc | point cloud |
| tree height (m) | tree_height_pc, tree_height_qsm | point cloud, QSM |
| projected area (m$^{2}$) | projected_area_pc | point cloud |
| alpha volume (m$^{3}$) | alpha_volume_pc | point cloud |
| tree volume (m$^{3}$) | tree_volume_qsm | QSM |
| trunk volume (m$^{3}$) | trunk_volume_qsm | QSM |
| total branch volume (m$^{3}$) | total_branch_volume_qsm | QSM |
| total branch length (m) | total_branch_length_qsm | QSM |
| total cylinder length (m) | total_cyl_length_qsm | QSM |
### Structural metrics from Terryn et al. (2020)
These are the metrics defined in
[Terryn et al. (2020)](https://doi.org/10.1016/j.isprsjprs.2020.08.009)
which were adapted from
[Akerblom et al. (2017)](https://doi.org/10.1016/j.rse.2016.12.002)
except for the branch angle ratio and the relative volume ratio. Definitions of
the metrics can be found in the help files of the functions and the papers of
Terryn et al. (2020) and Akerblom et al. (2017). Normalisation according to
Terryn et al. (2020) as well as Akerblom et al. (2017) is possible through the
normalisation parameter included in the functions of the metrics that were
adapted by Terryn et al. (2020). If the tree point cloud is provided along with
the TreeQSM in the functions, dbh and tree height values are based on the point
clouds rather than the QSMs. When the buttress parameter is indicated "TRUE" the
diameter above buttresses instead of the diameter at breast height is used.
| structural metric | function name | input |
| ------------------------------------------|:---------------------------------:|-------------------:|
| stem branch angle (degrees) | stem_branch_angle_qsm | QSM |
| stem branch cluster size | stem_branch_cluster_size_qsm | QSM |
| stem branch radius (-/m) | stem_branch_radius_qsm | QSM (+point cloud) |
| stem branch length (-/m) | stem_branch_length_qsm | QSM (+point cloud) |
| stem branch distance (-/m) | stem_branch_distance_qsm | QSM (+point cloud) |
| dbh tree height ratio | dbh_height_ratio_qsm | QSM (+point cloud) |
| dbh tree volume ratio (m$^{-2}$) | dbh_volume_ratio_qsm | QSM (+point cloud) |
| volume below 55 | volume_below_55_qsm | QSM |
| cylinder length volume ratio (m$^{-2}$) | cylinder_length_volume_ratio_qsm | QSM |
| shedding ratio | shedding_ratio_qsm | QSM |
| branch angle ratio | branch_angle_ratio_qsm | QSM |
| relative volume ratio | relative_volume_ratio_qsm | QSM |
| crown start height | crown_start_height_qsm | QSM (+point cloud) |
| crown height | crown_height_qsm | QSM (+point cloud) |
| crown evenness | crown_evenness_qsm | QSM |
| crown diameter crown height ratio | crown_diameterheight_ratio_qsm | QSM (+point cloud) |
| dbh minimum tree radius ratio | dbh_minradius_ratio_qsm | QSM (+point cloud) |
## Examples
For complete workflows, have a look at the ITSMe vignette with:
```{r eval = FALSE}
vignette("ITSMe")
```
Calculating the diameter at breast height versus the diameter above buttresses
of a tree:
```{r eval = FALSE}
library(ITSMe)
# Read the point cloud file from the Specified path to the tree point cloud file
pc_tree <- read_tree_pc(path = "path/to/point/cloud.txt")
# Use dbh_pc function with default parameters and plot the fit
out_dbh <- dbh_pc(pc = pc_tree, plot = TRUE)
# Access the dbh, residual and fdbh values from the output list
dbh <- out_dbh$dbh
residual_dbh <- out_dbh$R2
fdbh <- out_dbh$fdbh
# Use dab_pc function with default parameters and plot the fit
out_dab <- dab_pc(pc = pc_tree, plot = TRUE)
# Access the dab, residual and fdab values from the output list
ddab <- out_dab$dab
residual_dab <- out_dab$R2
fdab <- out_dab$fdab
```
<p align="center">
<img src="man/figures/dbh_example.jpeg" height="500" >
</p>
<p align="center">
<img src="man/figures/dab_example.jpeg" height="500" >
</p>
Calculating the stem branch distance of a TreeQSM:
```{r eval = FALSE}
library(ITSMe)
# Read the TreeQSM file from the Specified path to the TreeQSM file
qsm <- read_tree_qsm(path = "path/to/QSM.mat")
# Use stem_branch_distance_qsm function
sbd <- stem_branch_distance_qsm(
cylinder = qsm$cylinder,
treedata = qsm$treedata, normalisation = "dbh"
)
# Using the point cloud information for more accurate dbh normalisation
pc_tree <- read_tree_pc(path = "path/to/point/cloud.txt")
sbd <- stem_branch_distance_qsm(
cylinder = qsm$cylinder,
treedata = qsm$treedata, normalisation = "dbh",
pc = pc_tree, buttress = TRUE
)
```
Calculating a summary data.frame with the basic structural metrics
(tree position, dbh, dab, tree height, projected area, 3D alpha volume) that
can be obtained from individual tree point clouds for all point clouds in a
specific folder:
```{r eval = FALSE}
library(ITSMe)
# Run summary function with default parameter settings
basic_summary <- summary_basic_pointcloud_metrics(
PCs_path = "path/to/point/cloud/folder/",
extension = ".txt"
)
```
If you set the plot parameter TRUE and provide an OUT_path, this function saves
a summary figure for each tree:
<p align="center">
<img src="man/figures/summary.jpeg" height="500" >
</p>
Calculating a summary data.frame with the structural metrics defined by Terryn
et al. (2020) for all TreeQSMs in a specific folder:
```{r eval = FALSE}
library(ITSMe)
# Run summary function with default parameter settings
qsm_summary <- summary_qsm_metrics(
QSMs_path = "path/to/QSM/folder/",
version = "2.3.0",
PCs_path = "path/to/point/cloud/folder/",
extension = ".txt"
)
```