Drawing a symbol
renderSymbol
ts
import {renderSymbol} from '@zaes/military-symbols';
const {svg, width, height, anchor, octagon, problems} = renderSymbol(code, options);| Field | |
|---|---|
svg | a complete <svg> element |
width, height | its size in pixels, amplifiers included |
anchor | the point placed on the map, in pixels from the top left |
octagon | the bounding octagon's box, which amplifiers are placed around |
problems | everything that could not be drawn as the code asks |
fields | the amplifiers this symbol has a place for |
extensions | the host's registered icons, layouts and decorators it drew with (Extending) |
Size
size is the bounding octagon's height in pixels (default 50). The standard sizes everything from that octagon (5.3.1): frames run one to one and a half times it, a main icon sits in its middle two fifths. An icon that looks small in its frame is at the standard's size.
iconScale enlarges main icons, as a multiple of their standard size (default 1, the standard), when one or no sector modifiers are shown, as 5.3.1.2 allows. The room is the bounding octagon, or the octagon less the sector a shown modifier takes; 'fit' makes each icon as large as that room allows (0.9 of it). Lines keep their width.
ts
renderSymbol(sidc, {iconScale: 1.3});How far an icon can grow depends on its shape: a tall, narrow icon has more room than a wide one, and some wide icons already reach the octagon's sides. A size an icon has no room for is reduced to the largest that fits, and problems says so. Icons drawn to their frame (Infantry's X, for one) keep their size. Sizes below the standard are not accepted. To size one code differently from the rest, register style: {iconScale} for it (Extending). enlargeIcons: true is the same as iconScale: 'fit'.
hqStaffLength sets the headquarters staff's length below the frame, as a multiple of the standard's one octagon height (5.3.7.1), from 0.25 to 3 (default 1). Any other value is off-standard, so problems says so. The foot of the staff is the symbol's location, so a shorter staff draws the frame closer to it.
Display options (Table XIV)
| Option | Default | |
|---|---|---|
frame | true | draw the frame |
fill | true | fill the frame with its identity's color |
icon | true | draw the icon |
modifiers | true | the sector modifiers; off is the entity-type level display |
fillOpacity | 1 | 2525E 5.5 suggests 0.35 for a translucent fill |
They combine as Table XIV's rows say: no frame with fill and icon is the icon alone in its identity's color; no frame and no icon is the fill alone; nothing at all is a location dot.
Color
| Option | |
|---|---|
colorMode | Table XV's color range: 'light' (default), 'medium' or 'dark' |
unfilled | an unfilled symbol in its identity's Table XVI color |
monochrome | every line in this color, no fill |
frameColor, iconColor, fillColor, textColor | override one part's color: one color, or one per identity ({friend: '#0a5', hostile: '#c00'}; see Extending) |
lineWeight | scale every non-text stroke, for a house style |
outlineWidth, outlineColor | a halo round the whole symbol, for contrast on a map |
condition | operational condition as Table X's slashes ('slash') or Table XI's bars ('bar') |
mineWarfare | Appendix H's colored MEDAL icons in an unfilled frame ('medal') or the black alternative in the filled frame ('alternative'); mine warfare symbols take no amplifiers |
SVG, canvas or a data URL
The same drawing, in whatever form the host needs:
ts
import {drawSymbol, symbolCanvas, symbolDataUrl, symbolPngDataUrl} from '@zaes/military-symbols';
drawSymbol(ctx, code, {x: 120, y: 80, size: 40}); // onto any 2D context, its anchor at x, y
const {canvas} = symbolCanvas(code, {size: 40, pixelRatio: 2}); // a canvas just big enough
symbolDataUrl(code).url; // the SVG as a data: URL
symbolPngDataUrl(code).url; // a PNG, from a page canvasdrawSymbol draws the SVG element by element, with no image decoding, so it is synchronous and works on an OffscreenCanvas in a worker or a Node canvas.
For another library: the image provider
symbolImageProvider() answers {sidc, sizePx} with {src, sizePx}: an SVG data URL whose larger side is sizePx. It is the shape a library that asks for unit symbols, rather than drawing them, takes. It accepts the display options above, so the symbols match the rest of the map:
ts
import {symbolImageProvider} from '@zaes/military-symbols';
const provider = symbolImageProvider({fillOpacity: 0.5});
provider({sidc: '130310000012110000000000000000', sizePx: 32}); // {src: 'data:image/svg+xml,...', sizePx: 32}