THE AC3D FILE FORMAT
Last stolen on Nov 3rd, 2004 from this official
site
Last modified on Nov 7th, 04
The AC3D file format is ascii text and is very simple to parse.
It's also very easy to generate AC3D files from your own data.
This document describes the structure of AC3D files.
Some simple examples are included at the end.
AC3D filenames usually have a '.ac' suffix.
For more information about AC3D, see
the official site
Overall structure
An AC3D file has this overall structure
(HEADER)
(Materials - the palette)
(objects)
Basic structure
This is the basic structure. %f indicates a floating point value, %d an
integer and %s a string (must be surrounded by quotes " if it contains spaces).
Lines beginning with a '*' indicate an optional section. The tokens are
case-sensitive. The indentation is used to show the structure of the file - a
real AC3D file has no indentation.
AC3D%d
MATERIAL %s rgb %f %f %f amb %f %f %f emis %f %f %f spec %f %f %f shi %d trans %f
OBJECT %s
*name %s
*data %d
*texture %s
*texrep %f %f
*rot %f %f %f %f %f %f %f %f %f
*loc %f %f %f
*crease %f
*url %s
*numvert %d
numvert lines of %f %f %f
*numsurf %d
*SURF %d
*mat %d
refs %d
refs lines of %d %f %f
kids %d
Header section
AC3D%d
An AC3D file always starts with a header line e.g.: "AC3Db"
The first four characters are always 'AC3D' the next hex number following
immediately defines the internal version of the file (0xb == 11).
If the version is later than the program knows about then it will probably
may refuse to load it. As new versions of the AC3D file format evolve, this number
is used to make the loading code backwards compatible.
To parse an AC3D file, you need something like this:
read the header (AC3Dx)
while not end of file
{
read a line
check first token on line
handle this tokens values (this might involve reading more lines)
}
Material section
MATERIAL (name) rgb %f %f %f amb %f %f %f emis %f %f %f spec %f %f %f shi %d trans %f
Single line describing a material. These are referenced by the "mat"
token of a surface. The first "MATERIAL" in the file will be indexed as
zero. The materials are usually all specified at the start of the file,
imediately after the header.
Object section
OBJECT %s
Specifies the start of an object. The end of the object section must
be a 'kids' line which indicates how many children objects (may be zero)
follow. The parameter is the object type - one of: world, poly,
group.
name
*name %s
Optional - a name for the object
data
*data %d
Optional - object data. Usually the object-data string for an object.
The parameter is an interger which specifies the number of characters
(starting on the next line) to be read.
texture
*texture %s
Optional - default is no texture. the path of the texture bitmap file
for the texture of the current object.
texrep
*texrep %f %f
Optional - default 1.0,1.0 . The texture repeat values for the tiling of a texture
on an object's surfaces.
rot
*rot %f %f %f %f %f %f %f %f %f
The 3x3 rotation matrix for this objects vertices. Note that the rotation
is relative to the object's parent i.e. it is not a global rotation matrix.
If this token is not specified then the default rotation matrix
is 1 0 0, 0 1 0, 0 0 1
loc
*loc %f %f %f
The translation of the object. Effectively the definition of the centre of the object. This is
relative to the parent - i.e. not a global position. If this is not found then
the default centre of the object will be 0, 0, 0.
crease
*crease %f
The crease attribute is an angle (degrees). This is used when calculating
normals for smoothing. You can change this in the tools->object-property-editor.
url
*url %s
The url of an object - default is blank.
numvert
*numvert %d
numvert lines of %f %f %f
The number of vertices in an object. Parameter specifies the number of
lins that follow. If this token is read then you MUST read
that many lines of (%f %f %f) - specifying each vertex point as a local
coordinate. Some objects (e.g. groups) may not have a numvert token.
numsurf
*numsurf %d
*SURF %d
*mat %d
refs %d
refs lines of %d %f %f
The number of surfaces that this object contains. The parameter specifies
the number of subsections that follow - each one being a different surface.
Surf section
SURF %d
The start of a surface. The parameter specifies the surface type and flags.
The first 4 bits (flags & 0xF) is the type (0 = polygon, 1 = closedline,
2 = line). The next four bits (flags >> 4) specify the shading and
backface. bit1 = shaded surface bit2 = twosided.
mat
*mat %d
The index to the material that this surface has.
refs
refs %d
refs lines of %d %f %f
The number of vertices in the surface. This number indicates the number of lines
following. Each line contains an index to the vertex and the texture coordinates
for this surface vertex.
kids
kids %d
This is the final token of an object section and it must exist. If the parameter
is a number > 0 then more objects are recursively loaded as children of the
current object.
Here is an example file - a simple rectangle (white)
AC3Db
MATERIAL "" rgb 1 1 1 amb 0.2 0.2 0.2 emis 0 0 0 spec 0.5 0.5 0.5 shi 10 trans 0
OBJECT world
kids 1
OBJECT poly
name "rect"
loc 1 0.5 0
numvert 4
-1 0.5 0
1 0.5 0
1 -0.5 0
-1 -0.5 0
numsurf 1
SURF 0x20
mat 0
refs 4
3 0 0
2 1 0
1 1 1
0 0 1
kids 0
Another example
An object with 7 vertices (no surfaces, no materials defined).
This is a good way of getting point data into AC3D.
The Vertex->create convex-surface/object can be used on these
vertices to 'wrap' a 3d shape around them
AC3Db
OBJECT poly
numvert 7
-0.83 -0.235 -0.04
-0.63 0.185 -0.04
-0.55 0.235 -0.25
-0.33 0.235 0.29
0.09 0.235 -0.29
0.33 -0.195 -0.04
0.83 0.005 -0.04
kids 0
If you write a loader then you least you need is code to handle the object
token, and the objects numvert/vertice and numsurf/sufaces - esentially
the geometry of the model. You can ignore any line that starts with a
token other than these e,g textures, rotation, location etc.