man/man1/ximage.1

.\" RCSid "$Id: ximage.1,v 1.9 2019/07/20 02:07:23 greg Exp $"
.TH XIMAGE 1 10/27/98 RADIANCE
.SH NAME
ximage - RADIANCE picture display for X window system
.SH SYNOPSIS
.B ximage
[
.B \=geometry
][
.B "\-di display"
][
.B "\-c ncolors"
][
.B \-d
][
.B \-b
][
.B \-m
][
.B "\-g gamma"
][
.B \-f
][
.B "\-e spec
][
.BI -o spec
][
.B "\-t intvl"
][
.B \-s
]
.B "picture .."
.SH DESCRIPTION
.I Ximage
takes one or more RADIANCE picture files
and displays them on an X server.
The
.I \-c
option specifies the number of colors to use (default fills color table).
The
.I \-d
option turns off color dithering.
The
.I \-b
option displays the image in black and white (greyscale).
The
.I \-m
option forces monochrome output.
The
.I \-g
option specifies the exponent used in gamma correction;
the default value is 2.2.
The
.I \-f
option stores a Pixmap on the server side for faster refresh.
This may not work with large images on some servers.
The
.I \-o
option specifies a sequence of information to print to the standard
output for the 't' command (see below).
The
.I \-t
option specifies a minimum interval (in milliseconds)
between successive ray outputs
in mouse tracking mode (right button pressed).
.PP
The
.I \-e
option specifies an exposure compensation in f-stops (powers of two).
Only integer stops are allowed, for efficiency.
If the special word,
.I auto
is given instead of a number of stops, then
.I ximage
performs an automatic exposure adjustment similar to
.I pcond(1),
compressing the dynamic range of the image to fit
within the dynamic range of the display.
If the special word,
.I human
is given instead, then
.I ximage
performs an exposure adjustment similar to
.I pcond
with the
.I \-s
and
.I \-c
options, which compensate for human contrast and color sensitivity
at the corresponding scene luminance levels.
This option yields and appearance of the scene on the display that
closely matches what would be experienced in the real world.
.PP
The
.I \-s
option tells
.I ximage
to display multiple pictures sequentially, rather than all at once.
If no
.I picture
is given, input is read from stdin provided either the
.I \-b
or
.I \-m
option is in effect, or the X server is capable of 24-bit color.
However, many of the commands given below will not work.
.SH COMMANDS
Once a picture is displayed, the user
may perform a number of operations.
Some of the operations make use of an area of interest, defined by pressing
the left mouse button and dragging the cursor over a section of the image.
Pressing the button and immediately releasing it defines a single point as
the area of interest.
A command is a single character.
.TP 10n
.BR q
Quit picture.
(Also Q or ^D.)\0
.TP 10
.BR <space>
Redraw the area of interest.
.TP 10
.BR ^R
Redraw the entire image.
.TP
.BR <return>
Display the radiance averaged over the area of interest.
The maximum of the three (RGB) channels is reported.
.TP
.BR l
Display the photometrically-weighted luminance value in the area of interest.
This assumes that the image was correctly computed in terms of
luminance.
.TP
.BR c
Display the color in the area of interest, as adjusted by the current
exposure setting.
.TP
.BR p
Display the x and y location of the cursor.
.TP
.BR i
Identify identical pixels by assigning a random color at the cursor position.
This is useful for displaying contours, especially when combined
with the \-b option.
.TP
.BR t
Print information about the pixel under the cursor
according to the string following the
.I \-o
command line option.
The valid characters for this option correspond roughly to the other
.I ximage
commands:
.IP
o       ray origin
.IP
d       ray direction
.IP
v       radiance value
.IP
l       luminance value
.IP
p       pixel position
.IP
The default output is "\-ood", which prints
the ray origin and direction.
This can be used as input to rtrace(1) to get additional information
about the image (ie. pipe the output of ximage into rtrace).
Pressing the middle mouse button is equivalent to typing the 't' key.
Pressing and holding the right mouse button is equivalent to
continuously pressing the 't' key.
.TP
.BR =
Adjust the exposure to the area of interest.
A crude adjustment is made immediately, and the number of stops
is printed while the colors are resampled.
After a few seconds to a minute, the final image is redisplayed.
If the area of interest is already within 1/2 stop of the ideal,
no adjustment is made.
.TP
.BR @
Same as '=' command, only the exposure is adjusted to provide
roughly the same visibility for the selected region
on screen as a viewer would experience
in the actual space.
Like the 'l' command, this adjustment assumes that the image
has been correctly computed in terms of luminance.
(See also the 'h' command, below.)
.TP
.BR a
Perform automatic exposure compensation, as if
.I ximage
were started with the
.I "\-e auto"
option.
If a rectangular area has been selected, the pixels in this region
will be emphasized in the histogram, offering this area exposure preference.
(Each pixel within the rectangle will be weighted as 21 outside pixels.)
.TP
.BR h
Perform human expsoure compensation, as if
.I ximage
were started with the
.I "\-e human"
option.
See the 'a' command above regarding pixel weighting.
.TP
.BR 0
Reset the origin to the upper left corner of the image.
This command is used to restore the original image position after
using the shift or control key with the mouse to relocate the image
within the frame (see below).
.TP
.BR f
Switch on the fast redraw option
.I (\-f),
loading the image pixmap over to the server side.
This command is useful when network delays are causing slow image
refresh, and the user didn't notice it until after
.I ximage
was started.
.TP
.BR F
Switch off the fast redraw option.
This frees up some memory on the server, as well as the color table
for other windows.
.PP
In addition to the commands listed above, the control or shift key may
be held while the cursor is dragged to reposition the image within the
window.
.SH NOTES
Hyperspectral Radiance pictures (.hsr files) are understood and crudely
converted to RGB for display.
However, the colors may not be very accurate.
.SH "X RESOURCES"
radiance.gamma  the default gamma correction value
.SH ENVIRONMENT
DISPLAY_GAMMA           the default gamma correction value
.SH AUTHORS
Greg Ward
.br
Anat Grynberg (Paris)
.br
Philip Thompson (MIT)
.SH "SEE ALSO"
aedimage(1), normtiff(1), pcond(1), pfilt(1), rcode_depth(1),
rcode_ident(1), rcode_norm(1), rpict(1), rtrace(1),
rvu(1), xglaresrc(1), xshowtrace(1)
Revision:	1.10
Committed:	Tue Sep 10 20:24:42 2024 UTC (7 months, 3 weeks ago) by greg
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.9:	+5 -1 lines
Log Message:	feat(ra_bmp,ra_rgbe,ximage): Added quick conversion of spectral inputs to RGB
#	Content
1	.\" RCSid "$Id: ximage.1,v 1.9 2019/07/20 02:07:23 greg Exp $"
2	.TH XIMAGE 1 10/27/98 RADIANCE
3	.SH NAME
4	ximage - RADIANCE picture display for X window system
5	.SH SYNOPSIS
6	.B ximage
7	[
8	.B \=geometry
9	][
10	.B "\-di display"
11	][
12	.B "\-c ncolors"
13	][
14	.B \-d
15	][
16	.B \-b
17	][
18	.B \-m
19	][
20	.B "\-g gamma"
21	][
22	.B \-f
23	][
24	.B "\-e spec
25	][
26	.BI -o spec
27	][
28	.B "\-t intvl"
29	][
30	.B \-s
31	]
32	.B "picture .."
33	.SH DESCRIPTION
34	.I Ximage
35	takes one or more RADIANCE picture files
36	and displays them on an X server.
37	The
38	.I \-c
39	option specifies the number of colors to use (default fills color table).
40	The
41	.I \-d
42	option turns off color dithering.
43	The
44	.I \-b
45	option displays the image in black and white (greyscale).
46	The
47	.I \-m
48	option forces monochrome output.
49	The
50	.I \-g
51	option specifies the exponent used in gamma correction;
52	the default value is 2.2.
53	The
54	.I \-f
55	option stores a Pixmap on the server side for faster refresh.
56	This may not work with large images on some servers.
57	The
58	.I \-o
59	option specifies a sequence of information to print to the standard
60	output for the 't' command (see below).
61	The
62	.I \-t
63	option specifies a minimum interval (in milliseconds)
64	between successive ray outputs
65	in mouse tracking mode (right button pressed).
66	.PP
67	The
68	.I \-e
69	option specifies an exposure compensation in f-stops (powers of two).
70	Only integer stops are allowed, for efficiency.
71	If the special word,
72	.I auto
73	is given instead of a number of stops, then
74	.I ximage
75	performs an automatic exposure adjustment similar to
76	.I pcond(1),
77	compressing the dynamic range of the image to fit
78	within the dynamic range of the display.
79	If the special word,
80	.I human
81	is given instead, then
82	.I ximage
83	performs an exposure adjustment similar to
84	.I pcond
85	with the
86	.I \-s
87	and
88	.I \-c
89	options, which compensate for human contrast and color sensitivity
90	at the corresponding scene luminance levels.
91	This option yields and appearance of the scene on the display that
92	closely matches what would be experienced in the real world.
93	.PP
94	The
95	.I \-s
96	option tells
97	.I ximage
98	to display multiple pictures sequentially, rather than all at once.
99	If no
100	.I picture
101	is given, input is read from stdin provided either the
102	.I \-b
103	or
104	.I \-m
105	option is in effect, or the X server is capable of 24-bit color.
106	However, many of the commands given below will not work.
107	.SH COMMANDS
108	Once a picture is displayed, the user
109	may perform a number of operations.
110	Some of the operations make use of an area of interest, defined by pressing
111	the left mouse button and dragging the cursor over a section of the image.
112	Pressing the button and immediately releasing it defines a single point as
113	the area of interest.
114	A command is a single character.
115	.TP 10n
116	.BR q
117	Quit picture.
118	(Also Q or ^D.)\0
119	.TP 10
120	.BR <space>
121	Redraw the area of interest.
122	.TP 10
123	.BR ^R
124	Redraw the entire image.
125	.TP
126	.BR <return>
127	Display the radiance averaged over the area of interest.
128	The maximum of the three (RGB) channels is reported.
129	.TP
130	.BR l
131	Display the photometrically-weighted luminance value in the area of interest.
132	This assumes that the image was correctly computed in terms of
133	luminance.
134	.TP
135	.BR c
136	Display the color in the area of interest, as adjusted by the current
137	exposure setting.
138	.TP
139	.BR p
140	Display the x and y location of the cursor.
141	.TP
142	.BR i
143	Identify identical pixels by assigning a random color at the cursor position.
144	This is useful for displaying contours, especially when combined
145	with the \-b option.
146	.TP
147	.BR t
148	Print information about the pixel under the cursor
149	according to the string following the
150	.I \-o
151	command line option.
152	The valid characters for this option correspond roughly to the other
153	.I ximage
154	commands:
155	.IP
156	o ray origin
157	.IP
158	d ray direction
159	.IP
160	v radiance value
161	.IP
162	l luminance value
163	.IP
164	p pixel position
165	.IP
166	The default output is "\-ood", which prints
167	the ray origin and direction.
168	This can be used as input to rtrace(1) to get additional information
169	about the image (ie. pipe the output of ximage into rtrace).
170	Pressing the middle mouse button is equivalent to typing the 't' key.
171	Pressing and holding the right mouse button is equivalent to
172	continuously pressing the 't' key.
173	.TP
174	.BR =
175	Adjust the exposure to the area of interest.
176	A crude adjustment is made immediately, and the number of stops
177	is printed while the colors are resampled.
178	After a few seconds to a minute, the final image is redisplayed.
179	If the area of interest is already within 1/2 stop of the ideal,
180	no adjustment is made.
181	.TP
182	.BR @
183	Same as '=' command, only the exposure is adjusted to provide
184	roughly the same visibility for the selected region
185	on screen as a viewer would experience
186	in the actual space.
187	Like the 'l' command, this adjustment assumes that the image
188	has been correctly computed in terms of luminance.
189	(See also the 'h' command, below.)
190	.TP
191	.BR a
192	Perform automatic exposure compensation, as if
193	.I ximage
194	were started with the
195	.I "\-e auto"
196	option.
197	If a rectangular area has been selected, the pixels in this region
198	will be emphasized in the histogram, offering this area exposure preference.
199	(Each pixel within the rectangle will be weighted as 21 outside pixels.)
200	.TP
201	.BR h
202	Perform human expsoure compensation, as if
203	.I ximage
204	were started with the
205	.I "\-e human"
206	option.
207	See the 'a' command above regarding pixel weighting.
208	.TP
209	.BR 0
210	Reset the origin to the upper left corner of the image.
211	This command is used to restore the original image position after
212	using the shift or control key with the mouse to relocate the image
213	within the frame (see below).
214	.TP
215	.BR f
216	Switch on the fast redraw option
217	.I (\-f),
218	loading the image pixmap over to the server side.
219	This command is useful when network delays are causing slow image
220	refresh, and the user didn't notice it until after
221	.I ximage
222	was started.
223	.TP
224	.BR F
225	Switch off the fast redraw option.
226	This frees up some memory on the server, as well as the color table
227	for other windows.
228	.PP
229	In addition to the commands listed above, the control or shift key may
230	be held while the cursor is dragged to reposition the image within the
231	window.
232	.SH NOTES
233	Hyperspectral Radiance pictures (.hsr files) are understood and crudely
234	converted to RGB for display.
235	However, the colors may not be very accurate.
236	.SH "X RESOURCES"
237	radiance.gamma the default gamma correction value
238	.SH ENVIRONMENT
239	DISPLAY_GAMMA the default gamma correction value
240	.SH AUTHORS
241	Greg Ward
242	.br
243	Anat Grynberg (Paris)
244	.br
245	Philip Thompson (MIT)
246	.SH "SEE ALSO"
247	aedimage(1), normtiff(1), pcond(1), pfilt(1), rcode_depth(1),
248	rcode_ident(1), rcode_norm(1), rpict(1), rtrace(1),
249	rvu(1), xglaresrc(1), xshowtrace(1)