path: root/upstream/debian-unstable/man1/ppmcie.1

\
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
.\" the corresponding HTML page on the Netpbm website, generate a patch
.\" against that, and send it to the Netpbm maintainer.
.TH "Ppmcie User Manual" 1 "31 July 2005" "netpbm documentation"

.SH NAME

ppmcie - draw a CIE color chart as a PPM image

.UN synopsis
.SH SYNOPSIS

\fBppmcie\fP

[
\fB-rec709\fP|\fB-cie\fP|\fB-ebu\fP|\fB-hdtv\fP|\fB-ntsc\fP|\fB-smpte\fP
]
[\fB-xy\fP|\fB-upvp\fP]

[\fB-red\fP \fIrx\fP \fIry\fP]

[\fB-green\fP \fIgx\fP \fIgy\fP]

[\fB-blue\fP \fIbx\fP \fIby\fP]

[\fB-white\fP \fIwx\fP \fIwy\fP]

[\fB-size\fP \fIedge\fP]

[{\fB-xsize\fP|\fB-width\fP} \fIwidth\fP]

[{\fB-ysize\fP|\fB-height\fP} \fIheight\fP]

[\fB-noblack\fP]
[\fB-nowpoint\fP]
[\fB-nolabel\fP]
[\fB-noaxes\fP]
[\fB-full\fP]

.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.

\fBppmcie\fP creates a PPM file containing a plot of the CIE
"tongue" color chart -- to the extent possible in a PPM
image.  Alternatively, creates a pseudo-PPM image of the color tongue
using RGB values from a color system of your choice.
.PP
The CIE color tongue is an image of all the hues that can be described
by CIE X-Y chromaticity coordinates.  They are arranged on a two
dimensional coordinate plane with the X chromaticity on the horizontal
axis and the Y chromaticity on the vertical scale.  (You can choose
alternatively to use CIE u'-v' chromaticity coordinates, but the
general idea of the color tongue is the same).
.PP
Note that the PPM format specifies that the RGB values in the file are
from the ITU-R Recommendation BT.709 color system, gamma-corrected.
And positive.  See
.BR "ppm" (1)\c
\& for details.  If
you use one of the color system options on \fBppmcie\fP, what you get
is not a true PPM image, but is very similar.  If you display such
\fBppmcie\fP output using a device that expects PPM input (which
includes just about any computer graphics display program), it will
display the wrong colors.
.PP
However, you may have a device that expects one of these variations on 
PPM.
.PP
In every RGB color system you can specify, including the default
(which produces a true PPM image) there are hues in the color tongue
that can't be represented.  For example, monochromatic blue-green with 
a wavelength of 500nm cannot be represented in a PPM image.  
.PP
For these hues, \fBppmcie\fP substitutes a similar hue as follows:
They are desaturated and rendered as the shade where the edge of the
Maxwell triangle intersects a line drawn from the requested shade to
the white point defined by the color system's white point.
Furthermore, unless you specify the \fB-full\fP option, \fBppmcie\fP
reduces their intensity by 25% compared to the true hues in the image.
.PP
\fBppmcie\fP draws and labels the CIE X-Y coordinate axes unless you
choose otherwise with options.
.PP
\fBppmcie\fP draws the Maxwell triangle for the color system in use
on the color tongue.  The Maxwell triangle is the triangle whose
vertices are the primary illuminant hues for the color system.  The
hues inside the triangle show the color gamut for the color system.
They are also the only ones that are correct for the CIE X-Y
chromaticity coordinates shown.  (See explanation above).  \fBppmcie\fP
denotes the Maxwell triangle by rendering it at full brightness, while
rendering the rest of the color tongue as 3/4 brightness.  You can turn
this off with options.
.PP
\fBppmcie\fP also places a black cross at the color system's white
point (with the center of the cross open so you can actually see the
white color) and displays in text the CIE X-Y chromaticities of the
primary illuminants and white point for the color system.  You can
turn this off with options, though.
.PP
\fBppmcie\fP annotates the periphery of the color tongue with the
wavelength, in nanometers of the monochromatic hues which appear
there.
.PP
\fBppmcie\fP displays the black body chromaticity curve for Planckian
radiators from 1000 to 30000 kelvins on the image.  This curve traces the
colors of black bodies as various temperatures.
.PP
You can choose from several standard color systems, or specify one of
your own numerically.
.PP
CIE charts, by their very nature, contain a very large number of
colors.  If you're encoding the chart for a color mapped device or
file format, you'll need to use \fBpnmquant\fP or \fBppmdither\fP to
reduce the number of colors in the image.

.UN options
.SH OPTIONS
.PP
In addition to the options common to all programs based on libnetpbm
(most notably \fB-quiet\fP, see 
.UR index.html#commonoptions
 Common Options
.UE
\&), \fBppmcie\fP recognizes the following
command line options:
.PP
You may abbreviate any option to its shortest unique prefix.


.TP
\fB-rec709\fP
.TP
\fB-cie\fP
.TP
\fB-ebu\fP
.TP
\fB-hdtv\fP
.TP
\fB-ntsc\fP
.TP
\fB-smpte\fP
Select a standard color system whose gamut to plot.  The default is
\fB-rec709\fP, which chooses ITU-R Recommendation BT.709,
gamma-corrected.  This is the only color system for which
\fBppmcie\fP's output is a true PPM image.  See explanation above.
\fB-ebu\fP chooses the primaries used in the PAL and SECAM
broadcasting standards.  \fB-ntsc\fP chooses the primaries specified
by the NTSC broadcasting system (few modern monitors actually cover
this range).  \fB-smpte\fP selects the primaries recommended by the
Society of Motion Picture and Television Engineers (SMPTE) in
standards RP-37 and RP-145, and \fB-hdtv\fP uses the much broader
\fIHDTV ideal\fP primaries.  \fB-cie\fP chooses a color system that
has the largest possible gamut within the spectrum of the chart.  This
is the same color system as you get with the \fB-cie\fP option to
John Walker's \fBcietoppm\fP program.

.TP
\fB-xy\fP
plot CIE 1931 x y chromaticities.  This is the default.

.TP
\fB-upvp\fP
plot u' v' 1976 chromaticities rather than CIE 1931 x y
chromaticities.  The advantage of u' v' coordinates is that equal
intervals of distance on the u' v' plane correspond roughly to the
eye's ability to discriminate colors.

.TP
\fB-red\fP\fI rx ry\fP
specifies the CIE \fIx\fP and \fIy\fP co-ordinates of the red
illuminant of a custom color system and selects the custom system.

.TP
\fB-green\fP\fI gx gy\fP
specifies the CIE \fIx\fP and \fIy\fP co-ordinates of the green
illuminant of the color system and selects the custom system.

.TP
\fB-blue\fP\fI bx by\fP
specifies the CIE \fIx\fP and \fIy\fP co-ordinates of the blue
illuminant of the color system and selects the custom system.

.TP
\fB-white\fP\fI wx wy\fP
specifies the CIE \fIx\fP and \fIy\fP co-ordinates of the white
point of the color system and selects the custom system.

.TP
\fB-size\fP\fI edge\fP
Create an image of \fIedge\fP by \fIedge\fP pixels.  The default is
512x512.

.TP
\fB-xsize|-width\fP\fI width\fP
Sets the width of the generated image to \fIwidth\fP pixels.  The
default width is 512 pixels.  If the height and width of the image are
not the same, the CIE diagram will be stretched in the longer
dimension.

.TP
\fB-ysize|-height\fP\fI height\fP
Sets the height of the generated image to \fIheight\fP pixels.  The
default height is 512 pixels.  If the height and width of the image
are not the same, the CIE diagram will be stretched in the longer
dimension.

.TP
\fB-noblack\fP
Don't plot the black body chromaticity curve.

.TP
\fB-nowpoint\fP
Don't plot the color system's white point.

.TP
\fB-nolabel\fP
Omit the label.

.TP
\fB-noaxes\fP
Don't plot axes.

.TP
\fB-full\fP
Plot the entire CIE tongue in full brightness; don't dim the part
which is outside the gamut of the specified color system (i.e. outside
the Maxwell triangle).



.UN interpretation
.SH INTERPRETATION OF COLOR CHART
.PP
A color spectrum is a linear combination of one or more monochromatic
colors.
.PP
A color is a set of color spectra that all look the same to the
human eye (and brain).  Actually, for the purposes of the definition,
we assume the eye has infinite precision, so we can call two color
spectra different colors even though they're so close a person
couldn't possibly tell them apart.
.PP
The eye contains 3 kinds of color receptors (cones).  Each has a
different response to the various monochromatic colors.  One kind
responds most strongly to blue, another red, another green.  Because
there are only three, many different color spectra will excite the
cones at exactly the same level, so the eye cannot tell them apart.
All such spectra that excite the cones in the same way are a single
color.
.PP
Each point in the color tongue represents a unique color.  But
there are an infinite number of color spectra in the set that is that
color; i.e. an infinite number of color spectra that would look to you
like this point.  A machine could tell them apart, but you could not.
.PP
Remember that the colors outside the highlighted triangle are
approximations of the real colors because the PPM format cannot
represent them (and your display device probably cannot display them).
That is, unless you're using a variation of PPM and a special display
device, as discussed earlier in this manual.
.PP
A color is always relative to some given maximum brightness.  A
particular beam of light looks lime green if in a dim field, but
pea green if in a bright field.  An image on a movie screen may
look pitch black because the projector is not shining any light on
it, but when you turn off the projector and look at the same spot in
room light, the screen looks quite white.  The same light from that spot
hit your eye with the project on as with it off.
.PP
The chart shows two dimensions of color.  The third is intensity.
All the colors in the chart have the same intensity.  To get all
possible colors in the gamut, Make copies of the whole chart at every
intensity between zero and the maximum.
.PP
The edge of the tongue consists of all the monochromatic colors.
A monochromatic color is one with a single wavelength.  I.e. a color
that is in a rainbow.  The numbers you see are the wavelengths in
nanometers.
.PP
Any straight line segment within the tongue contains colors which
are linear combinations of two colors -- the colors at either end of
the line segment.
.PP
Any color in the chart can be created from two other colors (actually,
from any of an infinite number of pairs of other colors).
.PP
All the colors within a triangle inside the tongue can be created
from a linear combination of the colors at the vertices of that triangle.
.PP
Any color in the tongue can be created from at most 3 monochromatic
colors.
.PP
The highlighted triangle shows the colors that can be expressed
in the tristimulus color system you chose.  (ITU-R BT.709 by default).
The corners of the triangle are the 3 primary illuminants in that
system (a certain red, green, and blue for BT.709).  The edges of
the triangle, then, represent the colors you can represent with two
of the primary illuminants (saturated colors), and the interior colors
require all three primary illuminants (are not saturated).
.PP
In the ITU-R BT.709 color system (the default), the white point is
defined as D65, which is (and is named after) the color of a black
body at 6502 kelvins.  Therefore, you should see the temperature curve
on the image pass through the white part of the image, and the cross
that marks the white point, at 6502 kelvins.
.PP
D65 white is supposed to be the color of the sun.  If you have a
perfect BT.709 display device, you should see the color of the sun
at the white point cross.  That's an important color, because when you
look at an object in sunlight, the color that reflects of the object
is based on the color of sunlight.  Note that the sun produces a
particular color spectrum, but many other color spectra are the same
color, and display devices never use the actual color spectrum of the
sun.
.PP
The colors at the corners of the triangle have the chromaticities
phosphors in a monitor that uses the selected color system.  Note
that in BT.709 they are very close to monochromatic red, green,
and blue, but not quite.  That's why you can't display even one true
color of the rainbow on a video monitor.
.PP
Remember that the chart shows colors of constant intensity,
therefore the corners of the triangles are not the full colors of the
primary illuminants, but only their chromaticities.  In fact, the
illuminants typically have different intensities.  In BT.709, the
blue primary illuminant is far more intense than the green, which is
more intense than the red.  Designers did this in order to make an
equal combination of red, green, and blue generate gray.  I.e.  a
combination of full strength red, full strength green, and full
strength blue BT.709 primary illuminants is D65 white.
.PP
The tongue has a sharp straight edge at the bottom because that's
the limit of human vision.  There are colors below that line, but they
involve infrared and ultraviolet light, so you can't see them.  This
line is called the "line of purples."

.UN seealso
.SH SEE ALSO
.BR "ppmdither" (1)\c
\&,
.BR "pnmquant" (1)\c
\&,
.BR "ppm" (1)\c
\&

.UN author
.SH AUTHOR
.PP
Copyright (C) 1995 by John Walker (\fIkelvin@fourmilab.ch\fP)
.PP
WWW home page: 
.UR http://www.fourmilab.ch/
http://www.fourmilab.ch/
.UE
\&
.PP
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
without any conditions or restrictions.  This software is provided as
is without express or implied warranty.
.SH DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML
source.  The master documentation is at
.IP
.B http://netpbm.sourceforge.net/doc/ppmcie.html
.PP