Package {crownmetrics}

Title:	Tree Crown Shape and Morphometric Parameters
Version:	0.1.0
Description:	Provides functions to compute tree crown volume and projected area using geometric solid approximations (ellipsoid, cone, cylinder, paraboloid, and fan shapes), and to calculate morphometric indices commonly used in forest inventory and silviculture, including crown ratio, crown form factor, slenderness, salience index, and scope index. Methods are based on peer-reviewed literature in forest science.
License:	MIT + file LICENSE
Encoding:	UTF-8
Imports:	dplyr (≥ 1.0.0)
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
Config/roxygen2/version:	8.0.0
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2026-07-12 00:27:35 UTC; sergio.costa
Author:	Sergio Costa [aut, cre, cph], Gilmara Machado [aut, cph]
Maintainer:	Sergio Costa <sergio.vscf@gmail.com>
Repository:	CRAN
Date/Publication:	2026-07-21 10:30:34 UTC

crownmetrics: Tree Crown Shape and Morphometric Parameters

Description

crownmetrics provides functions to compute tree crown volume and projected area using geometric solid approximations, and to calculate morphometric indices used in forest inventory and silviculture.

Crown volume models

Five geometric solids are implemented, following Zhu et al. (2021):

• Ellipsoid — crown_volume_ellipsoid()

• Cone — crown_volume_cone()

• Cylinder — crown_volume_cylinder()

• Paraboloid — crown_volume_paraboloid()

• Fan / umbrella — crown_volume_fan()

• Unified dispatcher — crown_volume()

Crown area functions

Profile and horizontal projection areas:

• crown_area_ellipse(), crown_area_triangle(), crown_area_rectangle(), crown_area_fan()

• crown_projection_area() — horizontal circular projection

• crown_area() — unified dispatcher

Morphometric indices

Based on Durlo & Denardi (1998) and Burger (1939):

• crown_ratio() — Crown Ratio (CR)

• crown_form() — Crown Form Factor (CF)

• slenderness() — Slenderness Index (SLI)

• salience_index() — Salience Index (SAL)

• scope_index() — Scope Index (SCI)

• vital_space_index() — Vital Space Index (VSI)

• crown_morphometrics() — all indices in one call

Batch processing

• crown_metrics() — computes all metrics for every row of a data frame

Input units

All crown and height measurements must be supplied in meters; diameter at breast height (DBH) must be in centimeters.

Author(s)

Maintainer: Sergio Costa sergio.vscf@gmail.com (ORCID) [copyright holder]

Authors:

• Sergio Costa sergio.vscf@gmail.com (ORCID) [copyright holder]

• Gilmara Machado gmachado@unicentro.br (ORCID) [copyright holder]

References

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

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.

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

McPherson, E. G., & Rowntree, R. A. (1988). Geometric solids for simulation of tree crowns. Landscape and Urban Planning, 15(3–4), 79–83.

Crown Profile Area by Shape

Description

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

Usage

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

Arguments

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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:

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

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.

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.

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):

Usage

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

Arguments

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.

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

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.

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

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.

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:

Usage

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

Arguments

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

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.

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

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

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.

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

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

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.

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

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.

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

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.

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

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.

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

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.

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)