Extending
Four ways to change what is drawn, beyond the display options: your own icons and sector modifiers, your own amplifier placement, colors per identity, and decorators that draw on every symbol they accept.
Every registration:
- is checked when it is made. A mistake throws there, with every problem listed, and nothing is registered. It doesn't fail later on a map;
- returns a function that undoes it;
- is named in
RenderedSymbol.extensionswherever it was used, so a house drawing is never taken for the standard's; - reaches every output: SVG, canvas, atlas, the map renderers, Leaflet, ArcGIS and the picker.
Frames can't be replaced, because their shapes carry the identity (2525E 5.3.1).
Icons and sector modifiers
ts
import {registerIcons} from '@zaes/military-symbols';
const undo = registerIcons([
// A code the standard doesn't define, drawn in its own 100 x 100 box and fitted to the main sector.
{set: '10', entity: '199900', name: 'Drone Team', path: ['Drone Team'],
svg: '<path d="M10 50 50 10 90 50 50 90Z" fill="none" stroke="black" stroke-width="6"/>',
viewBox: [0, 0, 100, 100]},
// Replacing a standard icon needs override: true.
{set: '10', entity: '121100', svg: houseInfantry, viewBox: [0, 0, 64, 64], override: true},
// A sector modifier: two digits of the set's table, or three for a common one (identifier first).
{set: '15', modifier: '11', sector: 1, svg: '<rect width="60" height="20" fill="white" stroke="black"/>',
viewBox: [0, 0, 60, 20]},
], {name: 'house'});| Field | |
|---|---|
set, entity | the icon's symbol set and entity code (SIDC positions 5-6 and 11-16) |
modifier, sector | a sector modifier instead: '11' with set, or '104' for common modifier 04 of identifier 1 |
svg | SVG elements, without the <svg> around them |
viewBox | the drawing's own box, to fit from; default the box of what it draws |
fit | where it goes (below); default main for an icon and the modifier's own sector when a viewBox is given, none otherwise |
override | required to replace a drawing the standard has |
name, path | for people: the picker, a map's display name |
style | a house style for this icon's symbols: frameColor, fillColor, fillOpacity, iconColor, textColor, lineWeight, iconScale (below) |
Where it goes. fit puts the drawing where the standard puts its own:
fit | |
|---|---|
main | the main sector: centered, at most 0.4 of the octagon tall (5.3.1.2), as main icons are |
octagon | as large as fits inside the bounding octagon (a full-octagon icon) |
sector1, sector2 | the top and bottom sectors, as sector modifiers sit |
none | as given, in the drawing frame: 612 x 792 units with the octagon centered on (306, 396), 245 units tall |
Color. Black (or no paint at all) takes the icon color, monochrome and the unfilled colors, the same as the standard's icons. White becomes the identity's color when the symbol is drawn without a frame (Table XIV). Any other color stays as drawn.
Elements. Only the ones every output draws the same way are accepted: g, path, line, polyline, polygon, rect, circle, ellipse, text. These are refused: use, image, gradients, style and class attributes (give paint as fill, stroke and stroke-width), event handlers and links.
Codes the standard doesn't define are drawn, and problems says the code isn't in the standard: another system reading it will not know it. A code you replace with override draws with no problem and is listed in extensions.
Standards. A registration applies to 2525E's and 2525D's drawings unless you pass {standard: '2525E'} or {standard: '2525D'}. If the same code is registered again, the latest registration wins; undoing it brings back the one before.
A house style among doctrinal colors
A registered icon can carry its own colors and line weight. Its symbols are drawn that way wherever they appear, on the maps too, while the standard's symbols beside them keep the doctrinal colors of Table XV:
ts
registerIcons([{
set: '10', entity: '199900', name: 'Drone Team', svg: drone, viewBox: [0, 0, 100, 100],
style: {
frameColor: {friend: '#00507a', hostile: '#8a0000'},
fillColor: {friend: 'rgba(0,168,220,0.22)', hostile: 'rgba(255,48,49,0.22)'},
lineWeight: 4 / 3,
},
}]);The style takes the place of the display options' colors and line weight for those symbols only. Monochrome and unfilled display still apply to them, so a monochrome map stays monochrome. Give colors per identity so friend and hostile stay distinct: the frame shape carries the identity, and the fill helps. A style is for icons; sector modifiers draw in their symbol's colors.
Restyling a standard symbol
To give a real code house colors without redrawing it, leave out svg: with override: true and a style, the standard's own drawing is kept and only the style applies. extensions lists it as style: rather than icon:.
ts
registerIcons([{set: '10', entity: '121100', override: true, style: {frameColor: '#00507a', iconColor: '#00507a'}}]);A restyle needs a code the standard draws, and it is for icons only.
Sizing one icon
style.iconScale gives one code its own icon size, in place of the display options' iconScale (see Rendering). Every other code keeps following the display options:
ts
configureMilitarySymbols({display: {iconScale: 1.2}});
registerIcons([
{set: '10', entity: '200300', override: true, style: {iconScale: 1.6}},
{set: '10', entity: '200500', override: true, style: {iconScale: 'fit'}},
]);The same limits apply: the icon stays within the bounding octagon, and a size below the standard is refused when registered, as is a code whose icon is drawn to its frame.
Letter codes (2525C, 2525B, APP-6(B))
A letter code is drawn with its own standard's drawings, so by default a registration does not change it: a 2525C code keeps the look 2525C prints. Pass {letterCodes: true} to reach letter codes too:
ts
registerIcons([{set: '10', entity: '121100', svg, viewBox: [0, 0, 100, 100], override: true}], {letterCodes: true});
renderSymbol('SFGPUCI----'); // the registered icon in 2525C's own frame- A letter code that converts to the registered code draws the registered icon inside its own frame, and takes the registration's style.
- A restyle (no
svg) keeps the letter code's own icon and applies only the style.
Amplifier placement
ts
import {registerLayout} from '@zaes/military-symbols';
registerLayout({
name: 'house',
frameShapes: ['3'], // land units (Table A-LX); default every shape
left: [['T'], ['M']], // rows, top to bottom, against the frame
right: [['AP'], ['H']],
});A layout replaces the sides it gives (left, right, top); the others stay the standard's. accepts: (sidc) => boolean narrows which codes it applies to, and the latest layout that applies wins. Any Table VI text field can be placed, target number AP included, except AA (inside the frame) and AO (the engagement bar), which have their own places. Lengths and values are still checked against Table VI. amplifierFields follows the layout, so an editor offers exactly what is drawn, and a field the layout has no place for is reported. Control measure points keep their Appendix L templates.
Colors by identity
frameColor, fillColor, iconColor and textColor take one color, or one per standard identity:
ts
renderSymbol(code, {
frameColor: {hostile: '#7a0000'},
fillColor: {friend: 'rgba(0,168,220,0.2)', hostile: 'rgba(255,48,49,0.2)'},
lineWeight: 4 / 3,
});The keys are pending, unknown, assumedFriend, friend, neutral, suspect and hostile. An identity left out takes the color of the identity whose Table XV row it shares (pending takes unknown's, assumed friend takes friend's). If neither is given, it keeps the standard's color. On a map these are display options like the others (configureMilitarySymbols({display: {...}})).
Decorators
A decorator draws on every symbol it accepts, for a mark the standard doesn't have: a readiness dot, a highlight ring, a band.
ts
import {registerDecorator} from '@zaes/military-symbols';
registerDecorator({
name: 'readiness',
accepts: (sidc) => sidc.symbolSet === '10',
draw: ({octagon, unitsPerPixel}) =>
`<circle cx="${octagon[0] + octagon[2]}" cy="${octagon[1]}" r="${6 * unitsPerPixel}" fill="rgb(0,170,0)"/>`,
});draw gets the parsed code, the options, the boxes of the octagon, the frame, the main icon and everything drawn so far, the anchor, the colors the symbol is drawn in, and unitsPerPixel for sizes in pixels. Everything is in the drawing frame above. It returns SVG (measured for you), {svg, box}, or nothing. By default a decorator draws over everything; with below: true it draws under the frame. The picture grows to hold it. A decorator that throws, or returns elements the outputs can't draw, is left out and named in problems.
Keeping maps current
Cached map drawings follow extensionsVersion(), which changes with every registration and every undo. If a decorator's output depends on your own data, call refreshExtensions() when that data changes. To redraw a map that is already showing, listen for changes and refresh its renderer, as you would after configureMilitarySymbols:
ts
import {onExtensionsChange} from '@zaes/military-symbols';
onExtensionsChange(() => renderer.refresh());