The Munsell and Kubelka-Munk Toolbox

by Paul Centore

© September 30, 2017 (launched Oct. 20, 2010)



The Munsell and Kubelka-Munk Toolbox is a set of open-source Octave/MATLAB routines, that perform computations involving the Munsell colour system and the Kubelka-Munk mixture model, as well as computations for many other areas of colour science. Since they are open-source code, other investigators are encouraged to check and modify them as needed, and use them for further research, with the understanding that any modifications and extensions will likewise be made freely available. Each file contains a revision date at the end of the initial comments, for comparison with earlier versions if desired.

All the data files and routines have been archived and compressed into the file MunsellAndKubelkaMunkToolboxSept2017.zip, which can be downloaded and unzipped. Earlier toolboxes, such as MunsellConversionsMay2012 and MunsellToolboxApril2013, have been subsumed verbatim, excepting a few documentation updates, into MunsellAndKubelkaMunkToolboxSept2017. Some of the routines are taken from other open-source software projects. The code here was developed in Octave (download here), which is a freely available open source clone of MATLAB. Zsolt Kovacs has tested some of the earlier code in MATLAB, so that it runs under either program.

The files are listed in the tables below, and their text can be accessed by clicking on the highlighted links. There is a table of .mat files, which contain data structures in a binary format, that MATLAB or Octave can read. If there is difficulty with reading a downloaded .mat file, that file can be created directly by running the .m routine with the same name. While Octave can generally read .mat files created in MATLAB, MATLAB could not read some of the .mat files created in Octave.

The routines in this toolbox were created to achieve three major goals: to convert between CIE and Munsell coordinates, to reproduce colours via a printer at home, and to implement the Kubelka-Munk colorant mixing model. Some of these routines are so narrowly tailored to these goals that they would not be of much use for other purposes. Other routines help in the main goals, but would also be of general use. The tables reflect these distinctions. Routines of general application are further subdivided, into conversion routines, color matching routines, and so on. The X-Rite ColorMunki Design spectrophotometer, and the X-Rite i1Pro2 spectrophotometer (along with an automatic scanning table) were used in the development, so there is a table for routines that handle their output files.

The toolbox is continually expanding beyond its original outlines, and becoming something of a general colour science toolbox. For instance, routines dealing with electronic displays, the Pointer gamut, and the ISCC-NBS system have been added as needed, when those subjects became of interest. In the long term, it might morph into an all-purpose colour toolbox, perhaps in combination with other related open-source toolboxes.



Primary Routines
MunsellToxyY.m Expresses a Munsell specification in xyY coordinates, by interpolation over the 1943 renotation
xyYtoMunsell.m This inverse Munsell renotation expresses an xyY triple as a Munsell specification
PrintReproductionsOfColours.m Finds the RGBs that produce input CIE coordinates (for an input illuminant and observer), when printed with a specific printer-ink-paper combination


General Routines: Conversions
MunsellValueToLuminanceFactor.m Converts between a Munsell value and a luminance factor, using the 1943 quintic, CIELAB, and ASTM D 1535-08
LuminanceFactorToMunsellValue.m
xyY2XYZ.m Converts between CIE xyY and XYZ coordinates
XYZ2xyY.m
MunsellTosRGB.m Converts between Munsell specifications and sRGB coordinates
sRGBtoMunsell.m
DmaxOrDminToMunsellValue.m Converts between Munsell values and printer's D-values
MunsellValueToDmaxOrDmin.m
ReflectanceSpectrumToMunsellAndCIE.m Expresses a reflectance spectrum in CIE and/or Munsell coordinates
SpectralPowerDensityToXYZ.m Finds CIE XYZ coordinates for a self-luminous stimulus
MunsellHueToASTMHue.m Converts between a Munsell hue and an ASTM hue, which is a number between 0 and 100 (e.g. 3.4RP becomes 93.4)
ASTMHueToMunsellHue.m
XYZ2RGBapplergbD65.m Sets RGB coordinates on Apple computer for given CIE XYZ coordinates


Operations on Munsell Specifications
MunsellSpecToColorLabFormat.m Converts between a colour's Munsell specification (as a character string) and an internal ColorLab format
ColorLabFormatToMunsellSpec.m
HueStringFromMunsellSpec.m Extracts a hue string from a complete Munsell string (e.g. 2.5GY from 2.5GY 7.1/3.8)
HuePrefixAndLetterFromHueString.m Extracts a numerical hue prefix and the hue designator from a hue string (e.g. 2.5GY becomes 2.5 and GY)
ASTMHuesOfMunsellSpecifications.m Finds the hue, as a number between 0 and 100, of a colour in Munsell notation
ValuesAndChromasOfMunsellSpecifications.m Finds the Munsell value and chroma of a colour in Munsell notation
ValueChromaAndASTMHueToMunsellSpec.m Makes a Munsell specification from a value, a chroma, and a hue (given in ASTM form)
DE00BetweenTwoMunsellSpecifications.m Finds the perceptual distance between two Munsell specifications
OrderMunsellSpecifications.m Orders a set of colours in Munsell notation by hue, then value, then chroma
CheckIfMunsellSpecificationsAreNeutrals.m Determines whether colours in Munsell notation are achromatic
MunsellSpecificationsInMunsellTree.m Converts a Munsell specification, like 5G 3/6, to Cartesian coordinates in the Munsell tree
MunsellTreeToMunsellSpecifications.m Converts Cartesian coordinates in the Munsell tree to standard Munsell specifications
FormatMunsellSpec.m Formats a Munsell notation, with the numbers of decimal places as inputs


General Routines: Colour Matching
EvaluateAttemptedMatches.m Compares a set of colour samples against a set of colour aimpoints
FindBestMatchForMunsell.m Finds which colour sample in a set best matches an aimpoint, expressed in Munsell or xyY coordinates
FindBestMatchforxyY.m
EvaluateDEsToReflectanceSpectra.m Finds which colour sample in a set of reflectance spectra best matches an aimpoint, expressed in XYZ coordinates or as a reflectance spectrum. Different illuminants can be used
EvaluateDEsToReflectanceSpectraMultiIllum.m
EvaluateDEsToShadeBankFile.m Evaluates all potential RGB matches for an input XYZ colour, from the RGBs' reflectance spectra in a shade bank file, for an input illuminant and observer
EvaluateMultipleAimpointDEsToShadeBankFile.m Finds the best RGB matches for multiple input XYZ colours, from the RGBs' reflectance spectra in a shade bank file, for an input illuminant and observer
InterpolateLinearlyOverShadeBank.m Interpolates over a shade bank, that converts RGBs to CIE coordinates, to find the best match in the shade bank for input CIE specifications


Other General Routines
CIEDE2000ForxyY.m Finds the CIE DE 2000 difference between two stimuli in xyY or XYZ coordinates
CIEDE2000ForXYZ.m
PlotIlluminants.m Draws plots of standard illuminants
ChromaticityOfWhitePoint.m Finds CIE xy coordinates for the white point for an input illuminant and observer
WhitePointWithYEqualTo100.m Finds CIE XYZ coordinates for the perfect diffuse reflector, for an input illuminant and observer
ReflectancesToCIEwithWhiteY100.m Finds CIE xyY and XYZ coordinates for input reflectance spectra, relative to an input illuminant and observer
DrawMunsellHueSheet.m Draws the Munsell colours of one hue; works for nonstandard hues, such as 6.4PB, 9Y, etc.
PrintMunsellHueSheetFromMunsellRGBList.m Prints the Munsell colours of one hue, reading RGBs from an input file
IsWithinMacAdamLimits.m Determines whether an xyY triple is within the MacAdam limits, for a user-input illuminant
ShadowSeriesInMunsellSystem.m Calculates a shadow series in Munsell coordinates
MunsellAnalysisOfColourSet.m Produces histograms and tables of Munsell hues, values, and chromas, from a set of colours, given either in Munsell coordinates, or as reflectance spectra
MunsellAnalysisOfReflectanceSpectraFile.m
DescriptiveFileForReflectanceSpectra.m Uses Munsell, ISCC-NBS, and sRGB coordinates to describe an input set of reflectance spectra
PrintRGBs.m Prints a set of RGBs, to be measured by a spectrophotometer
DrawMetamerMismatchBody.m Finds and displays a metamer mismatch body for two sensing devices (including the human visual system) or one device with two different illuminants, when given a particular output for one device.


Kubelka-Munk Routines
EstimateConcentrations.m Uses the Kubelka-Munk model to estimate the concentrations of colorants, with known K's and S's, in a mixture.
The calculation uses a GJK-based algorithm to solve a least squares problem
KSandConcentrationsFromMixtures.m Uses the Kubelka-Munk model to estimate both the concentrations of colorants in mixtures, and the K's and S's for the colorants.
The calculation assumes the concentrations are known approximately at the start, but likely contain some error
KandSfromMixtures.m Calculates K and S for a set of colorants from the reflectance spectra of mixtures of those colorants at known concentrations. These
differ from the following algorithms by using a GJK-based approach rather than standard least squares methods
KandSusingGJK.m
KandSfromMixturesWalowit1987.m Calculates K and S for a set of colorants from the reflectance spectra of mixtures of those colorants at known concentrations. The
2013 algorithm weights least-squares residuals differently from the 1987 algorithm
KandSfromMixturesCentore2013.m
KoverSfromMasstoneR.m Finds K/S (absorption/scattering coefficient) as a function of bulk reflectance R, and vice versa
MasstoneRfromKandS.m
ReflectanceOfMixtureFromKandS.m Uses the Kubelka-Munk model to calculate the reflectance spectrum of colorants with known K's and S's, at given concentrations.
The Saunderson corrrection term k_2 can be used if available
ReflectanceOfMixtureFromKandSandk2.m
SaundersonCorrection.m Converts between measured reflectance and bulk reflectance
SaundersonCorrectionInverse.m
CompareReflectanceSpectra.m Quantifies the difference, both with DE2000 and root-mean-square (RMS) error, between known and predicted reflectance curves
K1FromIndicesOfRefraction.m Calculates the percentage of light that is reflected directly by a paint film, without first entering the film


GJK Routines (used by some Kubelka-Munk algorithms)
ClosestPointInConvexPolytopeGJK.m Implements a special case of the Gilbert-Johnson-Keerthi (GJK) algorithm, which finds the
closest point in a convex polytope to an input point in the space
ClosestPointInSimplex.m Uses Johnson's sub-distance algorithm to find the closest point in a simplex to an input point
CheckNewPointMakesSimplex.m A helper routine for the GJK algorithm, used when expanding a simplex whose vertices
are a subset of the generating points for a convex polytope
lsqnonnegGJK.m Implementations of a GJK-based algorithm for two problems in constrained least squares
(non-negative least squares (NNLS) and bounded variables least squares (BVLS))
BoundedVariablesLeastSquares0to1GJK.m


ISCC-NBS Colour System Routines
ISCCNBSnameFromNumber.m Finds the ISCC-NBS system name (e.g. light purplish pink), when given an ISCC-NBS level and number (in this case: Level 3, Number 249)
MunsellToISCCNBS.m Finds the ISCC-NBS name for a Munsell notation (e.g. 5R 4/6 is grayish red)
sRGBtoISCCNBS.m Converts an sRGB triplet (e.g. [172,38,208]) to an ISCC-NBS name (in this case: vivid purple)


Spectrophotometer Routines
MeanColourDifferenceFromTheMean.m Calculates the mean colour difference from the mean (MCDM) for a single sample,
measured repeatedly over a short time span with the same spectrophotometer
MCDMsFromMultipleSamples.m Calculates the MCDMs for several samples, instead of just one
BestMatchInColorMunkiCSVfile.m Finds the colour closest to a desired Munsell specification, in a set of ColorMunki measurements
CompareDuplicateColorMunkiMeasurements.m Calculates CIE DE 2000 differences between two ColorMunki measurements of the same samples, to evaluate consistency
AverageColorMunkiCSVFiles.m Averages multiple reflectance measurements of the same set of samples, to reduce measurement error
Averagei1i02txtFiles.m Averages multiple reflectance measurements of the same set of samples, measured by an i1iO2 AST
ConcatenateColorMunkiCSVFiles.m Concatenates two sets of ColorMunki measurements, of multiple different sets of samples
i1i02txtFileToColorMunkiCSVFormat.m Converts an i1i0 output file to a ColorMunki .csv file
ColorMunkiCSVfileToOctaveFormat.m Converts ColorMunki measurements into reflectance spectra in a vector format understood by Octave
OctaveFormatToColorMunkiCSVfile.m Saves an Octave matrix of reflectances as a file in ColorMunki .csv format


Electronic Displays
DisplayGamutFromPrimaries.m Draws a display gamut in CIE XYZ space, for three-primary or multi-primary displays
ConstructPositiveZonohedron.m A display gamut is a positive zonohedron, so this routine helps in drawing a gamut
ConstructCyclicZonohedron.m Use an easily-constructed table to calculate a cyclic zonohedron
CombinatorialStructureOfCyclicZonohedron.m Find the vertex-edge-face structure for a cyclic zonohedron
AllParallelepipedsInZonohedron.m Another helper routine, to be used when drawing a gamut
AnalyzeSensorResponses.m Calculates and displays geometric constructions, based on an RGB camera's response curves
ReflectanceSpectrumTosRGB.m Find the sRGB coordinates that match an input reflectance spectrum, when viewed under Illuminant D65


Specialized Routines: Renotation Inversion
CIELABtoApproxMunsellSpec.m Converts CIELab coordinates into an approximate Munsell specification
DrawRenotationFigure.m Plots Munsell hue and chroma in chromaticity diagrams; works for non-integer Munsell values, such as 7.8, 1.3, etc.
MaxChromaForExtrapolatedRenotation.m Finds the maximum chromas for which Munsell renotations can be interpolated
MunsellHueToChromDiagHueAngle.m Fixes a consistent conversion between Munsell hue and angle in the chromaticity diagram
ChromDiagHueAngleToMunsellHue.m
MunsellToxyYfromExtrapolatedRenotation.m The inverse renotation, extended beyond the MacAdam limits
MunsellToxyForIntegerMunsellValue.m The inverse renotation, restricted to integer Munsell values
FindHueOnRenotationOvoid.m Locates a particular hue on a chroma ovoid in a Munsell renotation figure
LinearVsRadialInterpOnRenotationOvoid.m Determines how to interpolate over segments of chroma ovoids in renotation figures
MakeMaximumChromaMatrix.m Makes matrix of maximum chromas, as function of Munsell hues and values
BoundingRenotationHues.m Bounds arbitrary hue between standard hues, e.g. 4.6B is between 2.5B and 5B
MaxChromaForMunsellHueAndValue.m Finds maximum chroma, for input Munsell hue and value
MakeMaxExtRenChromaMatrix.m Makes MaxChromaForExtrapolatedRenotation.mat
MakeExtrapolatedRenotationMatrices.m Makes ExtrapolatedRenotationMatrices.mat
MakeRenotationMatrices.m Makes RenotationMatrices.mat
MakeRenotationMacAdamLimitMatrix.m Makes MaxChromasInRenotationData.mat


Specialized Routines: Colour Reproductions with a Printer
PrintDryingTimeTestPage.m Makes a page with 64 colours that span the printing gamut, for testing the drying time of printouts
PrintRGBmatchesWithDEs.m Print the best RGBs for an attempted set of matches, along with the DE that each achieved
CompileMunsellBook.m Constructs hue leaves and assembles them into a Munsell book
ProcessInitialShadeBankFile.m Converts a file listing of reflectance spectra for RGBs into a .csv file in ColorMunki format
ConsolidateShadeBankFile.m Removes repeated entries from a shade bank. A set of repeated entries for the
same RGB is replaced with the averaged reflectances of the repeated entries
MakeFineRGBGridAroundTarget.m Prints and measures a large set of RGBs, that are near an input target
DisplayEdgeLengthsOfTessellation.m Makes a histogram of the lengths (in CIE DE 2000) of the edges in a tetrahedral tessellation
InterpolateForAimPoints.m Linearly interpolates over a tetrahedral tessellation, to estimate RGBs for aimpoints in Lab coordinates
NewLabVerticesInTessellation.m Constructs tetrahedra around aimpoints


Data Files
InverseRenotation.txt A text file, suitable for computer programs, of inverted Munsell renotation data
MunsellRenotation.txt The 1943 Munsell renotation data, from Newhall, Nickerson, & Judd
MunsellRenotationTosRGB.txt Conversion tables between Munsell colours and sRGB coordinates
sRGBToMunsell.txt
ExtrapolatedMunsellRenotation.txt A version of the file all.dat from the Munsell Color Science Laboratory
MacAdamLimitsFromRenotationData.txt A list of the maximum chromas in the 1943 Munsell renotation data
MaxChromaFromExtrapRenotationData.txt A listing of the maximum chromas in the file all.dat from the Munsell Color Science Laboratory
MaxChromasForStandardMunsellHuesAndValues.txt A list of maximum chromas for the Munsell system
IlluminantC.txt Power spectral densities for Illuminants C and D50
IlluminantD50.txt
1931ColourMatchingFunctions.txt The standard CIE colour-matching functions (2 deg)
1931ColourMatchingFunctions.mat
OptimalColoursForIlluminantC.txt The list from MacAdam's 1935 paper
OptimalColoursForIlluminantD65.txt The list from Wyszecki & Stiles
MaxChromaForExtrapolatedRenotation.mat These are .mat versions of data, to be read directly by MATLAB or Octave. If there is difficulty
reading them, try remaking them with the .m routines, Make***.m, of similar names.
ExtrapolatedRenotationMatrices.mat
MaxChromasInRenotationData.mat
RenotationMatrices.mat
Pointer1980TableII.txt The bounding vertices of the Pointer gamut in Lch coordinates, from Pointer's 1980 paper
PointerGamutInMunsellSpace.txt The bounding vertices of the Pointer gamut, as Munsell specifications
ISCCNBSDesignators.txt ISCC-NBS names, such as light purplish pink, for ISCC-NBS levels and numbers (in this case: Level 3, Number 249)
MunsellCentroidsForISCCNBS.txt Kelly's 1958 centroids for the ISCC-NBS Level 3 categories, in Munsell notation
sRGBCentroidsForISCCNBS.txt sRGB centroids (calculated in 2016) for the ISCC-NBS categories at all three levels
sRGBToMunsellAndISCCNBS.txt.zip A long list (over 135,00 entries) of sRGB triples, and their corresponding Munsell notations and ISCC-NBS names


Routines from Elsewhere
isdigit.m These routines are included in Octave, but not in (the basic version of) MATLAB
cart2bary.m
ols.m
xyz2lab.m Converts between CIE XYZ coordinates and CIE Lab coordinates (from Colorlab)
lab2xyz.m
lab2perc.m Extracts hue and chroma correlates from CIE Lab coordinates (from Colorlab)
FromOptProp Contains 31 routines, mostly dealing with illuminants, from Jerker Wagberg's optprop program. Some routines were modified slightly for compatibility with Octave
PreferenceFiles Contains 4 routines for Octave settings; these routines are in later versions of Octave, but not in earlier versions
deltaE2000.m Finds CIE DE 2000 difference between two stimuli in Lab coordinates (from Gaurav Sharma)
srgb2xyz.m Converts between CIE XYZ coordinates and sRGB (code, with some revisions, from the
Computational Colour Toolbox v1.3, by Stephen Westland, Caterina Ripamonti, and Vien Cheung)
xyz2srgb.m
combinator.m Routines for combinatorial calculations
combn.m
nchoose.m
ply_write.m Expresses a 3-d object in .ply format (written by Pascal Getreuer in 2004)


Site Map
Applications To Art Colour Science
Colour Tools For Painters The Geometry of Colour
Munsell Colour System Colour Science Papers
An Affordable Munsell Book The Munsell and Kubelka-Munk Toolbox
A Munsell-Accurate Value Scale Munsell Resources
Colour Analysis of Pastels
The ISCC-NBS Colour System