man/man1/xform.1

.\" RCSid "$Id: xform.1,v 1.3 2004/01/01 19:31:45 greg Exp $"
.TH XFORM 1 6/4/99 RADIANCE
.SH NAME
xform - transform a RADIANCE scene description
.SH SYNOPSIS
.B xform
[
.B \-c
][
.B \-I
][
.B "\-n name"
][
.B "\-m newmod"
][
.B "\-f argfile"
][
.B xf0
][
.B "\-a n1 xf1 .."
][
.B "\-i 1 xff"
]
.B "file .."
.SH DESCRIPTION
.I Xform
transforms each scene description
.I file
according to the options given.
If no
.I file
is specified, the standard input is read.
The
.I \-c
option causes commands in the input not to be expanded.
The default is to execute all in line commands.
(See note below about file names.)\0
The
.I \-n
option causes all identifiers to be prefixed with
.I name.
The
.I \-m
option causes all surfaces to be given the modifier
.I newmod.
The
.I \-I
option causes all surfaces to be inverted, reversing their
surface normal orientations.
These options are followed by the transformation options,
which are described below.
.PP
The
.I \-f
option causes the
.I xform
command line to be constructed from the given file,
by inserting each line of the file at the
current point in the command argument list.
Each line in the file will result in a logically separate invocation of
.I xform,
and may may contain any valid
.I xform
arguments, including nested
.I \-f
options.
This is a convenient way to specify multiple copies of an object that
do not fit a regular array pattern, without having to actually execute
.I xform
many times.
Separate scene files may be specified this way as well, but remember
that the constructed command line must fit the format of initial options
.I "(-n, -m, -c, -I)"
followed by the transform then the scene files.
No initial options may appear after the first transform option, and
no transform options will be understood after the first named file.
In the special case where the argument to the
.I \-f
option is a hyphen ('-'),
.I xform
will take its arguments from the standard input.
Note that
.I xform
cannot simultaneously take its scene information from the standard input
if the option is used in this way.
Competely empty lines and lines beginning with a pound sign ('#') will be
silently ignored.
Beginning "!xform" or "xform" command names will also be ignored.
.PP
If one or more scene files are given on the command line,
.I xform
will search the RADIANCE library directories for each file.
(No search takes place if a file name begins with a '.', '/' or '~'
character.)\0
Unless the
.I \-c
option is present,
.I xform
will also change to that file's directory before loading it.
Thus, any commands executed within that file will happen in that
file's directory, which simplifies object hierarchy construction.
.PP
The transformation consists of a sequence of operations which
are executed in the order they appear.
.SH OPTIONS
.TP 10n
.BI -t " x y z"
Translate the scene along the vector
.I "x y z".
.TP
.BI -rx \ degrees
Rotate the scene
.I degrees
about the x axis.
A positive rotation corresponds to counter-clockwise
when looking down the axis.
.TP
.BI -ry \ degrees
Rotate the scene
.I degrees
about the y axis.
.TP
.BI -rz \ degrees
Rotate the scene
.I degrees
about the z axis.
.TP
.BI -s \ factor
Scale the scene by
.I factor.
.TP
.BR \-mx
Mirror the scene about the yz plane.
.TP
.BR \-my
Mirror the scene about the xz plane.
.TP
.BR \-mz
Mirror the scene about the xy plane.
.TP
.BI -i \ count
Iterate (repeat) the following transformation (up to the next
.I \-i
option)
.I count
times.
This option is primarily to support the
.I \-a
option, which is described below.
.SS Arrays
An array is a repeated transformation that results in a repeated object.
It is specified using the
.I \-a
option, which takes the number to repeat as its argument.
The objects will step by the transformation given between
this
.I \-a
option and the next
.I \-a
or
.I \-i
option.
The first object will have zero applications of the transform.
A two-dimensional array is given by two different transformations
each preceded by an array count.
.SH EXAMPLE
To rotate ``book'' 30 degrees about the x axis then
move 20 in y, prepending the name book1:
.IP "" .2i
xform \-n book1 \-rx 30 \-t 0 20 0 book > book1
.PP
To expand all commands and see what information is actually used by RADIANCE:
.IP "" .2i
xform scene | more
.PP
To create a two-dimensional array of 20 lights, after an initial rotation
and followed by a global translation (no command expansion):
.IP "" .2i
xform \-c \-rz 90 \-a 5 \-t 2 0 0 \-a 4 \-t 0 1.5 0 \-i 1 \-t 0 0 10 light
.SH ENVIRONMENT
RAYPATH         path to search for scene files
.SH AUTHOR
Greg Ward
.SH BUGS
Only regular (distortion-free) transformations are allowed.
.SH "SEE ALSO"
genbox(1), gensurf(1), oconv(1), replmarks(1), rpict(1), rvu(1)
Revision:	1.4
Committed:	Tue Sep 4 17:36:41 2007 UTC (18 years, 2 months ago) by greg
Branch:	MAIN
CVS Tags:	rad4R2P2, rad4R2P1, rad4R2, rad4R1, rad4R0, rad3R9
Changes since 1.3:	+3 -3 lines
Log Message:	Added backslashes in front of hyphens (thanks to Bernd Zeimetz for his effort)
#	User	Rev	Content
1	greg	1.4	.\" RCSid "$Id: xform.1,v 1.3 2004/01/01 19:31:45 greg Exp $"
2	greg	1.1	.TH XFORM 1 6/4/99 RADIANCE
3			.SH NAME
4			xform - transform a RADIANCE scene description
5			.SH SYNOPSIS
6			.B xform
7			[
8			.B \-c
9			][
10			.B \-I
11			][
12			.B "\-n name"
13			][
14			.B "\-m newmod"
15			][
16			.B "\-f argfile"
17			][
18			.B xf0
19			][
20			.B "\-a n1 xf1 .."
21			][
22			.B "\-i 1 xff"
23			]
24			.B "file .."
25			.SH DESCRIPTION
26			.I Xform
27			transforms each scene description
28			.I file
29			according to the options given.
30			If no
31			.I file
32			is specified, the standard input is read.
33			The
34			.I \-c
35			option causes commands in the input not to be expanded.
36			The default is to execute all in line commands.
37			(See note below about file names.)\0
38			The
39			.I \-n
40			option causes all identifiers to be prefixed with
41			.I name.
42			The
43			.I \-m
44			option causes all surfaces to be given the modifier
45			.I newmod.
46			The
47			.I \-I
48			option causes all surfaces to be inverted, reversing their
49			surface normal orientations.
50			These options are followed by the transformation options,
51			which are described below.
52			.PP
53			The
54			.I \-f
55			option causes the
56			.I xform
57			command line to be constructed from the given file,
58			by inserting each line of the file at the
59			current point in the command argument list.
60			Each line in the file will result in a logically separate invocation of
61			.I xform,
62			and may may contain any valid
63			.I xform
64			arguments, including nested
65			.I \-f
66			options.
67			This is a convenient way to specify multiple copies of an object that
68			do not fit a regular array pattern, without having to actually execute
69			.I xform
70			many times.
71			Separate scene files may be specified this way as well, but remember
72			that the constructed command line must fit the format of initial options
73			.I "(-n, -m, -c, -I)"
74			followed by the transform then the scene files.
75			No initial options may appear after the first transform option, and
76			no transform options will be understood after the first named file.
77			In the special case where the argument to the
78			.I \-f
79			option is a hyphen ('-'),
80			.I xform
81			will take its arguments from the standard input.
82			Note that
83			.I xform
84			cannot simultaneously take its scene information from the standard input
85			if the option is used in this way.
86			Competely empty lines and lines beginning with a pound sign ('#') will be
87			silently ignored.
88			Beginning "!xform" or "xform" command names will also be ignored.
89			.PP
90			If one or more scene files are given on the command line,
91			.I xform
92			will search the RADIANCE library directories for each file.
93			(No search takes place if a file name begins with a '.', '/' or '~'
94			character.)\0
95			Unless the
96			.I \-c
97			option is present,
98			.I xform
99			will also change to that file's directory before loading it.
100			Thus, any commands executed within that file will happen in that
101			file's directory, which simplifies object hierarchy construction.
102			.PP
103			The transformation consists of a sequence of operations which
104			are executed in the order they appear.
105			.SH OPTIONS
106			.TP 10n
107			.BI -t " x y z"
108			Translate the scene along the vector
109			.I "x y z".
110			.TP
111			.BI -rx \ degrees
112			Rotate the scene
113			.I degrees
114			about the x axis.
115			A positive rotation corresponds to counter-clockwise
116			when looking down the axis.
117			.TP
118			.BI -ry \ degrees
119			Rotate the scene
120			.I degrees
121			about the y axis.
122			.TP
123			.BI -rz \ degrees
124			Rotate the scene
125			.I degrees
126			about the z axis.
127			.TP
128			.BI -s \ factor
129			Scale the scene by
130			.I factor.
131			.TP
132			.BR \-mx
133			Mirror the scene about the yz plane.
134			.TP
135			.BR \-my
136			Mirror the scene about the xz plane.
137			.TP
138			.BR \-mz
139			Mirror the scene about the xy plane.
140			.TP
141			.BI -i \ count
142			Iterate (repeat) the following transformation (up to the next
143			.I \-i
144			option)
145			.I count
146			times.
147			This option is primarily to support the
148			.I \-a
149			option, which is described below.
150			.SS Arrays
151			An array is a repeated transformation that results in a repeated object.
152			It is specified using the
153			.I \-a
154			option, which takes the number to repeat as its argument.
155			The objects will step by the transformation given between
156			this
157			.I \-a
158			option and the next
159			.I \-a
160			or
161			.I \-i
162			option.
163			The first object will have zero applications of the transform.
164			A two-dimensional array is given by two different transformations
165			each preceded by an array count.
166			.SH EXAMPLE
167			To rotate ``book'' 30 degrees about the x axis then
168			move 20 in y, prepending the name book1:
169			.IP "" .2i
170	greg	1.4	xform \-n book1 \-rx 30 \-t 0 20 0 book > book1
171	greg	1.1	.PP
172			To expand all commands and see what information is actually used by RADIANCE:
173			.IP "" .2i
174			xform scene \| more
175			.PP
176			To create a two-dimensional array of 20 lights, after an initial rotation
177			and followed by a global translation (no command expansion):
178			.IP "" .2i
179	greg	1.4	xform \-c \-rz 90 \-a 5 \-t 2 0 0 \-a 4 \-t 0 1.5 0 \-i 1 \-t 0 0 10 light
180	greg	1.1	.SH ENVIRONMENT
181			RAYPATH path to search for scene files
182			.SH AUTHOR
183			Greg Ward
184			.SH BUGS
185			Only regular (distortion-free) transformations are allowed.
186			.SH "SEE ALSO"
187	greg	1.3	genbox(1), gensurf(1), oconv(1), replmarks(1), rpict(1), rvu(1)