General
-------

The project definitions are stored in a file called setup.xml, which is supposed to be in the root folder of a project.
The referenced resources are assumed to be in sub folders of this folders. It is assumed that all references are relative, and that all resources (images etc) are located in sub folders. The project should be self-containing.

A project's setup file has the following structure.

<PieceSet>
  [DATA DEFINITIONS]  
</PieceSet>


Data definitions consist of project specific attributes and one or more layer definitions with layer specific attributes.

Project specific attributes
---------------------------

Layer specific attributes are the attributes for a specific layer, i.e. all values in the given hierarchy

<PieceSet>
  <Data>
    [PROJECT SPECIFIC ATTRIBUTES]
  </Data>
</PieceSet>

The following attributes are recognized:
    
ImageSizeX  - the horizontal size (width) of the result image in pixels
ImageSizeY - the horizontal size (height) of the result image in pixels
OutputFolder - the output folder where generated images will be stored. Normally a relative path with a trailing path separator.

Naming - settings for the naming of output files

possible values:

1 - the file name of the created image is built from the numeric indizes of all selected items
  - the resulting file name is used as the idenitifier name in tabular export
2 - the file name is the number of the created variant. The identifiers of the sub elements are not taken into account
  - the resulting file name is used as the idenitifier name in tabular export

RenderMode - specify how the images should be created, optional parameter

possible values:

0 (default) - separate images
1 - tiled images

If tiled images should be created, the value of RenderColumns specifies the 
number of columns. The number of row tiles is calculated by the number of columns and the GenAmm value.

If tiled mode is used, the tiled images are created in a file 
<output folder>/work.png. You should rename the old work.png if PWGen should be run multiple times.

Data - the tabular data to use. It is assumed that the value references a external file, which contains the data in CSV form. Later references to columns are zero-based, i.e. column "0" references the first column.
 
Layer specific attributes
-------------------------

Layer specific attributes are the attributes for a specific layer, i.e. all values in the given hierarchy

<PieceSet>
  <Data>
    <Layer>
       [LAYER SPECIFIC ATTRIBUTES]
    </Layer>
  </Data>
</PieceSet>

The following attributes are recognized:

Type - the type of the layer. 
       
possible values:

1 - "static text" layer
2 - "static image" layer
3 - "dynamic text" layer
4 - "dictionary based dynamic image" layer
5 - "resource based dynamic image" layer
6 - "collection" layer
7 - "invisible" layer
8 - "texture" layer
9 - "masked dynamic image" layer
10 - "static invisible" layer
11 - "textured invisible" layer
12 - "referenced image" layer

The different types of layer are described later in more depth.

Name - the name of the layer. Because a layer may be referenced later, it is advised to make the name unique.
Value - a text which should be displayed
FontType, FontSize - used to define the foont used for text output
Color - a color description, e.g. to describe the color in which the text should be rendered.
WriteAtXA, WriteAtYA - the position where the graphical element should be rendered.
Column - the column number from the tabular data. It is assumed to be a string. The interpretation dependent upon the layer type
Image - an image reference as (relative) file name
Folder, Extension - used to describe parts of a file name. A file name consists of the following pattern - folder, filename, extension, which are concatenated to get the real file name

MaskLayer - references another layer, which is used for masked image rendering

TextureLayer - references another layer, which is used as a texture

TransparentColor - a pixel of this color in the source image is made transparent in the resulting image. The value is assumed to 
                   be a name of the system colour palette, i.e. something like "blue". If no TransparentColor is given, no 
                   transparent pixels are created.
TextureColor -   a pixel of this color in the source image uses the pixel valu in the texture map. This pixel value is used in the 
                  in the resulting image. The value is assumed to be a name of the system colour palette, i.e. something like 
                  "blue". If no TextureColour is given, no textured pixels are created.     

ColourModel - this allows for complicated texture fill operations and is described later in more detail.

Align - the text alignment

possible values:

Center, Right, Left - the (horizontal) text alignment. Left Align is the default value

HorizAlign - a sub-element has a position. This position can be specified further by defining an alignment.

possible values:

0 - left align. The x-coordinate of the position marks the (horizontal) begin of the image
1 - center align. The x-coordinate of the position marks the (horizontal) center of the image 
2 - right align. The x-coordinate of the position marks the (horizontal) end of the image 

VertAlign - a sub-element has a position. This position can be specified further by defining an alignment.

possible values:

0 - top align. The y-coordinate of the position marks the (vertical) begin of the image
1 - center align. The y-coordinate of the position marks the (vertical) center of the image 
2 - bottom align. The y-coordinate of the position marks the (vertical) end of the image

Image Collections
-----------------

A collection is a a set of database columns  with similar structure, which are used to render a set of images in a layer

The collection is controlled by the following settings

MaxItems - the (maximum) number of elements in the collection
MaxAttributes - the number of different values per collection element
StartColumn - the index where the collection data starts
OffsetRes - the offset where the resource part of the image to render starts. The value is supposed to be in the range 0...MaxAttributes-1.
OffsetX - the offset where the x-position is stored. The value is supposed to be in the range 0...MaxAttributes-1.
OffsetY - the offset where the x-position is stored. The value is supposed to be in the range 0...MaxAttributes-1.

Image Dictionary
----------------

An image dictionary allows for "logical" name. It is a map from names to a file name reference.

An dictionary is defined af follows:

<Dictionary>
  <Entry key="red">./templates/coat/x1.png</Entry>
</Dictionary>
                  
Fill Strategies
---------------

There exist two fill strategies. Given are a a source image and one or more (non-obligatory) texture images. From this source image is created a destination image. This destination image is rendered into a "container" image.

The first fill strategy uses the source image as is. Each pixel in the (virtual) destination image is that from the source image

The second fill strategy has multipe modes for transfering:                    

- copy mode: the pixel value from the source image is used
- transparent mode: in the destination image a transparent pixel is created. The source pixel value is ignored
- texture: the pixel value from the selected texture image is used
- grey mode: in the destination image is a pixel of the given grey value  

The mode to be used is selected by the pixel value in the source image. There are assumed to be special pixels, like all blue pixels, which are to be made textured, and all white pixels should be made transparent. There exist a fallback mode, so that each pixel which doesn't have a special colour, is used directly (copy mode is used)
The behaviour is controlled by the values of the <TransparentColor/> and <TextureColor/> attributes.

In order to create more complex texture fill layers, it is also possible to define a colour model. A colour model allows to define multiple transparent and texture colours.

A colour model has the form

<ColourModel>
  <Entry ... />
</ColourModel>

A entry has one of the following forms

<Entry mode="1" key="white" />

this defines a transparent algorithm for a pixel of the colour white 

<Entry mode="2" key="blue" layer="BaseColor" />

this defines a texture algorithm for a pixel of the colour blue.
The used texture is taken from the layer "BaseColour". This should be an invisible, or an "select and lock" layer.

<Entry mode="3" value=".5" />

this defines a grey algorithm. The value should be on the range of 0..1.
The resulting pixels has equal red, green and blue values in the range of 0..255.

The valid colors are described later.

ImageEffects
------------

An additional feature for images is the possibility to apply filters on them. Filters allow for several sepcial effects.

ImageEffects are defined on a lyer and have the following form

<ImageEffects>
  ....
</ImageEffects>

There can be defined multiple effects per layer.

The following image effects are defined

DropShadow
==========

A drop-shadow filter is defined in the following way

<DropShadow value=".5"/>

The attribute value is assumed to be a floating point value.
The dropshadow effect works by extracting a heuristic map from the given input value. This means, from a coloured image is created a black and white image, where the black pixels are used as a mask. The colours from the image border are assumed to be the background colour and make up the white pixels.
From this heuristic map is created an alpha-mask. Each which pixel becomes transparent, while each black pixel becomes semi-transparent with an opacity value equals to the given "value" parameter.

BlurAlphaMask
=============

This filter is defined in the following way

<BlurAlphaMask radius="10" alpha=".5" />

The filter expects a grayscale image as its input. It extracts an heuristic mask, and applies a Gaussian blur filter. The blurred image is used together with the mask to create a "clipped" image. From this image is created an alpha-mask, where the grey value of a pixel is used to specify the opacity of the resulting image at this position.

Outline
=======

This filter is defined in the following way

<Outline />

This filter creates a result image where only black pixels are used. All other pixels are fully transparent. 

Layer types
-----------

"Static text" layer
===================

Select a static string from the value of "Value". The font related settings are used to render the string.  The layer can be controlled by the following attributes:

Name, Value, FontType, FontSize, Color, WriteAtXA, WriteAtYA, Align

"Static image" layer
====================

The value of the Select attribute is used to select an image from a static file name resource, which is rendered using the first fill strategy. The layer can be controlled by the following attributes:

Name, Image, WriteAtXA, WriteAtYA, HorizAlign, VertAlign, ImageEffects

"Dynamic text" layer
====================

Selects a value from the table, as specified by the value of the Column attribute. The font related settings are used to render the string. The layer can be controlled by the following attributes:

Name, Column, FontType, FontSize, Color, WriteAtXA, WriteAtYA, Align

"Dictionary based dynamic image" layer
======================================

Selects a value from the table, as specified by the value of the Column attribute. The selected value is used as a key into a dictionary. The resulting value is selected and rendered as an image  using the first fill strategy. The layer can be controlled by the following attributes:

Name, Column, Dictionary, WriteAtXA, WriteAtYA, HorizAlign, VertAlign, ImageEffects

"Resource based dynamic image" layer
====================================

Selects a value from the table, as specified by the value of the Column attribute. The selected value is used to build a file name resource. The resulting value is selected and rendered as an image  using the first fill strategy. The layer can be controlled by the following attributes:

Name, Column, Folder, Extension, WriteAtXA, WriteAtYA, HorizAlign, VertAlign, ImageEffects

"Collection" layer
==================

Selects and renders a number of images  using the first fill strategy as specified by a "image collection". The layer can be controlled by the following attributes:

Name, Folder, Extension, MaxItems, MaxAttributes, StartColumn, OffsetRes, OffsetX, OffsetY, HorizAlign, VertAlign, ImageEffects

"Invisible" layer
=================

Selects an image from a file name resource and writes it into the context. 
The layer can be controlled by the following attributes:

Name, Column, Folder, Extension, ImageEffects

"Texture" layer
===============

Selects a value from the table, as specified by the value of the Column attribute. The selected value is used to build a file name resource. The resulting value is selected and rendered as an image using the second fill strategy. Another image is selected from the context as referenced by the value of "TextureLayer". The layer can be controlled by the following attributes:

Name, Column, Folder, Extension, WriteAtXA, WriteAtYA, HorizAlign, VertAlign, TextureLayer, ColourModel, TransparentColor, TextureColor, ImageEffects

"Masked dynamic image" layer
============================

Selects a value from the table, as specified by the value of the Column attribute. The selected value is used to build a file name resource. The resulting value is selected and rendered as an image  using the first fill strategy. Another image is selected from the context as referenced by the value of "MaskLayer". This image is used as a mask, where each black pixel in the mask is used to determine if the pixel in the result image is rendered. If at the given pixel is a black pixel, the sourrce pixel is rendered. Source and Mask image use the same coordinates. The layer can be controlled by the following attributes:

Name, Column, Folder, Extension, WriteAtXA, WriteAtYA, HorizAlign, VertAlign, MaskLayer, ImageEffects

"Static invisible" layer
========================

This layer selects a static image (cf. "Static image" layer) and stores it into the context under the layer name for later reference. The layer can be controlled by the following attributes:

Name, Image

"Textured invisible" layer
==========================

This layer renders an image using the second fill strategy (cf. "Texture image" layer) and stores the resulting image into the context under the layer name for later reference. Image effects are applied. The layer can be controlled by the following attributes:

Name, Column, Folder, Extension, WriteAtXA, WriteAtYA, HorizAlign, VertAlign, TextureLayer, ColourModel, TransparentColor, TextureColor, ImageEffects

"Referenced image" layer
========================

This layer reads an image out of the context, using the value of the "ImageLayer" attribute as key from the context and outputs it. Image effects are applied. The combination of e.g. "textured invisible" layer and "referenced image" layers allows to apply pre- and post-selection image effects. Normally image effects are only executed at the beginning of the handling of a layer. The layer can be controlled by the following attributes:

ImageLayer, WriteAtXA, WriteAtYA, HorizAlign, VertAlign, ImageEffects


Colors
------

There exist two ways to define a color, e.g. in a color model:

A colour may be defined by its RGB value in hex format, by prepending a "#", so #ff0000 defines the color red.
All other values are interpreted as named colours from the following list:

aliceblue  --> RGB F0F8FF 
antiquewhite  --> RGB FAEBD7 
aqua  --> RGB 00FFFF 
aquamarine  --> RGB 7FFFD4 
azure  --> RGB F0FFFF 
beige  --> RGB F5F5DC 
bisque  --> RGB FFE4C4 
black  --> RGB 000000 
blanchedalmond  --> RGB FFEBCD 
blue  --> RGB 0000FF 
blueviolet  --> RGB 8A2BE2 
brown  --> RGB A52A2A 
burlywood  --> RGB DEB887 
cadetblue  --> RGB 5F9EA0 
chartreuse  --> RGB 7FFF00 
chocolate  --> RGB D2691E 
coral  --> RGB FF7F50 
cornflowerblue  --> RGB 6495ED 
cornsilk  --> RGB FFF8DC 
crimson  --> RGB DC143C 
cyan  --> RGB 00FFFF 
darkblue  --> RGB 00008B 
darkcyan  --> RGB 008B8B 
darkgoldenrod  --> RGB B8860B 
darkgray  --> RGB A9A9A9 
darkgreen  --> RGB 006400 
darkkhaki  --> RGB BDB76B 
darkmagenta  --> RGB 8B008B 
darkolivegreen  --> RGB 556B2F 
darkorange  --> RGB FF8C00 
darkorchid  --> RGB 9932CC 
darkred  --> RGB 8B0000 
darksalmon  --> RGB E9967A 
darkseagreen  --> RGB 8FBC8F 
darkslateblue  --> RGB 483D8B 
darkslategray  --> RGB 2F4F4F 
darkturquoise  --> RGB 00CED1 
darkviolet  --> RGB 9400D3 
deeppink  --> RGB FF1493 
deepskyblue  --> RGB 00BFFF 
dimgray  --> RGB 696969 
dodgerblue  --> RGB 1E90FF 
firebrick  --> RGB B22222 
floralwhite  --> RGB FFFAF0 
forestgreen  --> RGB 228B22 
fuchsia  --> RGB FF00FF 
gainsboro  --> RGB DCDCDC 
ghostwhite  --> RGB F8F8FF 
gold  --> RGB FFD700 
goldenrod  --> RGB DAA520 
gray  --> RGB 808080 
green  --> RGB 008000 
greenyellow  --> RGB ADFF2F 
honeydew  --> RGB F0FFF0 
hotpink  --> RGB FF69B4 
indianred  --> RGB CD5C5C 
indigo  --> RGB 4B0082 
ivory  --> RGB FFFFF0 
khaki  --> RGB F0E68C 
lavender  --> RGB E6E6FA 
lavenderblush  --> RGB FFF0F5 
lawngreen  --> RGB 7CFC00 
lemonchiffon  --> RGB FFFACD 
lightblue  --> RGB ADD8E6 
lightcoral  --> RGB F08080 
lightcyan  --> RGB E0FFFF 
lightgoldenrodyellow  --> RGB FAFAD2 
lightgreen  --> RGB 90EE90 
lightgrey  --> RGB D3D3D3 
lightpink  --> RGB FFB6C1 
lightsalmon  --> RGB FFA07A 
lightseagreen  --> RGB 20B2AA 
lightskyblue  --> RGB 87CEFA 
lightslategray  --> RGB 778899 
lightsteelblue  --> RGB B0C4DE 
lightyellow  --> RGB FFFFE0 
lime  --> RGB 00FF00 
limegreen  --> RGB 32CD32 
linen  --> RGB FAF0E6 
magenta  --> RGB FF00FF 
maroon  --> RGB 800000 
mediumaquamarine  --> RGB 66CDAA 
mediumblue  --> RGB 0000CD 
mediumorchid  --> RGB BA55D3 
mediumpurple  --> RGB 9370DB 
mediumseagreen  --> RGB 3CB371 
mediumslateblue  --> RGB 7B68EE 
mediumspringgreen  --> RGB 00FA9A 
mediumturquoise  --> RGB 48D1CC 
mediumvioletred  --> RGB C71585 
midnightblue  --> RGB 191970 
mintcream  --> RGB F5FFFA 
mistyrose  --> RGB FFE4E1 
moccasin  --> RGB FFE4B5 
navajowhite  --> RGB FFDEAD 
navy  --> RGB 000080 
oldlace  --> RGB FDF5E6 
olive  --> RGB 808000 
olivedrab  --> RGB 6B8E23 
orange  --> RGB FFA500 
orangered  --> RGB FF4500 
orchid  --> RGB DA70D6 
palegoldenrod  --> RGB EEE8AA 
palegreen  --> RGB 98FB98 
paleturquoise  --> RGB AFEEEE 
palevioletred  --> RGB DB7093 
papayawhip  --> RGB FFEFD5 
peachpuff  --> RGB FFDAB9 
peru  --> RGB CD853F 
pink  --> RGB FFC0CB 
plum  --> RGB DDA0DD 
powderblue  --> RGB B0E0E6 
purple  --> RGB 800080 
red  --> RGB FF0000 
rosybrown  --> RGB BC8F8F 
royalblue  --> RGB 4169E1 
saddlebrown  --> RGB 8B4513 
salmon  --> RGB FA8072 
sandybrown  --> RGB F4A460 
seagreen  --> RGB 2E8B57 
seashell  --> RGB FFF5EE 
sienna  --> RGB A0522D 
silver  --> RGB C0C0C0 
skyblue  --> RGB 87CEEB 
slateblue  --> RGB 6A5ACD 
slategray  --> RGB 708090 
snow  --> RGB FFFAFA 
springgreen  --> RGB 00FF7F 
steelblue  --> RGB 4682B4 
tan  --> RGB D2B48C 
teal  --> RGB 008080 
thistle  --> RGB D8BFD8 
tomato  --> RGB FF6347 
turquoise  --> RGB 40E0D0 
violet  --> RGB EE82EE 
wheat  --> RGB F5DEB3 
white  --> RGB FFFFFF 
whitesmoke  --> RGB F5F5F5 
yellow  --> RGB FFFF00 
yellowgreen  --> RGB 9ACD32 