README.asciidoc

   1 = aof2obj
   2
   3 *aof2obj* is a script to convert Artlantis Object Format files to Wavefront
   4 OBJ; it can be used to have .aof files imported into 3D modeling programs
   5 such as blender (http://blender.org).
   6
   7 Artlantis is a closed source 3D modeling and rendering software which can be
   8 found at http://www.artlantis.com/
   9
  10 Artlantis Object Format is one of the formats produced by Artlantis.
  11
  12 Wavefront OBJ is a very common format used to interchange data about 3D
  13 models, see https://en.wikipedia.org/wiki/Wavefront_.obj_file
  14
  15 *aof2obj* requires the lxml python module.
  16
  17 == Artlantis Object Format
  18
  19 The Artlantis Object Format is based on XML, it provides information about the
  20 vertices of the model (<Points> element), the objects it is composed by,
  21 the faces of the objects (<Polygons> element), the materials and the setup
  22 for example rendering. The XML file also embeds a preview image
  23 (<Preview.Image> element) of the rendering result.
  24
  25 Currently *aof2obj* supports only a small subset of these features, it was
  26 written only as a quick script hacked together to see what was inside some AOF
  27 files that can be found on the web.
  28
  29 Notes that the resulting models may need to be rescaled to become visible in
  30 the viewport of the destination 3D program which will import the .obj files
  31 produced by this script.
  32
  33 == Examples of .aof files
  34
  35 Some sample files can be found starting from this page:
  36
  37  - http://www.polantis.com/ikea/expedit-bookcase
  38
  39 Having the same model in both .aof and .obj makes it a little easier to
  40 reverse engineer the .aof format, even if its structure is very
  41 straightforward already.
  42
  43  - http://www.polantis.com/data/2/2/1093/formats/14/90/IKEA-Expedit_Bookcase-3d.aof
  44  - http://www.polantis.com/data/2/2/1093/formats/16/95/IKEA-Expedit_Bookcase-3d.obj
  45
  46  - http://www.polantis.com/data/2/2/1094/formats/14/90/IKEA-Expedit_Bookcase_Black-3d.aof
  47  - http://www.polantis.com/data/2/2/1094/formats/16/95/IKEA-Expedit_Bookcase_Black-3d.obj
  48
  49 == PRW files
  50
  51 *aof2obj* extracts also the Artlantis Preview Files embedded into the Artlantis
  52 Object Format files, and saves them with the .prw extension.
  53
  54 These files can be converted to ppm with the *prw2ppm* script.
  55
  56 The Artlantis Preview Files are bitmap images compressed using an RLE encoding.
  57
  58 There is a header with this structure:
  59
  60   TWH
  61
  62 where T, W and H are respectively the file type, the image width and height,
  63 as 32-bit big-endian integer values.
  64
  65 Immediately after the header there is the image data, which can be seen as divided into
  66 packets of the format:
  67
  68   CP+
  69
  70 Where C is the run count as a 32 bit big-endian integer, and P+ is
  71 a sequence of 1 or more Pixels encoded as 32-bit big-endian integers with the
  72 color information in the format 00RRGGBB.
  73
  74 [NOTE]
  75 The rightmost byte was always zero in the analyzed files.
  76
  77 A .prw file looks like:
  78
  79   TWHCPPPPCPCPCPCPCPPPPPPPPPCP...
  80
  81 The run counter C can refer to two types of packets:
  82
  83   - run-length packet: here the single P value has to be repeated C times
  84
  85   - raw packet: here C is followed by C different P pixels values
  86
  87 to decide if a packet is a 'run-length packet' or a 'raw packet' the last
  88 pixel value of the previous packet has to be inspected: let be P and Q two
  89 pixel values, and consider the sequence:
  90
  91   PCQX
  92
  93 We have these rules:
  94
  95  - if P == Q then C starts a run-length packet and Q is repeated C
  96    times and X will be the next run count,
  97
  98  - if P != Q then C starts a raw packet and Q is the first pixel of a sequence
  99    of C different pixel values (X will be the second pixel value).
 100
 101 Some special treatment might be still needed to handle the count in the first
 102 packet, in the analyzed files the first packet was always a 'run-length
 103 packet', so this is the assumption *prw2ppm* relies on.
 104
 105 I call this RLE compression method the 'sandwich encoding', because the count
 106 in run-length packets is between two identical pixel values.