man/man1/ra_xyze.1

.\" RCSid "$Id: ra_xyze.1,v 1.6 2010/12/16 21:34:41 greg Exp $"
.TH RA_XYZE 1 5/30/96 RADIANCE
.SH NAME
ra_xyze - convert between RADIANCE RGBE and XYZE formats
.SH SYNOPSIS
.B ra_xyze
[
.B \-r
][
.B "\-e exposure"
][
.B \-o
][
.B \-c
|
.B \-u
][
.B "\-p xr yr xg yg xb yb xw yw"
]
[
.B input
[
.B output
]
]
.SH DESCRIPTION
.I Ra_xyze
converts between RADIANCE RGBE (red,green,blue,exponent) and XYZE
(CIE X,Y,Z,exponent) formats.
The
.I \-e
option specifies an exposure compensation, which may be given as
a decimal multiplier or in f-stops (powers of two).
The
.I \-o
option may be used to specify original units, to which the exposure
compensation is applied.
Otherwise, the multiplier is in addition to any previous exposure adjustment.
By default,
.I ra_xyze
produces a flat XYZE RADIANCE picture file from any type of RADIANCE
input picture.
To override these defaults, the
.I \-c
option may be used to specify run-length encoded output,
or the
.I \-u
option may be used to specify a flat output.
.PP
The
.I \-r
option causes
.I ra_xyze
to produce a run-length encoded RGBE file instead, unless
.I \-u
is given, also, when it will produce a flat RGBE file.
The
.I \-p
option may be used to override the standard RADIANCE RGB primary
colors to tailor the image for a particular output device or
representation.
The eight floating-point arguments to this option are the 1931
CIE (x,y) chromaticity coordinates of the three RGB primaries
plus the white point, in that order.
The new primaries will be recorded in the header of the output file,
so that the original information may be fully recovered later.
It is not necessary that the input file be in XYZE format.
Th
.I \-r
option may therefore be used to convert from one RGB primary
representation to another using the
.I \-p
option.
.PP
If the output file is missing, the standard output is used.
If the input file is missing as well, the standard input is used.
.SH NOTES
The CIE standard used is the 1931 2-degree observer, and the
correct output representation relies on the original RADIANCE
input description being defined properly in terms of the standard
RADIANCE RGB primaries, whose CIE (x,y) chromaticity values are
defined in the header file in src/common/color.h.
In this same file is a standard for the luminous efficacy of white
light (WHTEFFICACY), which is used as a conversion between lumens
and watts throughout RADIANCE.
This same factor is applied by
.I ra_xyze
when converting between the radiometric units of the RGBE format
and the photometric units of the XYZE format.
The purpose of this factor is to ensure that the Y component of
the CIE representation is luminance in units of candelas/meter^2.
.PP
Most of the RADIANCE picture filters should work uniformly on either
RGBE or XYZE files, so it is not necessary to convert back to RGBE
format except for conversion or display, in which case the correct
primaries for the chosen output device should be specified with the
.I \-p
option if they are known.
.PP
Similar to the
.I ra_rgbe(1)
tool,
.I ra_xyze
silently converts hyperspectral pictures (.hsr) on input,
but does so more accurately (and slowly) than
.I ra_rgbe.
.SH EXAMPLES
To convert RGBE output from
.I rpict(1)
into run-length encoded XYZE format:
.IP "" .2i
rpict [options] scene.oct | ra_xyze \-c > scene_xyz.hdr
.PP
To prepare a RADIANCE picture for display on a calibrated NTSC monitor:
.IP "" .2i
ra_xyze \-r \-p .670 .330 .210 .710 .140 .080 .333 .333 stand.hdr ntsc.hdr
.SH AUTHOR
Greg Ward
.SH BUGS
Any color correction applied to the original image is not removed
or translated by
.I ra_xyze,
and it may result in color shifts in the output.
If color preservation is important and the correction is unwanted,
it is best to remove it with
.I pfilt(1)
using the
.I \-er,
.I \-eg
and
.I \-eb
options first.
(Simply look at the header and apply the reciprocal primaries of all
COLORCORR= lines multiplied together.)
Better still, get the picture before color correction is applied.
.SH "SEE ALSO"
pfilt(1), pvalue(1), ra_rgbe(1), rpict(1)
Revision:	1.7
Committed:	Tue Oct 1 01:16:26 2024 UTC (7 months ago) by greg
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.6:	+9 -1 lines
Log Message:	feat(ra_xyze): added accurate conversion of hyperspectral pictures on input
#	User	Rev	Content
1	greg	1.7	.\" RCSid "$Id: ra_xyze.1,v 1.6 2010/12/16 21:34:41 greg Exp $"
2	greg	1.1	.TH RA_XYZE 1 5/30/96 RADIANCE
3			.SH NAME
4			ra_xyze - convert between RADIANCE RGBE and XYZE formats
5			.SH SYNOPSIS
6			.B ra_xyze
7			[
8			.B \-r
9			][
10			.B "\-e exposure"
11			][
12	greg	1.3	.B \-o
13			][
14	greg	1.1	.B \-c
15			\|
16			.B \-u
17			][
18			.B "\-p xr yr xg yg xb yb xw yw"
19			]
20			[
21			.B input
22			[
23			.B output
24			]
25			]
26			.SH DESCRIPTION
27			.I Ra_xyze
28			converts between RADIANCE RGBE (red,green,blue,exponent) and XYZE
29			(CIE X,Y,Z,exponent) formats.
30			The
31			.I \-e
32			option specifies an exposure compensation, which may be given as
33			a decimal multiplier or in f-stops (powers of two).
34	greg	1.3	The
35			.I \-o
36			option may be used to specify original units, to which the exposure
37			compensation is applied.
38			Otherwise, the multiplier is in addition to any previous exposure adjustment.
39	greg	1.1	By default,
40			.I ra_xyze
41			produces a flat XYZE RADIANCE picture file from any type of RADIANCE
42			input picture.
43			To override these defaults, the
44			.I \-c
45			option may be used to specify run-length encoded output,
46			or the
47			.I \-u
48			option may be used to specify a flat output.
49			.PP
50			The
51			.I \-r
52			option causes
53			.I ra_xyze
54	greg	1.3	to produce a run-length encoded RGBE file instead, unless
55			.I \-u
56			is given, also, when it will produce a flat RGBE file.
57	greg	1.1	The
58			.I \-p
59			option may be used to override the standard RADIANCE RGB primary
60			colors to tailor the image for a particular output device or
61			representation.
62			The eight floating-point arguments to this option are the 1931
63			CIE (x,y) chromaticity coordinates of the three RGB primaries
64			plus the white point, in that order.
65			The new primaries will be recorded in the header of the output file,
66			so that the original information may be fully recovered later.
67	greg	1.6	It is not necessary that the input file be in XYZE format.
68	greg	1.1	Th
69			.I \-r
70			option may therefore be used to convert from one RGB primary
71			representation to another using the
72			.I \-p
73			option.
74			.PP
75			If the output file is missing, the standard output is used.
76			If the input file is missing as well, the standard input is used.
77			.SH NOTES
78			The CIE standard used is the 1931 2-degree observer, and the
79			correct output representation relies on the original RADIANCE
80			input description being defined properly in terms of the standard
81			RADIANCE RGB primaries, whose CIE (x,y) chromaticity values are
82			defined in the header file in src/common/color.h.
83			In this same file is a standard for the luminous efficacy of white
84			light (WHTEFFICACY), which is used as a conversion between lumens
85			and watts throughout RADIANCE.
86			This same factor is applied by
87			.I ra_xyze
88			when converting between the radiometric units of the RGBE format
89			and the photometric units of the XYZE format.
90			The purpose of this factor is to ensure that the Y component of
91			the CIE representation is luminance in units of candelas/meter^2.
92			.PP
93			Most of the RADIANCE picture filters should work uniformly on either
94			RGBE or XYZE files, so it is not necessary to convert back to RGBE
95			format except for conversion or display, in which case the correct
96			primaries for the chosen output device should be specified with the
97			.I \-p
98			option if they are known.
99	greg	1.7	.PP
100			Similar to the
101			.I ra_rgbe(1)
102			tool,
103			.I ra_xyze
104			silently converts hyperspectral pictures (.hsr) on input,
105			but does so more accurately (and slowly) than
106			.I ra_rgbe.
107	greg	1.1	.SH EXAMPLES
108			To convert RGBE output from
109			.I rpict(1)
110			into run-length encoded XYZE format:
111			.IP "" .2i
112	greg	1.5	rpict [options] scene.oct \| ra_xyze \-c > scene_xyz.hdr
113	greg	1.1	.PP
114			To prepare a RADIANCE picture for display on a calibrated NTSC monitor:
115			.IP "" .2i
116	greg	1.5	ra_xyze \-r \-p .670 .330 .210 .710 .140 .080 .333 .333 stand.hdr ntsc.hdr
117	greg	1.1	.SH AUTHOR
118			Greg Ward
119			.SH BUGS
120			Any color correction applied to the original image is not removed
121			or translated by
122			.I ra_xyze,
123			and it may result in color shifts in the output.
124			If color preservation is important and the correction is unwanted,
125			it is best to remove it with
126			.I pfilt(1)
127			using the
128			.I \-er,
129			.I \-eg
130			and
131			.I \-eb
132			options first.
133			(Simply look at the header and apply the reciprocal primaries of all
134			COLORCORR= lines multiplied together.)
135			Better still, get the picture before color correction is applied.
136			.SH "SEE ALSO"
137	greg	1.6	pfilt(1), pvalue(1), ra_rgbe(1), rpict(1)