1 |
greg |
1.1 |
.\" RCSid "$Id" |
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 (5) 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 8192. |
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 |
|
|
Sometimes a dense scene can be accomodated by increasing |
136 |
|
|
the maximum resolution (by powers of two) using the |
137 |
|
|
.I \-r |
138 |
|
|
option, but usually this error indicates something is wrong. |
139 |
|
|
Either too many surfaces are lying right on top of each other, |
140 |
|
|
or the bounding cube is inflated from an oversized object |
141 |
|
|
or an improper |
142 |
|
|
.I \-b |
143 |
|
|
specification. |
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), rad(1), |
172 |
|
|
rpict(1), rview(1), rtrace(1), xform(1) |