General
-------

The project definitions are stored in a file called Settings.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.

<Set>
  [DATA DEFINITIONS]  
</Set>


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

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

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
GenAmm - the number of images to generate
OutputFolder - the output folder where generated images will be stored. Normally a relative path with a trailing path separator.
ExportFile - the file name which is used to store the exported 

NamingRules - settings for the naming of output files, and the formatting of identifiers for CSV output

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
3 - the file name is the number of the created variant. The identifiers of the sub elements are not taken into account
  - the combination of the output folder and the resulting file name is used as the idenitifier name in tabular export
    (Note: the output folder may still be a relative path. If absolute paths are wanted, it is advised to use absolute paths as
     for the output folder - <OutputFolder>/tmp/</OutputFolder>) 

Export - create a tabular representation of the selected variants. Could be used to "replay" the variant in other tools. 

possible values:

CSV - do the export as comma separated values. This is a standard format which is understood by the most common additional software, e.g. a spreadsheet application.

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.
 
Layer specific attributes
-------------------------

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

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

The following attributes are recognized:

Type - the type of the layer. For compatibility reasons this attribute is not obligatory. If this attribute is not set, the layer
       type "0" is assumed.
       
possible values:

0 - "classic" layer
1 - "more of the same" layer
2 - "invisible" layer
3 - "texture" layer
4 - "select and lock" layer
5 - "texture" layer which uses a referenced image
6 - "visible context" layer 

The different types of layer are described later in more depth.
       
Name - the name of the layer. It is advised to make the layer names unique, because they are also used for referencing other layers 
       in some layer types
Location - the folder where the possible variant resources (images) are stored. Assumed to be a relative path with a trailing path
       separator.       
MinGenAmm - a layer may contain multiple sub-elements. This value specify the minimum number of these sub-elements       
MaxGenAmm - a layer may contain multiple sub-elements. This value specify the maximum number of these sub-elements       

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 

TextureLayer - references another layer by its name. It is assumed that this layer contains a selected image, which is used as the
               fill pattern.
LocationLayer - references another layer by its name. It is assumed that this layer contains a selected image, which is used as the
                location map. 
LocationLayer2 - references another layer by its name. It is assumed that this layer contains a selected image, which is used with
                 the "no white" position strategy.


BoundXMin - the minimum x-position for a coordinate
BoundXMax - the maximum x-position for a coordinate
BoundYMin - the minimum y-position for a coordinate
BoundYMax - the maximum y-position for a coordinate

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

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 coolours.

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.

The valid colors are described later.

Position strategies
-------------------

A layer is to be rendered by selecting one or multiple images from a folder specific to this layer. Each of these selected images is to be rendered on a position. There exist the following ways to specify the position

- area position - The values of the attributes <BoundXMin/>, <BoundXMax/>, <BoundYMin/>, <BoundYMax/> are used to specify a rectangular area. The positions are selected from a random position which are limited by this rectangular area.

- location map - an additional image is used. The black pixels in this image define the valid positions of the element.

- "no white" - an additional map is used. the values of the attributes <BoundXMin/>, <BoundXMax/>, <BoundYMin/>, <BoundYMax/> are used to specify a rectangular area. The positions are selected from a random position which are limited by this rectangular area.
If the selected pixel color is on a not white  in the map, the position is considered valid.

The strategies are mutually exclusive. The precedence is "location map", "no white", area position, in descending order.

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.

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

"Classic" layer
===============

The layer contains one more more subelements. Each sub element is selected separately. The positions are selected by one of the available position strategies. The first fill strategy is used. The layer can be controlled by the following attributes:

Name, Location, MinGenAmm, MaxGenAmm, HorizAlign, VertAlign, LocationLayer, LocationLayer2, BoundXMin, BoundXMax, BoundYMin,
BoundYMax, ImageEffects

"More of the same" layer
========================

The layer contains one more more subelements. The image to use is selected once. The positions are selected by one of the available position strategies. The first fill strategy is used. The layer can be controlled by the following attributes:

Name, Location, MinGenAmm, MaxGenAmm, HorizAlign, VertAlign, LocationLayer, LocationLayer2, BoundXMin, BoundXMax, BoundYMin,
BoundYMax, ImageEffects

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

The layer contains one seelcted image, which is not rendered. It is assumed that the layer will be referenced by other layers, where the selected image is used. The layer can be controlled by the following attributes:

Name, Location, ImageEffects

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

The layer contains one more more subelements. Each sub element is selected separately. The positions are selected by one of the available position strategies. The second fill strategy is used. The layer can be controlled by the following attributes:

Name, Location, MinGenAmm, MaxGenAmm, HorizAlign, VertAlign, TextureLayer, LocationLayer, LocationLayer2, BoundXMin, BoundXMax, BoundYMin, BoundYMax, TransparentColor, TextureColor, ColourModel, ImageEffects

"Select and Lock" layer
=======================

This is similar to an invisible layer and can be controlled by the same attributes, Name and Location.
However, during execution of pwgen there is only one value selected, instead of one per generated item. In connection with tiled mode this layer can be used to create "themed" elements, where each item in the tiled image use the same randomly selected colour scheme.

"Texture" layer which uses a referenced image
=============================================

The layer contains one more more subelements. Each sub element is selected separately. The positions are selected by one of the available position strategies. The second fill strategy is used. 
The layer doesn't select images, but uses one image which is read from the layer specified by "ImageLayer". The layer can be controlled by the following attributes:

Name, ImageLayer, MinGenAmm, MaxGenAmm, HorizAlign, VertAlign, TextureLayer, LocationLayer, LocationLayer2, BoundXMin, BoundXMax, BoundYMin, BoundYMax, TransparentColor, TextureColor, ColourModel, ImageEffects

"Visible context" layer
=======================

The layer works like a "classic" layer, but the selected image is stored in the context. The layer can be controlled by the following attributes:

Name, Location, MinGenAmm, MaxGenAmm, HorizAlign, VertAlign, LocationLayer, LocationLayer2, BoundXMin, BoundXMax, BoundYMin,
BoundYMax, 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 