Spectrum 4.0.1 User Manual

Abstract

[Thumbnail which links to a demo image] Spectrum is a library module from the Persistence of Vision Ray Tracer (POV-Ray) Object Collection for creating spectrum color maps and pigments.

Table of Contents

Overview

Downloaded Files

The italicized nnnnnn in some of the file names represents the 6-digit number that is in the name of the .zip file.

Key Files
File Description
spectrum.html The user manual (this document)
spectrum.inc The Spectrum software
spectrum.pov A demonstration scene description file
spectrum.png Sample output images
spectrum_thumbnail.png
Administrative Files
File Description
READMEnnnnnn.html Important information about using the POV-Ray Object Collection
spectrum_description.txt A brief description of Spectrum
spectrum_keywords.txt A list of keywords
spectrum_prereqs.txt Prerequisites
spectrum.css Other administrative files
cc-LGPL-a.png
Versionnnnnnn.js

Table of contents

Prerequisites

Namespace Compliance

All file names in this module and all global and local identifiers defined in spectrum.inc comply fully with the Object Collection naming standards, as revised August 2008 and proposed August 2012. The reserved prefix for this module is “Spectrum,” including any uppercase and lowercase variants. To avoid conflicts, do not introduce into your scene description file any identifiers with this name, or any identifiers that start with this prefix plus an underscore.

The identifier View_POV_Include_Stack from the standard include file debug.inc is referenced by spectrum.inc, although debug.inc itself is not used.

Spectrum reads one of the Lightsys files and references some of its identifiers. As Lightsys is not part of the Object Collection, there is no guarantee that its identifiers will not conflict with those of compliant Object Collection modules. If necessary, all of the identifiers from that file can be destroyed by macro CIE_ReleaseMemory() after all Lightsys-based spectra are defined.

Usage

Include this file once prior to using any of the features:

#include "spectrum.inc"

Including the file more than once is harmless, though unnecessary.

You will get a warning that the experimental feature spline is used. This is normal and expected.

For best results with the Lightsys-based spectra, set the assumed gamma to 1:

global_settings { assumed_gamma 1 }

Table of contents

Data Structures

Spectrum data
A two dimensional array of float. Each element of the first dimension corresponds to a wavelength. The elements of the second dimension are as follows:
[0]
The wavelength in nanometers.
[1]
The red channel value.
[2]
The green channel value.
[3]
The blue channel value.
Color maps
The domain value corresponds to the wavelength in microns.
Pigments
Pigments are gradients in the x direction. The x-coordinate corresponds to the wavelength in microns.

Table of contents

Macros

Several of these macros rely on the color system and gamut mapping settings in Lightsys IV. See readme_cie.txt in the LightsysIV folder for more information.

Lightsys IV’s default color system is appropriate for most users; you should not change it unless you know what you’re doing.

What is gamut mapping? Some colors, including pure spectral colors, cannot be represented with three primary colors. Gamut mapping is the art of choosing the best approximation for these colors. Lightsys IV’s default gamut mapping method, though it may be fine for some purposes, is not ideal for depicting spectra.

Spectrum_Lightsys_cm()

Returns a gamut-mapped color map using Lightsys IV, using the current Lightsys color system and gamut mapping method. The color map is normalized as a whole so that the maximum channel value is 1.0.

Spectrum_Lightsys_data()

Returns gamut-mapped color data from Lightsys IV, using the current Lightsys color system and gamut mapping method. The data are not normalized.

Spectrum_Lightsys_p()

Returns a gamut-mapped pigment using Lightsys IV, using the current Lightsys color system and gamut mapping method. The pigment is normalized as a whole so that the maximum channel value is 1.0.

Spectrum_Make_cm (Data)

Returns a color map derived from user-supplied spectrum data. The result is not normalized or gamut-mapped.

Argument

Formal Parameter Type Description
Data array[][4] Spectrum data.

Spectrum_Make_p (Data)

Returns a pigment derived from user-supplied spectrum data. The result is not normalized or gamut-mapped.

Argument

Formal Parameter Type Description
Data array[][4] Spectrum data.

Spectrum_Normalize (Data, Scale)

Normalizes spectrum data as a whole such that the highest channel value in the array is scaled to 1.0, then scales the data according the the given argument. The array is altered in-place, and not returned.

Argument

Formal Parameter Type Description
Data array[][4] Spectrum data.
Scale float The amount by which to scale the data after they are normalized.

Spectrum_Rule_p (Fine, c_Ink)

Returns a ruler-like pigment. The ruler is oriented in the x direction; the ticks are 1 unit apart and centered on integer positions; and the pigment is completely transparent between tick marks.

Arguments

Formal Parameter Type Description
Fine float The width of each tick mark.
c_Ink color The color of the tick marks.

Spectrum_Special_p()

Returns a pigment using Lightsys IV, using the current Lightsys color system. The pigment is gamut-mapped using a combination of methods, and normalized as a whole so that the maximum channel value is 1.0.

Warning! Spectrum_Special_p() changes the Lightsys gamut mapping method, then restores it after the pigment is defined. In order to restore the gamut mapping method, it references an undocumented variable in the Lightsys IV file CIE.inc. If this ever becomes a problem, the two lines of code in Spectrum_Special_p() that are marked with “//@@[1]” may be deleted, but then the user must remember to manually restore the gamut mapping method with CIE_GamutMapping(). The default in the current version of Lightsys IV (version 4D, March 2015) is CIE_GamutMapping (1).

Table of contents

Other Identifiers

Reference Identifiers

Identifier Type Description Value
SPECTRUM_BLUE float The wavelength, in nanometers, of the sRGB blue primary 464.3
SPECTRUM_CYAN float The wavelength, in nanometers, of the sRGB cyan with equal amounts of green and blue 491.5
SPECTRUM_GREEN float The wavelength, in nanometers, of the sRGB green primary 549.1
SPECTRUM_RED float The wavelength, in nanometers, of the sRGB red primary 611.3
SPECTRUM_VERSION float The Spectrum version, in case the scene file needs that information 4.01
SPECTRUM_YELLOW float The wavelength, in nanometers, of the sRGB yellow with equal amounts of red and green 570.5

Internal Identifiers

Any identifiers in spectrum.inc that are not documented in this manual are considered “private” or “protected,” and are subject to change or elimination in a future update.

Table of contents

About Spectrum

Copyright © 2014 – 2019 Richard Callwood III. Some rights reserved. Licensed under the Creative Commons-GNU Lesser General Public License.

Object Collection Categories

Unpublished Versions

Due to Fair Use of copyrighted material, I cannot make these versions public. This section is little more than a paper trail.

Version Date Notes
unversioned 2008 December 22
unversioned 2009 August 18
  • Two of Young’s illustrations are sampled in detail. I make no copyright claim on the derived data.
2.0 2012 October 7
  • Local variables are renamed to avoid future problems with POV-Ray’s namespace scope rules. This also brings the module into Object Collection namespace compliance.
  • Identifiers are renamed to clarify the roles of Young’s data.
  • The ability to use arbitrary spectral data is added, and with it, an interface to Lightsys IV.
2.1 2012 October 7
  • A macro is added to normalize spectrum data.
3.0 2014 January 4
  • A specially gamut-mapped Lightsys pigment is added.
  • An argument is added to adjust the brightness of the yellow in Young’s “brightest” spectrum.

Change Log

Version Date Notes
4.0 2014 January 10
  • Young’s data are removed, as I do not intend to seek authorization to publish them under the LGPL.
  • Old code, used only by my legacy scenes, is removed.
  • The wavelength unit for spectrum data is changed to nanometers. (Microns were used earlier because that unit is most convenient for color maps; but nanometers are probably better from the user point of view.)
  • The normalization macro is replaced.
4.0.1 2019 April 2
  • Some Web links are updated in this user manual.
  • The message to the debug stream stating that spectrum.inc is included is suppressed by default.

Table of contents