1 |
.\" RCSid "$Id: oconv.1,v 1.5 2004/01/01 19:31:45 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 tesselation. |
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) |