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.
| 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 |
| 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 |
| 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 |
| 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 |
| 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. |
| 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 |
| 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 |
| 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) |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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) |