= aof2obj

*aof2obj* is a script to convert Artlantis Object Format files to Wavefront
OBJ; it can be used to have .aof files imported into 3D modeling programs
such as blender (http://blender.org).

Artlantis is a closed source 3D modeling and rendering software which can be
found at http://www.artlantis.com/

Artlantis Object Format is one of the formats produced by Artlantis.

Wavefront OBJ is a very common format used to interchange data about 3D
models, see https://en.wikipedia.org/wiki/Wavefront_.obj_file

*aof2obj* requires the lxml python module.

== Artlantis Object Format

The Artlantis Object Format is based on XML, it provides information about the
vertices of the model (<Points> element), the objects it is composed by,
the faces of the objects (<Polygons> element), the materials and the setup
for example rendering. The XML file also embeds a preview image
(<Preview.Image> element) of the rendering result.

Currently *aof2obj* supports only a small subset of these features, it was
written only as a quick script hacked together to see what was inside some AOF
files that can be found on the web.

Notes that the resulting models may need to be rescaled to become visible in
the viewport of the destination 3D program which will import the .obj files
produced by this script.

== Examples of .aof files

Some sample files can be found starting from this page:

 - http://www.polantis.com/ikea/expedit-bookcase

Having the same model in both .aof and .obj makes it a little easier to
reverse engineer the .aof format, even if its structure is very
straightforward already.

 - http://www.polantis.com/data/2/2/1093/formats/14/90/IKEA-Expedit_Bookcase-3d.aof
 - http://www.polantis.com/data/2/2/1093/formats/16/95/IKEA-Expedit_Bookcase-3d.obj

 - http://www.polantis.com/data/2/2/1094/formats/14/90/IKEA-Expedit_Bookcase_Black-3d.aof
 - http://www.polantis.com/data/2/2/1094/formats/16/95/IKEA-Expedit_Bookcase_Black-3d.obj

== PRW files

*aof2obj* extracts also the Artlantis Preview Files embedded into the Artlantis
Object Format files, and saves them with the .prw extension.

These files can be converted to ppm with the *prw2ppm* script.

The Artlantis Preview Files are bitmap images compressed using an RLE encoding.

There is a header with this structure:

  TWH

where T, W and H are respectively the file type, the image width and height,
as 32-bit big-endian integer values.

Immediately after the header there is the image data, which can be seen as divided into
packets of the format:

  CP+

Where C is the run count as a 32 bit big-endian integer, and P+ is
a sequence of 1 or more Pixels encoded as 32-bit big-endian integers with the
color information in the format 00RRGGBB.

[NOTE]
The rightmost byte was always zero in the analyzed files.

A .prw file looks like:

  TWHCPPPPCPCPCPCPCPPPPPPPPPCP...

The run counter C can refer to two types of packets:

  - run-length packet: here the single P value has to be repeated C times

  - raw packet: here C is followed by C different P pixels values

to decide if a packet is a 'run-length packet' or a 'raw packet' the last
pixel value of the previous packet has to be inspected: let be P and Q two
pixel values, and consider the sequence:

  PCQX

We have these rules:

 - if P == Q then C starts a run-length packet and Q is repeated C
   times and X will be the next run count,

 - if P != Q then C starts a raw packet and Q is the first pixel of a sequence
   of C different pixel values (X will be the second pixel value).

Some special treatment might be still needed to handle the count in the first
packet, in the analyzed files the first packet was always a 'run-length
packet', so this is the assumption *prw2ppm* relies on.

I call this RLE compression method the 'sandwich encoding', because the count
in run-length packets is between two identical pixel values.
