diff --git a/NEWS.md b/NEWS.md index a50ad572f..f06158781 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# aqp 2.0 (2023-08-07) +# aqp 2.0 (2023-08-28) This is a major update to aqp that may create some issues for code depending on specific inputs/outputs in aqp < 1.42, particularly those relying on `slice()`, `slab()`, and `profile_compare()`. `slice()` and `profile_compare()` are now deprecated, but will continue to work for the rest of calendar year 2023. There are no plans to maintain these functions beyond aqp 2.0. The new version of `slab()` is a drop-in replacement for the previous version of the function. Notable changes include: diff --git a/R/colorContrast.R b/R/colorContrast.R index fd4225340..7c11bf565 100644 --- a/R/colorContrast.R +++ b/R/colorContrast.R @@ -1,6 +1,3 @@ -# compute metrics of color contrast: delta-Hue, Value, Chroma and delta-E00 -# m1: vector of Munsell colors ('10YR 3/3') -# m2: vector of Munsell colors ('10YR 3/4') #' @title Metrics of Contrast Suitable for Comparing Soil Colors #' @@ -14,25 +11,20 @@ #' #' The most meaningful representation of color contrast is the CIE2000 (dE00) metric. #' -#' @return -#' A `data.frame` with the following columns: +#' @return `data.frame` with the following columns: #' -#' \itemize{ -#' \item{m1: }{Munsell color 1} -#' \item{m2: }{Munsell color 2} -#' \item{dH: }{delta-hue, as computed by \code{huePosition}} -#' \item{dV: }{delta-value, absolute value of difference in Munsell value (m1 vs. m2)} -#' \item{dc: }{delta-chroma, absolute value of difference in Munsell chroma (m1 vs. m2)} -#' \item{dE00: }{delta-E00, e.g. the [CIE delta-E as refined in 2000](https://en.wikipedia.org/wiki/Color_difference#CIEDE2000)} -#' \item{cc: }{soil color contrast class, as specified in Soil Survey Technical Note 2 [wayback machine URL](https://web.archive.org/web/20220704214918/https://www.nrcs.usda.gov/wps/portal/nrcs/detail/soils/ref/?cid=nrcs142p2_053569)} -#' } +#' * m1: Munsell color 1 +#' * m2: Munsell color 2 +#' * dH: delta-hue, as computed by `huePosition` +#' * dV: delta-value, absolute value of difference in Munsell value (m1 vs. m2) +#' * dc: delta-chroma, absolute value of difference in Munsell chroma (m1 vs. m2) +#' * dE00: delta-E00, e.g. the [CIE delta-E as refined in 2000](https://en.wikipedia.org/wiki/Color_difference#CIEDE2000) +#' * cc: soil color contrast class, as specified in Soil Survey Technical Note 2. #' #' @references #' #' 1. https://en.wikipedia.org/wiki/Color_difference #' -#' 2. Soil Survey Technical Note 2 [wayback machine URL](https://web.archive.org/web/20220704214918/https://www.nrcs.usda.gov/wps/portal/nrcs/detail/soils/ref/?cid=nrcs142p2_053569) -#' #' @author D.E. Beaudette #' #' @note delta-E00 is computed by the \href{https://CRAN.R-project.org/package=farver}{farver package}. diff --git a/R/colorContrastPlot.R b/R/colorContrastPlot.R index 6b194e13c..06c1c5712 100644 --- a/R/colorContrastPlot.R +++ b/R/colorContrastPlot.R @@ -1,22 +1,13 @@ -## quickly display two sets of colors and soil color contrast metrics -# m1: munsell colors -# m2: munsell colors -# col.cex: scaling for color labels -# col.font: font for color labels -# d.cex: scaling for contrast metric labels -# cc.font: font for contrast class -# dE00.font: font for delta-E00 label -# labels: vector of labels for colors being compared -# printMetrics: add contrast metrics -# \dots{}: further arguments passed to colorspace::swatchplot -#' Color Contrast Plot + #' -#' A simple display of two sets of colors, NCSS color contrast class and CIE -#' delta-E00. +#' @title Color Contrast Plot #' -#' This function requires the \code{farver} package for calculation of CIE -#' delta-E00 +#' @description A simple display of two sets of colors, NCSS color contrast class and CIE +#' delta-E00. +#' +#' @note This function requires the `farver` package for calculation of CIE +#' delta-E00. #' #' @param m1 first set of Munsell colors for comparison (e.g. '5YR 3/2') #' @param m2 second set of Munsell colors for comparison @@ -29,9 +20,9 @@ #' @param label.cex scaling factor for labels #' @param label.font font for labels #' @param printMetrics logical, print metrics between color swatches -#' @param \dots further arguments to \code{colorspace::swatchplot} +#' @param \dots further arguments to `colorspace::swatchplot` #' @author D.E. Beaudette -#' @seealso \code{\link{colorContrast}} +#' @seealso [colorContrast()] #' @keywords hplots #' @export #' @examples diff --git a/R/mixMunsell.R b/R/mixMunsell.R index 371d761a2..7e93c2bc1 100644 --- a/R/mixMunsell.R +++ b/R/mixMunsell.R @@ -153,6 +153,8 @@ #' #' #' @details +#' See the [expanded tutorial](https://ncss-tech.github.io/AQP/aqp/mix-colors.html) for examples. +#' #' An accurate simulation of pigment mixtures ("subtractive" color mixtures) is incredibly complex due to factors that aren't easily measured or controlled: pigment solubility, pigment particle size distribution, water content, substrate composition, and physical obstruction to name a few. That said, it is possible to simulate reasonable, subtractive color mixtures given a reference spectra library (350-800nm) and some assumptions about pigment qualities and lighting. For the purposes of estimating a mixture of soil colors (these are pigments after all) we can relax these assumptions and assume a standard light source. The only missing piece is the spectral library for all Munsell chips in our color books. #' #' Thankfully, [Scott Burns has outlined the entire process](https://arxiv.org/ftp/arxiv/papers/1710/1710.06364.pdf), and Paul Centore has provided a Munsell color chip [reflectance spectra library](https://www.munsellcolourscienceforpainters.com). The estimation of a subtractive mixture of soil colors can proceed as follows: @@ -190,26 +192,6 @@ #' #' @seealso [munsell.spectra] #' @export -#' @examples -#' -#' # keep examples from using more than 2 cores -#' data.table::setDTthreads(Sys.getenv("OMP_THREAD_LIMIT", unset = 2)) -#' -#' # try a couple different methods -#' cols <- c('10YR 6/2', '5YR 5/6', '10B 4/4') -#' if(requireNamespace("gower")) { -#' mixMunsell(cols, mixingMethod = 'reference') -#' } -#' mixMunsell(cols, mixingMethod = 'exact') -#' mixMunsell(cols, mixingMethod = 'estimate') -#' -#' # 2.5 values -#' cols <- c('10YR 2.5/2', '5YR 5/6') -#' if(requireNamespace("gower")) { -#' mixMunsell(cols, mixingMethod = 'reference') -#' } -#' mixMunsell(cols, mixingMethod = 'exact') -#' mixMunsell(cols, mixingMethod = 'estimate') #' mixMunsell <- function(x, w = rep(1, times = length(x)) / length(x), mixingMethod = c('exact', 'reference', 'estimate', 'adaptive'), n = 1, keepMixedSpec = FALSE, distThreshold = 0.025, ...) { diff --git a/R/plotColorMixture.R b/R/plotColorMixture.R index 3ec7f6955..52867f62c 100644 --- a/R/plotColorMixture.R +++ b/R/plotColorMixture.R @@ -3,7 +3,7 @@ #' #' @description Lattice visualization demonstrating subtractive mixtures of colors in Munsell notation and associated spectra. #' -#' @details If present, `names` attribute of `x` is used for the figure legend. +#' @details If present, `names` attribute of `x` is used for the figure legend. See the [expanded tutorial](https://ncss-tech.github.io/AQP/aqp/mix-colors.html) for examples. #' #' @author D.E. Beaudette #' @@ -32,37 +32,6 @@ #' @seealso [mixMunsell()] #' @export #' -#' @examples -#' -#' # keep examples from using more than 2 cores -#' data.table::setDTthreads(Sys.getenv("OMP_THREAD_LIMIT", unset = 2)) -#' -#' # color chips -#' chips <- c('5B 5/10', '5Y 8/8') -#' names(chips) <- chips -#' -#' # weights -#' wt <- c(1, 1) -#' -#' if(requireNamespace("gower")) { -#' plotColorMixture( -#' x = chips, -#' w = wt, -#' label.cex = 0.65, -#' showMixedSpec = TRUE, -#' mixingMethod = 'reference' -#' ) -#' -#'} -#' -#' -#' plotColorMixture( -#' x = chips, -#' w = wt, -#' label.cex = 0.65, -#' mixingMethod = 'exact' -#' ) -#' plotColorMixture <- function(x, w = rep(1, times = length(x)) / length(x), mixingMethod = c('exact', 'reference'), n = 1, swatch.cex = 1.5, label.cex = 0.85, showMixedSpec = FALSE, overlapFix = TRUE) { # TODO plot will be incorrect if duplicate Munsell chips are specified diff --git a/R/spec2Munsell.R b/R/spec2Munsell.R index d254dfc21..9cf656376 100644 --- a/R/spec2Munsell.R +++ b/R/spec2Munsell.R @@ -7,6 +7,9 @@ ## TODO: allow for more flexibility in spectra min/max/res wavelength #' @title Convert reflectance spectra to closest Munsell chip +#' +#' @details See the [expanded tutorial](https://ncss-tech.github.io/AQP/aqp/mix-colors.html) for additional examples. +#' #' @param x reflectance spectra, must range from 380nm to 730nm with resolution specified in `res` #' #' @param res spectra resolution in nm, typically 5nm or 10nm @@ -61,6 +64,7 @@ #' labels = c('original', 'spectral\ninterpretation') #' ) #' +#' \dontrun{ #' if(requireNamespace("gower")) { #' # mix colors, return spectra, convert to color #' cols <- c('10YR 6/2', '5YR 5/6', '10B 4/4') @@ -71,6 +75,7 @@ #' spec2Munsell(res$spec) #' #' } +#' } #' spec2Munsell <- function(x, res = 10, convert = TRUE, SO = c('CIE1931', 'CIE1964'), illuminant = c('D65', 'F2'), ...) { diff --git a/man/colorContrast.Rd b/man/colorContrast.Rd index 07746c502..4d2f8b96e 100644 --- a/man/colorContrast.Rd +++ b/man/colorContrast.Rd @@ -12,16 +12,15 @@ colorContrast(m1, m2) \item{m2}{vector of Munsell colors ('10YR 3/6')} } \value{ -A \code{data.frame} with the following columns: - +\code{data.frame} with the following columns: \itemize{ -\item{m1: }{Munsell color 1} -\item{m2: }{Munsell color 2} -\item{dH: }{delta-hue, as computed by \code{huePosition}} -\item{dV: }{delta-value, absolute value of difference in Munsell value (m1 vs. m2)} -\item{dc: }{delta-chroma, absolute value of difference in Munsell chroma (m1 vs. m2)} -\item{dE00: }{delta-E00, e.g. the \href{https://en.wikipedia.org/wiki/Color_difference#CIEDE2000}{CIE delta-E as refined in 2000}} -\item{cc: }{soil color contrast class, as specified in Soil Survey Technical Note 2 \href{https://web.archive.org/web/20220704214918/https://www.nrcs.usda.gov/wps/portal/nrcs/detail/soils/ref/?cid=nrcs142p2_053569}{wayback machine URL}} +\item m1: Munsell color 1 +\item m2: Munsell color 2 +\item dH: delta-hue, as computed by \code{huePosition} +\item dV: delta-value, absolute value of difference in Munsell value (m1 vs. m2) +\item dc: delta-chroma, absolute value of difference in Munsell chroma (m1 vs. m2) +\item dE00: delta-E00, e.g. the \href{https://en.wikipedia.org/wiki/Color_difference#CIEDE2000}{CIE delta-E as refined in 2000} +\item cc: soil color contrast class, as specified in Soil Survey Technical Note 2. } } \description{ @@ -73,7 +72,6 @@ colorContrast(m1, m2) \references{ \enumerate{ \item https://en.wikipedia.org/wiki/Color_difference -\item Soil Survey Technical Note 2 \href{https://web.archive.org/web/20220704214918/https://www.nrcs.usda.gov/wps/portal/nrcs/detail/soils/ref/?cid=nrcs142p2_053569}{wayback machine URL} } } \seealso{ diff --git a/man/colorContrastPlot.Rd b/man/colorContrastPlot.Rd index 2e4e46572..d9af37606 100644 --- a/man/colorContrastPlot.Rd +++ b/man/colorContrastPlot.Rd @@ -48,9 +48,9 @@ colorContrastPlot( A simple display of two sets of colors, NCSS color contrast class and CIE delta-E00. } -\details{ +\note{ This function requires the \code{farver} package for calculation of CIE -delta-E00 +delta-E00. } \examples{ @@ -69,7 +69,7 @@ colorContrastPlot(m1, m2) } \seealso{ -\code{\link{colorContrast}} +\code{\link[=colorContrast]{colorContrast()}} } \author{ D.E. Beaudette diff --git a/man/mixMunsell.Rd b/man/mixMunsell.Rd index 2df2ad2ce..a83328404 100644 --- a/man/mixMunsell.Rd +++ b/man/mixMunsell.Rd @@ -54,6 +54,8 @@ When \code{keepMixedSpec = TRUE} then a \code{list}: Simulate mixing of colors in Munsell notation, similar to the way in which mixtures of pigments operate. } \details{ +See the \href{https://ncss-tech.github.io/AQP/aqp/mix-colors.html}{expanded tutorial} for examples. + An accurate simulation of pigment mixtures ("subtractive" color mixtures) is incredibly complex due to factors that aren't easily measured or controlled: pigment solubility, pigment particle size distribution, water content, substrate composition, and physical obstruction to name a few. That said, it is possible to simulate reasonable, subtractive color mixtures given a reference spectra library (350-800nm) and some assumptions about pigment qualities and lighting. For the purposes of estimating a mixture of soil colors (these are pigments after all) we can relax these assumptions and assume a standard light source. The only missing piece is the spectral library for all Munsell chips in our color books. Thankfully, \href{https://arxiv.org/ftp/arxiv/papers/1710/1710.06364.pdf}{Scott Burns has outlined the entire process}, and Paul Centore has provided a Munsell color chip \href{https://www.munsellcolourscienceforpainters.com}{reflectance spectra library}. The estimation of a subtractive mixture of soil colors can proceed as follows: @@ -80,28 +82,6 @@ Key assumptions include: For the purposes of estimating (for example) a "mixed soil color within the top 18cm of soil" these assumptions are usually valid. Again, these are estimates that are ultimately "snapped" to the nearest chip and not do not need to approach the accuracy of paint-matching systems. A message is printed when \code{scaledDistance} is larger than 1. -} -\examples{ - -# keep examples from using more than 2 cores -data.table::setDTthreads(Sys.getenv("OMP_THREAD_LIMIT", unset = 2)) - -# try a couple different methods -cols <- c('10YR 6/2', '5YR 5/6', '10B 4/4') -if(requireNamespace("gower")) { -mixMunsell(cols, mixingMethod = 'reference') -} -mixMunsell(cols, mixingMethod = 'exact') -mixMunsell(cols, mixingMethod = 'estimate') - -# 2.5 values -cols <- c('10YR 2.5/2', '5YR 5/6') -if(requireNamespace("gower")) { -mixMunsell(cols, mixingMethod = 'reference') -} -mixMunsell(cols, mixingMethod = 'exact') -mixMunsell(cols, mixingMethod = 'estimate') - } \references{ Marcus, R.T. (1998). The Measurement of Color. In K. Nassau (Ed.), Color for Science, Art, and Technology (pp. 32-96). North-Holland. diff --git a/man/plotColorMixture.Rd b/man/plotColorMixture.Rd index 7fb8e5176..9e42f7995 100644 --- a/man/plotColorMixture.Rd +++ b/man/plotColorMixture.Rd @@ -43,39 +43,7 @@ a \code{lattice} graphics object Lattice visualization demonstrating subtractive mixtures of colors in Munsell notation and associated spectra. } \details{ -If present, \code{names} attribute of \code{x} is used for the figure legend. -} -\examples{ - -# keep examples from using more than 2 cores -data.table::setDTthreads(Sys.getenv("OMP_THREAD_LIMIT", unset = 2)) - -# color chips -chips <- c('5B 5/10', '5Y 8/8') -names(chips) <- chips - -# weights -wt <- c(1, 1) - -if(requireNamespace("gower")) { -plotColorMixture( -x = chips, -w = wt, -label.cex = 0.65, -showMixedSpec = TRUE, -mixingMethod = 'reference' -) - -} - - -plotColorMixture( - x = chips, - w = wt, - label.cex = 0.65, - mixingMethod = 'exact' -) - +If present, \code{names} attribute of \code{x} is used for the figure legend. See the \href{https://ncss-tech.github.io/AQP/aqp/mix-colors.html}{expanded tutorial} for examples. } \seealso{ \code{\link[=mixMunsell]{mixMunsell()}} diff --git a/man/spec2Munsell.Rd b/man/spec2Munsell.Rd index cff538ae8..66ac8ca25 100644 --- a/man/spec2Munsell.Rd +++ b/man/spec2Munsell.Rd @@ -36,6 +36,9 @@ output from \code{\link[=rgb2munsell]{rgb2munsell()}} \description{ Convert reflectance spectra to closest Munsell chip } +\details{ +See the \href{https://ncss-tech.github.io/AQP/aqp/mix-colors.html}{expanded tutorial} for additional examples. +} \examples{ # Munsell reference spectra @@ -66,6 +69,7 @@ colorContrastPlot( labels = c('original', 'spectral\ninterpretation') ) +\dontrun{ if(requireNamespace("gower")) { # mix colors, return spectra, convert to color cols <- c('10YR 6/2', '5YR 5/6', '10B 4/4') @@ -75,6 +79,7 @@ res <- mixMunsell(cols, keepMixedSpec = TRUE, mixingMethod = 'reference') res$mixed spec2Munsell(res$spec) +} } }