ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/src/cv/mgflib/spec.txt
Revision: 1.6
Committed: Fri Sep 2 16:04:13 1994 UTC (29 years, 8 months ago) by greg
Content type: text/plain
Branch: MAIN
Changes since 1.5: +15 -12 lines
Log Message:
corrected problems with cmix function (I think -- needs checking!)

File Contents

# User Rev Content
1 greg 1.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 greg 1.3 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 greg 1.1
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 greg 1.5 objects are to be scaled and placed in the final description. Hierarchical
72     contexts may be nested in any way, but should not overlap.
73 greg 1.1
74     Without further ado, here are the proposed entities and their interpretations:
75    
76     Keyword Arguments Meaning
77     ------- --------- -------
78     # anything a comment
79     i filename [xform] include file (with transformation)
80     ies filename [-m f][xform] include IES luminaire (with transformation)
81     v [id [= [template]]] get/set vertex context
82     p x y z set point position for current vertex
83     n dx dy dz set surface normal for current vertex
84     c [id [= [template]]] get/set color context
85     cxy x y set CIE (x,y) chromaticity for current color
86     cspec l_min l_max v1 v2 .. set relative spectrum for current color
87     cmix w1 c1 w2 c2 .. mix named colors to make current color
88     m [id [= [template]]] get/set material context
89 greg 1.3 sides {1|2} set number of sides for current material
90 greg 1.1 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 greg 1.5 prism v1 v2 v3 .. length truncated right prism (closed solid)
101 greg 1.1 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 greg 1.3 sides material
112 greg 1.1 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 greg 1.4 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 greg 1.1
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 greg 1.2 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 greg 1.1 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 greg 1.6 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     must 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 mixing
222     entity is intended not only for the mixing of named colors, but also
223     for color specifications using an arbitrary set of basis functions.
224     The mixing coefficients are in effect relative luminances for each
225     color "primary." The actual total of the mixing coefficients or
226     spectral values is irrelevant, since the results will always be
227     normalized.
228 greg 1.1
229     Diffuse emittance is always given in SI units of lumens/meter^2. Note that
230     this is emittance, not exitance, and does not include light reflected or
231     transmitted by the surface.
232    
233     The roughness associated with specular reflectance and transmittance
234     is the RMS surface facet slope. A value of 0 indicates a perfectly
235     smooth surface, meaning that reflected or transmitted rays will not
236     be scattered.
237    
238     The sum of the diffuse and specular reflectances and transmittances
239     must be strictly less than one (with no negative values, obviously).
240    
241     The object entity establishes a hierarchical context, consisting of
242     this identifier and all those preceding. It has no real meaning except
243     to group the following surfaces up until an empty object statement
244     under a descriptive name for improved file readability.
245    
246 greg 1.3 Surfaces are two-sided unless the "sides" entity is used to set the
247     number of sides for a material to one. If a surfaces is one-sided,
248     then it appears invisible when viewed from the back side. This means
249     that a transmitting object will affect the light coming in through the
250     front surface and ignore the characteristics of the back surface. As
251     long as the characteristics are the same, the results should be
252     correct. If the rendering technique does not allow for one-sided
253     surfaces, an approximately correct result can be obtained for one-sided
254     transmitting surfaces by using the square root of the given tau_s and
255     half the given alpha_t. If a rendering technique does not permit
256     two-sided surfaces, then each surface must be made into two for
257     full compliance if "sides" is set to 2 (the default).
258 greg 1.1
259     The surface normal of a face is oriented by the right-hand rule.
260     Specifically, the surface normal faces towards the viewer when the
261     vertices circulate counter-clockwise. Faces may be concave or convex,
262     but must be planar. Holes may be represented as concave polygons with
263     coincident sides (i.e. seams).
264    
265     A prism consists of a set of coplanar vertices specifying an end-face,
266     and a length value. The prism will be extruded so that the end-face
267     points outward, unless the length value is negative, in which case the
268     object is extruded in the opposite direction, resulting in inward-
269 greg 1.5 directed surface normals. If surface normals are specified for the
270     vertices, they will be applied to the side faces but not the end
271     faces, and they must generally point in the appropriate direction
272     (i.e. in or out depending on whether extrusion is negative or positive).
273 greg 1.1
274     A sphere, cylinder or cone with negative radii is interpreted as having
275     an inward facing surface normal. Otherwise, the normal is assumed
276     to face outwards. (It is illegal for a cone to have one positive and
277     one negative radius.)
278    
279     The central vertex for a ring or torus must have an associated normal,
280     which serves to orient the ring. The inner radius must be given first,
281     and must be strictly less than the outer radius. The inner radius may
282     be zero but not negative. There is an exception for a torus with
283     inward-pointing normal, which is identified by a negative outer radius
284     and a non-positive inner radius.
285    
286     Examples
287     ========
288     The following is a complete example input file (don't ask me what it is):
289    
290     # Define some materials:
291     m red_plastic =
292     c red =
293     cxy .8 .1
294     rd 0.5
295     # reestablish unnamed (neutral) color context:
296     c
297     rs 0.04 0.02
298     m green_plastic =
299     c green =
300     cxy .2 .6
301     rd 0.4
302     c
303     rs .05 0
304     m bright_emitter =
305     c
306     ed 1000
307     m dark =
308     c
309     rd .08
310     # Define some vertices:
311     v v1 =
312     p 10 5 7
313     v v2 =
314     p 15 3 9
315     v v3 =
316     p 20 -7 6
317     v v4 =
318     p 20 10 6
319     v v5 =
320     p 10 10 6
321     v v6 =
322     p 10 -7 6
323     v cv1 =
324     p -5 3 8
325     n 0 0 -1
326     v cv2 =
327     p -3 3 8
328     n 0 0 1
329     # make some faces:
330     m green_plastic
331     f v1 v3 v4
332     m red_plastic
333     f v3 v4 v5
334     f v5 v6 v7
335     m bright_emitter
336     f v3 v4 v5 v6
337     # make a cylindrical source with dark end caps:
338     m bright_emitter
339     cyl cv1 .15 cv2
340     m dark
341     ring cv1 0 .15
342     ring cv2 0 .15
343    
344     The following is a more typical example, which relies on a material library:
345    
346     # Include our materials:
347     i material.mgf
348     # Modify red_plastic to have no specular component:
349     m red_plastic
350     rs 0 0
351     # Make an alias for blue_plastic:
352     m outer_material = blue_plastic
353     # Make a new material based on brass, with greater roughness:
354     m rough_brass = brass
355     c brass_color
356     rs 0.9 0.15
357     # Load our vertices:
358     i lum1vert.mgf
359     # Modify appropriate vertices to make luminaire longer:
360     v v10
361     p 5 -2 -.1
362     v v11
363     p 5 2 -.1
364     v v8
365     p 5 2 0
366     v v9
367     p 5 -2 0
368     # Load our surfaces, rotating them -90 degrees about Z:
369     i lum1face.mgf -rz -90
370     # Make a 2-D array of sequins covering the face of the fixture:
371     m silver
372     i sequin.mgf -a 5 -t .5 0 0 -a 4 -t 0 .75 0
373    
374     Note that by using libraries and modifying values, it is possible to create
375     a variety of fixtures without requiring large files to describe each one.
376    
377     Interpretation
378     ==============
379     Interpretation of this language will be simplified by the creation
380     of a general parser that will be able to express the defined entities
381     in simpler forms and remove entities that would not be understood by
382     the caller.
383    
384     For example, a caller may ask the standard parser to produce only
385     the entities for diffuse uncolored materials, vertices without normals,
386     and polygons. The parser would then expand all include statements,
387     remove all color statements, convert spheres and cones to polygonal
388     approximations, and so forth.
389    
390     This way, a single general parser can permit software to operate
391     at whatever level it is capable, with a minimal loss of generality.
392     Furthermore, distribution of a standard parser will improve
393     both forward and backward compatibility as new entities are added
394     to the specification.
395    
396     Rationale
397     =========
398     Why create yet another file format for geometric data, when so many
399     others already exist? The main answer to this question is that we
400     are not merely defining geometry, but materials as well. Though the
401     number of committee and de facto standards for geometric data is large,
402     the number of standards for geometry + materials is small. Of these,
403     almost all are non-physical in origin, i.e. they are based on common,
404     ad hoc computer graphics rendering practices and cannot be used to create
405     physical simulations. Of the one or two formats that were intended
406     for or could be adapted to physical simulation, the syntax and semantics
407     are at the same time too complex and too limiting to serve as a suitable
408     standard.
409    
410     Specifically, establishing the above, new standard has the following
411     advantages:
412    
413     o It is easy to parse.
414     o It is easy to support, at least as a least common denominator.
415     o It is ASCII and fairly easy for a person to read and understand.
416     o It supports simple color, material and vertex libraries.
417     o It includes a simple yet fairly complete material specification.
418     o It is easy to skip unsupported entities (e.g. color, vertex normals)
419     o It supports transformations and instances.
420     o It is easy to add new entities, and as long as these entities can
421     be approximated by the original set, backwards compatibility
422     can be maintained through a standard parsing library.
423    
424     Most of the disadvantages of this format relate to its simplicity, but
425     since simplicity was our most essential goal, this could not be helped.
426     Specifically:
427    
428     o There is no general representation of curved surfaces (though
429     vertex normals make approximations straightforward).
430     o There are no general surface scattering functions.
431     o There are no textures or bump-maps.
432    
433     If any of these seems particularly important, I will look into adding them,
434     though they will tend to complicate the specification and make it more
435     difficult to support.