Package 'crownmetrics'

Crown Profile Area by Shape

Description

A unified interface to the four lateral profile area functions. The shape is selected via the shape argument:

shape	Model	Formula
"ellipse"	Ellipse	π (CL/2)(CW/2)
"triangle"	Triangle (cone)	CW · CL / 2
"rectangle"	Rectangle (cylinder)	CW · CL
"fan"	Fan / umbrella	π · CL / 4

Usage

crown_area(crown_width = NULL, crown_length, shape = "ellipse")

Arguments

crown_width	Numeric. Crown width (mean diameter) in meters. Not used for shape = "fan".
crown_length	Numeric. Crown length in meters.
shape	Character. One of "ellipse", "triangle", "rectangle", or "fan". Default: "ellipse".

Value

A numeric vector of crown profile areas in square meters (m²).

References

Zhu, Z., Kleinn, C., & Nölke, N. (2021). Assessing tree crown volume — a review. Forestry, 94(1), 18–35. doi:10.1093/forestry/cpaa037

See Also

crown_area_ellipse(), crown_area_triangle(), crown_area_rectangle(), crown_area_fan(), crown_projection_area()

Examples

crown_area(crown_width = 3.0, crown_length = 4.5)
crown_area(crown_width = 2.0, crown_length = 5.0, shape = "triangle")
crown_area(crown_length = 4.0, shape = "fan")

---

Crown Profile Area — Ellipse

Description

Estimates the lateral profile area of a crown approximated as an ellipse. This is the cross-sectional area seen from the side (not the horizontal projection).

$A_{ellipse} = \pi \left(\frac{CL}{2}\right) \left(\frac{CW}{2}\right)$

Usage

crown_area_ellipse(crown_width, crown_length)

Arguments

crown_width	Numeric. Crown width (mean diameter) in meters.
crown_length	Numeric. Crown length in meters.

Value

A numeric vector of crown profile areas in square meters (m²).

References

Zhu, Z., Kleinn, C., & Nölke, N. (2021). Assessing tree crown volume — a review. Forestry, 94(1), 18–35. doi:10.1093/forestry/cpaa037

Examples

crown_area_ellipse(crown_width = 3.0, crown_length = 4.5)

---

Crown Profile Area — Fan (Umbrella) Shape

Description

Estimates the lateral profile area for a fan or umbrella-shaped crown. The formula is based on a quarter-circle sector approximation using the crown length as the characteristic dimension.

$A_{fan} = \frac{\pi \cdot CL}{4}$

Usage

crown_area_fan(crown_length)

Arguments

crown_length

Numeric. Crown length in meters.

Value

A numeric vector of crown profile areas in square meters (m²).

References

Lanner, R. M. (1989). An observation on apical dominance and the umbrella-crown of Italian stone pine (Pinus pinea, Pinaceae). Economic Botany, 43(1), 128–130. doi:10.1007/BF02858917

Examples

crown_area_fan(crown_length = 4.0)

---

Crown Profile Area — Rectangle (Cylinder)

Description

Estimates the lateral profile area of a crown approximated as a rectangle, corresponding to a cylindrical crown shape.

$A_{rectangle} = CW \cdot CL$

Usage

crown_area_rectangle(crown_width, crown_length)

Arguments

crown_width	Numeric. Crown width (mean diameter) in meters.
crown_length	Numeric. Crown length in meters.

Value

A numeric vector of crown profile areas in square meters (m²).

References

Hecht, R., Meinel, G., & Buchroithner, M. F. (2008). Estimation of urban green volume based on single-pulse LiDAR data. IEEE Transactions on Geoscience and Remote Sensing, 46(11), 3832–3840. doi:10.1109/TGRS.2008.2001771

Examples

crown_area_rectangle(crown_width = 3.0, crown_length = 4.0)

---

Crown Profile Area — Triangle (Cone)

Description

Estimates the lateral profile area of a crown approximated as a triangle, corresponding to a conical crown shape.

$A_{triangle} = \frac{CW \cdot CL}{2}$

Usage

crown_area_triangle(crown_width, crown_length)

Arguments

crown_width	Numeric. Crown width (mean diameter) in meters.
crown_length	Numeric. Crown length in meters.

Value

A numeric vector of crown profile areas in square meters (m²).

References

Zhu, Z., Kleinn, C., & Nölke, N. (2021). Assessing tree crown volume — a review. Forestry, 94(1), 18–35. doi:10.1093/forestry/cpaa037

Examples

crown_area_triangle(crown_width = 2.0, crown_length = 5.0)

---

Crown Form Factor

Description

Computes the crown form factor, defined as the ratio between crown width and crown length. Values close to 1 indicate a hemispherical crown; values > 1 indicate a wide, flat crown; values < 1 indicate a narrow, elongated crown.

$CF = \frac{CW}{CL}$

Usage

crown_form(crown_width, crown_length)

Arguments

crown_width	Numeric. Crown width (mean diameter) in meters.
crown_length	Numeric. Crown length in meters.

Value

A numeric vector of crown form factor values (dimensionless).

References

Durlo, M. A., & Denardi, L. (1998). Morfometria de Cabralea canjerana, em mata secundária nativa do Rio Grande do Sul. Ciência Florestal, 8(1), 55–66. doi:10.5902/19805098357

Examples

crown_form(crown_width = 3.0, crown_length = 4.5)

---

Compute All Crown Metrics for a Data Frame

Description

Applies all crownmetrics calculations to a data.frame or tibble in a single step, returning the original data with additional columns for crown volume, crown profile area, crown projection area, and all six morphometric indices. Internally uses dplyr::mutate() for a tidy workflow.

The crown shape is specified per-row via a character or integer column, allowing mixed-shape inventories. Accepted values:

Integer	Character	Geometric solid
0	"ellipsoid"	Ellipsoid (default)
1	"cone"	Cone
2	"cylinder"	Cylinder
3	"paraboloid"	Paraboloid
4	"fan"	Fan / umbrella

Usage

crown_metrics(
  data,
  col_crown_width = "crown_width",
  col_crown_length = "crown_length",
  col_total_height = "total_height",
  col_dbh = "dbh",
  col_shape = NULL,
  as_percentage = FALSE
)

Arguments

data	A data.frame or tibble containing at least the columns specified by the ⁠col_*⁠ arguments.
col_crown_width	Character. Name of the column with crown width (meters). Default: "crown_width".
col_crown_length	Character. Name of the column with crown length (meters). Default: "crown_length".
col_total_height	Character. Name of the column with total tree height (meters). Default: "total_height".
col_dbh	Character. Name of the column with DBH (centimeters). Default: "dbh".
col_shape	Character. Name of the column with crown shape codes (integer 0–4 or character; see table above). If NULL, all trees are treated as ellipsoid. Default: NULL.
as_percentage	Logical. If TRUE, crown ratio is returned as a percentage. Default: FALSE.

Value

The input data with the following columns appended:

crown_volume_m3

Crown volume (m³).

crown_area_m2

Crown profile area (m²).

crown_projection_area_m2

Horizontal crown projection area (m²).

crown_ratio

Crown ratio (CR).

crown_form

Crown form factor (CF).

slenderness

Slenderness index (SLI).

salience_index

Salience index (SAI).

scope_index

Scope index (SCI).

vital_space_index

Vital space index (VSI).

References

Zhu, Z., Kleinn, C., & Nölke, N. (2021). Assessing tree crown volume — a review. Forestry, 94(1), 18–35. doi:10.1093/forestry/cpaa037

Durlo, M. A., & Denardi, L. (1998). Morfometria de Cabralea canjerana, em mata secundária nativa do Rio Grande do Sul. Ciência Florestal, 8(1), 55–66. doi:10.5902/19805098357

Examples

trees <- data.frame(
  tree_id      = 1:4,
  crown_width  = c(3.0, 2.0, 3.5, 4.0),
  crown_length = c(4.5, 5.0, 4.0, 3.0),
  total_height = c(15,  18,  12,  10),
  dbh          = c(18.5, 15.0, 22.0, 25.0),
  shape_code   = c(0L, 1L, 2L, 3L)
)

crown_metrics(trees, col_shape = "shape_code")

# Without a shape column — all trees treated as ellipsoid
crown_metrics(trees)

---

All Crown Morphometric Indices

Description

Computes all five standard crown morphometric indices in a single call, returning a named list (for scalar inputs) or a tibble / data.frame (for vector inputs):

Symbol	Name	Formula
CR	Crown Ratio	CL / H
CF	Crown Form	CW / CL
SLI	Slenderness	H / (DBH / 100)
SAI	Salience Index	CW / (DBH / 100)
SCI	Scope Index	CW / H
VSI	Vital Space Index	(CW/2)² / (DBH/200)²

Usage

crown_morphometrics(
  crown_width,
  crown_length,
  total_height,
  dbh,
  as_percentage = FALSE
)

Arguments

crown_width	Numeric. Crown width (mean diameter) in meters.
crown_length	Numeric. Crown length in meters.
total_height	Numeric. Total tree height in meters.
dbh	Numeric. Diameter at breast height in centimeters.
as_percentage	Logical. If TRUE, crown ratio (PC) is returned as a percentage (0–100 %). Default: FALSE.

Value

A data.frame with columns crown_ratio (CR), crown_form (CF), slenderness (SLI), salience_index (SAI), scope_index (SCI), and vital_space_index (VSI).

References

Durlo, M. A., & Denardi, L. (1998). Morfometria de Cabralea canjerana, em mata secundária nativa do Rio Grande do Sul. Ciência Florestal, 8(1), 55–66. doi:10.5902/19805098357

Burger, H. (1939). Baumkrone und Zuwachs in zwei hiebsreifen Fichtenbeständen. Mitteilungen der Schweizerischen Anstalt für das Forstliche Versuchswesen, 21, 147–176.

Examples

crown_morphometrics(
  crown_width  = 3.5,
  crown_length = 4.5,
  total_height = 15.0,
  dbh          = 18.5
)

# With a data frame
trees <- data.frame(
  cw = c(3.0, 3.5, 4.0),
  cl = c(4.0, 4.5, 5.0),
  h  = c(12,  15,  18),
  d  = c(15,  18,  22)
)
crown_morphometrics(trees$cw, trees$cl, trees$h, trees$d)

---

Crown Projection Area (Horizontal)

Description

Computes the crown projection area (CPA) — the area of the crown's shadow on a horizontal plane, assuming a circular crown outline.

$CPA = \pi \left(\frac{CW}{2}\right)^2$

Usage

crown_projection_area(crown_width)

Arguments

crown_width

Numeric. Crown width (mean diameter) in meters.

Value

A numeric vector of crown projection areas in square meters (m²).

References

Sayn-Wittgenstein, L., & Aldred, A. H. (1972). Tree size from large-scale photos. Photogrammetric Engineering, 38, 971–973.

Durlo, M. A., & Denardi, L. (1998). Morfometria de Cabralea canjerana, em mata secundária nativa do Rio Grande do Sul. Ciência Florestal, 8(1), 55–66. doi:10.5902/19805098357

Examples

crown_projection_area(crown_width = 3.5)

# Compare multiple trees
crown_projection_area(c(2.0, 3.0, 4.5))

---

Crown Ratio

Description

Computes the crown ratio, defined as the ratio between crown length and total tree height. It represents the proportion of the tree height occupied by the living crown and is an indicator of crown vitality and light-use efficiency.

$CR = \frac{CL}{H_{tot}}$

Usage

crown_ratio(crown_length, total_height, as_percentage = FALSE)

Arguments

crown_length	Numeric. Crown length in meters — the vertical distance from the base of the live crown to the crown top.
total_height	Numeric. Total tree height in meters.
as_percentage	Logical. If TRUE, the result is multiplied by 100 and returned as a percentage (0–100 %). Default: FALSE.

Value

A numeric vector of crown ratio values (dimensionless, or % when as_percentage = TRUE).

References

Durlo, M. A., & Denardi, L. (1998). Morfometria de Cabralea canjerana, em mata secundária nativa do Rio Grande do Sul. Ciência Florestal, 8(1), 55–66. doi:10.5902/19805098357

Burger, H. (1939). Baumkrone und Zuwachs in zwei hiebsreifen Fichtenbeständen. Mitteilungen der Schweizerischen Anstalt für das Forstliche Versuchswesen, 21, 147–176.

Examples

crown_ratio(crown_length = 4.5, total_height = 15.0)
crown_ratio(crown_length = 4.5, total_height = 15.0, as_percentage = TRUE)

# Vectorised use
crown_ratio(crown_length = c(3, 4.5, 6), total_height = c(12, 15, 18))

---

Crown Volume by Shape

Description

A unified interface to the five geometric solid volume functions. The crown shape is selected via the shape argument:

shape	Model	Typical species / use
"ellipsoid"	Ellipsoid (default)	Broadleaf, urban trees
"cone"	Cone	Conifers with pointed crowns
"cylinder"	Cylinder	Dense, columnar crowns
"paraboloid"	Paraboloid	Broadleaf trees
"fan"	Fan / umbrella	Flat-crowned species

Usage

crown_volume(crown_width = NULL, crown_length, dbh = NULL, shape = "ellipsoid")

Arguments

crown_width	Numeric. Crown width (mean diameter) in meters. Not used for shape = "fan".
crown_length	Numeric. Crown length in meters.
dbh	Numeric. Diameter at breast height in centimeters. Required only for shape = "fan".
shape	Character. One of "ellipsoid", "cone", "cylinder", "paraboloid", or "fan". Default: "ellipsoid".

Value

A numeric vector of crown volumes in cubic meters (m³).

References

Zhu, Z., Kleinn, C., & Nölke, N. (2021). Assessing tree crown volume — a review. Forestry, 94(1), 18–35. doi:10.1093/forestry/cpaa037

See Also

crown_volume_ellipsoid(), crown_volume_cone(), crown_volume_cylinder(), crown_volume_paraboloid(), crown_volume_fan()

Examples

crown_volume(crown_width = 3.0, crown_length = 4.5)
crown_volume(crown_width = 2.0, crown_length = 5.0, shape = "cone")
crown_volume(crown_length = 4.0, dbh = 25.0, shape = "fan")

# Compare all shapes for the same tree
shapes <- c("ellipsoid", "cone", "cylinder", "paraboloid")
sapply(shapes, function(s) {
  crown_volume(crown_width = 3.0, crown_length = 4.5, shape = s)
})

---

Crown Volume — Cone

Description

Estimates crown volume by approximating the crown shape as a cone. Suitable for coniferous species with narrow, pointed crowns (e.g., Pinus spp., young Picea spp.).

$V_{cone} = \frac{1}{3} \pi \left(\frac{CW}{2}\right)^2 CL$

Usage

crown_volume_cone(crown_width, crown_length)

Arguments

crown_width	Numeric. Crown width (mean diameter) in meters.
crown_length	Numeric. Crown length in meters.

Value

A numeric vector of crown volumes in cubic meters (m³).

References

Zhu, Z., Kleinn, C., & Nölke, N. (2021). Assessing tree crown volume — a review. Forestry, 94(1), 18–35. doi:10.1093/forestry/cpaa037

McPherson, E. G., & Rowntree, R. A. (1988). Geometric solids for simulation of tree crowns. Landscape and Urban Planning, 15(3–4), 79–83. doi:10.1016/0169-2046(88)90022-3

Examples

crown_volume_cone(crown_width = 2.0, crown_length = 5.0)

---

Crown Volume — Cylinder

Description

Estimates crown volume by approximating the crown shape as a cylinder. Represents trees with uniform crown width from base to top.

$V_{cylinder} = \pi \left(\frac{CW}{2}\right)^2 CL$

Usage

crown_volume_cylinder(crown_width, crown_length)

Arguments

crown_width	Numeric. Crown width (mean diameter) in meters.
crown_length	Numeric. Crown length in meters.

Value

A numeric vector of crown volumes in cubic meters (m³).

References

Zhu, Z., Kleinn, C., & Nölke, N. (2021). Assessing tree crown volume — a review. Forestry, 94(1), 18–35. doi:10.1093/forestry/cpaa037

Hecht, R., Meinel, G., & Buchroithner, M. F. (2008). Estimation of urban green volume based on single-pulse LiDAR data. IEEE Transactions on Geoscience and Remote Sensing, 46(11), 3832–3840. doi:10.1109/TGRS.2008.2001771

Examples

crown_volume_cylinder(crown_width = 3.0, crown_length = 4.0)

---

Crown Volume — Ellipsoid (or Sphere)

Description

Estimates crown volume by approximating the crown shape as a half-ellipsoid (prolate or oblate spheroid). This is one of the most widely used geometric approximations in forest inventory and urban tree assessment.

$V_{ellipsoid} = \frac{4}{3} \pi \left(\frac{CL}{2}\right) \left(\frac{CW}{2}\right)^2$

When crown_width == crown_length, the formula reduces to a sphere.

Usage

crown_volume_ellipsoid(crown_width, crown_length)

Arguments

crown_width	Numeric. Crown width (mean diameter) in meters.
crown_length	Numeric. Crown length in meters.

Value

A numeric vector of crown volumes in cubic meters (m³).

References

Zhu, Z., Kleinn, C., & Nölke, N. (2021). Assessing tree crown volume — a review. Forestry, 94(1), 18–35. doi:10.1093/forestry/cpaa037

McPherson, E. G., & Rowntree, R. A. (1988). Geometric solids for simulation of tree crowns. Landscape and Urban Planning, 15(3–4), 79–83. doi:10.1016/0169-2046(88)90022-3

Examples

crown_volume_ellipsoid(crown_width = 3.0, crown_length = 4.5)

# Sphere (equal axes)
crown_volume_ellipsoid(crown_width = 3.0, crown_length = 3.0)

---

Crown Volume — Fan (Umbrella) Shape

Description

Estimates crown volume for trees with a wide, flat fan or umbrella-shaped crown (e.g., Pinus pinea, some tropical species). The model treats the crown as a disc-like solid whose vertical extent is approximated by the trunk diameter at breast height (DBH), and whose horizontal extent is characterised by the crown length.

$V_{fan} = \frac{\pi \cdot CL^2}{4} \cdot \frac{DBH}{100}$

Usage

crown_volume_fan(crown_length, dbh)

Arguments

crown_length	Numeric. Crown length in meters.
dbh	Numeric. Diameter at breast height in centimeters.

Value

A numeric vector of crown volumes in cubic meters (m³).

References

Lanner, R. M. (1989). An observation on apical dominance and the umbrella-crown of Italian stone pine (Pinus pinea, Pinaceae). Economic Botany, 43(1), 128–130. doi:10.1007/BF02858917

Zhu, Z., Kleinn, C., & Nölke, N. (2021). Assessing tree crown volume — a review. Forestry, 94(1), 18–35. doi:10.1093/forestry/cpaa037

Examples

crown_volume_fan(crown_length = 4.0, dbh = 25.0)

---

Crown Volume — Paraboloid

Description

Estimates crown volume by approximating the crown shape as a paraboloid of revolution. This shape is intermediate between a cone and a cylinder and is often considered a good approximation for broadleaf trees.

$V_{paraboloid} = \frac{1}{2} \pi \left(\frac{CW}{2}\right)^2 CL$

Usage

crown_volume_paraboloid(crown_width, crown_length)

Arguments

crown_width	Numeric. Crown width (mean diameter) in meters.
crown_length	Numeric. Crown length in meters.

Value

A numeric vector of crown volumes in cubic meters (m³).

References

Zhu, Z., Kleinn, C., & Nölke, N. (2021). Assessing tree crown volume — a review. Forestry, 94(1), 18–35. doi:10.1093/forestry/cpaa037

McPherson, E. G., & Rowntree, R. A. (1988). Geometric solids for simulation of tree crowns. Landscape and Urban Planning, 15(3–4), 79–83. doi:10.1016/0169-2046(88)90022-3

Examples

crown_volume_paraboloid(crown_width = 3.0, crown_length = 4.5)

---

Salience Index

Description

Computes the salience index, defined as the ratio between crown width and DBH (both converted to the same unit). It expresses how many times wider the crown is compared to the trunk diameter, reflecting the tree's ability to occupy horizontal space relative to its stem size.

$SAI = \frac{CW}{DBH / 100}$

Usage

salience_index(crown_width, dbh)

Arguments

crown_width	Numeric. Crown width (mean diameter) in meters.
dbh	Numeric. Diameter at breast height in centimeters.

Value

A numeric vector of salience index values (dimensionless).

References

Durlo, M. A., & Denardi, L. (1998). Morfometria de Cabralea canjerana, em mata secundária nativa do Rio Grande do Sul. Ciência Florestal, 8(1), 55–66. doi:10.5902/19805098357

Examples

salience_index(crown_width = 3.5, dbh = 18.5)

---

Scope Index

Description

Computes the scope index, defined as the ratio between crown width and total tree height. It describes the lateral reach of the crown relative to tree height and is used to characterise the crown's competitive influence on neighbouring trees.

$SCI = \frac{CW}{H_{tot}}$

Usage

scope_index(crown_width, total_height)

Arguments

crown_width	Numeric. Crown width (mean diameter) in meters.
total_height	Numeric. Total tree height in meters.

Value

A numeric vector of scope index values (dimensionless).

References

Durlo, M. A., & Denardi, L. (1998). Morfometria de Cabralea canjerana, em mata secundária nativa do Rio Grande do Sul. Ciência Florestal, 8(1), 55–66. doi:10.5902/19805098357

Examples

scope_index(crown_width = 3.5, total_height = 15.0)

---

Slenderness Index

Description

Computes the slenderness index, defined as the ratio between total tree height and diameter at breast height (DBH). Higher values indicate more slender trees that are more susceptible to wind and snow damage.

$SLI = \frac{H_{tot}}{DBH / 100}$

Usage

slenderness(total_height, dbh)

Arguments

total_height	Numeric. Total tree height in meters.
dbh	Numeric. Diameter at breast height in centimeters.

Value

A numeric vector of slenderness index values (dimensionless).

References

Durlo, M. A., & Denardi, L. (1998). Morfometria de Cabralea canjerana, em mata secundária nativa do Rio Grande do Sul. Ciência Florestal, 8(1), 55–66. doi:10.5902/19805098357

Sterba, H. (1991). Forstliche Wuchslehre. Universität für Bodenkultur, Wien.

Examples

slenderness(total_height = 15.0, dbh = 18.5)

---

Vital Space Index

Description

Computes the vital space index, defined as the ratio between the crown projection area (m²) and the basal area of the stem (m²). It quantifies how much ground area the crown occupies per unit of stem cross-sectional area, and is used as an indicator of competition and growing space efficiency.

$VSI = \frac{CPA}{BA} = \frac{\pi (CW/2)^2}{\pi (DBH/200)^2}$

Usage

vital_space_index(crown_width, dbh)

Arguments

crown_width	Numeric. Crown width (mean diameter) in meters.
dbh	Numeric. Diameter at breast height in centimeters.

Value

A numeric vector of vital space index values (dimensionless).

References

Durlo, M. A., & Denardi, L. (1998). Morfometria de Cabralea canjerana, em mata secundária nativa do Rio Grande do Sul. Ciência Florestal, 8(1), 55–66. doi:10.5902/19805098357

Wink, C., Monteiro, J. S., Reinert, D. J., & Liberalesso, E. (2012). Parâmetros da copa e a sua relação com o diâmetro e altura das árvores de eucalipto em diferentes idades. Scientia Forestalis, 40(93), 57–67.

Examples

vital_space_index(crown_width = 3.5, dbh = 18.5)

---