-
Notifications
You must be signed in to change notification settings - Fork 17
Charge metadata
In principle, using a charge is fairly simple - calculate the size and position, scale and transform to suit, set an appropriate fill. There are however some complications, most of which are very hard to figure out in any sort of automated way and some human intervention is required.
This human knowledge we refer to as "metadata", it is data that we need to know to properly place or modify the charge but we can't work it out programmatically.
This can be done in two ways, the first of which is now preferred
The required metadata is embedded in the SVG source file. We use the existing metadata capability of the SVG specification and put the information into the dc:description element. This field is convenient as it can easily be populated using the 'Metadata' tab in the 'Document Properties' of Inkscape. It is free format text, of any size - an extract from the text of an SVG file is shown below:
<metadata
id="metadata3448">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
<dc:description>hflex = 1.2, vflex= 1.4 "fixStroke"=true ;</dc:description>
</cc:Work>
</rdf:RDF>
</metadata>
Metadata within the description element consists of property/value pairs which are described further below. Note that as seen in the example, the precise layout of the metadata is pretty forgiving; just make sure that you have property / value pairs of strings separated by an equals sign.
There is an alternative format which will be needed when we fully implement proper colours as embedded data and this is to further encode the metadata as JSON data. If DrawShield finds the first character of the description field is an opening curly brace '{' it will treat the metadata as JSON, otherwise it will treat it as text. An example of JSON formatted data is shown below:
<metadata
id="metadata29">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
<dc:creator>
<cc:Agent>
<dc:title>https://commons.wikimedia.org/wiki/User:Adalric67</dc:title>
</cc:Agent>
</dc:creator>
<dc:description>{"situation":"palewise", "hflex":1.2, "vflex":1.2,
"proper":{"body":"#050505","beaked":"#EFD807"}}</dc:description>
</cc:Work>
</rdf:RDF>
</metadata>
The other method for specifying metadata is in the various arrays in the file 'svg/metadata.inc' where an associative array has keys which are charge names (or charge groups) and the value is a further array containing the metadata. This has some nice features such as the ability to apply a set of metadata to an entire group fo charges but further use of this file is deprecated in favour of embedding the data directly into the SVG as described above.
This describes how the charge should be depicted if it is described as "demi". Two values are allowed, 'horizontal' (you will see the top half of the charge), 'vertical' (you will see the dexter side of the charge).
This takes the value 1 or -1 and tells the program whether the charge should be placed in the same orientation as bend, fess or pale if it is placed "on" the ordinary. THIS IS NOT FULLY IMPLEMENTED YET.
This determines whether a charge is turned when it is described as "fesswise" or "palewise". Sometimes charges are described as "palewise" meaning 'upright' when they already are upgright. This is not an error, it is perfectly reasonable to say things like "in first quarter a sword fesswise and in 2nd quarter a sword palewise" - the sword is, by default already upright so the "palewise" is in theory redundant but is used to make clear the contrast with the first sword. Hence we cannot simply just turn everything if it is "fesswise" or "palewise" we need to know its normal attitude.
For this we use the metadata term "Situation". It may take values of either "fesswise" or "palewise", and obviously if a charge has the situation "fesswise" it will NOT be turned if it is desrcribed as "fesswise" (because it already is) but it WILL be turned if it is described as "palewise".
Determining what the actual situation for any given charge is hard to automate so it really needs a human to look at the charge and decide, it most cases it is pretty obvious.
This may take the values true or false and indicates whether the charge can be fimbriated. If not present 'false' is assumed. (This may have been superceded by Mattias's filter based fimbriation code so it may be removed in the future).
This describes how charges that are "on" the current charge will be placed. By default, the "on" charge(s) will be placed in the center of the underlying charge and scaled to about 3/4 of the size of the underlying charge. This metadata allows that default to be overridden and can take up to three comma-separated numeric values. The values are:
- The X coordinate of the centre of the superposed charges, expressed as a percentage of the width of the underlying charge
- The Y coordinate of the centre of the superposed charges, expressed as a percentage of the height of the underlying charge
- The scale of the superposed charges, expressed as a percentage of the size of the underlying charge
For the coordinates, 0,0 places the centre of the superposed charges at the top left of the underlying charge, 100,100 at the bottom right.
For the scale 100 will completely obscure the underlying charge, anything less will leave at least the outer parts of the underlying charge visible.
This item of metadata can be used to place superposed charges in a particular size and a particular location on specific underlying charges.
These are multipliers which tell how much the charge is able to stretch to fill the available space. The default value is "1", which means that the charge cannot stretch at all. A value of 1.5 indicates that it can be stretched to 150% of normal size, a value of 2 200% and so on.
The program tries to choose a stroke colour that is a good contrast to the body colour that is used for the charge - this doesn't always work and if the fixStroke item exists then a fixed colour will be used instead. The value of this colour will be whatever is set to charge-stroke in the current palette (by default, #696969 - see svg/schemes/drawshield.txt)