man/man1/oconv.1

.\" RCSid "$Id: oconv.1,v 1.7 2004/04/21 15:01:46 greg Exp $"
.TH OCONV 1 8/15/95 RADIANCE
.SH NAME
oconv - create an octree from a RADIANCE scene description
.SH SYNOPSIS
.B oconv
[
.B "\-i octree"
|
.B "\-b xmin ymin zmin size
][
.B "\-n objlim"
][
.B "\-r maxres"
][
.B \-f
][
.B \-w
][
-
]
[
.B "input .."
]
.SH DESCRIPTION
.I Oconv
adds each scene description
.I input
to
.I octree
and sends the result to the standard output.
Each
.I input
can be either a file name, or a command (enclosed in quotes
and preceded by a `!').
Similarly, the octree input may be given as a command preceded
by a `!'.
If any of the surfaces will not fit in
.I octree,
an error message is printed and the program aborts.
If no
.I octree
is given, a new one is created large enough for
all of the surfaces.
.PP
The
.I \-b
option allows the user to give a bounding cube for the
scene, starting at
.I "xmin ymin zmin"
and having a side length
.I size.
If the cube does not contain all of the surfaces, an error results.
The
.I \-b
and
.I \-i
options are mutually exclusive.
.PP
The
.I \-n
option specifies the maximum surface set size for
each voxel.
Larger numbers result in quicker octree generation,
but potentially slower rendering.
Smaller values may or may not produce faster renderings,
since the default number (6) is close to optimal for most scenes.
.PP
The
.I \-r
option specifies the maximum octree resolution.
This should be greater than or equal to the ratio of the largest
and smallest dimensions in the scene (ie. surface size or distance between 
surfaces).
The default is 16384.
.PP
The
.I \-f
option produces a frozen octree containing all the scene information.
Normally, only a reference to the scene files is stored in the
octree, and changes to those files may invalidate the result.
The freeze option is useful when the octree file's
integrity and loading speed is more important than its size, or
when the octree is to be relocated to another directory, and is
especially useful for creating library objects for the "instance"
primitive type.
If the input octree is frozen, the output will be also.
.PP
The
.I \-w
option suppresses warnings.
.PP
A hyphen by itself ('-') tells
.I oconv
to read scene data from its standard input.
This also implies the
.I \-f
option.
.PP
The only scene file changes that do not require octree regeneration are
modifications to non-surface parameters.
If the coordinates of a surface are changed, or any primitives are added
or deleted, oconv must be run again.
Programs will abort with a "stale octree" message
if they detect any dangerous inconsistencies between
the octree and the input files.
.PP
Although the octree file format is binary, it is meant to be portable
between machines.
The only limitation is that machines with radically different integer
sizes will not work together.
For the best results, the \-f option should be used if an octree is
to be used in different environments.
.SH DIAGNOSTICS
There are four basic error types reported by oconv:
.IP
warning - a non-fatal input-related error
.IP
fatal - an unrecoverable input-related error
.IP
system - a system-related error
.IP
internal - a fatal error related to program limitations
.IP
consistency - a program-caused error
.PP
Most errors are self-explanatory.
However, the following internal errors should be mentioned:
.IP "Too many scene files"
Reduce the number of scene files by combining them or using calls
to xform(1) within files to create a hierarchy.
.IP "Set overflow in addobject (id)"
This error occurs when too many surfaces are close together in a
scene.
Either too many surfaces are lying right on top of each other,
or the bounding cube is inflated from an oversized object
or an improper
.I \-b
specification.
If hundreds of triangles come together at a common vertex, it may
not be possible to create an octree from the object.
This happens most often when inane CAD systems create spheres using
a polar tessellation.
Chances are, the surface "id" is near one of those causing the problem.
.IP "Hash table overflow in fullnode"
This error is caused by too many surfaces.
If it is possible to create an octree for the scene at all,
it will have to be done in stages using the
.I \-i
option.
.SH EXAMPLE
To add book1, book2 and a
transformed book3 to the octree ``scene.oct'':
.IP "" .2i
oconv \-i scene.oct book1 book2 '\\!xform \-rz 30 book3' > newscene.oct
.SH AUTHOR
Greg Ward
.SH NOTES
In the octree, the names of the scene files are stored rather
than the scene information.
This means that a new octree must be generated whenever the
scene files are changed or moved.
Also, an octree that has been moved to a new directory will not be able to find
scene files with relative pathnames.
The freeze option avoids these problems.
.I make(1)
or
.I rad(1)
can be used to automate octree creation and maintenance.
.SH "SEE ALSO"
getbbox(1), getinfo(1), make(1), obj2mesh(1), rad(1),
rpict(1), rvu(1), rtrace(1), xform(1)
Revision:	1.8
Committed:	Tue Sep 4 17:36:40 2007 UTC (18 years, 2 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R4, rad5R2, rad5R3, rad5R0, rad5R1, rad4R2, rad6R0, rad4R1, rad4R0, rad3R9, rad4R2P1, rad4R2P2, HEAD
Changes since 1.7:	+3 -3 lines
Log Message:	Added backslashes in front of hyphens (thanks to Bernd Zeimetz for his effort)
#	Content
1	.\" RCSid "$Id: oconv.1,v 1.7 2004/04/21 15:01:46 greg Exp $"
2	.TH OCONV 1 8/15/95 RADIANCE
3	.SH NAME
4	oconv - create an octree from a RADIANCE scene description
5	.SH SYNOPSIS
6	.B oconv
7	[
8	.B "\-i octree"
9	\|
10	.B "\-b xmin ymin zmin size
11	][
12	.B "\-n objlim"
13	][
14	.B "\-r maxres"
15	][
16	.B \-f
17	][
18	.B \-w
19	][
20	-
21	]
22	[
23	.B "input .."
24	]
25	.SH DESCRIPTION
26	.I Oconv
27	adds each scene description
28	.I input
29	to
30	.I octree
31	and sends the result to the standard output.
32	Each
33	.I input
34	can be either a file name, or a command (enclosed in quotes
35	and preceded by a `!').
36	Similarly, the octree input may be given as a command preceded
37	by a `!'.
38	If any of the surfaces will not fit in
39	.I octree,
40	an error message is printed and the program aborts.
41	If no
42	.I octree
43	is given, a new one is created large enough for
44	all of the surfaces.
45	.PP
46	The
47	.I \-b
48	option allows the user to give a bounding cube for the
49	scene, starting at
50	.I "xmin ymin zmin"
51	and having a side length
52	.I size.
53	If the cube does not contain all of the surfaces, an error results.
54	The
55	.I \-b
56	and
57	.I \-i
58	options are mutually exclusive.
59	.PP
60	The
61	.I \-n
62	option specifies the maximum surface set size for
63	each voxel.
64	Larger numbers result in quicker octree generation,
65	but potentially slower rendering.
66	Smaller values may or may not produce faster renderings,
67	since the default number (6) is close to optimal for most scenes.
68	.PP
69	The
70	.I \-r
71	option specifies the maximum octree resolution.
72	This should be greater than or equal to the ratio of the largest
73	and smallest dimensions in the scene (ie. surface size or distance between
74	surfaces).
75	The default is 16384.
76	.PP
77	The
78	.I \-f
79	option produces a frozen octree containing all the scene information.
80	Normally, only a reference to the scene files is stored in the
81	octree, and changes to those files may invalidate the result.
82	The freeze option is useful when the octree file's
83	integrity and loading speed is more important than its size, or
84	when the octree is to be relocated to another directory, and is
85	especially useful for creating library objects for the "instance"
86	primitive type.
87	If the input octree is frozen, the output will be also.
88	.PP
89	The
90	.I \-w
91	option suppresses warnings.
92	.PP
93	A hyphen by itself ('-') tells
94	.I oconv
95	to read scene data from its standard input.
96	This also implies the
97	.I \-f
98	option.
99	.PP
100	The only scene file changes that do not require octree regeneration are
101	modifications to non-surface parameters.
102	If the coordinates of a surface are changed, or any primitives are added
103	or deleted, oconv must be run again.
104	Programs will abort with a "stale octree" message
105	if they detect any dangerous inconsistencies between
106	the octree and the input files.
107	.PP
108	Although the octree file format is binary, it is meant to be portable
109	between machines.
110	The only limitation is that machines with radically different integer
111	sizes will not work together.
112	For the best results, the \-f option should be used if an octree is
113	to be used in different environments.
114	.SH DIAGNOSTICS
115	There are four basic error types reported by oconv:
116	.IP
117	warning - a non-fatal input-related error
118	.IP
119	fatal - an unrecoverable input-related error
120	.IP
121	system - a system-related error
122	.IP
123	internal - a fatal error related to program limitations
124	.IP
125	consistency - a program-caused error
126	.PP
127	Most errors are self-explanatory.
128	However, the following internal errors should be mentioned:
129	.IP "Too many scene files"
130	Reduce the number of scene files by combining them or using calls
131	to xform(1) within files to create a hierarchy.
132	.IP "Set overflow in addobject (id)"
133	This error occurs when too many surfaces are close together in a
134	scene.
135	Either too many surfaces are lying right on top of each other,
136	or the bounding cube is inflated from an oversized object
137	or an improper
138	.I \-b
139	specification.
140	If hundreds of triangles come together at a common vertex, it may
141	not be possible to create an octree from the object.
142	This happens most often when inane CAD systems create spheres using
143	a polar tessellation.
144	Chances are, the surface "id" is near one of those causing the problem.
145	.IP "Hash table overflow in fullnode"
146	This error is caused by too many surfaces.
147	If it is possible to create an octree for the scene at all,
148	it will have to be done in stages using the
149	.I \-i
150	option.
151	.SH EXAMPLE
152	To add book1, book2 and a
153	transformed book3 to the octree ``scene.oct'':
154	.IP "" .2i
155	oconv \-i scene.oct book1 book2 '\\!xform \-rz 30 book3' > newscene.oct
156	.SH AUTHOR
157	Greg Ward
158	.SH NOTES
159	In the octree, the names of the scene files are stored rather
160	than the scene information.
161	This means that a new octree must be generated whenever the
162	scene files are changed or moved.
163	Also, an octree that has been moved to a new directory will not be able to find
164	scene files with relative pathnames.
165	The freeze option avoids these problems.
166	.I make(1)
167	or
168	.I rad(1)
169	can be used to automate octree creation and maintenance.
170	.SH "SEE ALSO"
171	getbbox(1), getinfo(1), make(1), obj2mesh(1), rad(1),
172	rpict(1), rvu(1), rtrace(1), xform(1)