+= 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.