man/man1/pvalue.1

.\" RCSid "$Id: pvalue.1,v 1.12 2022/02/04 20:11:48 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 NOTES
Hyperspectral Radiance pictures (.hsr files) are
converted to approximate RGB.
However, the colors may not be very accurate.
Use
.I rcomb(1)
for conversion if greater color fidelity is required.
.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), rcomb(1), rpict(1), rtrace(1), rvu(1)
Revision:	1.13
Committed:	Wed Sep 11 18:56:11 2024 UTC (7 months, 3 weeks ago) by greg
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.12:	+9 -2 lines
Log Message:	feat(pcond,pvalue): Added hyperspectral input handling
#	Content
1	.\" RCSid "$Id: pvalue.1,v 1.12 2022/02/04 20:11:48 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	For reverse conversions, the
46	.I \-u
47	option writes uncompressed output rather than the standard run-length RGBE
48	encoding.
49	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	If the input file is in XYZE format, the Y (green) channel
56	will correspond to units of candelas/meter^2, unless
57	.I \-O
58	is specified, when watts/sr/meter^2 are always reported.
59	Specifying
60	.I \+o
61	uses final exposed values, which is the default.
62	.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	.BR \-dF
131	Output byte-swapped binary float values.
132	.TP
133	.BR \-dd
134	Output binary double values.
135	.TP
136	.BR \-dD
137	Output byte-swapped binary double values.
138	.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	.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	.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	This corresponds to a specification of the form "\-y yres +x xres".
226	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	pvalue \-o \-u picture \| more
236	.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	pvalue \-r \-db \-b \-h +y 400 +x 512 input.im > flipped.hdr
241	.br
242	pflip \-v flipped.hdr > final.hdr
243	.SH NOTES
244	Hyperspectral Radiance pictures (.hsr files) are
245	converted to approximate RGB.
246	However, the colors may not be very accurate.
247	Use
248	.I rcomb(1)
249	for conversion if greater color fidelity is required.
250	.SH AUTHOR
251	Greg Ward
252	.SH BUGS
253	Input pixel locations are ignored during a reverse
254	conversion, so this information is not used in determining
255	the scanline ordering or picture size.
256	.SH "SEE ALSO"
257	getinfo(1), pcompos(1), pfilt(1), pflip(1),
258	protate(1), ra_xyze(1), rcomb(1), rpict(1), rtrace(1), rvu(1)