Skip to content

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.extensions wherever 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, entitythe icon's symbol set and entity code (SIDC positions 5-6 and 11-16)
modifier, sectora sector modifier instead: '11' with set, or '104' for common modifier 04 of identifier 1
svgSVG elements, without the <svg> around them
viewBoxthe drawing's own box, to fit from; default the box of what it draws
fitwhere it goes (below); default main for an icon and the modifier's own sector when a viewBox is given, none otherwise
overriderequired to replace a drawing the standard has
name, pathfor people: the picker, a map's display name
stylea 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
mainthe main sector: centered, at most 0.4 of the octagon tall (5.3.1.2), as main icons are
octagonas large as fits inside the bounding octagon (a full-octagon icon)
sector1, sector2the top and bottom sectors, as sector modifiers sit
noneas 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());

Released under the MIT License; the drawings derive from Apache-2.0 work.