ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/src/cv/mgflib/spec.txt
Revision: 1.9
Committed: Fri Feb 28 20:19:26 2003 UTC (21 years, 1 month ago) by greg
Content type: text/plain
Branch: MAIN
CVS Tags: rad5R4, rad5R2, rad4R2P2, rad5R0, rad5R1, rad3R7P2, rad3R7P1, rad4R2, rad4R1, rad4R0, rad3R5, rad3R6, rad3R6P1, rad3R8, rad3R9, rad4R2P1, rad5R3, HEAD
Changes since 1.8: +1 -1 lines
Log Message:
Fixed RCSid's

File Contents

# Content
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.