The DrawShield API
The Shield Drawing function of DrawShield can be invoked in 3 ways:
-
From the command line (no options are processed and the output is fixed as PNG). This mode is largely for debugging but might also be useful for bulk generation of PNG images.
-
Via an HTTP POST request - this is the recommended method as it gives the greatest flexibility and range of options (described below). This the method used by the drawshield.net website "create" page.
-
Via an HTTP GET request - this is also useful and quite flexible, the only option not available is that it is not possible to provide the blazon in an uploaded file.
This is a very simple process, all of the arguments will be concatenated into a single string, separated by spaces and this will be treated as the blazon. A file named shield.png will be created which will be 500 pixels wide, using the DrawShield colour scheme, the heater shield shape and the shiny effect.
The program should be run from the top level directory containing the drawshield code. An example command line would be:
php drawshield.php azure a bend or
If there are no arguments the program will instead look for a file in the same folder named ‘debug.inc’. If this exists it will be “included” and hence should consist of PHP code. Most usefully this code should set the various values of the $options array, for example:
$options[“blazon”] = ”azure a bend or“;
You can also set other options as required. This is the suggested method for using a PHP debugger.
If the drawshield code is installed on a PHP enabled web-server it can be invoked either by a GET or a POST request. An equivalent GET request to the example above would be:
http://drawshield.net/include/drawshield.php?blazon=azure%20a%20bend%20or
If you install the drawshield code on your own server then obviously the URL and the initial path may be different.
Except where noted below, the GET and POST methods to drawshield accept the same set of arguments. All argument names and values must be lowercase, except for the blazon, which may in mixed case and contain accented characters.
This is the only mandatory argument, although it can be blank, in which case an empty shield is constructed and returned. The value must be entity encoded.
As noted above, mixed case and accented characters are supported (although this is not necessary, for parsing purposes the program will lowercase all input and "collapse" accented characters to their unaccented versions). Case and accents are preserved in strings, for example vert the word "Olé" argent will display as shown.
This argument is only available with the POST method. If a form includes multi-part data with the name "blazonfile", a filename that ends in ".txt" and is less than 100,000 characters long then the contents of that multi-part data will be used as the input blazon. Note that the existence of blazonfile will take precedence over a blazon given in the "blazon" argument.
This argument determines the output format of the drawn shield, allowable values are:
- svg - SVG vector graphic format, XML data rendered as an image by your browser (default)
- jpg - JPEG image
- png - PNG image with a transparent background
- json - This format combines several types of data in a JSON wrapper, see the section below
(Note that if the argument "asfile" is present then this argument is ignored - the argument "saveformat" is used instead)
This argument is slightly mis-named in that it is actually the width of the resulting image. It will be coerced to be at least 100 but has no upper limit. The default value is 500. It represents the width in pixels of the rendered image. The height of the image will usually be 1.2 times the width but some shapes have slightly different values.
This option sets the outline shape of the shield, allowable values are:
| Value | Shape |
|---|---|
| heater (default) |  |
| french |  |
| oval |  |
| lozenge |  |
| square |  |
| italian |  |
| swiss |  |
| english |  |
| german |  |
| polish |  |
| spanish |  |
| flag |  |
This option only makes a difference if the flag shape is chosen - it sets the proportions (aspect ratio) of the flag and can be specified either as a ratio (e.g. 9:10) or a decimal value (e.g. 0.9). The value is automatically constrained to sensible limits.
This option sets the choice of colours to be used in displaying the shield. (There is no defined meaning of heraldic colours other than, for example, "gules" is to be represented as something resembling "red"). Various authorities have developed their own colour choices and drawshield supports the following option values:
| Value | Example Palette |
|---|---|
| drawshield (default) |  |
| wikipedia |  |
| emoji |  |
| wappenwiki |  |
| outline |  |
| bajuvarian | (N/A) |
You can define your own colour palette, following the instructions on this page..
The palette above refers to the colour values for the standard heraldic named colours. In addition to these it is also possible use sets of other colours, that are NOT heraldic but are useful in specific situations like flags, pauldrons and tartans. These additional colour sets can be enabled by the following options:
- webcols=yes - allow any of the named web colours to be used
- whcols=yes - allow any of the named Warhammer 40,000 colours from the Citadel Minatures paint range to be used
- tartancols=yes - allow any of the standard Tartan colour names to be used
For more details on these colours see the Colour Reference section in the visual catalog
DrawShield supports some simple effects to give your shield the appearance of being constructed in a particular material. These effects are achieved by applying an SVG filter, most of which are based on those built in to Inkscape whose authors I would like to thank. All the filters except plain (which actually means "no filter") affect the colour values set by the palette. To get just the pure colours from your chosen palette select the "plain" value for effect. The available values are:
| Value | Example Effect | Explanation |
|---|---|---|
| shiny |  |
Supposed to look like a metallic surface with a highlight in the top left and coloured shadows to lower right |
| plain (default) |  |
No filters, show the pure colours from the palette. |
| stonework |  |
Supposed to look like a slightly roughened stone surface that has been overpainted with the shield. |
| plaster |  |
Supposed to look like the design has been embossed into wet plaster but isn't really very good! |
| vellum |  |
Supposed to look like the design has been inked onto rough vellum (animal skin). I quite like this one! |
Suggestions for new filters (ideally in the form of SVG code!) are very welcome.
If this option is present then instead of returning the image the program will force the download of the image as a file, called "shield.svg", "shield.png" or "shield.jpg" depending on the setting of the "saveformat" option.
This option selects the file format for the "asfile" option, it takes the same values as "outputformat" above.
This option used to turn off the text shown to the bottom left of the shield when saving as a file. This happens automatically now so the option is no longer required.
This used to provide debugging information but there is now more complete data available in the json format.
This format combines several items of useful data wrapped in a JSON object. Top level object properties are as follows:
This is the shield image, in PNG format at the requested size, but encoded as Base64 text. It is the identical image that you would have received had the output format been set to 'png'.
This is the result of the parsing stage and contains a representation of the blazon in XML, conforming to the blazonML schema. This is the "pure" prase tree before any rendering has been attempted.
This is a simplified, pretty-printed version of the parse tree which is sometimes easier to read. For example the input "azure a mullet or" will produce the mintree value of:
shield ID=N1-9
simple ID=N1-3
field ID=N1-2
tincture ID=N1-0 index=1 origin=given
colour ID=N1-1 keyterm=azure tokens=azure linenumber=1/
/tincture
/field
objects ID=N1-4
charge ID=N1-6 number=1 tokens=a mullet linenumber=1 keyterm=mullet/mullet
tincture ID=N1-7 index=1 origin=given
colour ID=N1-8 keyterm=or tokens=or linenumber=1/
/tincture
modifier type=chargemod keyterm=chg_data ID=S1-2 value=chg1/
/charge
/objects
/simple
/shield
Not that is extracted after any cross-references have been resolved and so may contain additional rendering hints. For example the "chg_data" modifier is the key to a cached version of the information needed to draw mullets (for use when drawing multiple charges). I'm not sure how useful this actually is, so this behaviour is subject to change, it may in future be a simple extract from the simple parse tree above.
This is the set of global options that were used to create the shield. These will either have been set elsewhere in the API call or take the default value. They are as described above, although note that some of the names change (hopefully in obvious ways), for example the API argument 'ar' becomes 'aspectRatio' in the set of options.
Each message object may contain the following properties:
- ID - (string - optional) if the message can be related to a specific part of the phrase tree this property gives value of the ID attribute of the relevant node
- category - (string) type of message, one of blazon / warning / internal / licence, all hopefully self-explanatory
- content - (string) the message text
- context - (string - optional) if this is an error message related to the blazon this is that part of the input blazon text in which the error occcured
You can see examples of simple applications that use this API in the GitHub Gists here: