man/man1/macbethcal.1

.\" RCSid "$Id: macbethcal.1,v 1.4 2007/09/04 17:36:40 greg Exp $"
.TH MACBETHCAL 1 1/16/97 RADIANCE
.SH NAME
macbethcal - compute color compensation based on measured Macbeth chart
.SH SYNOPSIS
.B macbethcal
[
.B "\-d debug.hdr"
][
.B "\-p xul yul xur yur xll yll xlr ylr"
]
.B scannedin.hdr
[
.B calibout.cal
]
.br
.B macbethcal
.B \-c
[
.B "\-d debug.hdr"
]
[
.B measured.xyY
[
.B calibout.cal
]
]
.SH DESCRIPTION
.I Macbethcal
takes a scanned image or measurement set
of a Macbeth ColorChecker\u\s-3TM\s+3\d color
rendition chart and computes a color mapping
function suitable as input to
.I pcomb(1).
.PP
In the first form,
.I macbethcal
takes a scanned image of a Macbeth chart that has been converted
into a Radiance picture using a fixed procedure.
When used properly as input to
.I pcomb,
the computed calibration file will adjust the
brightness and color of any similarly scanned and converted image
so as to best match the original.
If the lighting conditions are carefully controlled (as in the case
of a flatbed scanner), it is even possible to get reliable
reflectance values this way, at least within 10% or so.
The input picture is named on the command line.
The output calibration file will be written to the standard output
if no file name is given on the command line.
.PP
In the second form, the input is from a file containing measured
values for each Macbeth color.
This file must contain entries of the form:
.sp
.nf
N       x       y       Y
.fi
.sp
Where
.I N
is the number of the corresponding Macbeth color.
(See back of ColorChecker chart
for color names and indexing, but it basically starts from the upper
left with 1 and proceeds in English text order to the lower right,
which is 24.)
The values
.I x,
.I y
and
.I Y
are the 1931 CIE (x,y) chromaticity coordinates followed by the
luminance for that color, which can be in any units.
If a white value is known (i.e. maximum output level), then it may
be given as entry number 0.
The entries may be in any order, and comments may be included
delimited by a pound sign ('#') and continuing to the end of line.
It is recommended that measurements be done for all 24 colors,
but the only required entries are the 6 neutral values on the bottom
row of the chart.
.PP
Computing a mapping from measured colors is usually more convenient
when calibrating a particular output device.
This is accomplished by printing the picture
.I macbeth_spec.hdr
(which may be found in the standard RADIANCE library directory in
the lib subdirectory) and measuring the output with a chroma meter
or spectrophotometer.
.PP
For a scanned image, the locations of the 24 Macbeth patches
in the input picture must be known.
If the chart borders are not at the edges of the input picture, or
the chart has been reversed or rotated or is uncentered or at an
oblique angle, then it is necessary to specify the pixel locations
of the corners of the chart with the
.I \-p
option.
The corner postions (x,y pixel addresses as given by the
.I ximage(1)
"p" command)
are ordered on the command line:
upper-left, upper-right, lower-left, lower-right
(i.e. English text ordering).
These coordinates should be the outside corner positions of
the following patches:
.sp
.nf
upper-left      = 1. dark skin
upper-right     = 6. bluish green
lower-left      = 19. white
lower-right     = 24. black
.fi
.sp
If the chart has been flipped or rotated, simply give the pixel
positions of the appropriate patch corners, wherever
they are in the image.
(Note: if the Radiance picture has been flipped or rotated with
.I pflip(1)
or
.I protate(1),
.I ximage
will report the original pixel positions if the
.I \-c
option was not used by the reorienting program(s).
This will be wrong, so be sure to use the
.I \-c
option.)
.I Macbethcal
can handle a chart with any orientation or perspective warping if
the corner coordinates are given correctly.
The debug picture output is the best way to check for consistency.
(See the
.I \-d
option, below.)
.PP
The
.I \-d
option may be used to specify an additional output file, which will
be a picture comparing the scanned image processed according to the
computed mapping against the standard Macbeth colors.
It is a good idea to use the debug option to check that the color
patches are being located correctly, and to see how well
.I macbethcal
does at matching colors.
The center of each patch will show the target color;
the left side of each patch will show the original
color, and the right side will show the corrected value.
If the match works well, the debug picture should have a sort of
"notch on the left" look in each patch.
Macbeth colors that could not be matched because they were out of
gamut on this device are indicated with diagonal lines drawn
through the associated target colors.
.SH METHOD
.I Macbethcal
computes the color mapping in two stages.
The first stage uses the six neutral color patches at the bottom of
the Macbeth chart to compute a piecewise linear approximation to the
brightness mapping of each RGB primary.
The second stage looks at all the colors that are within the
device's gamut to compute a
least-sqaures fit for a linear color transformation from the
measured space into the standard Radiance RGB space (as defined by
the three primaries in src/common/color.h).
.PP
Thanks to the nature of inverse mappings, this method should work
either for converting scanned data to match the original, or for
preconditioning pictures to be sent to specific output devices.
In other words, the same calibration file works either for
correcting scanned images OR precorrecting images before printing.
.PP
A warning is printed if some unsaturated colors are determined to
be out of gamut, as this may indicate a poor rendition or improper
picture alignment.
The debug picture will show which colors were excluded by drawing
diagonal lines through their entries.
.SH NOTE
It is very important that the same settings be applied when
scanning or printing other images to be calibrated with the computed file.
In particular, all exposure adjustments should be fixed manually,
and no tweaking of the settings should be done along the way.
The final result will be best if the original scanned image is not
too far off from what it should be.
In the case of slide and negative scanners, it is best to apply the
recommended calibration file for the type of film used, so long as
this calibration is fixed and not adjusted on a per-image basis.
.SH CHART AVAILABILITY
The Macbeth chart is available at most photographic supply stores,
or may be ordered directly from Macbeth:
.sp
.nf
Macbeth
Munsell Color
405 Little Britain Rd.
New Windsor, NY  12553-6148
tel. 1-800-622-2384 (USA)
fax. 1-914-561-0267
.fi
.sp
The chart sells for under $50 US at the time of this writing.
.SH EXAMPLES
To compute a calibration for a FunkyThing scanner and check the
results:
.IP "" .2i
ra_tiff \-r mbscan.tif mbscan.hdr
.br
macbethcal \-d debug.hdr mbscan.hdr FunkyThing.cal
.br
ximage debug.hdr
.PP
To apply this computed calibration to another scanned image:
.IP "" .2i
ra_tiff \-r another.tif | pcomb \-f FunkyThing.cal \- > another_calib.hdr
.PP
To compute a calibration file for the BigWhiz film recorder, after
taking measurements of a slide made from macbeth_spec.hdr:
.IP "" .2i
macbethcal \-c macbeth_spec.xyY BigWhiz.cal
.PP
To prepare a picture prior to output on the same film recorder:
.IP "" .2i
pcomb \-f BigWhiz.cal standard.hdr > toprint.hdr
.PP
To use
.I pcond(1)
to also adjust the image for human response:
.IP "" .2i
pcond \-f BigWhiz.cal \-h standard.hdr > toprint.hdr
.SH AUTHOR
Greg Ward
.br
Paul Heckbert supplied code for perspective projective mapping
.SH "SEE ALSO"
icalc(1), pcomb(1), pcond(1), pfilt(1), ximage(1)
Revision:	1.5
Committed:	Mon Nov 10 19:08:17 2008 UTC (16 years, 11 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R4, rad5R2, rad5R3, rad5R0, rad5R1, rad4R2, rad6R0, rad4R1, rad4R0, rad4R2P1, rad4R2P2, HEAD
Changes since 1.4:	+12 -12 lines
Log Message:	Changed ".pic" extension to ".hdr" throughout
#	Content
1	.\" RCSid "$Id: macbethcal.1,v 1.4 2007/09/04 17:36:40 greg Exp $"
2	.TH MACBETHCAL 1 1/16/97 RADIANCE
3	.SH NAME
4	macbethcal - compute color compensation based on measured Macbeth chart
5	.SH SYNOPSIS
6	.B macbethcal
7	[
8	.B "\-d debug.hdr"
9	][
10	.B "\-p xul yul xur yur xll yll xlr ylr"
11	]
12	.B scannedin.hdr
13	[
14	.B calibout.cal
15	]
16	.br
17	.B macbethcal
18	.B \-c
19	[
20	.B "\-d debug.hdr"
21	]
22	[
23	.B measured.xyY
24	[
25	.B calibout.cal
26	]
27	]
28	.SH DESCRIPTION
29	.I Macbethcal
30	takes a scanned image or measurement set
31	of a Macbeth ColorChecker\u\s-3TM\s+3\d color
32	rendition chart and computes a color mapping
33	function suitable as input to
34	.I pcomb(1).
35	.PP
36	In the first form,
37	.I macbethcal
38	takes a scanned image of a Macbeth chart that has been converted
39	into a Radiance picture using a fixed procedure.
40	When used properly as input to
41	.I pcomb,
42	the computed calibration file will adjust the
43	brightness and color of any similarly scanned and converted image
44	so as to best match the original.
45	If the lighting conditions are carefully controlled (as in the case
46	of a flatbed scanner), it is even possible to get reliable
47	reflectance values this way, at least within 10% or so.
48	The input picture is named on the command line.
49	The output calibration file will be written to the standard output
50	if no file name is given on the command line.
51	.PP
52	In the second form, the input is from a file containing measured
53	values for each Macbeth color.
54	This file must contain entries of the form:
55	.sp
56	.nf
57	N x y Y
58	.fi
59	.sp
60	Where
61	.I N
62	is the number of the corresponding Macbeth color.
63	(See back of ColorChecker chart
64	for color names and indexing, but it basically starts from the upper
65	left with 1 and proceeds in English text order to the lower right,
66	which is 24.)
67	The values
68	.I x,
69	.I y
70	and
71	.I Y
72	are the 1931 CIE (x,y) chromaticity coordinates followed by the
73	luminance for that color, which can be in any units.
74	If a white value is known (i.e. maximum output level), then it may
75	be given as entry number 0.
76	The entries may be in any order, and comments may be included
77	delimited by a pound sign ('#') and continuing to the end of line.
78	It is recommended that measurements be done for all 24 colors,
79	but the only required entries are the 6 neutral values on the bottom
80	row of the chart.
81	.PP
82	Computing a mapping from measured colors is usually more convenient
83	when calibrating a particular output device.
84	This is accomplished by printing the picture
85	.I macbeth_spec.hdr
86	(which may be found in the standard RADIANCE library directory in
87	the lib subdirectory) and measuring the output with a chroma meter
88	or spectrophotometer.
89	.PP
90	For a scanned image, the locations of the 24 Macbeth patches
91	in the input picture must be known.
92	If the chart borders are not at the edges of the input picture, or
93	the chart has been reversed or rotated or is uncentered or at an
94	oblique angle, then it is necessary to specify the pixel locations
95	of the corners of the chart with the
96	.I \-p
97	option.
98	The corner postions (x,y pixel addresses as given by the
99	.I ximage(1)
100	"p" command)
101	are ordered on the command line:
102	upper-left, upper-right, lower-left, lower-right
103	(i.e. English text ordering).
104	These coordinates should be the outside corner positions of
105	the following patches:
106	.sp
107	.nf
108	upper-left = 1. dark skin
109	upper-right = 6. bluish green
110	lower-left = 19. white
111	lower-right = 24. black
112	.fi
113	.sp
114	If the chart has been flipped or rotated, simply give the pixel
115	positions of the appropriate patch corners, wherever
116	they are in the image.
117	(Note: if the Radiance picture has been flipped or rotated with
118	.I pflip(1)
119	or
120	.I protate(1),
121	.I ximage
122	will report the original pixel positions if the
123	.I \-c
124	option was not used by the reorienting program(s).
125	This will be wrong, so be sure to use the
126	.I \-c
127	option.)
128	.I Macbethcal
129	can handle a chart with any orientation or perspective warping if
130	the corner coordinates are given correctly.
131	The debug picture output is the best way to check for consistency.
132	(See the
133	.I \-d
134	option, below.)
135	.PP
136	The
137	.I \-d
138	option may be used to specify an additional output file, which will
139	be a picture comparing the scanned image processed according to the
140	computed mapping against the standard Macbeth colors.
141	It is a good idea to use the debug option to check that the color
142	patches are being located correctly, and to see how well
143	.I macbethcal
144	does at matching colors.
145	The center of each patch will show the target color;
146	the left side of each patch will show the original
147	color, and the right side will show the corrected value.
148	If the match works well, the debug picture should have a sort of
149	"notch on the left" look in each patch.
150	Macbeth colors that could not be matched because they were out of
151	gamut on this device are indicated with diagonal lines drawn
152	through the associated target colors.
153	.SH METHOD
154	.I Macbethcal
155	computes the color mapping in two stages.
156	The first stage uses the six neutral color patches at the bottom of
157	the Macbeth chart to compute a piecewise linear approximation to the
158	brightness mapping of each RGB primary.
159	The second stage looks at all the colors that are within the
160	device's gamut to compute a
161	least-sqaures fit for a linear color transformation from the
162	measured space into the standard Radiance RGB space (as defined by
163	the three primaries in src/common/color.h).
164	.PP
165	Thanks to the nature of inverse mappings, this method should work
166	either for converting scanned data to match the original, or for
167	preconditioning pictures to be sent to specific output devices.
168	In other words, the same calibration file works either for
169	correcting scanned images OR precorrecting images before printing.
170	.PP
171	A warning is printed if some unsaturated colors are determined to
172	be out of gamut, as this may indicate a poor rendition or improper
173	picture alignment.
174	The debug picture will show which colors were excluded by drawing
175	diagonal lines through their entries.
176	.SH NOTE
177	It is very important that the same settings be applied when
178	scanning or printing other images to be calibrated with the computed file.
179	In particular, all exposure adjustments should be fixed manually,
180	and no tweaking of the settings should be done along the way.
181	The final result will be best if the original scanned image is not
182	too far off from what it should be.
183	In the case of slide and negative scanners, it is best to apply the
184	recommended calibration file for the type of film used, so long as
185	this calibration is fixed and not adjusted on a per-image basis.
186	.SH CHART AVAILABILITY
187	The Macbeth chart is available at most photographic supply stores,
188	or may be ordered directly from Macbeth:
189	.sp
190	.nf
191	Macbeth
192	Munsell Color
193	405 Little Britain Rd.
194	New Windsor, NY 12553-6148
195	tel. 1-800-622-2384 (USA)
196	fax. 1-914-561-0267
197	.fi
198	.sp
199	The chart sells for under $50 US at the time of this writing.
200	.SH EXAMPLES
201	To compute a calibration for a FunkyThing scanner and check the
202	results:
203	.IP "" .2i
204	ra_tiff \-r mbscan.tif mbscan.hdr
205	.br
206	macbethcal \-d debug.hdr mbscan.hdr FunkyThing.cal
207	.br
208	ximage debug.hdr
209	.PP
210	To apply this computed calibration to another scanned image:
211	.IP "" .2i
212	ra_tiff \-r another.tif \| pcomb \-f FunkyThing.cal \- > another_calib.hdr
213	.PP
214	To compute a calibration file for the BigWhiz film recorder, after
215	taking measurements of a slide made from macbeth_spec.hdr:
216	.IP "" .2i
217	macbethcal \-c macbeth_spec.xyY BigWhiz.cal
218	.PP
219	To prepare a picture prior to output on the same film recorder:
220	.IP "" .2i
221	pcomb \-f BigWhiz.cal standard.hdr > toprint.hdr
222	.PP
223	To use
224	.I pcond(1)
225	to also adjust the image for human response:
226	.IP "" .2i
227	pcond \-f BigWhiz.cal \-h standard.hdr > toprint.hdr
228	.SH AUTHOR
229	Greg Ward
230	.br
231	Paul Heckbert supplied code for perspective projective mapping
232	.SH "SEE ALSO"
233	icalc(1), pcomb(1), pcond(1), pfilt(1), ximage(1)