Cyberspace Description Format (CDF)Reference Specification Proposal for VRMLIntroduction and Scope. 1.1. This document details a proposed standard text format for describing cyberspace decks and virtual worlds. It is based on Autodesk's internal experience using the Cyberspace Developer Kit CDF. As a result, this proposal contains some changes from the CDF found in CDK Versions 1.0 and 1.01. The specification reflects a change in focus from supporting the CDF as a proprietary developer's tool to promoting the CDF as a set of guidelines that will evolve towards an industry standard. 1.2. The purpose of the CDF is to provide a standard framework to store, retrieve, modify and exchange descriptions of cyberspace objects. These descriptions encompass object initialization, object state and object scheduling within a cyberspace simulation. 1.3. We start with a small core containing basic syntax, organizational and reference semantics. The next layer (level 2) contains semantics for creating certain classes of objects fundamental to all virtual worlds. The third layer (level 3) contains vendor-specific or experimental extensions in such a way that those extensions can be read or bypassed by a given CDF parser (see figure 1).
 Figure 1. CDF as a layered standard.
1.4. The CDF as an industry standard allows any number of implementations, just as today there are any number of implementations of DXF readers and writers. It gains this flexibility through layering and by allowing delegation of parsing of various resource files (such as DXF, 3DS, Inventor, OOGL, and others). For example, a given CDF parser may not itself know how to parse a 3DS file, but may delegate this task to a parser object for that capability as in figure 2. The sub-parser can either create native objects from the resource file, or rewrite it as CDF which can then be reparsed by the CDF parser.
 Figure 2. CDF Parser delegation. 1.5. The CDF describes cyberspace simulations, in which changing constellations of geometry and behaviour reflect some domain of interest, rather than merely assembling static geometrical scenes. Autodesk has created a large number of scene description classes in its Cyberspace Developer Kit that are expressible in CDF; however, the specification for these classes can apply equally well to a variety of class libraries. A proposed standard for these specifications is included in the second layer of the CDF. 1.6. There are a large number of possible kinds of cyberspace behaviours. The description of these behaviour types is in its infancy. Although Autodesk has several in-house behaviour description languages that can be expressed in CDF, creating a general framework for behaviour expression and interoperability is and will continue to be an ongoing issue. The CDF can help this effort by providing a basic syntax in which behaviour specification proposals can be expressed and evaluated. 1.7. This remainder of this document considers the purpose of the CDF as a VRML candidate, a set of design goals for the CDF, and the proposed syntax and semantics. CDF Design Goals This is a discussion of the design goals for the CDF. 2.1. Declarative, not procedural. The CDF strives to be independent of procedural semantics and particular language implementations, though interpretable code fragments or executables can be embedded within CDF extensions. A CDF file is a description of a cyberspace, or virtual world, and not a program to create one. 2.2. Platform-independent. CDF is simply a text format, and contains no bias towards any particular operating system or hardware platform. 2.3. Small and easily understandable. The CDF uses a layered strategy. A small, easily understood set of core elements containing the basic syntactic and semantic idioms are handled by all parsers. A second layer, built on top of the core, contains standard specification mechanisms to specify widely used constructs that are common to all 3D simulations. The specification contains extension protocols to enable the developer to experiment with additional layers on top of the first two. 2.4. Easy orientation within a CDF file by authors and readers. Authors and readers of a CDF file (both persons and software agents) can easily tell where they are in the file. 2.5. Concise. In as much as the standard is intended as a medium of exchange, CDF files and strings containing CDF fragments should impose a minimum burden on storage space and bandwidth. 2.6. Object oriented, but not to any particular programming language model. The CDF expresses that some particular object instance of a class or type is to be created and initialized with a particular set of attributes, while not mandating in what language the object class is implemented.
2.7. Expressive. All file formats enable the translation of text into some set of internal data structures within a program. These data structures are usually hierarchical in nature. The CDF provides a small set of "utility" built-in data structures within the format. It also provides a means for the CDF developer community to expand on this set on a per-project basis. 2.8. Expandable. The CDF enables both ad-hoc and per-project extensions, as well as a means to incorporate them into standard extension protocols. There are two dimensions along which these extensions can occur. First, the range of objects that can be described can easily be extended; second, more data structures can be added to describe values for object initialization descriptions. 2.9. Facilitates experimentation. The spirit of the CDF is to enable and encourage extensions to itself without violating basic parsability. 3. CDF Syntax. The CDF core syntax has three parts. The first is the reserved character set for object description; the second is the set of data types and structures expressible by the character set; the third is an protocol under which the number of data types can be extended. The use of several mandated data structures within the syntax sets the stage for greater compatibility between delegated parsers. Some programs use the resulting structures for an object's runtime state. Such a 1:1 mapping between the CDF and object state is intuitive and also facilitates trouble-shooting. 3.1. Character Set. 3.1.1. A CDF file or string is composed of whitespace (spaces, tabs, newlines and return characters), data types and any of the nine reserved characters % , ; , ( , ) , { , } , [ , ] and " . All other characters not part of the data type syntax are ignored by the parser, unless they occur within the string data type. White space and reserved characters that do not occur within the context of a double quoted string are treated as token separators. 3.1.2. Arithmetic and logical characters occurring singly or in conjunction with other such symbols not part of the reserved set in 3.1.1 are reserved for their use as arithmetic and logical symbols and shall not be used in any data type extension. They are read as strings unless they appear with other characters inside double quotes. These characters are ~ , ! , ^ , & , * , - , + , = , / , | , : , < and > . 3.2. Core Data Types.
3.2.1. Integers -- Integers are expressed as themselves. Unary minus is supported. For example, 0, -42, 138 are legal. Range is signed, 32-bit base 10 by default, though other ranges and bases can be specified by directions to the CDF reader functions. See also 4.6 on the file mode line. 3.2.2. Reals -- Real numbers are expressed as themselves. Unary minus is supported. Numbers between -1 and 1 (exclusive) have a leading zero to the left of the decimal point. For example, 0.12394729, -45.67, 78.9 are legal. Range is signed IEEE double precision. All reals are in base 10. If a real number is called for in an extended data type specification and an integer is offered, the integer is cast to a real. (While the number 3 is a real number, it is parsed as an integer.) 3.2.3. Strings -- Strings are expressed as follows. 3.2.3.1. Any sequence of characters between a double quote and the next double quote is read as a string. 3.2.3.2. Any non-double-quoted sequence of characters that does not contain whitespace or reserved characters and is not a number is read as a string. 3.2.3.3. All strings are case sensitive. 3.2.4. Tuples -- A tuple is delimited by parentheses ( ) and can contain any number of CDF data structures and data objects, including other tuples. All tuple elements are separated by spaces. Tuples are used as heterogeneous lists, as in Lisp. 3.2.5. Queues -- A queue is delimited by braces { } and can contain any number of CDF data structures or data objects. The structures or objects must be of the same type, e.g., all integers, all tuples, etc. 3.2.6. Dictionaries -- A dictionary is delimited by brackets [ ] and can contain any number of string-queue pairs. The string acts as the lookup key for the queue and items in the queue. Any number of items of the same type can be stored under the same key. The queue in the context of a dictionary is also called a value queue in this document. Thus:
[ A { B } ] -- A is a key to the value queue containing B;
the value of A is B.
[ A { B C } ] -- A is a key to the value queue containing B;
the value of A is B and C.
[ A { { B C } } ] -- A is a key to the value queue
containing the queue containing B and C; the value of A is
{ B C }.
3.2.7.Comments -- Comments are any number of characters, reserved or not, that are preceded by a semicolon and terminated by a newline character. Comments are ignored (except for the mode line, see 4.6 below). In this, they are identical to Lisp style comments. 3.3. Extended Data Types 3.3.1 Data type syntax extension protocol -- A data structure extension is delimited by percent signs. The first percent sign is always followed by the name of the object type. This is followed by tokens as needed to specify the data type. For example, in the CDF extended data type package detailed below, % vector3 (5.8 6.2 35.78) % might specify a 3 dimensional vector with 5.8, 6.2 and 35.78 as the vector elements. The CDF core does not itself contain any of these extensions, only the means for specifying them. The CDF level 2 contains an extended data type package containing some of the basic data structures common to all 3D simulations. Vendors and developers can add their own packages as desired. Parsers that do not know of a particular extended data type ignore it and the object attribute of which it is a value. For linear algebra data types, a right-handed coordinate system is assumed. 3.3.2. CDF Extended Data Type Package -- The CDF level 2 contains a set of extended data types built on top of the core extension protocol. 3.3.2.1. Data block -- This is a block of data, which the parser regards as unstructured. The block can be any size. The CDF specification is:
% data_block ( readwrite_flag printable_flag executable_flag filename) % The readwrite_flag is one of READWRITE or READONLY. The printable_flag is one of PRINTABLE or NON_PRINTABLE. The executable_flag is EXECUTABLE or NON_EXECUTABLE. The filename is a filename string with the path information delimited by forward slashes. 3.3.2.2 3D vertex -- The CDF specification is:
% vertex3 ( x y z ) % where x, y, and z are real numbers. 3.3.2.3 3D vector -- The CDF specification is:
% vector3 ( x y z ) % where x, y, and z are real numbers. 3.3.2.4 3D matrix -- This is a PHIGS-style matrix of four columns: U,V,N,T. An invariant fourth row of ( 0 0 0 1) is assumed, so it is unnecessary to specify it. The matrix is therefore specifiable by three vectors and a vertex. The CDF specification is:
% matrix ( ux uy uz ) ( vx vy vz ) ( nx ny nz ) ( tx ty tz ) % where,
ux, uy and uz are real numbers in the U column vector, vx, vy and vz are real numbers in the V column vector, nx, ny and nz are real numbers in the N column vector, tx, ty and tz are real numbers in the T column vertex. 3.3.2.5Rotation -- These are similar to quaternions (an economical way to specify rotations) but are easier to specify. The CDF specification is:
% rotation theta ( x y z ) % where theta is the amount of rotation in radians and x, y and z are the components of the vector part of the rotation (the axis of rotation). Rotation around the axis is according to the right hand rule.
4. CDF Organization and Semantics. 4.1. The CDF organizes the data objects and extended data types into specifications for cyberspace objects around the section concept. A deck or virtual world specification in CDF is composed of a number of these sections. Each section encapsulates the specifications for a particular class or type hierarchy. For example, there might be a viewer section, a display section, a geometry section, a lights section and so on. For a particular application, sections should have unique names. Autodesk's CDK comes with its own set of sections, where each section groups class instance specifications from a different C++ class hierarchy. Developers and other vendors can also create their own sections for any class hierarchy or sub hierarchy, or map CDF into another language than C++. 4.2. A section is expressed as a dictionary, and has three entries. A mandatory section name string, e.g. GEOMETRY, DISPLAYS, VIEWERS, LIGHTS, MATERIALS. An optional defaults dictionary, containing such things as the default class name for objects in the hierarchy, usual initializer arguments, and so forth. A mandatory specs dictionary, containing object specification dictionaries kept under the object's name. Object specification dictionaries are attribute values kept under the attribute name key. The words section, defaults, specs, class and like are reserved. 4.3. In the example below, items have been indented for clarity. This is not necessary; in fact indentation and newline characters are not necessary at all.
[ section { mysection }
defaults { [ attribute_name_4 { on }
class { ThingAMaBob }
]
}
specs { [ object_name_1 { [ attribute_name_1 { 4 }
attribute_name_2 { yes }
attribute_name_3 { (F5 34 no ) }
]
}
object_name_2 { [ attribute_name_1 { 5 }
attribute_name_2 { no }
attribute_name_3 { (F24 9 no ) }
attribute_name_4 { off }
]
}
]
}
]
Figure 3. Section example. We could of course call the object_names and attribute_names anything we wanted. Each default attribute is applied to any object description that lacks an explicit value for that attribute. In figure 3, for the first object object_name_1, the value of attribute_name_4 is on. 4.4. Attributes of an object might contain direct references to its state, or initialization information, or code fragments, or filenames of DXF or 3DS information, or anything at all. The precise way the CDF description of a particular object is parsed and turned into an object is the responsibility of the developers of that object. 4.5. Section extension protocol -- There can be an unlimited number of different sections, so long as they have unique names. Vendor specific section names are to be prefixed by a vendor-specific sentinel. The form for this sentinel is several letters followed by an underscore. Autodesk reserves the sentinels "AD_" and "CY_". 4.6. Mode line -- The mode line contains information about how CDF is to be read within a text file. This includes integer base information and other directions for CDF reader. The mode line is contained on one comment line (preceded by a semicolon). The mode line is the first line of the file and only one mode line is allowed per file. The mode line is prefixed by a "; -*-" (semicolon hyphen star hyphen) symbol. After this delimiter are one or more variable : value; pairs, separated by semicolons. For example, if we wanted to set the integer base to 8 and the path default to "../../geom", we would use a mode line like this:
; -*- base : 8 ; path_default : "../../geom" No variable/value pairs are specified by the core CDF guidelines, only the syntax for expressing them. We will probably wish to incorporate some into the standard before its release. 4.7. Specification by example -- Object specifiers can be instructed to use the specification from another specified object within the same section. This makes the specification of similar items much easier, in that the author can in effect say "I want one of those with these modifications."
[ section { mysection }
defaults { [ class { ThingAMaBob }
attribute_name_2 { no }
attribute_name_4 { on }
]
}
specs { [ objectname_1 { [ attribute_name_1 { 4 }
attribute_name_2 { yes }
attribute_name_3 { ( F5 34 no ) }
attribute_name_4 { off }
]
}
objectname_2 { [ like { objectname_1 }
attribute_name_3 { ( F24 9 no ) }
]
}
]
}
]
Figure 4. Specification by example. In the preceding example, object_name_2 has the same values for attribute_name_1 and attribute_name_2 as does object_name_1. Attribute_name_3's value is different. Attribute_name_4 is taken from the "like" object, in this case object_name_1, so its value is "off". Attribute_name_2 is also taken from the "like" object specifier, rather than from the default. 4.8. Referring to objects built from other sections -- It is useful to have object specifiers in one section refer to other object specifiers in other sections. A viewer object instance, for example, may need to refer to one of several display object instances. 4.8.1 These references are done by placing section and object names in the attributes value queue. Thus, an XXX_VIEWER section might have a viewer_1 object specifier that refers to an object specified in the XXX_DISPLAYS section. The viewer_1 object specifier might would look like:
[ attribute_name_1 { value_1 }
display { section XXX_DISPLAYS display_name_1 }
...
]
Figure 5. Object specifier dictionary showing a reference. Objects and sections that are referred to must have been described previously in the file. If the parser finds that the first element of the queue is the word "section", it retrieves the second and third elements of the queue to find the section's name and name of the object within it. Exactly what it does with this information is up to the implementation. Typically an application would keep a database of the objects stored hierarchically under their section name and CDF specifier name, so that the objects are available to other sections. 4.8.2. This mechanism enables building up of arbitrary hierarchies. The following shows a possible CDF file that builds up a simple space of a room, a chair and a table. The classes and section names are fictional, this is just to show how cross referencing between sections works:
[ section { XXX_LIGHT }
defaults { [ class { XXXLight }
]
}
specs { [ light0 { [ type { ambient }
magnitude { 0.3 }
]
}
light1 { [ type { directed }
magnitude { 0.65 }
aim { %vector3 ( 1.0 1.0 -1.0 )% }
]
}
]
}
]
[ section { XXX_GEOMETRY }
defaults { [ file { /net/vajra/geom } ; your net path here
class { XXXGeometry }
space { section XXX_SPACE myspace }
]
}
specs { [ room_geom { [ file { room.3ds } ] }
chair_geom { [ file { chair.3ds } ] }
table_geom { [ file { table.dxf } ] }
]
}
]
[ section { XXX_ SIM_OBJECT }
defaults { [ class { XXXSimObj }
units { pounds feet seconds }
]
}
specs { [ room { [ geometry { section XXX_GEOMETRY room_geom }
location { %vertex3 ( 0 0 0 )% }
]
}
chair { [ class { XXXPhysical }
geometry { section XXX_GEOMETRY chair_geom }
contained_by { section XXX_SIM_OBJECTS room }
location { %vertex3 ( 5 0 5 )% }
rotation { %rotation 0.25 ( 0 1 0 )% }
mass { 10.0 }
]
}
table { [ like { section XXX_SIM_OBJECT chair }
geometry { section XXX_GEOMETRY chair_geom }
location { %vertex3 (10 0 10)% }
mass { 50.0 }
]
}
]
}
]
[ section { XXX_SPACE }
defaults { [ class { XXXSpace }
]
}
specs { myspace [ schedule { ( { section XXX_SIMOBJECT room }
{ section XXX_SIMOBJECT chair }
{ section XXX_SIMOBJECT table }
{ section XXX_LIGHT light0 }
{ section XXX_LIGHT light1 }
)
]
}
]
Figure 6. Simple scene description showing referencing. 4.9. Parser Delegation -- A program's CDF parser can delegate the parsing of non-CDF resource files to sub-parser objects, as in paragraph 1.4 and figure 2. A sub-parser can parse the resource file in one of several ways. It changes the resource into CDF and invokes the CDF reader recursively, It recognizes that the resource contains CDF and invokes the reader recursively, It reads, parses and converts the resource directly into one or more native objects to be used by the virtual world. These objects are either placed into an object database directly or held with the sub-parser object for later retrieval by the program. For example, a 3DS file contains a variety of scene information such as lights, materials, textures, polygonal meshes, and so forth. A class, 3DS_Parser, might be a part an object created as part of an XXX_EXTERNAL_RESOURCES section.
{specs [ bird_resource { [ class { 3DS_Parser }
Figure 7. Description of a resource.
Specifiers found in the file "bird.3ds" are converted to parsable CDF structures where possible and placed in the corresponding section with the appropriate sentinel characters, though as with references, the resulting descriptions must be parsed and the objects created before they can be referred to. Alternatively, the sub-parser can create the objects and store them and other sections can refer to them using the cross-reference mechanism described in 4.8. In our example, if you wanted to refer to the material "beakstuff" in the resource, the following CDF reference could be used: { section XXX_EXTERNAL_RESOURCES bird_resource MATERIALS beakstuff } CDF Parsers that understand how to parse XXX_EXTERNAL_RESOURCES will know how to deal with the extra items in the queue. The ability of a CDF parser to reference components of hierarchical structures such as geometry is dependent upon the sophistication of the delegated-to parser of the external resource that contains that structure. The internals of delegated parsers (beyond the storage of their results) are not specified by this document. 4.10 CDF Level 2 section extensions -- Level 2 contains section description proposals for scene description. We have omitted a MATERIALS section at this time, but have a detailed material section proposal in preparation. 4.10.1. Section GEOMETRY -- Geometry can either be obtained from a file or from a CDF description of simple parameterized closed figures. In either case, the geometrical object is called a component. Any component may contain other components. If geometry is obtained directly from a file, a delegated parser is used and the variable names used are:
path, string -- a file system path name (If not present, the section parser looks in the current directory), 4.10.1.1. If the non-CDF geometry file is parsed as an external resource as in 4.9, the resource may contain multiple components, as well as other information retrievable as per 4.9. In this case, the description of the geometry would contain:
resource, reference to resource -- a reference to a resource as in 4.9. 4.10.1.2. If the file is parsed as a GEOMETRY section object, all the geometry is placed as a hierarchy of objects under one component, and any other information in the file (including the names of the sub-components is not accessible. This is useful and more concise if the file contains non-hierarchical geometry (e.g., only a simple table or chair).
[ section { XXX_GEOMETRY }
defaults { [ class { XXX_Component } ] }
specs { [ chair_geom { [ file { chair.3ds }
scale { 1. 5 }
] } ] } ]
Figure 8. A GEOMETRY section. In this example, the chair_geom is found in the file chair.3ds. We aren't interested in anything else the file has to tell us, only the specific geometrical component of a chair. The scale factor enables us to uniformly resize the component; in this case the component will be a uniform 1.5 times the size it is specified as in the 3DS file. If, instead of a simple chair, the file contained several pieces of geometry, say, a footstool, a chair and a TV tray, they would all be created as a single hierarchically arranged component under "chair_geom". While a program familiar with the specific XXX_Component object could walk the geometry tree and retrieve the footstool, the footstool could not be referred to by any other CDF specification. If this capability is needed, see 4.10.2. The XXX_Component acts much like a delegated parser (in fact, it may invoke one), but throws away non-geometrical information. 4.10.1.3. A CDF spec for a simulation object in the virtual world that contains geometry refers to the Component (as in 4.8.2 or 4.9). 4.10.1.4. Parameterized closed figures that can be described in this section include box, cone, pyramid, cylinder, sphere, dome, nose, reducer, torus, and solid figures of extrusion and revolution. If the figures are supported as solids by the implementation, there is also a solid figure described by boolean operations on other solid figures. 4.10.1.5. Box -- A rectilinear parallelepiped. There are three ways of describing a box:
4.10.1.6. Cone -- A right circular cone, with option to truncate. There are two ways of describing a cone:
4.10.1.7. Dome -- A portion of a sphere, sometimes called a spherical sector of one base. There are two ways of describing a dome:
4.10.1.8 Nose -- A conical figure, with one end offset from the other like an air plane nose. If neither end of the nose has radius zero, the two end planes are parallel. There are two ways of describing a nose:
4.10.1.9 Pyramid -- The classical pyramid with a rectangular base. There are three ways to describe a pyramid.
4.10.1.10 Reducer -- A hollow cone, cylinder or nose, with center shaft of varying size. There are two ways to describe a reducer:
4.10.1.11 Sphere -- The number of longitude and latitude tessellations are equal.
4.10.1.12 Torus -- Orientation is through the hole. The major axis is centered on the hole. The minor axis is a circle centered in the ring.
4.10.1.13 Solid of Extrusion -- A closed polygon extruded some distance along a vector, where the polygon is defined by a sequence of coplanar vertices in a value queue. There are two ways to describe a solid of extrusion.
4.10.1.14 Solid of Revolution -- a radially symmetric figure defined by revolution of a polygon about an axis.
4.10.1.16 Solid Boolean -- A solid figure defined from a Boolean operation on two other solid figures.
4.10.1.17 Solid Creation -- Create a solid figure from a piece of geometry that encloses a single finite volume. Useful for creating solids that can partake in Boolean operations.
4.10.2. Section LIGHTS -- Lights can be of four types: point, spot, directed or ambient. These types have overlapping sets of parameters detailing position, aim, colour, distribution, and so forth. For each light parameter specified in this document, the parameter name and type will be followed with one or more of PSDA, (for Point, Spot, Directed, Ambient) indicating which light type it is appropriate for. Not all displays can handle all these of parameters.
4.10.3. Section VIEWERS -- A viewer defines a point of view in space, and optionally a means to move that point of view. All viewers have:
4.10.4. Section SIMS -- A Sim is an object to be simulated in a cyberspace simulation. It has properties such as geometry, mass and dynamical properties, location, orientation and behaviour. This document does not detail how behaviour is to be specified, but it is assumed that different kinds of behaviour will have their own sections yet to be defined. A sim may also have its own internal behaviour as part of its implementation. Sims do not use geometrical components directly, but create an instance of the component for their own use. In this way, geometrical descriptions can be reused by multiple sims in different locations. All sims can be described by the following variables:
Mass is not normally specified unless volume and/or density are unknown. For closed geometrical figures volume and other properties can often be calculated. Principal moments and principal axes are calculated by the physical sim object from these properties as needed by physical simulators.
Several dynamical properties can also be described:
4.10.5. Section SPACES -- A space is an organizing and scheduling container. Each entry in a space description contains a tuple of references to objects from a particular section that are to be included in and scheduled by the space. The names of these description variables include: lights, materials, geometry, viewers and sims. As more section types are used, spaces will be come more sophisticated to make use of them. 5. Contact Information Requests for further information and comments about this proposal should be directed to Carl Tollander, email carlt@autodesk.com.
|