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