man/man1/falsecolor.1

.\" RCSid "$Id: falsecolor.1,v 1.15 2022/11/12 20:51:47 greg Exp $"
.TH "FALSECOLOR" "1" "12/12/11" "RADIANCE" ""
.SH "NAME"
falsecolor \- make a false color RADIANCE picture
.SH "SYNOPSIS"
.B falsecolor
[
.B "\-i input"
][
.B "\-p picture"
][
.B "\-cb | \-cl | \-cp | \-c0"
][
.B \-e
][
.B "\-s scale"
][
.B "\-d digits"
][
.B "\-l label"
][
.B "\-n ndivs"
][
.B "\-lw lwidth"
][
.B "\-lh lheight"
][
.B "\-log decades"
][
.B "\-m mult"
][
.B "\-odim ncols nrows
][
.B "\-orct xmin ymin xmax ymax
][
.B "\-pal palette"
][
.B "\-r redv"
][
.B "\-g grnv"
][
.B "\-b bluv"
]

.B falsecolor \-palettes
.SH "DESCRIPTION"
.I Falsecolor
produces a false color picture for lighting analysis.
Input is a rendered Radiance picture.
.PP 
By default, luminance is displayed on a linear scale from 0 to 1000 cd/m2, where
dark areas are purple and brighter areas move through blue, green, red to yellow.
A different scale can be given with the
.I \-s
option.
If the argument given to
.I \-s
begins with an "a" for "auto," then the maximum is used for scaling the result.
The default multiplier is 179, which converts from radiance or irradiance
to luminance or illuminance, respectively.
A different multiplier can be given with
.I \-m
to get daylight factors or whatever.
For a logarithmic rather than a linear mapping, the
.I \-log
option can be used, where
.I decades
is the number of decades below the maximum scale desired.
.PP 
The 
.I \-d 
option controls the max number of decimal places printed for legend
entries. The default is 3 decimal places.
.PP 
A legend is produced for the new image with a label given by the
.I \-l
option.
The default label is "cd/m2", which is appropriate for standard Radiance
images.
If the
.I \-i
option of
.I rpict(1)
was used to produce the image, then the appropriate label would be "Lux".
.PP 
If contour lines are desired rather than just false color, the
.I \-cl
option can be used.
These lines can be placed over another Radiance picture using the
.I \-p
option.
If the input picture is given with
.I \-ip
instead of
.I \-i,
then it will be used both as the source of values and as the picture
to overlay with contours.
The
.I \-cb
option produces contour bands instead of lines, where the thickness of
the bands is related to the rate of change in the image.
The
.I \-cp
option creates a posterization effect where colours are banded without
the background image showing through.
The
.I \-n
option can be used to change the number of contours (and corresponding
legend entries) from the default value of 8.
The
.I \-lw
and
.I \-lh
options may be used to change the legend dimensions from the default width
and height of 100x200.
A value of zero for either dimension eliminates the legend in the output.
.PP
The
.I \-c0
option turns off false color output entirely, and is really only useful
with the
.I \-odim
option to overlay a matrix of values, or the
.I \-e
option to print the extrema values, as described below.
The
.I \-c0
option simultaneously removes the legend.
.PP
The
.I \-odim
option sets the number of columns and rows to overlay
a value matrix on the false color output.
The
.I \-orct
option may be used to specify a subrectangle of the image to overlay,
where the minimum x and y picture coordinates for the lower-left
corner are given before the maximum coordinates corresponding
to the upper-right corner.
The input picture must still cover the entire image area and match
the underlying background dimensions.
.PP
The
.I \-e
option causes extrema points to be printed on the brightest and
darkest pixels of the input picture, on top of any matrix values.
.PP 
The
.I "\-pal"
option provides different color palettes for
.I falsecolor.
The current choices are
.I spec
for the old spectral mapping,
.I tbo
for the "turbo" spectral mapping,
.I hot
for a thermal scale,
.I eco
for a blue-red-yellow scale, and
.I pm3d
for a variation of the default mapping,
.I def.
A Radiance HDR image of all available palettes can be created with the 
.I \-palettes
option.
The remaining options,
.I "\-r, \-g,"
and
.I \-b
are for changing the mapping of values to colors.
These are expressions of the variable 
.I v,
where
.I v
varies from 0 to 1.
These options are not recommended for the casual user.
.PP 
If no
.I \-i
or
.I \-ip
option is used, input is taken from the standard input.
The output image is always written to standard output, which should
be redirected, and is frequently converted to a non-HDR image format.
.SH "EXAMPLES"
To create a false color image directly from
.I rpict(1):
.IP "" .2i
rpict \-vf default.vp scene.oct | falsecolor > scene.hdr
.PP
To show the available color palettes:
.IP "" .2i
falsecolor -palettes | ximage
.PP 
To create a logarithmic contour plot of illuminance values on a
Radiance image:
.IP "" .2i
rpict -i -vf default.vp scene.oct > irrad.hdr
.br 
rpict -vf default.vp scene.oct > rad.hdr
.br 
falsecolor -i irrad.hdr -p rad.hdr -cl -log 2 -l Lux > lux.hdr
.PP
To overlay a matrix of 3 columns by 4 rows on the image above:
.IP "" .2i
falsecolor -odim 3 4 -i irrad.hdr -p rad.hdr -cl -log 2 -l Lux > lux.hdr
.PP
The same but without false color lines:
.IP "" .2i
falsecolor -odim 3 4 -i irrad.hdr -p rad.hdr -c0 > lux.hdr
.SH "AUTHOR"
Greg Ward
.br 
Axel Jacobs (Perl port and -pal options)
.br
Taoning Wang added the "turbo" palette.
.br
David Geisler-Moroder & Stephen Wasilewski (Legend additions and improvements)
.SH "ACKNOWLEDGEMENT"
Work on this program was initiated and sponsored by the LESO
group at EPFL in Switzerland.
The 'eco' palette was sponsored by Foster + Partners in London.
.SH "SEE ALSO"
getinfo(1), pcomb(1), pcompos(1), pextrem(1), pfilt(1), pflip(1), protate(1),
psign(1), pvalue(1), ra_tiff(1), ra_bmp(1), rpict(1), ximage(1)
Revision:	1.16
Committed:	Tue Aug 15 23:39:58 2023 UTC (22 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R4, HEAD
Changes since 1.15:	+4 -2 lines
Log Message:	docs(falsecolor): clarified the -orct option
#	Content
1	.\" RCSid "$Id: falsecolor.1,v 1.15 2022/11/12 20:51:47 greg Exp $"
2	.TH "FALSECOLOR" "1" "12/12/11" "RADIANCE" ""
3	.SH "NAME"
4	falsecolor \- make a false color RADIANCE picture
5	.SH "SYNOPSIS"
6	.B falsecolor
7	[
8	.B "\-i input"
9	][
10	.B "\-p picture"
11	][
12	.B "\-cb \| \-cl \| \-cp \| \-c0"
13	][
14	.B \-e
15	][
16	.B "\-s scale"
17	][
18	.B "\-d digits"
19	][
20	.B "\-l label"
21	][
22	.B "\-n ndivs"
23	][
24	.B "\-lw lwidth"
25	][
26	.B "\-lh lheight"
27	][
28	.B "\-log decades"
29	][
30	.B "\-m mult"
31	][
32	.B "\-odim ncols nrows
33	][
34	.B "\-orct xmin ymin xmax ymax
35	][
36	.B "\-pal palette"
37	][
38	.B "\-r redv"
39	][
40	.B "\-g grnv"
41	][
42	.B "\-b bluv"
43	]
44
45	.B falsecolor \-palettes
46	.SH "DESCRIPTION"
47	.I Falsecolor
48	produces a false color picture for lighting analysis.
49	Input is a rendered Radiance picture.
50	.PP
51	By default, luminance is displayed on a linear scale from 0 to 1000 cd/m2, where
52	dark areas are purple and brighter areas move through blue, green, red to yellow.
53	A different scale can be given with the
54	.I \-s
55	option.
56	If the argument given to
57	.I \-s
58	begins with an "a" for "auto," then the maximum is used for scaling the result.
59	The default multiplier is 179, which converts from radiance or irradiance
60	to luminance or illuminance, respectively.
61	A different multiplier can be given with
62	.I \-m
63	to get daylight factors or whatever.
64	For a logarithmic rather than a linear mapping, the
65	.I \-log
66	option can be used, where
67	.I decades
68	is the number of decades below the maximum scale desired.
69	.PP
70	The
71	.I \-d
72	option controls the max number of decimal places printed for legend
73	entries. The default is 3 decimal places.
74	.PP
75	A legend is produced for the new image with a label given by the
76	.I \-l
77	option.
78	The default label is "cd/m2", which is appropriate for standard Radiance
79	images.
80	If the
81	.I \-i
82	option of
83	.I rpict(1)
84	was used to produce the image, then the appropriate label would be "Lux".
85	.PP
86	If contour lines are desired rather than just false color, the
87	.I \-cl
88	option can be used.
89	These lines can be placed over another Radiance picture using the
90	.I \-p
91	option.
92	If the input picture is given with
93	.I \-ip
94	instead of
95	.I \-i,
96	then it will be used both as the source of values and as the picture
97	to overlay with contours.
98	The
99	.I \-cb
100	option produces contour bands instead of lines, where the thickness of
101	the bands is related to the rate of change in the image.
102	The
103	.I \-cp
104	option creates a posterization effect where colours are banded without
105	the background image showing through.
106	The
107	.I \-n
108	option can be used to change the number of contours (and corresponding
109	legend entries) from the default value of 8.
110	The
111	.I \-lw
112	and
113	.I \-lh
114	options may be used to change the legend dimensions from the default width
115	and height of 100x200.
116	A value of zero for either dimension eliminates the legend in the output.
117	.PP
118	The
119	.I \-c0
120	option turns off false color output entirely, and is really only useful
121	with the
122	.I \-odim
123	option to overlay a matrix of values, or the
124	.I \-e
125	option to print the extrema values, as described below.
126	The
127	.I \-c0
128	option simultaneously removes the legend.
129	.PP
130	The
131	.I \-odim
132	option sets the number of columns and rows to overlay
133	a value matrix on the false color output.
134	The
135	.I \-orct
136	option may be used to specify a subrectangle of the image to overlay,
137	where the minimum x and y picture coordinates for the lower-left
138	corner are given before the maximum coordinates corresponding
139	to the upper-right corner.
140	The input picture must still cover the entire image area and match
141	the underlying background dimensions.
142	.PP
143	The
144	.I \-e
145	option causes extrema points to be printed on the brightest and
146	darkest pixels of the input picture, on top of any matrix values.
147	.PP
148	The
149	.I "\-pal"
150	option provides different color palettes for
151	.I falsecolor.
152	The current choices are
153	.I spec
154	for the old spectral mapping,
155	.I tbo
156	for the "turbo" spectral mapping,
157	.I hot
158	for a thermal scale,
159	.I eco
160	for a blue-red-yellow scale, and
161	.I pm3d
162	for a variation of the default mapping,
163	.I def.
164	A Radiance HDR image of all available palettes can be created with the
165	.I \-palettes
166	option.
167	The remaining options,
168	.I "\-r, \-g,"
169	and
170	.I \-b
171	are for changing the mapping of values to colors.
172	These are expressions of the variable
173	.I v,
174	where
175	.I v
176	varies from 0 to 1.
177	These options are not recommended for the casual user.
178	.PP
179	If no
180	.I \-i
181	or
182	.I \-ip
183	option is used, input is taken from the standard input.
184	The output image is always written to standard output, which should
185	be redirected, and is frequently converted to a non-HDR image format.
186	.SH "EXAMPLES"
187	To create a false color image directly from
188	.I rpict(1):
189	.IP "" .2i
190	rpict \-vf default.vp scene.oct \| falsecolor > scene.hdr
191	.PP
192	To show the available color palettes:
193	.IP "" .2i
194	falsecolor -palettes \| ximage
195	.PP
196	To create a logarithmic contour plot of illuminance values on a
197	Radiance image:
198	.IP "" .2i
199	rpict -i -vf default.vp scene.oct > irrad.hdr
200	.br
201	rpict -vf default.vp scene.oct > rad.hdr
202	.br
203	falsecolor -i irrad.hdr -p rad.hdr -cl -log 2 -l Lux > lux.hdr
204	.PP
205	To overlay a matrix of 3 columns by 4 rows on the image above:
206	.IP "" .2i
207	falsecolor -odim 3 4 -i irrad.hdr -p rad.hdr -cl -log 2 -l Lux > lux.hdr
208	.PP
209	The same but without false color lines:
210	.IP "" .2i
211	falsecolor -odim 3 4 -i irrad.hdr -p rad.hdr -c0 > lux.hdr
212	.SH "AUTHOR"
213	Greg Ward
214	.br
215	Axel Jacobs (Perl port and -pal options)
216	.br
217	Taoning Wang added the "turbo" palette.
218	.br
219	David Geisler-Moroder & Stephen Wasilewski (Legend additions and improvements)
220	.SH "ACKNOWLEDGEMENT"
221	Work on this program was initiated and sponsored by the LESO
222	group at EPFL in Switzerland.
223	The 'eco' palette was sponsored by Foster + Partners in London.
224	.SH "SEE ALSO"
225	getinfo(1), pcomb(1), pcompos(1), pextrem(1), pfilt(1), pflip(1), protate(1),
226	psign(1), pvalue(1), ra_tiff(1), ra_bmp(1), rpict(1), ximage(1)