AC3D File Format

By ac3d.org

Last updated 27th March 2003

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 http://www.ac3d.org.

An AC3D file has this overall structure:

(HEADER)
(Materials - the palette)
(objects)

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)
    }

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.

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
	*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

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, immediately after the header.

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 %s

Optional - a name for the object

*data %d

Optional - object data. Usually the object-data string for an object. The parameter is an integer which specifies the number of characters (starting on the next line) to be read.

*texture %s

Optional - default is no texture. the path of the texture bitmap file for the texture of the current object.

*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 %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 %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.

*url %s

The url of an object - default is blank.

*numvert %d
	numvert lines of %f %f %f

The number of vertices in an object. Parameter specifies the number of lines 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 %d

The number of surfaces that this object contains. The parameter specifies the number of subsections that follow - each one being a different surface

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 %d

The index to the material that this surface has.

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 %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.

Example
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.