-
Notifications
You must be signed in to change notification settings - Fork 18
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.
There are two possible approaches to setting options:
- Accepting the default options and making individual changes if desired
- Setting all options either on or off and setting your own choices
By default, the random generator will produce traditional heraldic forms. The default options are mostly "on", except for those things that are of more recent usage, or non-standard additions added by drawshield.net. For example, the modern tincture group is turned "off" by default.
To use the default values no options are required, however if you wish to make minor changes, for example if you wish to use the default options but disallow the use of furs you can use a URL of the form:
https://drawshield.net/include/randomblazon.php?tinc-furs=off
The alternative approach is to set all of the options to a "known" state - either all on or all off and making individual changes as required. For example if you just want to generate random divided fields using only plain colours and shapes you can use a URL of the form:
https://drawshield.net/include/randomblazon?opt-all=off&tinc-common=on&tinc-second=on&div-chance=100&div-2part=on&div-3part=on
Note that the actual order of the arguments in the URL doesn't matter - "opt-all" will always be processed first.
Also, be aware that you can turn entire option groups on or off - see the details in the table below. For example, if you wanted to achieve something similar to the above but were less concerned about the type of division you could use a URL such as:
https://drawshield.net/include/randomblazon.php?opt-all=off&tinc-common=on&tinc-second=on&div-all=on
If this is all too confusing and you don't understand what set of options you are using just add "show-opt=1" to your URL, for example:
https://drawshield.net/include/randomblazon.php?opt-all=off&tinc-common=on&tinc-second=on&div-all=on&show-opt=1
This will generate a random blazon as normal but will also list all the option settings afterwards.
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 |
| tinc-all | Turn all tinctures on or off (processed first) | on,off (n/a) | (n/a) |
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-counter | Use two overlapping divisions, counterchanged | on,off (on) | 16 |
| div-edges | Vary the edge types (wavy, rayonny...) | on,off (on) | 400 |
| div-all | Turn all divisions on or off (processed first) | on,off (n/a) | (n/a) |
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.
If the "div-all" option is used this will be processed first. A value of "on" will set the "div-chance" option to its default setting (60), a value of "off" will set it to 0.
| 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) | 24 |
| ord-minor | Use less common ordinaries (Canton, gyron...) | on,off (on) | 33 |
| ord-rare | Use rarely seen ordinaries (Crancelin, gorge...) | on,off (on) | 16 |
| ord-mods | Vary edges, add cottices etc. (nowy, voided...) | on,off (on) | 400 |
| ord-all | Turn all ordinaries on or off (processed first) | on,off (n/a) | (n/a) |
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".
The varying edges and cottices can only be applied to the larger ordinaries, which occur in the "ord-common" and "ord-multi" groups. If neither of these groups are "on" then "ord-mods" will not have any effect.
If the "ord-all" option is used this will be processed first. A value of "on" will set the "ord-chance" option to its default setting (60), a value of "off" will set it to 0.
| 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) | 110 |
| chg-geom | Use geometric charges (mullet, triangle...) | on,off (on) | 80 |
| chg-cross | Use some of the many styles of heraldic crosses as charges (tau, bottony...) | on,off (on) | 120 |
| chg-bird | Use charges of various birds, possibly in different poses (chough, dove...) | on,off (on) | 60 |
| chg-crown | Crown's, coronets and jewels (Naval, Ducal, orb...) | on,off (on) | 30 |
| chg-animal | Use charges of animals that do not fall into other categories, possibly in different poses (fox, sheep...) | on,off (on) | 50 |
| 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-symbols | Use charges that represent various symbols (planet mars, alchemical...) | on,off (TBD) | ? |
| (TBD) | (Other charge groups still to add) | ? | |
| chg-loc-chance | %-age likelyhood that the charge is in a location other than centered on the field | 0-100 (10) | 6 |
| chg-all | Turn all charges on or off (processed first) | on,off (n/a) | (n/a) |
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.
If the "chg-all" option is used this will be processed first. A value of "on" will set the "chg-chance" option to its default setting (60) and "chg-loc-chance" to 10 , a value of "off" will set both to 0.
The program attempts to create a blazon exactly suited to the user's requirements by using:
- An analysis of their neural pathways and brainwave patterns
- A comprehensive trawl through their 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.