---
title: "Introduction to crownmetrics"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to crownmetrics}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment  = "#>",
  fig.width = 6,
  fig.height = 4
)
library(crownmetrics)
```

## Overview

`crownmetrics` is a R package for computing tree crown metrics
from basic field measurements. It provides two categories of functions:

1. **Geometric volume and area models** — crown volume (m³) and crown profile
   area (m²) using five classic geometric solid approximations.
2. **Morphometric indices** — six dimensionless indices widely used in forest
   inventory and silviculture to characterise tree architecture and competitive
   status.

### Notation

Throughout this document the following symbols are used:

| Symbol | Variable | Unit |
|--------|----------|------|
| $CW$ | Crown width (mean diameter) | **meters** |
| $CL$ | Crown length | **meters** |
| $H$ | Total tree height | **meters** |
| $DBH$ | Diameter at breast height | **centimeters** |

---

## 1. Crown volume

Crown volume is approximated by fitting a geometric solid to the crown
envelope. The appropriate shape depends on the species and management history
(Zhu, Kleinn & Nölke, 2021).

### 1.1 Ellipsoid

The ellipsoid is the most widely used approximation for broadleaf and urban
trees. When $CW = CL$ the formula reduces to a sphere.

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

```{r vol-ellipsoid}
crown_volume_ellipsoid(crown_width = 3.5, crown_length = 5.0)
```

### 1.2 Cone

Suitable for conifers with narrow, pointed crowns (e.g. *Pinus* spp.,
*Picea* spp.).

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

```{r vol-cone}
crown_volume_cone(crown_width = 3.5, crown_length = 5.0)
```

### 1.3 Cylinder

Represents trees with a uniform crown width from base to top.

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

```{r vol-cylinder}
crown_volume_cylinder(crown_width = 3.5, crown_length = 5.0)
```

### 1.4 Paraboloid

An intermediate shape between the cone and the cylinder, often considered a
reasonable approximation for broadleaf trees.

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

```{r vol-paraboloid}
crown_volume_paraboloid(crown_width = 3.5, crown_length = 5.0)
```

### 1.5 Fan / Umbrella

Used for trees with wide, flat crowns (e.g. *Pinus pinea*). The vertical
extent of the crown solid is approximated by the stem diameter at breast
height converted to meters ($DBH / 100$).

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

```{r vol-fan}
crown_volume_fan(crown_length = 5.0, dbh = 22.0)
```

### 1.6 Comparing shapes

The relationship between shapes is fixed for given $CW$ and $CL$:
$V_{\text{cylinder}} = 2\,V_{\text{paraboloid}} = 3\,V_{\text{cone}}$,
with the ellipsoid falling between the paraboloid and the cylinder.

```{r volume-compare}
cw <- 3.5   # crown width (m)
cl <- 5.0   # crown length (m)

volumes <- c(
  ellipsoid  = crown_volume_ellipsoid(cw, cl),
  cone       = crown_volume_cone(cw, cl),
  cylinder   = crown_volume_cylinder(cw, cl),
  paraboloid = crown_volume_paraboloid(cw, cl)
)

round(volumes, 2)
```

```{r volume-bar, echo = FALSE}
barplot(
  volumes,
  col    = c("#2d6a4f", "#52b788", "#95d5b2", "#d8f3dc"),
  border = NA,
  ylab   = expression("Crown volume (m"^3*")"),
  main   = "Crown volume by geometric shape",
  las    = 1
)
```

### 1.7 Unified dispatcher

`crown_volume()` selects the model via its `shape` argument, accepting
`"ellipsoid"`, `"cone"`, `"cylinder"`, `"paraboloid"`, or `"fan"`:

```{r volume-dispatcher}
crown_volume(crown_width = 3.5, crown_length = 5.0, shape = "ellipsoid")
crown_volume(crown_width = 3.5, crown_length = 5.0, shape = "cone")
crown_volume(crown_length = 5.0, dbh = 22.0, shape = "fan")
```

---

## 2. Crown area

Two types of area are available.

### 2.1 Crown profile areas (lateral cross-section)

These represent the two-dimensional silhouette of the crown as seen from the
side (McPherson & Rowntree, 1988; Zhu, Kleinn & Nölke, 2021).

**Ellipse** — used with the ellipsoid and paraboloid volume models:

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

**Triangle** — used with the cone volume model:

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

**Rectangle** — used with the cylinder volume model:

$$A_{\text{rectangle}} = CW \cdot CL$$

**Fan / umbrella** — used with the fan volume model:

$$A_{\text{fan}} = \frac{\pi\,CL}{4}$$

```{r area-profile}
crown_area(crown_width = 3.5, crown_length = 5.0, shape = "ellipse")
crown_area(crown_width = 3.5, crown_length = 5.0, shape = "triangle")
crown_area(crown_width = 3.5, crown_length = 5.0, shape = "rectangle")
crown_area(crown_length = 5.0, shape = "fan")
```

### 2.2 Crown projection area (horizontal)

The crown projection area (CPA) is the area of the crown's shadow on the
ground, assuming a circular crown outline (Sayn-Wittgenstein & Aldred, 1972):

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

```{r area-projection}
crown_projection_area(crown_width = 3.5)
```

---

## 3. Morphometric indices

Morphometric indices are dimensionless ratios that characterise tree
architecture, stability, and competitive status. All indices follow Durlo &
Denardi (1998) and Burger (1939).

### 3.1 Crown Ratio — CR

The fraction of total height occupied by the living crown. Higher values
indicate greater photosynthetic potential and crown vitality.

$$CR = \frac{CL}{H}$$

```{r idx-pc}
crown_ratio(crown_length = 5.0, total_height = 18.0)
crown_ratio(crown_length = 5.0, total_height = 18.0, as_percentage = TRUE)
```

### 3.2 Crown Form Factor — CF

The ratio of crown width to crown length. Values $> 1$ indicate wide, flat
crowns; values $< 1$ indicate tall, narrow crowns.

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

```{r idx-fc}
crown_form(crown_width = 3.5, crown_length = 5.0)
```

### 3.3 Slenderness Index — SLI

The ratio of total height to DBH (both expressed in meters). Higher values
indicate more slender trees with greater susceptibility to wind and snow damage.

$$SLI = \frac{H}{DBH / 100}$$

```{r idx-ge}
slenderness(total_height = 18.0, dbh = 22.0)
```

### 3.4 Salience Index — SAI

Expresses how many times wider the crown is than the trunk diameter (both in
meters). Reflects the tree's capacity to occupy horizontal space relative to
its stem size.

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

```{r idx-is}
salience_index(crown_width = 3.5, dbh = 22.0)
```

### 3.5 Scope Index — SCI

The ratio of crown width to total tree height. Describes the lateral
competitive reach of the crown relative to tree height.

$$SCI = \frac{CW}{H}$$

```{r idx-ia}
scope_index(crown_width = 3.5, total_height = 18.0)
```

### 3.6 Vital Space Index — VSI

The ratio of crown projection area to stem basal area. Expresses how many
times more ground area the crown occupies compared to the stem cross-section.
Note that the $\pi$ terms cancel, so $VSI = SAI^{2}$.

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

```{r idx-iev}
vital_space_index(crown_width = 3.5, dbh = 22.0)
```

### 3.7 Summary table

| Symbol | Name | Equation | Interpretation |
|--------|------|----------|----------------|
| CR | Crown Ratio | $CL\,/\,H$ | Crown occupancy; higher = more leaf area |
| CF | Crown Form | $CW\,/\,CL$ | $>1$: wide flat; $<1$: narrow tall |
| SLI | Slenderness | $H\,/\,(DBH/100)$ | Higher = more wind-sensitive |
| SAI | Salience Index | $CW\,/\,(DBH/100)$ | Crown breadth relative to stem |
| SCI | Scope Index | $CW\,/\,H$ | Lateral reach relative to height |
| VSI | Vital Space Index | $(CW/DBH_{m})^{2}$ | Growing space efficiency |

### 3.8 Computing all indices at once

```{r morph-single}
crown_morphometrics(
  crown_width  = 3.5,
  crown_length = 5.0,
  total_height = 18.0,
  dbh          = 22.0
)
```

---

## 4. Batch processing with `crown_metrics()`

For inventory datasets, `crown_metrics()` computes every volume, area, and
morphometric index in one pass, returning the original data frame with all
metric columns appended. Crown shape is specified per-row via integer codes
or character strings:

| Integer | Character | Solid |
|---------|-----------|-------|
| 0 | `"ellipsoid"` | Ellipsoid |
| 1 | `"cone"` | Cone |
| 2 | `"cylinder"` | Cylinder |
| 3 | `"paraboloid"` | Paraboloid |
| 4 | `"fan"` | Fan |

```{r batch}
inventory <- data.frame(
  tree_id      = 1:6,
  species      = c("Araucaria", "Pinus",  "Eucalyptus",
                   "Araucaria", "Pinus",  "Eucalyptus"),
  crown_width  = c(3.0,  2.0,  4.0,  3.5,  2.5,  4.5),
  crown_length = c(5.0,  6.0,  3.5,  4.5,  5.5,  3.0),
  total_height = c(18.0, 20.0, 12.0, 16.0, 19.0, 11.0),
  dbh          = c(22.0, 18.0, 25.0, 20.0, 17.0, 28.0),
  shape_code   = c(0L,   1L,   0L,   0L,   1L,   3L)
)

result <- crown_metrics(inventory, col_shape = "shape_code")

result[, c("tree_id", "species", "crown_volume_m3",
           "crown_projection_area_m2", "slenderness", "crown_ratio")]
```

If no shape column is provided, all rows default to the ellipsoid model.

---

## References

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

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.

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

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

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

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.

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