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