Making XML image description files

Making XML image description files
For more information contact us at info@psoft.net

Images that are described in the xml image file are loaded by the program in the form of "trees", which each image being made up of a number of nodes. The root of each tree is the place to set global image parameters.

The xml file consists of one big "<images>" tag. Between the opening and closing of the <images> tag, each individual image is described. (This is done with the <image> tag. Note that the word "image" is singular in this case.) Each <image> tag is self-contained, and has no relation to any other <image> tag, with the exception that it must be given a name that is unique within the scope of the XML file.

So the skeleton of the XML file would look something like this:


<images>
	<image name="image1">
	       . . .
	</image>
	
	<image name="image2">
	       . . .
	</image>

	.  .  .

</images>

From here on, we will concentrate on the structure of the <image> tag itself. This tag can be given a large number of parameters. The parameters can be assigned inside the <image> tag itself as in


	<image param_name="param_value">
	       . . .
	</image>

or using a <param> tag inside of the <image> tag.


	<image>
		. . .
		<param name="param_name">param_value</param>
		. . .
	</image>

While there is no functional difference between the parameters defined in these two ways, for keeping to convention, and better readability, you should define the image name and values relating to the image's physical properties (i.e. format, size, color depth, transparency) right inside the <image> tag, and define miscelaneous properties using the <para> tag. (Note that the order of parameter definition plays no role here)

No parameters other than "name" are required by the <image> tag, however you may wish to specify some to let image maker know what kind of image you want constructed:

parameter	values	function
x, y	integers	these specify image dimentions desired. If they are not given, the image will be sized to accomodate all of its nodes
bgcolor	html color	the color to set image background to. this defaults to black (#000000)
format	"gif" or "jpg"	indicates the preferred format for saving the image. gif is the default
depth	2 - 256 (int)	color depth for saving gif images. this parameter defaults to 256, and is ignored for jpg images
transparency	"true"	turns on transparency for a gif file. any value but "true" will not work. The declared (or default) background color for the image will be used to determine transparency. Note that because of antialiasing, even trasnparent images should have their background color set to a value similar to the color they will be drawn on top of
arguments	see below	this parameter declares the arguments needed to properly construct this image. The arguments will be substituted for parameter values, and their use will be discussed in detail further in this document. This parameter should be declared using a <param> tag

The actual image is built using a combination of image operations (defined by the <imgop> tag) and primitives (such as lines, circles and rectangles). The <image> tag may contain only ONE primitive or operation tag. (In most cases it will be an <imgop> tag that will put together the image)

Every <imgop> tag MUST have a "type" parameter, which specifies the type of operation you wish this node toperform.

As a rule, operations will have "children" that they work with. These children can be either primitives, or results of other operations. Some operations, such as addition or overlaying, can have unlimited children. Others can only have two or one (like the maskedfill operation). A special case is the "file" operation, the result of which is an image loaded from a file. It can have no children.

The "file" operation must have an "src" parameter, that indicates the local path or the URL from which to retrieve the image file. Many graphical formats are currently supported, but it is recommended that you stick to using either gif or jpg files. Png file support is available but the alpha channels are not handled properly at this time.

The simplest image definition would be


    <image name="static_image">
	   <imgop type="file" src="image.gif">
    </image>

This would load an image from the file "image.gif" and draw it on the image you are building. It's not very useful since you could have just as easily used the original image.gif, but it's a start.

In addition to the "type" and "src" parameters, which are mandatory, the <imgop type="file"> operation can have two optional parameters:

parameter	values	function
opacity	0.0 - 1.0	Determines the opacity of the image once drawn. Default is 1.0
base	path or URL	This value will be pre-pended to the "src" value to get the full path of the image. If the "base" parameter is missing, imagemaker assumes that the "src" parameter already contains the full image path

The most basic operation other than "file" is the "overlay" operation, that simply draws its children one onto another. Here is an example of using "overlay" with the "circle" primitive for drawing olympic rings:


    <image name="olympic" bgcolor="#000000">
	   <imgop type="overlay">
		  <circle x="20" y="20" radius="20"/>
		  <circle x="35" y="20" radius="20"/>
		  <circle x="50" y="20" radius="20"/>
		  <circle x="27" y="35" radius="20"/>
		  <circle x="43" y="35" radius="20"/>
	  </imgop>
   </image>

The use of the <circle> tag here is pretty clear. Note that <circle> is a primitive, and can therefore have no children. The primitives supported by the image maker are

Each of the primitives must have a certain set of parameters in order to be drawn properly, and can also be supplied additional, optional parameters, that will specify drawing options. The neccessary parameters are:

tag

parameters

function

x, y

center coordinates

radius

<line>

x1, y1

start coordinates

x2, y2

end coordinates

x1, y1

upper left corner coordinates

w, h

width and height of the rectangle

<oval>

x, y

center coordinates

radiusX

horisontal radius

radiusY

vertical radius

* All of the above parameters should have integer values and refer to pixel coordinates and dimensions.

Without these minimum parameters supplied, the primitive tags may cause errors, be ignored, or result in unpredictable behavior. Please make sure that the bare minimum of parameters is given for any primitive tag you use. Also note that while parameter values are, for the most part case-insensitive, their names are not, so you must be careful to observe proper case when entering parameter names.

As stated above,these parameters are just the minimum required ot get the shape to be drawn. You can specify optional parameters to pass to the primitive tags to alter the way in which they are drawn. These are listed below:

parameter supported by function

color all specifies drawing color (html color, i.e #000000)

width all specifies line width to draw shape with (integer)

opacity all specifies opacity of the primitive. can be a float value from (0.0 - transparent to 1.0 - opaque)

fill <rectangle>,<oval>,<circle> specifies that you wish the shape filled, not outlined. This parameter should have the value "true" if you wish to fill the shape. Any other value will cause the shape to be outlined. When this is set to true, the width parameter is ignored.

Using the tags already described, we can already load an image, use it as a background, and then draw primitive graphics on top of it. The following code, for example, would draw properly colored olympic rings on top of "rings.gif"


    <image name="olympic">
	   <imgop type="overlay">
		  <imgop type="file" src="flag.gif"/>
		  <circle x="20" y="20" radius="20" color="#0000FF"/>
		  <circle x="35" y="20" radius="20" color="#000000"/>
		  <circle x="50" y="20" radius="20" color="#FF0000"/>
		  <circle x="27" y="35" radius="20" color="#FFFF00"/>
		  <circle x="43" y="35" radius="20" color="#00FF00"/>
	  </imgop>
   </image>

But what if you already have a ready image of the symbol that you wish to be painted on top of an image of a background? You could use the code:



    <image name="olimpic">
	   <imgop type="overlay">
		  <imgop type="file" src="flag.gif"/>
		  <imgop type="file" src="rings.gif"/>
	   </imgop>
    </image>

This would draw the image rings.gif on top of flag.gif, and return the result. (rings.gif should be a transparent gif for best results). However the code would only give you the result needed if the images are the same in size, and the rings are already centered in the rings.gif image:

flag.gif rings.gif result

A more likely scenario would be that the rings.gif image will be sized to the same dimensions as the actual rings:

In this case the result will be

Clearly not the desired result. What we need is a way to move the rings.gif image over so it is centered in the flag.gif image. For this purpose, we can use the <offset> tag:

    
	    <offset x="20" y="10">
		<imgop type="file" src="rings.gif"/>
	    </offset>

An offset tag makes everything that is drawn inside of it move over by the given amount of pixels, so that for all the nodes inside that tag, the coordinate (0,0) is physically located at (x,y) in the parent image. In the case of the rings.gif node, it would receive a sub-image of the main image that has its upper-left corner at x=20 and y=10:

Note that both the x and y parameters are required by the <offset> tag, and that they cannot, at present have negative values. If you were to place a <line> tag inside of this <offset> to draw a line from (0,0) to (10,10), the physical line drawn on the image would be translated by the amounts specified in the <offset> and the resulting line would runf from (20,10) to (30,20).

Using a combination of <imgop type="overlay"> <imgop type="file"> and <offset> tags, it is possible to build a large image from a number of smaller pieces:

	    
	 <image name="collage">
		<imgop type="overlay">
		       <imgop type="file" src="a.gif"/>
		       <offset x="20" y="0">
			       <imgop type="file" src="b.gif"/>
		       </offset>
		       <offset x="0" y="20">
			       <imgop type="file" src="c.gif"/>
		       </offset>
		       <offset x="20" y="20">
			       <imgop type="file" src="d.gif"/>
		       </offset>
		</imgop>
	 </image>

The above code, assuming images a through d .gif measure 20x20 pixels would create a composite as follows:

	    
  +---+  +---+      
  | A |  | B |      +------+
  +---+  +---+  =>  | A  B |
  +---+  +---+      | C  D |
  | C |  | D |	    +------+
  +---+  +---+

We have already discussed the <imgop type="overlay"> and <imgop type="file"> operations. There are three more that are currently supported by image maker: <imgop type="add">, <imgop type="greymask">,<imgop type="shadow"> and <imgop type="maskedfill">.

The result of the "add" operation, simplest to understand, is nothing more than arithmetic addition of it's children's outputs. For example if one child paints a pixel with red color and another paints it with blue, the resulting pixel after addition would be purple, since

	    
		       #FF0000
		      +#0000FF
		      =========
		       #FF00FF

if a green pixel was later added, the result would be white:

	    
		       #FF00FF
		      +#00FF00
		      =========
		       #FFFFFF

Note that each color channel is limited to the value of #FF, and there is no overflow into other color channels. so #0000FF + #0000FF would result in #0000FF, not #0001FE.

The "add" operation must have at least two child nodes. There is no upper limit on this number.

The "shadow" opertion is really simple and basic. It can have only one child, from which it will cast a shadow. It can accept the following parameters:

parameter value function

xd, yd integer Indicate the length of the shadow vertically and horizontally. these values default to 0,0 so if they are not supplied you will not see the shadow at all.

color HTML color The color in which to cast the shadow. This defaults to black.

blur 0 - 10 The amount by which the shadow should be blurred. Default is 0

opacity 0.0 - 1.0 Indicates how transparent the shadow should be. Default is 1.0

An example of using the shadow operation is:

    
	   <imgop type="shadow" dx="5" dy="5" blur="3" color="#440000" opacity="0.5">
		  <circle x="10" y="10" radius="9" color="#FF0000" fill="true" />
           </imgop>

The "greymask" operation is used to change apply a grey gamma mask to an image. This means that a greyscale image, or a "mask" is used as a guide to make some pixels of the source image lighter, and others darker. Pixels that are colored 50% grey (#808080) on the mask are left unchanged on the source image. pixels darker than 50% grey are proportionately darkened, and pixels that are lighter are in turn lightened. The change of gamma value on the source pixel is proportional to how much darker or lighter the mask pixel is than the 50% grey.

The "greymask" operation needs two children to work properly:

the first child is used as the mask

the second child is used as the image to apply the mask to. if this child is missing, the image maker will look for a color parameter of this node, and if it is found, apply the mask to a flat rectangle of the specified color.

If you wish to add a beveled frame to an image, you can use a grey mask with a 50% grey center, and a top and left borders that are a light shade of grey and bottom and right borders that are a dark shade:

	    
	+---------------+   Key:
	|++++++++++++++=|		+ : light grey
	|+=============-|		= : 50% grey
	|+=============-|		- : dark grey
	|=--------------|
	+---------------+

If this image is stored in a file called mask.gif, you can apply this mask using the following code:

	    
	  <imgop type="greymask">
		 <imgop type="file" src="mask.gif"/>
		 <imgop type="file" src="image.gif"/>
	  </imgop>
</font></pre>

To simply create a beveled area of some color, you can omit the second child and insert a "color" parameter in its place:

	    
	  <imgop type="greymask">
		 <imgop type="file" src="mask.gif"/>
		 <param name="color">#00FF00</param>
	  </imgop>

This code would create a beveled green rectangle. The color parameter is ignored if a second child is present.

The "greymask" operation will ignore all children after the first two, and will cause an error unless it has either two children (mask and source) or one child (mask) and a color parameter.

Finally we have the "maskedfill" operation. While its functionality is not very difficult to grasp, it is quite powerful and offers a number of options if used properly. The basic purpose of the maskedfill operation is to allow copying an image from source to destination using a separate alpha mask to determine the shape and opacity of the area to be filled.

A mask for this operation is a greyscale image, in which a black pixel indicates full transparency, a white pixel indicates full opacity and a grey value means that the source pixel will be translucent, with it's alpha value determined by how light the pixel on the mask is. If the purpose of the mask is to convey a simple shape, then just the black and white colors will suffice, though grey values can be added along the border for antialiasing.

The "maskedfill" operation can have two children:

the first child is used as the mask

the second child is the source for the fill operation. this is the result of an imgop, or a primitive. If it is absent, image maker will look for a "color" parameter, and fill the area with that color. if both the second child and the "color" parameter are supplied, image maker will first convert the second child image to a monotone scale of the given color (i.e. "bluescale", "greenscale", etc) and then use the result to fill the shape.

The "maskedfill" operation's parameters are:

parameter values function

color HTML color The color to use if no second child supplied. if the second child is supplied, it is converted to a monotone image of this color's scale.

resize "true" If this parameter is equal to "true" then the second child image will be resized to fit the mask exactly. All values other than "true" will be ignored. The parameter is meaningless if there is no second child.

resize "fill" or "fit" Specifies how to preserve the second child's aspect ratio when resizing. A value other than "fit" or "fill" will cause the aspect ratio to be lost, and the image to be stretched to fit the mask size. If "aspect" is "fit", the image will be sized so that all of it fits into the mask. This may result in some empty space being left. If this parameter has the value "fill", then the image will be sized so that it fills all of the mask area, though this may result in some of it being drawn "offscreen". This parameter is ignored unless "resize" is set to "true".

opacity 0.0 - 1.0 Determines how opaque the result will be. Default is 1.0

A final element you need to be familiar with is the <label> tag. <label>s are used for drawing text strings. <label> is actually a type of primitive in that it cannot have any children, and it is not considered ot be an <imgop>.

The <label> tag needs to have two child tags:

the <text> tag contains the text to be written on the label. Without a text tag, the label will not be considered properly declared.

the <font> tag defines the font to use for the drawing of the label. While it is not absolutely neccessary to use the font tag, its absence will cause image maker to use the default system font, causing unpredictable behavior.

Here is an example of a simple use of the <label> tag:

	    
     <label>
	<font face="Times New Roman" size="14" bold="true"/>
	<text>Label text goes here</text>
     </label>

As you see, the <font> tag receives parameters indicating the name of the font to use ("face") and the size to use ("size"). The font name should correspond to it's identifier as perceived by your system. Additionallly, the <font> tag may include the "bold" and "italic" parameters, that, if set to "true" will cause the font to become bold and italic respectively. (Note that all values other than "true" will be ignored for these parameters)

The <label> tag itself can also take a number of parameters:

parameter values function

color HTML color The color of the label. This color will be used to draw the text.

w integer Optional width limiter for the label. If this parameter is present, the width of the label will not exceed its value.

h integer Optional height limiter for the label. If this parameter is present, the height of the label will not exceed its value.

fit "true" If the parameter is set to "true" the image maker will keep trying smaller point sizes of the font specified until it can fit the label into the constraints provided by the "w" and/or "h" parameters without cutting off any part of the label. Any other value of this parameter will cause the label to be simply cropped to fit the designated bounds.

center "true" This parameter is used to indicate that you want the label to be centered within the bounds specified. The label will be centered if the parameter value is "true", and left-aligned for all other values.

opacity 0.0 - 1.0 Indicates opacity of the label. Default is 1.0

With the primitives, operations and labels, we are able to describe a large number of images. However this structure is limited to images for which all the parameters are known ahead of time. What if you wish to allow the user to select the color of the text on a label, or, better yet the text itself? To allow for this kind of flexibility, we introduce image arguments. These are parameter values that are not known at the time that the xml code is being written. Rather in their place you can put an argument name, that will indicate that the value is to be looked up from the argument list at the time the image is being built.

The arguments in parameter values must begin with a dollar sign ($). The declaration will look like this:

    
     <circle x="10" y="10" radius="5" color="$color"/>

This means that the color of the circle is to be looked up at the time of image generation from an argument called "color". The declaration can also take the form of

	    
     <param name="color">$color</param>

Arguments can be used in vitually all parameter values of the xml declaration. Two notable exceptions are the "name" parameter of the <image> tag and the "type" parameter of the <imgop> tag.

Here is and example of the use of arguments:

	    
     <image name="dynamic_label">
	    <label color="$textcolor">
		   <font face="Times New Roman" size="$size"/>
		   <text>$text</text>
	    </label>
     </image>
</font></pre>

This code will generate an image that contains a string of user-specified text, in a user-specified size of the Times New Roman font, painted in the user-specified color. The arguments textcolor,size and text will need to be provided to image maker at the time that the image is built.

While this is not neccessary, it is a good style to declare what arguments will be needed to properly build a given image. (Providing this information also helps automate the invokation of image maker later on.) To this end, you should use the "arguments" parameter of the <image> tag. This parameter's value should be all the needed arguments listed in a comma-separated string with no spaces. For example the image definition of the above label with an added "arguments" parameter would become

	    
     <image name="dynamic_label">
	    <label color="$textcolor">
		   <font face="Times New Roman" size="$size"/>
		   <text>$text</text>
	    </label>
	    <param name="arguments">textcolor,size,text</param>
     </image>
</font></pre>

Using arguments s very convinient in conjunction with the <imgop type="file"> operation. Because it provides the option of including a "base" parameter, you can code all your image paths relative to a base directory, which you can set as an argument:

    
	<imgop type="file" src="images1/mypic1.gif" base="$img_path"/>
	<imgop type="file" src="images2/mypic2.gif" base="$img_path"/>
	<imgop type="file" src="images3/mypic3.gif" base="$img_path"/>

Then you can set the img_path argument to different values depending on where your image base is located. Or if it moves to a remote server, you can set the argument to the base URL. (i.e. "http://www.remoteserver.com/~mydir/")

HOME