man/man1/pcond.1

.\" RCSid "$Id: pcond.1,v 1.5 2021/04/07 21:13:52 greg Exp $"
.TH PCOND 1 10/27/98 RADIANCE
.SH NAME
pcond - condition a RADIANCE picture for output
.SH SYNOPSIS
.B pcond
[
.B options
]
.B input
[
.B output
]
.SH DESCRIPTION
.I Pcond
conditions a Radiance picture for output to a display or hard copy
device.
If the dynamic range of the scene exceeds that of the display (as is
usually the case),
.I pcond
will compress the dynamic range of the picture such that both
dark and bright regions are visible.
In addition, certain limitations in human vision may be mimicked in
order to provide an appearance similar to the experience one might
have in the actual scene.
.PP
Command line switches turn flags off and on, changing program behavior.
A switch given by itself toggles the flag from off to on or on to
off depending on its previous state.
A switch followed by a '+' turns the option on explicitly.
A switch followed by a '-' turns the option off.
The default is all switches off.
Other options specify output device parameters in order to get more
accurate color and contrast.
.TP 10n
.BI -h [+-]
Mimic human visual response in the output.
The goal of this process is to produce output that correlates
strongly with a person's subjective impression of a scene.
This switch is a bundle of the
.I \-a,
.I \-v,
.I \-s
and
.I \-c
options.
.TP
.BI -a [+-]
Defocus darker regions of the image to simulate human visual acuity loss.
This option will not affect well-lit scenes.
.TP
.BI -v [+-]
Add veiling glare due to very bright regions in the image.
This simulates internal scattering in the human eye, which
results in a loss of visible contrast near bright sources.
.TP
.BI -s [+-]
Use the human contrast sensitivity function in determining the
exposure for the image.
A darker scene will have relatively lower exposure with lower
contrast than a well-lit scene.
.TP
.BI -c [+-]
If parts of the image are in the mesopic or scotopic range where
the cone photoreceptors lose their efficiency, this switch will
cause a corresponding loss of color visibility in the output and a
shift to a scotopic (blue-dominant) response function.
.TP
.BI -w [+-]
Use a center-weighted average for the exposure rather than the
default uniform average.
This may improve the exposure for scenes with high or low peripheral
brightness.
.TP
.BI -i \ fixfrac
Set the relative importance of fixation points to
.I fixfrac,
which is a value between 0 and 1.
If
.I fixfrac
is zero (the default), then no fixation points are used in
determining the local or global adaptation.
If
.I fixfrac
is greater than zero, then a list of fixation points is read from
the standard input.
These points are given as tab-separated (x,y) picture
coordinates, such as those produced by the
.I \-op
option of
.I ximage(1).
The foveal samples about these fixation points will then be weighted
together with the global averaging scheme such that the fixations receive
.I fixfrac
of the total weight.
If
.I fixfrac
is one, then only the fixation points are considered for
adaptation.
.TP
.BI -I [+-]
Rather than computing a histogram of foveal samples from the source picture,
use the precomputed histogram provided on the standard input.
This data should be given in pairs of the base-10 logarithm of
world luminance and a count for each bin in ascending order, as
computed by the
.I phisto(1)
script.
This option is useful for producing identical exposures of multiple
pictures (as in an animation), and provides greater control
over the histogram computation.
.TP
.BI -l [+-]
Use a linear response function rather than the standard dynamic
range compression algorithm.
This will prevent the loss of usable physical values in the output
picture, although some parts of the resulting image may be too
dark or too bright to see.
.TP
.BI -e \ expval
Set the exposure adjustment for the picture to
.I expval.
This may either be a real multiplier, or a (fractional) number of
f-stops preceeded by a '+' or '-'.
This option implies a linear response (see the
.I \-l
option above).
.TP
.BI -u \ Ldmax
Specifies the top of the luminance range for the target output device.
That is, the luminance (in candelas/m^2) for an output pixel value
of (R,G,B)=(1,1,1).
The default value is 100 cd/m^2.
.TP
.BI -d \ Lddyn
Specifies the dynamic range for the target output device, which is
the ratio of the maximum and minimum usable display luminances.
The default value is 100.
.TP
.BI -p " xr yr xg yg xb yb xw yw"
Specifies the RGB primaries for the target output device.
These are the 1931 CIE (x,y) chromaticity values for red, green,
blue and white, respectively.
.TP
.BI -f \ macbeth.cal
Use the given output file from
.I macbethcal(1)
to precorrect the color and contrast for the target output device.
This does a more thorough job than a simple primary correction
using the
.I \-p
option.
Only one of
.I \-f
or
.I \-p
may be given.
.TP
.BI -x \ mapfile
Put out the final mapping from world luminance to display luminance to
.I mapfile.
This file will contain values from the minimum usable world
luminance to the maximum (in candelas/m^2) in one column, and their
corresponding display luminance values (also in candelas/m^2) in the
second column.
This file may be used for debugging purposes, or to plot the mapping
function created by
.I pcond.
.SH EXAMPLES
To display an image as a person might perceive it
in the actual scene:
.IP "" .2i
pcond \-h final.hdr > display.hdr
.br
ximage display.hdr ; rm display.hdr &
.PP
To do the same on a 24\-bit display with known primary values:
.IP "" .2i
setenv DISPLAY_PRIMARIES ".580 .340 .281 .570 .153 .079 .333 .333"
.br
pcond \-h \-p $DISPLAY_PRIMARIES final.hdr | ximage &
.PP
To prepare a picture to be sent to a film recorder destined eventually
for a slide projector with a minimum and maximum screen luminance of
1.5 and 125 candelas/m^2, respectively:
.IP "" .2i
pcond \-d 83 \-u 125 final.hdr > film.hdr
.PP
To do the same if the output colors of the standard image
"ray/lib/lib/macbeth_spec.hdr" have been measured:
.IP "" .2i
macbethcal \-c mbfilm.xyY > film.cal
.br
pcond \-d 83 \-u 125 \-f film.cal final.hdr > film.hdr
.PP
To further tweak the exposure to bring out certain areas indicated by
dragging the right mouse button over them in
.I ximage:
.IP "" .2i
ximage \-op \-t 75 final.hdr | pcond \-i .5 \-d 83 \-u 125 \-f film.cal
final.hdr > film.hdr
.PP
To use a histogram computed on every 10th animation frame:
.IP "" .2i
phisto frame*0.hdr > global.hist
.br
pcond \-I \-s \-c frame0352.hdr < global.hist | ra_tiff \- frame0352.tif
.SH REFERENCE
Greg Ward Larson, Holly Rushmeier, Christine Piatko,
``A Visibility Matching Tone Reproduction Operator for High Dynamic Range
Scenes,''
.I "IEEE Transactions on Visualization and Computer Graphics",
December 1997.
.PP
http://www.sgi.com/Technology/pixformat/Larsonetal.html
.SH NOTES
Hyperspectral Radiance pictures (.hsr files) are
converted to approximate RGB pixels.
However, the colors may not be very accurate.
Pass the HSR picture through
.I rcomb(1)
first if greater color fidelity is required.
.SH AUTHOR
Greg Ward Larson
.SH "SEE ALSO"
getinfo(1), macbethcal(1), normtiff(1),
pcompos(1), pflip(1), phisto(1), pinterp(1),
pvalue(1), protate(1), ra_xyze(1), rad(1),
rcomb(1), rpict(1), ximage(1)
Revision:	1.6
Committed:	Wed Sep 11 18:56:11 2024 UTC (13 months, 2 weeks ago) by greg
Branch:	MAIN
CVS Tags:	rad6R0, HEAD
Changes since 1.5:	+10 -2 lines
Log Message:	feat(pcond,pvalue): Added hyperspectral input handling
#	User	Rev	Content
1	greg	1.6	.\" RCSid "$Id: pcond.1,v 1.5 2021/04/07 21:13:52 greg Exp $"
2	greg	1.1	.TH PCOND 1 10/27/98 RADIANCE
3			.SH NAME
4			pcond - condition a RADIANCE picture for output
5			.SH SYNOPSIS
6			.B pcond
7			[
8			.B options
9			]
10			.B input
11			[
12			.B output
13			]
14			.SH DESCRIPTION
15			.I Pcond
16			conditions a Radiance picture for output to a display or hard copy
17			device.
18			If the dynamic range of the scene exceeds that of the display (as is
19			usually the case),
20			.I pcond
21			will compress the dynamic range of the picture such that both
22			dark and bright regions are visible.
23			In addition, certain limitations in human vision may be mimicked in
24			order to provide an appearance similar to the experience one might
25			have in the actual scene.
26			.PP
27			Command line switches turn flags off and on, changing program behavior.
28			A switch given by itself toggles the flag from off to on or on to
29			off depending on its previous state.
30			A switch followed by a '+' turns the option on explicitly.
31			A switch followed by a '-' turns the option off.
32			The default is all switches off.
33			Other options specify output device parameters in order to get more
34			accurate color and contrast.
35			.TP 10n
36			.BI -h [+-]
37			Mimic human visual response in the output.
38			The goal of this process is to produce output that correlates
39			strongly with a person's subjective impression of a scene.
40			This switch is a bundle of the
41			.I \-a,
42			.I \-v,
43			.I \-s
44			and
45			.I \-c
46			options.
47			.TP
48			.BI -a [+-]
49			Defocus darker regions of the image to simulate human visual acuity loss.
50			This option will not affect well-lit scenes.
51			.TP
52			.BI -v [+-]
53			Add veiling glare due to very bright regions in the image.
54			This simulates internal scattering in the human eye, which
55			results in a loss of visible contrast near bright sources.
56			.TP
57			.BI -s [+-]
58			Use the human contrast sensitivity function in determining the
59			exposure for the image.
60			A darker scene will have relatively lower exposure with lower
61			contrast than a well-lit scene.
62			.TP
63			.BI -c [+-]
64			If parts of the image are in the mesopic or scotopic range where
65			the cone photoreceptors lose their efficiency, this switch will
66			cause a corresponding loss of color visibility in the output and a
67			shift to a scotopic (blue-dominant) response function.
68			.TP
69			.BI -w [+-]
70			Use a center-weighted average for the exposure rather than the
71			default uniform average.
72			This may improve the exposure for scenes with high or low peripheral
73			brightness.
74			.TP
75			.BI -i \ fixfrac
76			Set the relative importance of fixation points to
77			.I fixfrac,
78			which is a value between 0 and 1.
79			If
80			.I fixfrac
81			is zero (the default), then no fixation points are used in
82			determining the local or global adaptation.
83			If
84			.I fixfrac
85			is greater than zero, then a list of fixation points is read from
86			the standard input.
87			These points are given as tab-separated (x,y) picture
88			coordinates, such as those produced by the
89			.I \-op
90			option of
91			.I ximage(1).
92			The foveal samples about these fixation points will then be weighted
93			together with the global averaging scheme such that the fixations receive
94			.I fixfrac
95			of the total weight.
96			If
97			.I fixfrac
98			is one, then only the fixation points are considered for
99			adaptation.
100			.TP
101			.BI -I [+-]
102			Rather than computing a histogram of foveal samples from the source picture,
103			use the precomputed histogram provided on the standard input.
104			This data should be given in pairs of the base-10 logarithm of
105			world luminance and a count for each bin in ascending order, as
106			computed by the
107			.I phisto(1)
108			script.
109			This option is useful for producing identical exposures of multiple
110			pictures (as in an animation), and provides greater control
111			over the histogram computation.
112			.TP
113			.BI -l [+-]
114			Use a linear response function rather than the standard dynamic
115			range compression algorithm.
116			This will prevent the loss of usable physical values in the output
117			picture, although some parts of the resulting image may be too
118			dark or too bright to see.
119			.TP
120			.BI -e \ expval
121			Set the exposure adjustment for the picture to
122			.I expval.
123			This may either be a real multiplier, or a (fractional) number of
124			f-stops preceeded by a '+' or '-'.
125			This option implies a linear response (see the
126			.I \-l
127			option above).
128			.TP
129			.BI -u \ Ldmax
130			Specifies the top of the luminance range for the target output device.
131			That is, the luminance (in candelas/m^2) for an output pixel value
132			of (R,G,B)=(1,1,1).
133			The default value is 100 cd/m^2.
134			.TP
135			.BI -d \ Lddyn
136			Specifies the dynamic range for the target output device, which is
137			the ratio of the maximum and minimum usable display luminances.
138	greg	1.5	The default value is 100.
139	greg	1.1	.TP
140			.BI -p " xr yr xg yg xb yb xw yw"
141			Specifies the RGB primaries for the target output device.
142			These are the 1931 CIE (x,y) chromaticity values for red, green,
143			blue and white, respectively.
144			.TP
145			.BI -f \ macbeth.cal
146			Use the given output file from
147			.I macbethcal(1)
148			to precorrect the color and contrast for the target output device.
149			This does a more thorough job than a simple primary correction
150			using the
151			.I \-p
152			option.
153			Only one of
154			.I \-f
155			or
156			.I \-p
157			may be given.
158			.TP
159			.BI -x \ mapfile
160			Put out the final mapping from world luminance to display luminance to
161			.I mapfile.
162			This file will contain values from the minimum usable world
163			luminance to the maximum (in candelas/m^2) in one column, and their
164			corresponding display luminance values (also in candelas/m^2) in the
165			second column.
166			This file may be used for debugging purposes, or to plot the mapping
167			function created by
168			.I pcond.
169			.SH EXAMPLES
170			To display an image as a person might perceive it
171			in the actual scene:
172			.IP "" .2i
173	greg	1.4	pcond \-h final.hdr > display.hdr
174	greg	1.1	.br
175	greg	1.4	ximage display.hdr ; rm display.hdr &
176	greg	1.1	.PP
177	greg	1.3	To do the same on a 24\-bit display with known primary values:
178	greg	1.1	.IP "" .2i
179			setenv DISPLAY_PRIMARIES ".580 .340 .281 .570 .153 .079 .333 .333"
180			.br
181	greg	1.4	pcond \-h \-p $DISPLAY_PRIMARIES final.hdr \| ximage &
182	greg	1.1	.PP
183			To prepare a picture to be sent to a film recorder destined eventually
184			for a slide projector with a minimum and maximum screen luminance of
185			1.5 and 125 candelas/m^2, respectively:
186			.IP "" .2i
187	greg	1.4	pcond \-d 83 \-u 125 final.hdr > film.hdr
188	greg	1.1	.PP
189			To do the same if the output colors of the standard image
190	greg	1.4	"ray/lib/lib/macbeth_spec.hdr" have been measured:
191	greg	1.1	.IP "" .2i
192	greg	1.3	macbethcal \-c mbfilm.xyY > film.cal
193	greg	1.1	.br
194	greg	1.4	pcond \-d 83 \-u 125 \-f film.cal final.hdr > film.hdr
195	greg	1.1	.PP
196			To further tweak the exposure to bring out certain areas indicated by
197			dragging the right mouse button over them in
198			.I ximage:
199			.IP "" .2i
200	greg	1.4	ximage \-op \-t 75 final.hdr \| pcond \-i .5 \-d 83 \-u 125 \-f film.cal
201			final.hdr > film.hdr
202	greg	1.1	.PP
203			To use a histogram computed on every 10th animation frame:
204			.IP "" .2i
205	greg	1.4	phisto frame*0.hdr > global.hist
206	greg	1.1	.br
207	greg	1.4	pcond \-I \-s \-c frame0352.hdr < global.hist \| ra_tiff \- frame0352.tif
208	greg	1.1	.SH REFERENCE
209			Greg Ward Larson, Holly Rushmeier, Christine Piatko,
210			``A Visibility Matching Tone Reproduction Operator for High Dynamic Range
211			Scenes,''
212			.I "IEEE Transactions on Visualization and Computer Graphics",
213			December 1997.
214			.PP
215			http://www.sgi.com/Technology/pixformat/Larsonetal.html
216	greg	1.6	.SH NOTES
217			Hyperspectral Radiance pictures (.hsr files) are
218			converted to approximate RGB pixels.
219			However, the colors may not be very accurate.
220			Pass the HSR picture through
221			.I rcomb(1)
222			first if greater color fidelity is required.
223	greg	1.1	.SH AUTHOR
224			Greg Ward Larson
225			.SH "SEE ALSO"
226			getinfo(1), macbethcal(1), normtiff(1),
227			pcompos(1), pflip(1), phisto(1), pinterp(1),
228	greg	1.6	pvalue(1), protate(1), ra_xyze(1), rad(1),
229			rcomb(1), rpict(1), ximage(1)