man/man1/rsensor.1

.\" RCSid "$Id: rsensor.1,v 1.5 2012/06/14 22:42:21 greg Exp $"
.TH RSENSOR 1 4/11/2008 RADIANCE
.SH NAME
rsensor - compute sensor signal from a RADIANCE scene
.SH SYNOPSIS
.B rsensor
[
.B -n nprocs
][
.B -h
][
.B render options
]
[
.B $EVAR
]
[
.B @file
]
{
[
.B -rd nrays
][
.B -dn nsrc
][
.B sensor_view
]
.B sensor_file ..
}
.B octree
.br
.B rsensor
[
.B -h
]
{
[
.B -rd nrays
][
.B sensor_view
]
.B sensor_file ..
}
.B "."
.br
.B "rsensor [ options ] \-defaults"
.SH DESCRIPTION
.I Rsensor
traces rays outward from one or more specified illumination
sensors into the RADIANCE scene given by
.I octree,
sending the computed sensor value to the standard output.
(The octree may be given as the output of a command enclosed in quotes
and preceded by a `!'.)\0
In the second form, a single period ('.') is given in place of an
octree, and the origin and directions of the specified
number of rays will be printed on the standard output.
If these rays are later traced and added together, the results
will sum to a signal proportional to the given sensor distribution.
In the third form, the default values
for the options (modified by those options present)
are printed with a brief explanation.
.PP
Options may be given on the command line and/or read from the
environment and/or read from a file.
A command argument beginning with a dollar sign ('$') is immediately
replaced by the contents of the given environment variable.
A command argument beginning with an at sign ('@') is immediately
replaced by the contents of the given file.
.PP
The sensor files themselves will be searched for in the path
locations specified by the
.I RAYPATH
environment variable, similar to other types of Radiance
auxiliary files.
If the sensor file path begins with '/', '.' or '~', no search
will take place.
Before each sensor file, a separate view may be specified.
In this case, the view origin and direction will correspond to
the position and orientation of the sensor, and the view up
vector will determine the zero azimuthal direction of the sensor.
The fore clipping distance may be used as well, but other view
options will be ignored.
(See
.I rpict(1)
for details on how to specify a view.)\0
The actual data contained in the sensor file corresponds to the
.I SPOT
tab-separated matrix specification, where the
column header has "degrees" in the leftmost column, followed
by evenly-spaced azimuthal angles.
Azimuth angles must start at 0 and proceed to at least 270 degrees.
No symmetry is applied to missing values.
Each row begins with the polar angle, and is followed by the
relative sensitivity values for each direction.
Polar angles must start from 0 and continue to the edge of
the sensor's view.
Polar angles above the last row listed are assumed to have
zero sensitivity.
A low-resolution example of a sensor file is given below:
.sp
.nf
        degrees 0       90      180     270
        0       .02     .04     .02     .04
        45      .01     .02     .01     .02
        90      .001    .002    .001    .002
.fi
.sp
As well as different views, the number of samples may be changed between
sensors, where the
.I \-rd
option controls the number of ray samples sent at random, and the
.I \-dn
option controls the number of rays sent to each light source per sensor.
.PP
The
.I \-h
option toggles header output, which defaults to "on."
The
.I \-n
option may be used to specify multiple calculation processes on
systems with more than one CPU.
For additional options, consult the
.I rtrace(1)
man page.
The final
.I octree
argument must be given, as the octree cannot be read from the
standard input.
.SH EXAMPLES
To compute values for the same sensor with two different positions:
.IP "" .2i
rsensor -ab 2 -vf posA.vf mysens.dat -vf posB.vf mysens.dat scene.oct
.PP
To generate a set of rays corresponding to a given sensor and compute
the resulting signal with rtrace:
.IP "" .2i
rsensor -h -vf posC.vf mysens.dat . | rtrace -h scene.oct | total -m
.SH ENVIRONMENT
RAYPATH         the directories to check for auxiliary files.
.SH AUTHOR
Greg Ward for Architectural Energy Corporation
.SH "SEE ALSO"
oconv(1), rpict(1), rcontrib(1), rtrace(1)
Revision:	1.6
Committed:	Tue Jun 9 21:34:14 2015 UTC (9 years, 11 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R4, rad5R2, rad5R0, rad5R1, rad5R3, HEAD
Changes since 1.5:	+7 -1 lines
Log Message:	Added checks for extra and missing angles and documented behavior
#	User	Rev	Content
1	greg	1.6	.\" RCSid "$Id: rsensor.1,v 1.5 2012/06/14 22:42:21 greg Exp $"
2	greg	1.1	.TH RSENSOR 1 4/11/2008 RADIANCE
3			.SH NAME
4			rsensor - compute sensor signal from a RADIANCE scene
5			.SH SYNOPSIS
6			.B rsensor
7			[
8			.B -n nprocs
9			][
10	greg	1.2	.B -h
11			][
12			.B render options
13	greg	1.1	]
14			[
15			.B $EVAR
16			]
17			[
18			.B @file
19			]
20			{
21			[
22			.B -rd nrays
23			][
24			.B -dn nsrc
25			][
26			.B sensor_view
27			]
28			.B sensor_file ..
29			}
30			.B octree
31			.br
32	greg	1.4	.B rsensor
33			[
34			.B -h
35			]
36			{
37			[
38			.B -rd nrays
39			][
40			.B sensor_view
41			]
42			.B sensor_file ..
43			}
44			.B "."
45			.br
46	greg	1.1	.B "rsensor [ options ] \-defaults"
47			.SH DESCRIPTION
48			.I Rsensor
49			traces rays outward from one or more specified illumination
50			sensors into the RADIANCE scene given by
51			.I octree,
52			sending the computed sensor value to the standard output.
53			(The octree may be given as the output of a command enclosed in quotes
54			and preceded by a `!'.)\0
55	greg	1.4	In the second form, a single period ('.') is given in place of an
56			octree, and the origin and directions of the specified
57			number of rays will be printed on the standard output.
58			If these rays are later traced and added together, the results
59			will sum to a signal proportional to the given sensor distribution.
60			In the third form, the default values
61	greg	1.1	for the options (modified by those options present)
62			are printed with a brief explanation.
63			.PP
64			Options may be given on the command line and/or read from the
65			environment and/or read from a file.
66			A command argument beginning with a dollar sign ('$') is immediately
67			replaced by the contents of the given environment variable.
68			A command argument beginning with an at sign ('@') is immediately
69			replaced by the contents of the given file.
70			.PP
71			The sensor files themselves will be searched for in the path
72			locations specified by the
73			.I RAYPATH
74			environment variable, similar to other types of Radiance
75			auxiliary files.
76			If the sensor file path begins with '/', '.' or '~', no search
77			will take place.
78			Before each sensor file, a separate view may be specified.
79			In this case, the view origin and direction will correspond to
80			the position and orientation of the sensor, and the view up
81			vector will determine the zero azimuthal direction of the sensor.
82	greg	1.2	The fore clipping distance may be used as well, but other view
83			options will be ignored.
84	greg	1.1	(See
85	greg	1.3	.I rpict(1)
86	greg	1.1	for details on how to specify a view.)\0
87			The actual data contained in the sensor file corresponds to the
88			.I SPOT
89			tab-separated matrix specification, where the
90			column header has "degrees" in the leftmost column, followed
91			by evenly-spaced azimuthal angles.
92	greg	1.6	Azimuth angles must start at 0 and proceed to at least 270 degrees.
93			No symmetry is applied to missing values.
94	greg	1.1	Each row begins with the polar angle, and is followed by the
95			relative sensitivity values for each direction.
96	greg	1.6	Polar angles must start from 0 and continue to the edge of
97			the sensor's view.
98			Polar angles above the last row listed are assumed to have
99			zero sensitivity.
100	greg	1.1	A low-resolution example of a sensor file is given below:
101			.sp
102			.nf
103			degrees 0 90 180 270
104			0 .02 .04 .02 .04
105			45 .01 .02 .01 .02
106			90 .001 .002 .001 .002
107			.fi
108			.sp
109			As well as different views, the number of samples may be changed between
110			sensors, where the
111			.I \-rd
112			option controls the number of ray samples sent at random, and the
113			.I \-dn
114	greg	1.3	option controls the number of rays sent to each light source per sensor.
115	greg	1.1	.PP
116			The
117	greg	1.2	.I \-h
118			option toggles header output, which defaults to "on."
119			The
120	greg	1.1	.I \-n
121			option may be used to specify multiple calculation processes on
122			systems with more than one CPU.
123			For additional options, consult the
124	greg	1.3	.I rtrace(1)
125	greg	1.1	man page.
126			The final
127			.I octree
128			argument must be given, as the octree cannot be read from the
129			standard input.
130			.SH EXAMPLES
131			To compute values for the same sensor with two different positions:
132			.IP "" .2i
133			rsensor -ab 2 -vf posA.vf mysens.dat -vf posB.vf mysens.dat scene.oct
134	greg	1.4	.PP
135			To generate a set of rays corresponding to a given sensor and compute
136			the resulting signal with rtrace:
137			.IP "" .2i
138			rsensor -h -vf posC.vf mysens.dat . \| rtrace -h scene.oct \| total -m
139	greg	1.1	.SH ENVIRONMENT
140			RAYPATH the directories to check for auxiliary files.
141			.SH AUTHOR
142			Greg Ward for Architectural Energy Corporation
143			.SH "SEE ALSO"
144	greg	1.5	oconv(1), rpict(1), rcontrib(1), rtrace(1)