man/man1/pvalue.1

.\" RCSid "$Id: pvalue.1,v 1.7 2008/11/10 19:08:17 greg Exp $"
.TH PVALUE 1 1/15/99 RADIANCE
.SH NAME
pvalue - convert RADIANCE picture to/from alternate formats
.SH SYNOPSIS
.B pvalue
[
.B options
]
[
.B file
]
.br
.B "pvalue -r"
[
.B options
]
[
.B file1
[
.B "file2 file3"
]
]
.SH DESCRIPTION
.I Pvalue
converts the pixels of a RADIANCE picture to or from another format.
In the default mode, pixels are sent to the
standard output, one per line, in the following ascii format:

        xpos    ypos    red     green   blue

If no
.I file
is given, the standard input is read.
.PP
The reverse conversion option
.I (-r)
may be used with a single input file or when reading from the
standard input, but if the second form is used with three separate
input files, the three primaries are presumed to be separated in
these files.
.TP 10n
.BR \-u
Print only unique values in the output, skipping runs of equal pixels.
Specifying
.I \+u
turns this option off, which is the default.
.TP
.BR \-o
Print original values, before exposure compensation.
If the input file is in XYZE format, the Y (green) channel
will correspond to units of candelas/meter^2.
Otherwise, the RGB values should be in spectral watts/steradian/meter^2.
Specifying
.I \+o
uses final exposed values, which is the default.
.TP
.BR \-h
Do not print header.
Specifying
.I \+h
causes the header to be printed, which is the default.
.TP
.BI \-H
Do not print the resolution string.
(See also the
.I \-r
option below.)
Specifying an input resolution for reverse conversion also turns
this option off.
Specifying
.I \+H
causes the resolution string to be printed, which is the default.
.TP
.BI \-s \ nbytes
Skip the specified number of bytes on the input header.
This option is useful for skipping unintelligible headers in
foreign file formats.
(Does not work when reading from standard input.)
.TP
.BI \-e \ exposure
Adjust the exposure by the amount specified.
If the exposure is being given as a conversion factor, use
.I \+e
instead, so an EXPOSURE line will not be recorded in the header
(if any).
.TP
.BI \-g \ gamma
Set gamma correction for conversion.
When converting from a RADIANCE picture to another format,
the inverse gamma is applied to correct for monitor response.
When converting to a RADIANCE picture
.I (\-r
option), the gamma is applied directly to recover the linear values.
By default,
.I gamma
is set to 1.0, meaning no gamma correction is performed.
.TP
.BR \-d
Data only,
do not print x and y pixel position.
.TP
.BR \-da
Same as
.I \-d.
.TP
.BR \-di
Print ascii integer values from 0 to 255+.
If
.I \+di
is given, the integer values will be preceded by
the x and y pixel locations.
.TP
.BR \-db
Output binary byte values from 0 to 255.
.TP
.BR \-dw
Output binary 16-bit words from 0 to 65535.
.TP
.BR \-dW
Output binary 16-bit words from 0 to 65535, byte-swapped.
.TP
.BR \-df
Output binary float values.
.TP
.BR \-dF
Output byte-swapped binary float values.
.TP
.BR \-dd
Output binary double values.
.TP
.BR \-dD
Output byte-swapped binary double values.
.TP
.BR \-R
Reverse ordering of colors so that the output is blue then green
then red.
The default ordering (specified with
.I \+R)
is red then green then blue.
.TP
.BR \-n
The RGB values are non-interleaved, meaning that all the red, green
and blue data are stored together in separate chunks.
Interleaving may be turned on with the
.I \+n
option, which is the default.
.TP
.BR \-b
Print brightness values rather than RGB.
Specifying
.I \+b
turns this option off, which is the default.
.TP
.BI \-p P
Put out only the primary
.I P,
where
.I P
is one of upper or lower case 'R', 'G' or 'B' for red, green or
blue, respectively.
This option may be used to separate the Radiance primaries into
three files with three separate runs of
.I pvalue,
or only one file when only one primary is needed.
Note that there is no space between this option and its argument.
.TP
.BR \-r
Perform reverse conversion.
Input is in the format given by the other options.
The x and y resolution must be specified on the command line, unless
the image file contains a Radiance resolution string at the
beginning (see 
.I \-H
option above and
.I \-y
option below).
Specifying
.I \+r
converts from a Radiance picture to other values, which is the
default.
.TP
.BI \-p " xr yr xg yg xb yb xw yw"
On reverse conversion, RGB input uses the given set of color primaries.
These are written into the output header with the PRIMARIES variable.
.TP
.BR \-pXYZ
On reverse conversion, input is in CIE XYZ coordinates, rather than RGB.
The Y channel is assumed to be in candelas/meter^2.
.TP
.BI -y \ res
Set the output y resolution to
.I res.
If
.I \+y
is specified, then the scanlines are assumed to be in
increasing order (ie. bottom to top).
The default value for this option is 0, which means
that the picture size and scanline order must appear
as the first line after the header (if any) in the
input file.
Either an upper or lower case 'Y' may be used for this option.
Since Radiance files always contain such a line, 
this option has no effect for forward conversions.
.TP
.BI +x \ res
Set the output x resolution to
.I res.
If
.I \-x
is specified, then the scanlines are assumed to be in
decreasing order (ie. right to left).
The ordering of the
.I \-y
and
.I \+x
options determines whether the scanlines are sorted along
x or along y.
Most Radiance pictures are sorted top to bottom, then left
to right.
This corresponds to a specification of the form "\-y yres +x xres".
Either an upper or lower case 'X' may be used for this option.
Like the
.I \-y
option,
.I \-x
options have no effect for forward conversions.
.SH EXAMPLE
To look at the original, unique pixels in picture:
.IP "" .2i
pvalue \-o \-u picture | more
.PP
To convert from a 512x400 8-bit greyscale image in bottom to top,
left to right scanline ordering:
.IP "" .2i
pvalue \-r \-db \-b \-h +y 400 +x 512 input.im > flipped.hdr
.br
pflip \-v flipped.hdr > final.hdr
.SH AUTHOR
Greg Ward
.SH BUGS
The
.I \-r
option does not work with the
.I \-u
option.
Also, input pixel locations are ignored during a reverse
conversion, so this information is not used in determining
the scanline ordering or picture size.
.SH "SEE ALSO"
getinfo(1), pcompos(1), pfilt(1), pflip(1),
protate(1), ra_xyze(1), rpict(1), rtrace(1), rvu(1)
Revision:	1.8
Committed:	Thu Dec 16 21:34:41 2010 UTC (13 years, 5 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R2, rad4R2P2, rad5R0, rad5R1, rad4R2, rad4R1, rad4R2P1
Changes since 1.7:	+10 -2 lines
Log Message:	Added recording of other color spaces to pvalue -r conversion
#	Content
1	.\" RCSid "$Id: pvalue.1,v 1.7 2008/11/10 19:08:17 greg Exp $"
2	.TH PVALUE 1 1/15/99 RADIANCE
3	.SH NAME
4	pvalue - convert RADIANCE picture to/from alternate formats
5	.SH SYNOPSIS
6	.B pvalue
7	[
8	.B options
9	]
10	[
11	.B file
12	]
13	.br
14	.B "pvalue -r"
15	[
16	.B options
17	]
18	[
19	.B file1
20	[
21	.B "file2 file3"
22	]
23	]
24	.SH DESCRIPTION
25	.I Pvalue
26	converts the pixels of a RADIANCE picture to or from another format.
27	In the default mode, pixels are sent to the
28	standard output, one per line, in the following ascii format:
29
30	xpos ypos red green blue
31
32	If no
33	.I file
34	is given, the standard input is read.
35	.PP
36	The reverse conversion option
37	.I (-r)
38	may be used with a single input file or when reading from the
39	standard input, but if the second form is used with three separate
40	input files, the three primaries are presumed to be separated in
41	these files.
42	.TP 10n
43	.BR \-u
44	Print only unique values in the output, skipping runs of equal pixels.
45	Specifying
46	.I \+u
47	turns this option off, which is the default.
48	.TP
49	.BR \-o
50	Print original values, before exposure compensation.
51	If the input file is in XYZE format, the Y (green) channel
52	will correspond to units of candelas/meter^2.
53	Otherwise, the RGB values should be in spectral watts/steradian/meter^2.
54	Specifying
55	.I \+o
56	uses final exposed values, which is the default.
57	.TP
58	.BR \-h
59	Do not print header.
60	Specifying
61	.I \+h
62	causes the header to be printed, which is the default.
63	.TP
64	.BI \-H
65	Do not print the resolution string.
66	(See also the
67	.I \-r
68	option below.)
69	Specifying an input resolution for reverse conversion also turns
70	this option off.
71	Specifying
72	.I \+H
73	causes the resolution string to be printed, which is the default.
74	.TP
75	.BI \-s \ nbytes
76	Skip the specified number of bytes on the input header.
77	This option is useful for skipping unintelligible headers in
78	foreign file formats.
79	(Does not work when reading from standard input.)
80	.TP
81	.BI \-e \ exposure
82	Adjust the exposure by the amount specified.
83	If the exposure is being given as a conversion factor, use
84	.I \+e
85	instead, so an EXPOSURE line will not be recorded in the header
86	(if any).
87	.TP
88	.BI \-g \ gamma
89	Set gamma correction for conversion.
90	When converting from a RADIANCE picture to another format,
91	the inverse gamma is applied to correct for monitor response.
92	When converting to a RADIANCE picture
93	.I (\-r
94	option), the gamma is applied directly to recover the linear values.
95	By default,
96	.I gamma
97	is set to 1.0, meaning no gamma correction is performed.
98	.TP
99	.BR \-d
100	Data only,
101	do not print x and y pixel position.
102	.TP
103	.BR \-da
104	Same as
105	.I \-d.
106	.TP
107	.BR \-di
108	Print ascii integer values from 0 to 255+.
109	If
110	.I \+di
111	is given, the integer values will be preceded by
112	the x and y pixel locations.
113	.TP
114	.BR \-db
115	Output binary byte values from 0 to 255.
116	.TP
117	.BR \-dw
118	Output binary 16-bit words from 0 to 65535.
119	.TP
120	.BR \-dW
121	Output binary 16-bit words from 0 to 65535, byte-swapped.
122	.TP
123	.BR \-df
124	Output binary float values.
125	.TP
126	.BR \-dF
127	Output byte-swapped binary float values.
128	.TP
129	.BR \-dd
130	Output binary double values.
131	.TP
132	.BR \-dD
133	Output byte-swapped binary double values.
134	.TP
135	.BR \-R
136	Reverse ordering of colors so that the output is blue then green
137	then red.
138	The default ordering (specified with
139	.I \+R)
140	is red then green then blue.
141	.TP
142	.BR \-n
143	The RGB values are non-interleaved, meaning that all the red, green
144	and blue data are stored together in separate chunks.
145	Interleaving may be turned on with the
146	.I \+n
147	option, which is the default.
148	.TP
149	.BR \-b
150	Print brightness values rather than RGB.
151	Specifying
152	.I \+b
153	turns this option off, which is the default.
154	.TP
155	.BI \-p P
156	Put out only the primary
157	.I P,
158	where
159	.I P
160	is one of upper or lower case 'R', 'G' or 'B' for red, green or
161	blue, respectively.
162	This option may be used to separate the Radiance primaries into
163	three files with three separate runs of
164	.I pvalue,
165	or only one file when only one primary is needed.
166	Note that there is no space between this option and its argument.
167	.TP
168	.BR \-r
169	Perform reverse conversion.
170	Input is in the format given by the other options.
171	The x and y resolution must be specified on the command line, unless
172	the image file contains a Radiance resolution string at the
173	beginning (see
174	.I \-H
175	option above and
176	.I \-y
177	option below).
178	Specifying
179	.I \+r
180	converts from a Radiance picture to other values, which is the
181	default.
182	.TP
183	.BI \-p " xr yr xg yg xb yb xw yw"
184	On reverse conversion, RGB input uses the given set of color primaries.
185	These are written into the output header with the PRIMARIES variable.
186	.TP
187	.BR \-pXYZ
188	On reverse conversion, input is in CIE XYZ coordinates, rather than RGB.
189	The Y channel is assumed to be in candelas/meter^2.
190	.TP
191	.BI -y \ res
192	Set the output y resolution to
193	.I res.
194	If
195	.I \+y
196	is specified, then the scanlines are assumed to be in
197	increasing order (ie. bottom to top).
198	The default value for this option is 0, which means
199	that the picture size and scanline order must appear
200	as the first line after the header (if any) in the
201	input file.
202	Either an upper or lower case 'Y' may be used for this option.
203	Since Radiance files always contain such a line,
204	this option has no effect for forward conversions.
205	.TP
206	.BI +x \ res
207	Set the output x resolution to
208	.I res.
209	If
210	.I \-x
211	is specified, then the scanlines are assumed to be in
212	decreasing order (ie. right to left).
213	The ordering of the
214	.I \-y
215	and
216	.I \+x
217	options determines whether the scanlines are sorted along
218	x or along y.
219	Most Radiance pictures are sorted top to bottom, then left
220	to right.
221	This corresponds to a specification of the form "\-y yres +x xres".
222	Either an upper or lower case 'X' may be used for this option.
223	Like the
224	.I \-y
225	option,
226	.I \-x
227	options have no effect for forward conversions.
228	.SH EXAMPLE
229	To look at the original, unique pixels in picture:
230	.IP "" .2i
231	pvalue \-o \-u picture \| more
232	.PP
233	To convert from a 512x400 8-bit greyscale image in bottom to top,
234	left to right scanline ordering:
235	.IP "" .2i
236	pvalue \-r \-db \-b \-h +y 400 +x 512 input.im > flipped.hdr
237	.br
238	pflip \-v flipped.hdr > final.hdr
239	.SH AUTHOR
240	Greg Ward
241	.SH BUGS
242	The
243	.I \-r
244	option does not work with the
245	.I \-u
246	option.
247	Also, input pixel locations are ignored during a reverse
248	conversion, so this information is not used in determining
249	the scanline ordering or picture size.
250	.SH "SEE ALSO"
251	getinfo(1), pcompos(1), pfilt(1), pflip(1),
252	protate(1), ra_xyze(1), rpict(1), rtrace(1), rvu(1)