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, 1 month ago) by greg
Branch:	MAIN
CVS Tags:	rad4R2, rad4R1, rad4R0, rad3R9, rad4R2P1, rad4R2P2
Changes since 1.3:	+3 -3 lines
Log Message:	Added backslashes in front of hyphens (thanks to Bernd Zeimetz for his effort)
#	Content
1	.\" RCSid "$Id: xform.1,v 1.3 2004/01/01 19:31:45 greg Exp $"
2	.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	xform \-n book1 \-rx 30 \-t 0 20 0 book > book1
171	.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	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	.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	genbox(1), gensurf(1), oconv(1), replmarks(1), rpict(1), rvu(1)