% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spectra-munsell.R
\name{predict_munsell_from_spectra}
\alias{predict_munsell_from_spectra}
\title{Predict Munsell hue / value / chroma from Vis-NIR reflectance spectra}
\usage{
predict_munsell_from_spectra(spectra, wavelengths, round_chip = TRUE)
}
\arguments{
\item{spectra}{Reflectance values, in 0..1 or 0..100. A numeric
vector (one sample), a numeric matrix (rows = samples,
cols = wavelengths) or a data.frame.}

\item{wavelengths}{Numeric vector of the wavelengths (in nm)
corresponding to the columns of \code{spectra}. Must cover
at least 400-700 nm; values outside 380-780 are ignored.}

\item{round_chip}{If \code{TRUE} (default), snaps the predicted
HVC to the nearest standard Munsell chip grid via
\code{munsellinterpol::roundHVC()}. \code{FALSE} returns
continuous HVC (useful for further numeric work).}
}
\value{
A data.frame with columns \code{munsell_hue_moist},
        \code{munsell_value_moist}, \code{munsell_chroma_moist},
        \code{munsell_string} (e.g. \code{"7.5YR 4/6"}),
        \code{X}, \code{Y}, \code{Z}, one row per sample.
}
\description{
Combines \code{\link{predict_xyz_from_spectra}} with the Munsell
renotation interpolation in \pkg{munsellinterpol} (CRAN, GPL).
Returns hue (e.g. \code{"7.5YR"}), value (0..10) and chroma
(0..20) per sample, plus the soilKey fields
}
\details{
The Munsell renotation is defined under \emph{Illuminant C}, while
the colorimetry here is computed under D65, so the conversion adapts
D65 -> C. It calls \code{munsellinterpol::XYZtoMunsell(XYZ, white =)}
(munsellinterpol >= 3.4-0), which performs that chromatic adaptation
internally, and falls back to the numerically identical
XYZ -> CIELAB(D65) -> \code{LabToMunsell()} route on older versions.
Feeding D65 chromaticities straight to \code{xyYtoMunsell()} (with no
\code{white}) would bias every colour toward green-yellow (a perfect
neutral would return Chroma ~ 0.65 rather than 0); this routine avoids
that. The D65 reference white is derived from the same bundled CIE
table the colorimetry integrates against (so a constant-reflectance
spectrum maps to an exact neutral, and a perfect reflecting diffuser
to Munsell value 10), and the conversion is vectorised over all rows
of \code{spectra} at once. At zero Chroma the Munsell hue is undefined,
so a neutral is reported with hue \code{"N"} in both the rounded and the
continuous (\code{round_chip = FALSE}) notation.
\code{munsell_hue_moist}, \code{munsell_value_moist},
\code{munsell_chroma_moist} ready to write into a
\code{\link{PedonRecord}} via the pedon's \code{add_measurement}
method (see also \code{\link{fill_munsell_from_spectra}}).

This is the v0.9.47 unblock for the v0.9.35 Argissolo Vermelho /
Amarelo / Vermelho-Amarelo color-confusion case: when a user has
Vis-NIR spectra (which Embrapa's BDsolos / FEBR do not include
but the OSSL does), the Munsell hue can be recovered physically
without waiting for the surveyor's morphological description.
}
\examples{
\dontrun{
# White reflector across the visible: should map to a near-neutral
# high-value Munsell color.
wl <- seq(380, 780, by = 5)
R  <- rep(0.9, length(wl))
predict_munsell_from_spectra(R, wavelengths = wl)
}
}
