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