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
#	User	Rev	Content
1	greg	1.16	.\" RCSid "$Id: falsecolor.1,v 1.15 2022/11/12 20:51:47 greg Exp $"
2	greg	1.9	.TH "FALSECOLOR" "1" "12/12/11" "RADIANCE" ""
3			.SH "NAME"
4			falsecolor \- make a false color RADIANCE picture
5			.SH "SYNOPSIS"
6	greg	1.1	.B falsecolor
7			[
8			.B "\-i input"
9			][
10			.B "\-p picture"
11			][
12	greg	1.15	.B "\-cb \| \-cl \| \-cp \| \-c0"
13	greg	1.1	][
14			.B \-e
15			][
16			.B "\-s scale"
17			][
18	greg	1.13	.B "\-d digits"
19			][
20	greg	1.1	.B "\-l label"
21			][
22			.B "\-n ndivs"
23			][
24	greg	1.3	.B "\-lw lwidth"
25			][
26			.B "\-lh lheight"
27			][
28	greg	1.1	.B "\-log decades"
29			][
30			.B "\-m mult"
31			][
32	greg	1.15	.B "\-odim ncols nrows
33			][
34			.B "\-orct xmin ymin xmax ymax
35			][
36	greg	1.7	.B "\-pal palette"
37	greg	1.4	][
38	greg	1.1	.B "\-r redv"
39			][
40			.B "\-g grnv"
41			][
42			.B "\-b bluv"
43			]
44	greg	1.9
45			.B falsecolor \-palettes
46			.SH "DESCRIPTION"
47	greg	1.1	.I Falsecolor
48			produces a false color picture for lighting analysis.
49			Input is a rendered Radiance picture.
50	greg	1.9	.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	greg	1.1	A different scale can be given with the
54			.I \-s
55			option.
56	greg	1.4	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	greg	1.1	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	greg	1.9	.PP
70	greg	1.13	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	greg	1.1	A legend is produced for the new image with a label given by the
76			.I \-l
77			option.
78	greg	1.9	The default label is "cd/m2", which is appropriate for standard Radiance
79	greg	1.1	images.
80			If the
81	greg	1.9	.I \-i
82	greg	1.1	option of
83			.I rpict(1)
84			was used to produce the image, then the appropriate label would be "Lux".
85	greg	1.9	.PP
86	greg	1.1	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	greg	1.9	.I \-p
91	greg	1.1	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	greg	1.9	.I \-cp
104			option creates a posterization effect where colours are banded without
105			the background image showing through.
106			The
107	greg	1.1	.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	greg	1.3	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	greg	1.15	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	greg	1.16	.I \-odim
123	greg	1.15	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	greg	1.16	The input picture must still cover the entire image area and match
141			the underlying background dimensions.
142	greg	1.15	.PP
143	greg	1.1	The
144			.I \-e
145			option causes extrema points to be printed on the brightest and
146	greg	1.15	darkest pixels of the input picture, on top of any matrix values.
147	greg	1.9	.PP
148	greg	1.4	The
149	greg	1.7	.I "\-pal"
150			option provides different color palettes for
151	greg	1.4	.I falsecolor.
152	greg	1.7	The current choices are
153			.I spec
154			for the old spectral mapping,
155	greg	1.14	.I tbo
156			for the "turbo" spectral mapping,
157	greg	1.7	.I hot
158	greg	1.10	for a thermal scale,
159			.I eco
160	greg	1.11	for a blue-red-yellow scale, and
161	greg	1.7	.I pm3d
162			for a variation of the default mapping,
163			.I def.
164	greg	1.9	A Radiance HDR image of all available palettes can be created with the
165			.I \-palettes
166			option.
167	greg	1.1	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	greg	1.9	.PP
179	greg	1.1	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	greg	1.15	be redirected, and is frequently converted to a non-HDR image format.
186	greg	1.9	.SH "EXAMPLES"
187	greg	1.1	To create a false color image directly from
188			.I rpict(1):
189			.IP "" .2i
190	greg	1.6	rpict \-vf default.vp scene.oct \| falsecolor > scene.hdr
191	greg	1.10	.PP
192			To show the available color palettes:
193			.IP "" .2i
194			falsecolor -palettes \| ximage
195	greg	1.9	.PP
196	greg	1.1	To create a logarithmic contour plot of illuminance values on a
197			Radiance image:
198			.IP "" .2i
199	greg	1.15	rpict -i -vf default.vp scene.oct > irrad.hdr
200	greg	1.9	.br
201	greg	1.15	rpict -vf default.vp scene.oct > rad.hdr
202	greg	1.9	.br
203	greg	1.15	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	greg	1.9	.SH "AUTHOR"
213	greg	1.1	Greg Ward
214	greg	1.9	.br
215	greg	1.15	Axel Jacobs (Perl port and -pal options)
216			.br
217			Taoning Wang added the "turbo" palette.
218	greg	1.13	.br
219			David Geisler-Moroder & Stephen Wasilewski (Legend additions and improvements)
220	greg	1.9	.SH "ACKNOWLEDGEMENT"
221	greg	1.1	Work on this program was initiated and sponsored by the LESO
222	greg	1.15	group at EPFL in Switzerland.
223			The 'eco' palette was sponsored by Foster + Partners in London.
224	greg	1.1	.SH "SEE ALSO"
225			getinfo(1), pcomb(1), pcompos(1), pextrem(1), pfilt(1), pflip(1), protate(1),
226	greg	1.15	psign(1), pvalue(1), ra_tiff(1), ra_bmp(1), rpict(1), ximage(1)