Compute colour volume overlap in 3D with alphashapes

overlap3d(
colsp1,
colsp2,
avalue = "auto",
plot = FALSE,
interactive = TRUE,
col = c("blue", "red", "darkgrey"),
fill = FALSE,
new = TRUE,
nsamp = 1000,
psize = 0.001,
lwd = 1,
...
)

## Arguments

colsp1 |
(required) data frame, possibly a result from the `colspace()`
function, containing
values for the 'x', 'y' (and possibly 'z') coordinates as columns (labeled as such) |

colsp2 |
(required) data frame, possibly a result from the `colspace()`
function, containing
values for the 'x', 'y' (and possibly 'z') coordinates as columns (labeled as such) |

avalue |
if `type = alpha` , the alpha parameter values for `colsp1` and
`colsp2` respectively to compute the alphashapes. Can be a numeric of length
one if the same value is used in both cases. `avalue = "auto"` (default)
finds and use the α*
value as defined in Gruson (2020). |

plot |
logical. Should the volumes and points be plotted? (defaults to `FALSE` ).
This only works for tetrahedral colourspaces at the moment. |

interactive |
logical. If `TRUE` , uses the rgl engine for interactive plotting;
if `FALSE` then a static plot is generated. |

col |
a vector of length 3 with the colours for (in order) the first volume,
the second volume, and the overlap. |

fill |
logical. should the two volumes be filled in the plot? (defaults to `FALSE` ) |

new |
logical. Should a new plot window be called? If `FALSE` , volumes and their
overlap are plotted over the current plot (defaults to `TRUE` ). |

nsamp |
if `type = "alpha"` , the number of points to be sampled for the
Monte Carlo computation. Stoddard & Stevens(2011) use around 750,000 points,
but more or fewer might be required depending on the
degree of overlap. |

psize |
if `type = "alpha"` and `plot = TRUE` , sets the size to plot the points
used in the Monte Carlo computation. |

lwd |
if `plot = TRUE` , sets the line width for volume grids. |

... |
additional arguments passed to the plot. See `vol()` |

## Value

a data.frame with the following columns:

`s_in1, s_in2`

the number of sampled points that fall within each of the
volumes individually.

`s_inboth`

the number of sampled points that fall within both volumes.

`s_ineither`

the number of points that fall within either of the volumes.

`psmallest`

the proportion of points that fall within both volumes divided
by the number of points that fall within the smallest volume.

`pboth`

the proportion of points that fall within both volumes divided by
the total number of points that fall within both volumes.

## References

Gruson H. 2020. Estimation of colour volumes as concave hypervolumes using
α‐shapes. Methods in
Ecology and Evolution, early view doi: 10.1111/2041-210X.13398

## Examples

#> vol1 vol2 s_in1 s_in2 s_inboth s_ineither psmallest
#> 1 5.183721e-06 6.231493e-06 5 10 1 14 0.2
#> pboth
#> 1 0.07142857

#> vol1 vol2 s_in1 s_in2 s_inboth s_ineither psmallest pboth
#> 1 0 4.684183e-06 0 4 0 4 NaN 0

#> vol1 vol2 s_in1 s_in2 s_inboth s_ineither psmallest pboth
#> 1 0 4.684183e-06 0 6 0 6 NaN 0

# }