man/man1/pvalue.1

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