ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/src/cv/mgflib/spec.txt
Revision: 1.2
Committed: Wed Jun 29 16:15:27 1994 UTC (29 years, 10 months ago) by greg
Content type: text/plain
Branch: MAIN
Changes since 1.1: +5 -6 lines
Log Message:
made the -a (array) option work within files as well

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