The unofficial guide to the complete Inivis AC3D fileformat specification (This document last updated 13th March 2017)
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 or AC3Dc
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 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 (used in AC3Db)
MAT %s (this block used in AC3Dc)
rgb %f %f %f
amb %f %f %f
emis %f %f %f
spec %f %f %f
shi %d
trans %f
data %d
lines of data
ENDMAT
OBJECT %s
*name %s
*data %d
*data lines of %s
*texture %s
*texrep %f %f
*texoff %f %f
*subdiv %d
*crease %f
*rot %f %f %f %f %f %f %f %f %f
*loc %f %f %f
*url %s
*hidden
*locked
*folded
*numvert %d
numvert lines of %f %f %f
*numsurf %d
*SURF %d
*mat %d
refs %d
refs lines of %d %f %f
kids %d
Materials are defined differently in AC3Db and AC3Dc.
rgb - diffuse color
amb - ambient color
emis - emissive color
spec - specular spot color
shi - specular spot size (higher number means smaller spot)
trans - transparency
Material section for AC3Db:
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. All floats are from 0-1. Shi goes from 0-128 inclusive.
Material section for AC3Dc:
MAT (name)
rgb %f %f %f
amb %f %f %f
emis %f %f %f
spec %f %f %f
shi %d
trans %f
data %d
lines of data
ENDMAT
multiple lines describing a material. These are referenced by the "mat"
token of a surface. The first "MAT" in the file will be indexed as
zero. The materials are usually all specified at the start of the file,
immediately after the header. All floats are from 0-1. Shi goes from 0-128 inclusive.
Data is optional. Usually contains an description or notes about a material.
The parameter is an integer which specifies the number of characters
(starting on the next line) to be read, newlines can be used also.
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 and light. Notice that the light object is a pointlight with no
possibility to change any of its lightning parameters.
*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 interger which specifies the number of characters
(starting on the next line) to be read, newlines can be used also.
*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.
*texoff %f %f
Optional - default 0.0,0.0 . The texture UV offset values for texture
on an object's surfaces.
Notice the final UV value of a face becomes: UV*texrep+texoff
*subdiv %d
Optional - default 0. Change subdivision level. Also at the same time the mesh will be smoothed.
*crease %f
The angle in degrees between normals, below which smoothing will take place for smooth surfaces.
*rot %f %f %f %f %f %f %f %f %f
The 3x3 rotation/scale matrix for this objects vertices. Note that the rotation/scale 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
The matrix is interpreted as this:
rot 1 2 3 4 5 6 7 8 9
Will give:
1 4 7
2 5 8
3 6 9
*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.
*hidden
If this object should be hidden.
*locked
If this object should not be able to be manipulated as long as its locked.
*folded
If this object should be folded (collapsed) in the hierarchy dialog.
*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 %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.
Some examples:
0X0 - single-sided flat face
0X10 - single-sided smooth face
0X20 - double-sided flat face
0X30 - double-sided smooth face
0x31 - Closed smooth double-sided line
0x32 - Open line, double-sided, smooth
0x12 - Open line, single-sided, smooth
0x11 - Closed line, single-sided, smooth
0x02 - Open line, single-sided, flat
0x01 - Closed line, single-sided, flat
etc. etc.
*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.
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.
Compiled and expanded from the official format old guide which dates back to 2003.
- Nikolai V. Chr.