POV-Ray export

Exporting to POV-Ray was one of the main historical reasons for writing Arabeske. While an implicit form, using material_maps, has been available for a while, the development release 1.1.7 introduces a direct export mechanism as POV-Ray source code.

The exporter exports shapes. Therefore it needs either coloured polygons or "thick" segments to be available, and cannot be invoked in modes where they are not calculated. The POV-Ray exporter is only available in "final" and "interlace" modes.

To run it, select File -> Export -> POV-Ray, then choose the filename. The default output file extension, if this feature is enabled, is ".pov", while the file selector shows .pov and .inc files. Click export

You are then prompted to choose between two export flavours:

• Basic exports the pattern as a simple, ready-made scene file. This scene file can be run directly from POV-Ray, and needs neither editing, nor other file inclusion. It outputs a rather simple, centered, untextured picture, which is suitable for uses such as background tiling or texturing in software like 3DS.

• Expert is the fully customisable output you dreamed of. No object, camera or light is directly exported in this system: everything is described as macro calls, and while the bad news is that you need to write the macros by yourself, the good news is that you can make them do whatever you want, not only plain polygons, but uneven polygons, isosurfaces, blobs. Texturing is also fully opened here.

Here is an example of the basic export style:

Let's concentrate on the expert-style exporting. The information provided by the exported file are:

• AraColors. This 256-long array contains the colours assigned by the user to each texture used in the picture. Special entries are 0 (background), 1 (lines), and 2 (groove). They can provide simple pigment reference, while complex texturing is always available...

• AraUserSegmentThickness. This floating-point value is the width of the segments.

• AraUserSegmentSubThickness. This floating-point value is the width of the groove of the segments.

• AraBBoxLL. This vector is the lower-left angle of the theoretical bounding box of the pattern. Note that the "y" coordinate must be adapted to the thickness of your objects.

• AraBBoxUR. This vector is the upper-right angle of the theoretical bounding box of the pattern. Note that the "y" coordinate must be adapted to the thickness of your objects.

Finally, you must provide one to four macros, depending on the mode from which you exported:

• AraUserPolygon(vertices, index). This macro draws (or manages, or whatever...) the exported polygons. This one is mandatory. The index parameter is the index of the texture assigned to the polygon. The "vertices" array is a list of vertices of the polygon, followed by the vertices of the polygons to be cut out of the main one. Each polygon is properly closed. It is exactly the same kind of information needed by the "prism" object, so please refer to this part of the POV-Ray documentation for more details.

• AraUserBezierPolygon(vertices, index). This macro is the equivalent of the previous one for closed surfaces bounded by at least one Bézier curve. The vertices are provided as sets of four points, each set describing one Bézier curve.

  It should not be assumed that the first point of a curve is always the end point of the previous curve. It is highly recommended to add another curve segment to link each given curve. This is automatically handled by the basic export, and an example is provided in the sample wrapping scene below.

• AraUserSegment(Start, End). This macro is mandatory in "Final" mode only, and handles segments. The parameters are simply the extremities of the segment to be drawn. The colour index is always 1 for segments.

• AraUserBezierCurve(Start, Ctrl1, Ctrl2, End). This macro is mandatory in "Final" mode only, when you export Bézier curves. The parameters are simply the extremities of the segment to be drawn, and the two associated control points.

  Note that POV-Ray does not currently provided direct support for Bézier splines. A custom macro is thus generated by the basic exporter, and is included in the sample wrapping scene below.

Please note that the expert export does not provide any form of clipping, which means that you are likely to get much more objects that needed, and probably suitable. This clipping has to be done in your own code.

Also note that the bounding box information tells you everything about the size of the exported pattern. There is no scaling option: if you need a 10x10 output, just use the scale operator in your macros.

Sample wrapping scene

An improved version of this example is available as source code here.

General POV-Ray statements:

#include "metals.inc"
#include "colors.inc"

camera {
    up y
    right -x
    location <10, 10, -20>
    look_at <0, 0, 0>
    angle 5
}

light_source{
    <-1, -2, -5>
    rgb 1.5
}

First mandatory macro, draws a polygon using the "prism" object, using the plain colour exported from Arabeske.

#macro AraUserPolygon(A, index)
    prism{
        -1, 0,
        dimension_size(A, 1)
        #local i=0;
        #while (i<dimension_size(A, 1))
            A[i]
            #local i=i+1;
        #end
        pigment {rgb AraColors[index]}
        clipped_by{box{<-1, -.01, -1>, <1, .1, 1>}}
        rotate -90*x
    }
#end

Second macro, mandatory for "final" mode exports. It just draws segments, using AraUserSegmentThickness/2 as radius. The segments are round-capped cylinders with a golden texture.

#macro AraUserSegment(Origin, End)
    union{
        cylinder{Origin, End, AraUserSegmentThickness/2}
        sphere{Origin, AraUserSegmentThickness/2}
        sphere{End, AraUserSegmentThickness/2}
        clipped_by{box{<-1, -.01, -1>, <1, .1, 1>}}
        rotate -90*x
        texture{T_Gold_1E}
    }
#end

Finally, include the file exported from Arabeske:

#include "expert.pov"

And that's all! Adding a simple background, the result looks like: