-
Notifications
You must be signed in to change notification settings - Fork 19
The RandomBlazon API
The DrawShield suite includes a facility to generate a random blazon. This blazon will be heraldically valid, and also will have an extremely high probability of being drawn correctly by the DrawShield program(!)
It is available from a dedicated page on the drawshield.net site but can also be invoked through a simple API.
The aim of the random generator is to inspire creativity and be the basis for new heraldic designs by:
- Being heraldically valid and syntactically correct
- Having no adjacent tinctures the same
- Choosing from a comprehensive set of choices
- Being drawable by DrawShield without errors or warnings
- Having a preference for the more commonly found features of heraldry
- But the rarer features might still appear occasionally
- Allowing the user to tailor the high level choices available
The API can be invoked by either a GET or POST request to the URL:
https://drawshield.net/include/randomblazon.php
This will return a blazon in plain text which can be used as required, for example it could be re-submitted to the drawshield API to have it drawn in a variety of styles and sizes. With no arguments the generator will simply apply some default tailoring of the options and return a plain text, neatly formatted blazon.
The high level choices made by the generator can be controlled by the user by setting argument options, either in the GET or POST request. For simplicity I will refer to the GET format.
Note that the generator will apply its own set of default values, which may change, and are not all the same. In particular, you should NOT ASSUME that an argument that is not present means that those choices will not be available. If you want to ensure that a particular set of choices is NOT used, then you should explicitly provide the argument and set its value to "off".
For example if you want to disallow the use of furs in your generated blazon you would use the following GET URL:
`https://drawshield.net/include/randomblazon.php?tinc-furs=off
All other options would take their default values.
In the tables below columns show:
- "Option" gives the name of the argument
- "Meaning" is a brief explanation, and examples
- "Values" shows the available values, and the default value in brackets
- "Size" an estimate of the number of different possible choices
Very crudely, the total number of possible blazons that might be generated can be found by adding the sizes of all the "on" options of each table and multiplying the table totals together. The default values give a range of possible blazons in the hundreds of millions.
| Option | Meaning | Values | Size |
|---|---|---|---|
| tinc-common | Use the most common heraldic colours (Gules, azure...) | on,off (on) | 7 |
| tinc-second | Use the secondary heraldic colours (Tenne, murrey...) | on,off (on) | 11 |
| tinc-modern | Use modern colours (Copper, iron, buff...) | on,off (off) | 10 |
| tinc-treatments | Use any two of the preceeding colours in one of a number of repeating patterns (Fretty, maily...) | on,off (on) | 420 |
| tinc-furs | Use any of the known furs (Ermine, potent...) | on,off (on) | 12 |
Note that furs and treatments will only appear as part of the field of the blazon (i.e. as the field itself, or as part of a divided field), never as the colouring for an ordinary or charge. For this reason you should set at least one of the first three choices to "on". (If you turn all three "off" then tinc-common will be forced back on).
| Option | Meaning | Values | Size |
|---|---|---|---|
| div-chance | %-age likelyhood of a divided field (as opposed to a plain field) | 0-100 (50) | n/a |
| div-2part | Use the major two part divisions (per fess, per pale...) | on,off (on) | 12 |
| div-3part | Use the major three part divisions (tierced in fess...) | on,off (on) | 8 |
| div-bars | Use divisions made up of bars (barry, bendy...) | on,off (on) | 6 |
| div-small | Use the smaller, less common divisions (Chape, chausse...) | on,off (on) | 3 |
| div-pattern | Use divisions of over-lapping bars (Barry bendy...) | on,off (on) | 8 |
| div-edges | Vary the edge types (wavy, rayonny...) | on,off (on) | 400 |
| div-counter | Allow two overlapping divisions, counterchanged | on,off (on) | 16 |
Obviously, a value of 0 for "div-chance" means that a divided field will never occur, while 100 means that it always will. If the value is greater than 0 then you should ensure that at least one of the remaining options is set to "on". If all are turned off then "div-2part" will be forced back on.
| Option | Meaning | Values | Size |
|---|---|---|---|
| ord-chance | %-age likelyhood of an ordinary appearing | 0-100 (50) | n/a |
| ord-common | Use common ordinaries (Fess, pale, bend...) | on,off (on) | 12 |
| ord-multi | Use ordinaries made of multiple bars (bars, pales...) | on,off (on) | 8 |
| ord-minor | Use less common ordinaries (Canton, gyron...) | on,off (on) | 6 |
| ord-rare | Use rarely seen ordinaries (Crancelin, gorge...) | on,off (on) | 3 |
| ord-mods | Vary edges, add cottices etc. (nowy, voided...) | on,off (on) | 8 |
As usual, if the chance of an ordinary appearing being greater than 0, and all the options being turned "off" then "ord-common" will be forced to "on".
| Option | Meaning | Values | Size |
|---|---|---|---|
| chg-chance | %-age likelyhood of a charge appearing | 0-100 (50) | n/a |
| chg-lion | Use various poses of lions and their features (lion rampant...) | on,off (on) | 12 |
| chg-geom | Use geometric charges (mullet, triangle...) | on,off (on) | ? |
| chg-cross | Use some of the many styles of heraldic crosses as charges (tau, bottony...) | on,off (on) | ? |
| chg-bird | Use charges of various birds, possibly in different poses (chough, dove...) | on,off (on) | ? |
| chg-weapon | Use charges of weapons and related items (sword, pheon...) | on,off (TBD) | ? |
| chg-myth | Use charges of mythical creatures, possibly in different poses (dragon, basilisk...) | on,off (TBD) | ? |
| chg-animal | Use charges of animals that do not fall into other categories, possibly in different poses (fox, sheep...) | on,off (TBD) | ? |
| chg-symbols | Use charges that represent various symbols (planet mars, alchemical...) | on,off (TBD) | ? |
| locate-chg | %-age likelyhood that the charge is in a location other than centered on the field | 0-100 (10) | 6 |
As usual, if the chance of an charge appearing is greater than 0, and all the options being turned "off" then "chg-lion" will be forced to "on". There is a certain amount of interaction between ordinaries and charges - if both are chosen to appear then in some cases the charges will be placed on the ordinaries.
The program attempts to create a blazon exactly suited to the user's requirements by using:
- An analysis of the user's neural pathways and brainwave patterns
- A comprehensive trawl through the user's browser history and email folders
- Interviews with friends and close family members
- Repeated applications of the PHP "rand()" function
(Okay, I'm joking, it only uses the last one!)
The heart of the program is a large data structure known as the lexicon containing keys and arrays of strings. The strings are of the form:
"a {ord-common} {edge-all} {base-tincture}"
Where the items in curly braces are the key values of other arrays. For example, the {ord-common} key might contain strings such as:
"fess", "pale", "bend {sinister}"...
Sometimes the arrays of strings might contain empty strings, such as that for {sinister} which might contain:
"", "", "sinister"
The program starts from a "seed" string and repeatedly scans it for key values in curly braces. It replaces the braces and key with a randomly chosen item from the array of strings associated with that key in the lexicon. It will then recursively re-scan the new string replacing key values in braces until none remain. The final string is formatted and punctuated properly and returned as the output.
Hence, with the example above, when the program encounters {ord-common} it might randomly chose "bend {sinister}" from the strings associated with that key. It will re-scan the string to find {sinister} and replace that with a randomly chosen item from the array with the key "sinister". This array contains two empty strings and the word "sinister", so in this case there is a one third chance that we end with "a bend sinister" and a two thirds chance that we end with "a bend".
There are some additional complications such as ensuring that tinctures are not re-used in adjacent items. This is done by recording each use of a tincture in a global list; and, in addition, adding to the table the component colours if the chosen tincture is a fur. For example, if "ermine" ends up being chosen then the tinctures "ermine", "sable" and "argent" will be added to the list and not used again.
The program can also chose from amongst a range of numbers, with the construction {n-m} where n and m are integers in ascending order. Large numbers are comparatively rare in heraldry so the program has a built-in preference for the lower end of the range. For example, the range {3-6} will be expanded into the set of choices below, one of which will be chosen randomly:
"3", "3", "3", "3", "4", "4", "4", "5", "5", "6"
Finally, the program also makes some decisions for artistic effect based on what has already been chosen, so for example if a charge is required and there is a large ordinary already present the program may place the charge on or around the ordinary rather than in the usual position centered in the field.