1 |
MATERIALS AND GEOMETRY FORMAT |
2 |
SCCSid "$SunId$ LBL" |
3 |
|
4 |
Introduction |
5 |
============ |
6 |
The following file format is a simple ASCII representation of surface |
7 |
geometry and materials for the purpose of visible-light simulation |
8 |
and rendering. The overall objective of this format is to provide |
9 |
a very simple yet fairly complete modeling language that does not |
10 |
place unreasonable demands on the applications programmer or the |
11 |
object library creator. |
12 |
|
13 |
Similar to Wavefront's .OBJ file format, our format utilizes a |
14 |
number of object entities, one per line, some of which establish |
15 |
a context for the entities that follow. Specifically, there is |
16 |
a context for the current vertex, the current color, and the |
17 |
current material. The current vertex is used only for setting |
18 |
values related to that vertex. The current color is used for |
19 |
setting values related to that color, as well as by certain |
20 |
material attributes which take an optional color setting. |
21 |
The current material is used for setting material-related |
22 |
parameters, and for establishing the material for the following |
23 |
geometric entities. In addition to these three named contexts, |
24 |
there are two hierarchical (i.e. cumulative) contexts, the |
25 |
current transform and the current object name. |
26 |
|
27 |
Each entity is given by a short keyword, followed by space- or tab- |
28 |
delimited arguments on a single line. A single entity may be extended |
29 |
over multiple lines using a backslash ('\') character right before the |
30 |
end of line, though no extended line may exceed 512 characters in total |
31 |
length. (Given the current set of entities, even approaching 80 |
32 |
characters would be highly unusual.) |
33 |
|
34 |
Entities and Contexts |
35 |
===================== |
36 |
There are three contexts in effect at all times, current vertex, |
37 |
current color and current material. Initially, these contexts are |
38 |
unnamed, and have specific default values. The unnamed vertex is the |
39 |
origin. The unnamed color is neutral gray. The unnamed material is a |
40 |
perfect absorber. The unnamed contexts may be modified, but those |
41 |
modifications will not be saved. Thus, reestablishing an unnamed |
42 |
context always gets its initial default value. To save a new context |
43 |
or modify an old one, it must first be named. Entities associated with |
44 |
named contexts (i.e. "v", "c" and "m") may be followed by an identifier |
45 |
and an equals sign ('='), indicating a new context. If there is no |
46 |
equals, then the context must already be defined, and the appearance of |
47 |
the entity merely reestablishes this context. If the context id is |
48 |
followed by an equals, then a new context is defined, destroying any |
49 |
previous instance of that context name. Redefining or changing values |
50 |
of a context does not affect earlier uses of the same name, however. |
51 |
Contexts are always associated with a name id, which is any non-blank |
52 |
sequence of printing ASCII characters. An optional template may be |
53 |
given following the equals, which is a previously defined context to |
54 |
use as a source of default values for this definition. If no template |
55 |
is given, then the unnamed context of that type is used to set initial |
56 |
values. Named contexts continue until the next context definition of |
57 |
the same type. |
58 |
|
59 |
Hierarchical Contexts |
60 |
===================== |
61 |
Two entities define a second type of context, which is hierarchical. |
62 |
These are the transform ("xf") entity and the object ("o") entity. |
63 |
The object entity is used simply for naming collections of surfaces. |
64 |
An object entity with a name applies to the following surfaces up |
65 |
until an object entity with no name, which signifies the end of this |
66 |
object's scope. Object entities may be nested to any level, and |
67 |
can be thought of as parts and subparts of an enclosing global object. |
68 |
Note that this is strictly for ease of identification, and has no |
69 |
real meaning as far as the geometric description goes. In contrast, |
70 |
the transform entity is very significant as it determines how enclosing |
71 |
objects are to be scaled and placed in the final description. |
72 |
|
73 |
Without further ado, here are the proposed entities and their interpretations: |
74 |
|
75 |
Keyword Arguments Meaning |
76 |
------- --------- ------- |
77 |
# anything a comment |
78 |
i filename [xform] include file (with transformation) |
79 |
ies filename [-m f][xform] include IES luminaire (with transformation) |
80 |
v [id [= [template]]] get/set vertex context |
81 |
p x y z set point position for current vertex |
82 |
n dx dy dz set surface normal for current vertex |
83 |
c [id [= [template]]] get/set color context |
84 |
cxy x y set CIE (x,y) chromaticity for current color |
85 |
cspec l_min l_max v1 v2 .. set relative spectrum for current color |
86 |
cmix w1 c1 w2 c2 .. mix named colors to make current color |
87 |
m [id [= [template]]] get/set material context |
88 |
rd rho_d set diffuse reflectance for current material |
89 |
td tau_d set diffuse transmittance for current material |
90 |
ed epsilon_d set diffuse emittance for current material |
91 |
rs rho_s alpha_r set specular reflectance for current material |
92 |
ts tau_s alpha_t set specular transmittance for current material |
93 |
o [name] begin/end object context |
94 |
f v1 v2 v3 .. polygon using current material, spec. vertices |
95 |
sph vc radius sphere |
96 |
cyl v1 radius v2 truncated right cylinder (open-ended) |
97 |
cone v1 rad1 v2 rad2 truncated right cone (open-ended) |
98 |
prism v1 v2 v3 .. length right prism (closed solid) |
99 |
ring vc rmin rmax circular ring with inner and outer radii |
100 |
torus vc rmin rmax circular torus with inner and outer radii |
101 |
xf [xform] begin/end transformation context |
102 |
|
103 |
These are the context dependencies of each entity: |
104 |
|
105 |
Entities Contexts |
106 |
-------- -------- |
107 |
p, n vertex |
108 |
cxy, cspec, cmix color |
109 |
rd, td, ed, rs, ts color, material |
110 |
f, sph, cyl, cone, ring, torus, prism material, object, transformation |
111 |
|
112 |
Transformations |
113 |
=============== |
114 |
A rigid body transformation is given with the transform entity, or as |
115 |
part of an included file. The following transformation flags and |
116 |
arguments are defined: |
117 |
|
118 |
-t dx dy dz translate objects along the given vector |
119 |
-rx degrees rotate objects about the X-axis |
120 |
-ry degrees rotate objects about the Y-axis |
121 |
-rz degrees rotate objects about the Z-axis |
122 |
-s scalefactor scale objects by the given factor |
123 |
-mx mirror objects about the Y-Z plane |
124 |
-my mirror objects about the X-Z plane |
125 |
-mz mirror objects about the X-Y plane |
126 |
-i N repeat the following arguments N times |
127 |
-a N make an array of N geometric instances |
128 |
|
129 |
Transform arguments have a cumulative effect. That is, a rotation |
130 |
about X of 20 degrees followed by a rotation about X of -50 degrees |
131 |
results in a total rotation of -30 degrees. However, if the two |
132 |
rotations are separated by some translation vector, the cumulative |
133 |
effect is quite different. It is best to think of each argument as |
134 |
acting on the included geometric objects, and each subsequent transformation |
135 |
argument affects the objects relative to their new position/orientation. |
136 |
|
137 |
For example, rotating an object about its center requires translating |
138 |
the object back to the origin, applying the desired rotation, and translating |
139 |
it again back to its original position. |
140 |
|
141 |
Rotations are given in degrees counter-clockwise about a principal axis. |
142 |
That is, with the thumb of the right hand pointing in the direction |
143 |
of the axis, rotation follows the curl of the fingers. |
144 |
|
145 |
The transform command itself is also cumulative, and a transform |
146 |
command with no arguments is used to return to the previous |
147 |
condition. It is necessary that transforms and their end statements |
148 |
("xf" by itself) be balanced in a file, so that later or enclosing |
149 |
files are not affected. |
150 |
|
151 |
Transformations apply only to geometric types, e.g. polygons, spheres, etc. |
152 |
Vertices and the components that go into geometry are not directly affected. |
153 |
This is to avoid confusion and the inadvertent multiple application of a |
154 |
given transformation. |
155 |
|
156 |
Arrays |
157 |
====== |
158 |
The -a N transform specification causes the following transform |
159 |
arguments to be repeated along with the contents of the included |
160 |
objects N times. The first instance of the geometry will be in its |
161 |
initial location; the second instance will be repositioned according |
162 |
to the named transformation; the third instance will be repositioned by |
163 |
applying this transformation twice, and so on up to N-1 applications. |
164 |
|
165 |
Multi-dimensional arrays may be specified with a single include |
166 |
entity by giving multiple array commands separated by their |
167 |
corresponding transforms. A final transformation may be given |
168 |
by preceeding it with a -i 1 specification. In other words, the |
169 |
scope of an array command continues until the next -i or -a option. |
170 |
|
171 |
Other Details |
172 |
============= |
173 |
End of line may be any one of the sequences: linefeed ('\n'), carriage- |
174 |
return ('\r'), or a carriage return followed by a linefeed. |
175 |
|
176 |
Blank lines are ignored on the input, as are any blanks preceeding |
177 |
a keyword on a line. Indentation may improve readability, especially |
178 |
in context definitions. |
179 |
|
180 |
The comment character ('#') must be followed by at least one blank |
181 |
character (space or tab) for easy parsing. Like any other line, |
182 |
a comment may be extended to multiple lines using a backslash ('\'). |
183 |
|
184 |
Include filename paths are relative to the current file. Absolute |
185 |
paths are expressly forbidden. UNIX conventions should be used for the |
186 |
path separator ('/') and disk names should not be used (i.e. no |
187 |
"C:\file"). To further enhance portability across systems, directory |
188 |
names should be 8 characters or fewer with no suffix, filenames should |
189 |
fit within an 8.3 format, and all characters should be lower case. |
190 |
(They will be automatically promoted to upper case by DOS systems.) |
191 |
We suggest the standard suffix ".mgf" for "materials and geometry format". |
192 |
|
193 |
The XYZ coordinate system is right-handed, and lengths are always in |
194 |
SI meters. This is not really a limitation as the first statement |
195 |
in the file can always be a transform with the -s option to convert |
196 |
to a more convenient set of units. Included IES files will also start |
197 |
out in meters, and it is important to specify a transform into the |
198 |
local coordinate system. The -m option (preceeding any transform) |
199 |
may be used to specify an output multiplication factor. |
200 |
|
201 |
Vertex normals need not be normalized, and a normal equal to (0,0,0) indicates |
202 |
that the exact surface normal should be used. (This is the default.) |
203 |
|
204 |
Color in this system does not include intensity, only hue and |
205 |
saturation. Intensity, such as reflectance or emittance, is explicitly |
206 |
included in the other material parameters. All colors are absolute, |
207 |
e.g. spectral reflectance or transmittance under uniform white light. |
208 |
|
209 |
A CIE xy chromaticity pair is the most basic color specification. |
210 |
A full spectrum is the most general specification, and the starting |
211 |
(i.e. minimum) and ending (i.e. maximum) wavelengths are given along |
212 |
with a set of evenly spaced values. Wavelengths are given in nanometers, |
213 |
and must be within the range of 380-780. The spectral values themselves |
214 |
are located starting at the first wavelength and proceeding at even |
215 |
increments to the ending wavelength. The values in between will be |
216 |
interpolated as necessary, so there must be at least two specified points. |
217 |
The color mixing entity is intended not only for the mixing of named |
218 |
colors, but also for color specifications using an arbitrary set |
219 |
of basis functions. The actual totals for spectral and mixing |
220 |
coefficients is irrelevant, since the results will be normalized. |
221 |
|
222 |
Diffuse emittance is always given in SI units of lumens/meter^2. Note that |
223 |
this is emittance, not exitance, and does not include light reflected or |
224 |
transmitted by the surface. |
225 |
|
226 |
The roughness associated with specular reflectance and transmittance |
227 |
is the RMS surface facet slope. A value of 0 indicates a perfectly |
228 |
smooth surface, meaning that reflected or transmitted rays will not |
229 |
be scattered. |
230 |
|
231 |
The sum of the diffuse and specular reflectances and transmittances |
232 |
must be strictly less than one (with no negative values, obviously). |
233 |
|
234 |
The object entity establishes a hierarchical context, consisting of |
235 |
this identifier and all those preceding. It has no real meaning except |
236 |
to group the following surfaces up until an empty object statement |
237 |
under a descriptive name for improved file readability. |
238 |
|
239 |
Surfaces are one-sided, and appear invisible when viewed from the |
240 |
back side. This means that a transmitting object will affect the |
241 |
light coming in through the front surface and ignore the characteristics |
242 |
of the back surface. As long as the characteristics are the same, |
243 |
the results should be correct. If the rendering technique does not |
244 |
allow for one-sided surfaces, an approximately correct result can |
245 |
be obtained for transmitting surfaces by using the square root of |
246 |
the given tau_s and half the given alpha_t. |
247 |
|
248 |
The surface normal of a face is oriented by the right-hand rule. |
249 |
Specifically, the surface normal faces towards the viewer when the |
250 |
vertices circulate counter-clockwise. Faces may be concave or convex, |
251 |
but must be planar. Holes may be represented as concave polygons with |
252 |
coincident sides (i.e. seams). |
253 |
|
254 |
A prism consists of a set of coplanar vertices specifying an end-face, |
255 |
and a length value. The prism will be extruded so that the end-face |
256 |
points outward, unless the length value is negative, in which case the |
257 |
object is extruded in the opposite direction, resulting in inward- |
258 |
directed surface normals. |
259 |
|
260 |
A sphere, cylinder or cone with negative radii is interpreted as having |
261 |
an inward facing surface normal. Otherwise, the normal is assumed |
262 |
to face outwards. (It is illegal for a cone to have one positive and |
263 |
one negative radius.) |
264 |
|
265 |
The central vertex for a ring or torus must have an associated normal, |
266 |
which serves to orient the ring. The inner radius must be given first, |
267 |
and must be strictly less than the outer radius. The inner radius may |
268 |
be zero but not negative. There is an exception for a torus with |
269 |
inward-pointing normal, which is identified by a negative outer radius |
270 |
and a non-positive inner radius. |
271 |
|
272 |
Examples |
273 |
======== |
274 |
The following is a complete example input file (don't ask me what it is): |
275 |
|
276 |
# Define some materials: |
277 |
m red_plastic = |
278 |
c red = |
279 |
cxy .8 .1 |
280 |
rd 0.5 |
281 |
# reestablish unnamed (neutral) color context: |
282 |
c |
283 |
rs 0.04 0.02 |
284 |
m green_plastic = |
285 |
c green = |
286 |
cxy .2 .6 |
287 |
rd 0.4 |
288 |
c |
289 |
rs .05 0 |
290 |
m bright_emitter = |
291 |
c |
292 |
ed 1000 |
293 |
m dark = |
294 |
c |
295 |
rd .08 |
296 |
# Define some vertices: |
297 |
v v1 = |
298 |
p 10 5 7 |
299 |
v v2 = |
300 |
p 15 3 9 |
301 |
v v3 = |
302 |
p 20 -7 6 |
303 |
v v4 = |
304 |
p 20 10 6 |
305 |
v v5 = |
306 |
p 10 10 6 |
307 |
v v6 = |
308 |
p 10 -7 6 |
309 |
v cv1 = |
310 |
p -5 3 8 |
311 |
n 0 0 -1 |
312 |
v cv2 = |
313 |
p -3 3 8 |
314 |
n 0 0 1 |
315 |
# make some faces: |
316 |
m green_plastic |
317 |
f v1 v3 v4 |
318 |
m red_plastic |
319 |
f v3 v4 v5 |
320 |
f v5 v6 v7 |
321 |
m bright_emitter |
322 |
f v3 v4 v5 v6 |
323 |
# make a cylindrical source with dark end caps: |
324 |
m bright_emitter |
325 |
cyl cv1 .15 cv2 |
326 |
m dark |
327 |
ring cv1 0 .15 |
328 |
ring cv2 0 .15 |
329 |
|
330 |
The following is a more typical example, which relies on a material library: |
331 |
|
332 |
# Include our materials: |
333 |
i material.mgf |
334 |
# Modify red_plastic to have no specular component: |
335 |
m red_plastic |
336 |
rs 0 0 |
337 |
# Make an alias for blue_plastic: |
338 |
m outer_material = blue_plastic |
339 |
# Make a new material based on brass, with greater roughness: |
340 |
m rough_brass = brass |
341 |
c brass_color |
342 |
rs 0.9 0.15 |
343 |
# Load our vertices: |
344 |
i lum1vert.mgf |
345 |
# Modify appropriate vertices to make luminaire longer: |
346 |
v v10 |
347 |
p 5 -2 -.1 |
348 |
v v11 |
349 |
p 5 2 -.1 |
350 |
v v8 |
351 |
p 5 2 0 |
352 |
v v9 |
353 |
p 5 -2 0 |
354 |
# Load our surfaces, rotating them -90 degrees about Z: |
355 |
i lum1face.mgf -rz -90 |
356 |
# Make a 2-D array of sequins covering the face of the fixture: |
357 |
m silver |
358 |
i sequin.mgf -a 5 -t .5 0 0 -a 4 -t 0 .75 0 |
359 |
|
360 |
Note that by using libraries and modifying values, it is possible to create |
361 |
a variety of fixtures without requiring large files to describe each one. |
362 |
|
363 |
Interpretation |
364 |
============== |
365 |
Interpretation of this language will be simplified by the creation |
366 |
of a general parser that will be able to express the defined entities |
367 |
in simpler forms and remove entities that would not be understood by |
368 |
the caller. |
369 |
|
370 |
For example, a caller may ask the standard parser to produce only |
371 |
the entities for diffuse uncolored materials, vertices without normals, |
372 |
and polygons. The parser would then expand all include statements, |
373 |
remove all color statements, convert spheres and cones to polygonal |
374 |
approximations, and so forth. |
375 |
|
376 |
This way, a single general parser can permit software to operate |
377 |
at whatever level it is capable, with a minimal loss of generality. |
378 |
Furthermore, distribution of a standard parser will improve |
379 |
both forward and backward compatibility as new entities are added |
380 |
to the specification. |
381 |
|
382 |
Rationale |
383 |
========= |
384 |
Why create yet another file format for geometric data, when so many |
385 |
others already exist? The main answer to this question is that we |
386 |
are not merely defining geometry, but materials as well. Though the |
387 |
number of committee and de facto standards for geometric data is large, |
388 |
the number of standards for geometry + materials is small. Of these, |
389 |
almost all are non-physical in origin, i.e. they are based on common, |
390 |
ad hoc computer graphics rendering practices and cannot be used to create |
391 |
physical simulations. Of the one or two formats that were intended |
392 |
for or could be adapted to physical simulation, the syntax and semantics |
393 |
are at the same time too complex and too limiting to serve as a suitable |
394 |
standard. |
395 |
|
396 |
Specifically, establishing the above, new standard has the following |
397 |
advantages: |
398 |
|
399 |
o It is easy to parse. |
400 |
o It is easy to support, at least as a least common denominator. |
401 |
o It is ASCII and fairly easy for a person to read and understand. |
402 |
o It supports simple color, material and vertex libraries. |
403 |
o It includes a simple yet fairly complete material specification. |
404 |
o It is easy to skip unsupported entities (e.g. color, vertex normals) |
405 |
o It supports transformations and instances. |
406 |
o It is easy to add new entities, and as long as these entities can |
407 |
be approximated by the original set, backwards compatibility |
408 |
can be maintained through a standard parsing library. |
409 |
|
410 |
Most of the disadvantages of this format relate to its simplicity, but |
411 |
since simplicity was our most essential goal, this could not be helped. |
412 |
Specifically: |
413 |
|
414 |
o There is no general representation of curved surfaces (though |
415 |
vertex normals make approximations straightforward). |
416 |
o There are no general surface scattering functions. |
417 |
o There are no textures or bump-maps. |
418 |
|
419 |
If any of these seems particularly important, I will look into adding them, |
420 |
though they will tend to complicate the specification and make it more |
421 |
difficult to support. |