Draw Instructions: milsymbol's Rendering Model

Milsymbol does not write SVG strings or Canvas API calls directly inside its symbol logic. Instead, every visual element — frames, icons, text fields, modifier badges — is first described as a draw instruction: a plain JavaScript object with a type field and geometry properties. Once all symbol parts have assembled their draw instructions into a flat array, milsymbol’s output layer translates that array into either an SVG string (via asSVG()) or Canvas 2D API calls (via asCanvas()). This separation of concerns is what makes milsymbol both extensible and output-agnostic.

Why Draw Instructions Matter for Extension Authors

When you call ms.addSymbolPart() or ms.addIconParts(), you are writing functions that produce draw instructions. Milsymbol collects the pre and post arrays from every registered symbol part and merges them into a single ordered list before rendering. Understanding the draw instruction schema therefore lets you:

Add entirely new graphical elements on top of any symbol
Override or replace built-in icon parts
Position and transform custom geometry in the same coordinate space as the standard icons

Coordinate System

All draw instructions share a single logical coordinate system:

Origin: (100, 100) — the centre of the icon octagon
Icon octagon: 100 logical units wide and 100 logical units tall, spanning from (50, 50) to (150, 150)
A reference SVG showing the octagon and its grid lines is available in the repository at dev/octagon.svg

When you define a path or place a circle, use coordinates relative to this space. The size option scales the entire output uniformly at render time, so your geometry is always authored at the canonical 100×100 scale.

  (50,50) ─────────────── (150,50)
     │                        │
     │    icon octagon        │
     │      origin at         │
     │       (100,100)        │
     │                        │
  (50,150) ──────────────(150,150)

Draw Instruction Types

Milsymbol recognises seven draw instruction types. All types are defined in index.d.ts as a discriminated union (DrawInstruction).

`path`

Renders an SVG path. Use standard SVG d path syntax with coordinates in the 100×100 icon space.

{
  type: "path",
  d: "M 60,140 L 100,60 L 140,140 Z",  // SVG path data string
  fill: "rgb(128,224,255)",             // Fill color string, or false for no fill
  fillopacity: 0.8,                     // Fill opacity 0–1 (optional)
  stroke: "black",                      // Stroke color string, or false for no stroke
  strokedasharray: "4,4",              // SVG stroke-dasharray value (optional)
  strokewidth: 2,                       // Stroke width in logical units (optional)
}

`circle`

Renders a filled and/or stroked circle.

{
  type: "circle",
  cx: 100,                 // Centre x
  cy: 100,                 // Centre y
  r: 25,                   // Radius
  fill: "rgb(255,128,128)",
  fillopacity: 1,          // Optional
  stroke: "black",
  strokedasharray: "",     // Optional
  strokewidth: 3,          // Optional
}

`text`

Renders a text label at a specific position.

{
  type: "text",
  x: 100,                  // x position
  y: 70,                   // y position (baseline)
  textanchor: "middle",    // "start" | "middle" | "end"
  fontsize: 20,            // Font size in logical units
  fontfamily: "Arial",     // Font family string
  fontweight: "bold",      // Font weight string (e.g. "normal", "bold")
  text: "II",              // The text to render
  fill: "black",
  fillopacity: 1,          // Optional
  stroke: false,
  strokedasharray: "",     // Optional
  strokewidth: 0,          // Optional
}

`svg`

Embeds a complete SVG XML string verbatim. Useful for including pre-existing SVG artwork as part of a symbol without converting it to path instructions.

{
  type: "svg",
  svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200"><circle cx="100" cy="100" r="30" fill="blue"/></svg>'
  // svg: string — full SVG XML content
}

SVG embedded via the svg type is inserted into the output as-is. Ensure the inner viewBox matches the milsymbol coordinate space (0 0 200 200 or relative to the icon octagon) or use a translate/scale wrapper to position it correctly.

`translate`

Wraps one or more draw instructions and applies a translation (offset) before rendering them. The nested draw array is itself a DrawInstruction[].

{
  type: "translate",
  x: 10,    // Translate right by 10 units
  y: -5,    // Translate up by 5 units
  draw: [
    // Any draw instructions to shift
    { type: "circle", cx: 100, cy: 100, r: 10, fill: "black", stroke: false }
  ]
}

`rotate`

Wraps draw instructions and applies a rotation around a given centre point.

{
  type: "rotate",
  degree: 45,   // Rotation angle in degrees (clockwise)
  x: 100,       // Centre of rotation x
  y: 100,       // Centre of rotation y
  draw: [
    { type: "path", d: "M 100,60 L 120,100 L 80,100 Z", fill: "black", stroke: false }
  ]
}

`scale`

Wraps draw instructions and scales them by a uniform factor relative to the current transformation.

{
  type: "scale",
  factor: 0.5,  // Scale down to 50 %
  draw: [
    { type: "circle", cx: 100, cy: 100, r: 20, fill: "red", stroke: false }
  ]
}

Arrays of Draw Instructions

A DrawInstruction can be either a single object or an array of objects. Milsymbol’s renderer handles both transparently, which means you can group related shapes into a sub-array and return that array from a symbol part without flattening it first.

// A single instruction — valid
const badge = { type: "circle", cx: 150, cy: 50, r: 12, fill: "black", stroke: false };

// An array of instructions — also valid as a DrawInstruction
const echelonBadge = [
  { type: "circle", cx: 100, cy: 55, r: 15, fill: false, stroke: "black", strokewidth: 2 },
  { type: "text",   x: 100, y: 60, textanchor: "middle", fontsize: 14,
    fontfamily: "Arial", fontweight: "bold", text: "II", fill: "black", stroke: false },
];

// Nested transforms wrapping arrays are fine too
const shifted = {
  type: "translate",
  x: 5,
  y: 0,
  draw: echelonBadge,   // array nested inside a transform instruction
};

Common Fields Reference

All primitive draw instruction types (path, circle, text) share the same set of optional visual styling fields:

Field	Type	Required	Description
`fill`	`string \| false`	Yes	Fill color as a CSS color string, or `false` for no fill
`fillopacity`	`number`	No	Fill opacity from `0` (transparent) to `1` (opaque)
`stroke`	`string \| false`	Yes	Stroke color as a CSS color string, or `false` for no stroke
`strokewidth`	`number`	No	Width of the stroke in logical coordinate units
`strokedasharray`	`string`	No	SVG `stroke-dasharray` value, e.g. `"4,4"` or `"8,12"`

The transformation wrapper types (translate, rotate, scale) do not carry visual fields of their own — those belong to the nested draw instructions.

Using Draw Instructions in Symbol Extensions

A symbol part is a function called with this bound to the current Symbol instance. It must return an object with pre, post, and bbox.

ms.addSymbolPart(function myBadge(ms) {
  // Access current symbol options and metadata
  const options  = this.getOptions();
  const metadata = this.getMetadata();
  const colors   = this.getColors();

  const pre  = [];
  const post = [];
  const bbox = new ms.BBox();

  if (options.customBadge) {
    // Draw a small coloured circle at the top-right of the frame
    post.push({
      type: "circle",
      cx: 148,
      cy: 52,
      r: 10,
      fill: colors.fillColor[metadata.affiliation] || "grey",
      stroke: "black",
      strokewidth: 1.5,
    });
    bbox.merge({ x1: 138, y1: 42, x2: 158, y2: 62 });
  }

  return { pre, post, bbox };
});

Add icon parts with ms.addIconParts()

Icon parts extend the named icon-parts dictionary used when assembling icon glyphs from reusable building blocks. The function receives the current icon parts object, symbol metadata, and symbol colors.

ms.addIconParts(function (iconParts, metadata, colors) {
  // Add a custom path reusable across multiple SIDCs
  iconParts["CUSTOM.HARBOR"] = {
    type: "path",
    fill: false,
    stroke: colors.iconColor[metadata.affiliation],
    strokewidth: 3,
    d: "M 80,140 L 50,60 L 150,60 L 120,140",
  };
});

TypeScript Types

The full set of draw instruction types is exported from milsymbol:

import type { DrawInstruction } from "milsymbol";

// DrawInstruction is a discriminated union:
// DrawPath | DrawCircle | DrawText | DrawSVG |
// DrawTranslate | DrawRotate | DrawScale

const arrow: DrawInstruction = {
  type: "path",
  d: "M 100,50 L 120,80 L 100,70 L 80,80 Z",
  fill: "black",
  stroke: false,
};

For writing typed extensions see the Extending milsymbol guide.

Get Started

Core Concepts

Guides

Integrations

Draw Instructions: milsymbol's Rendering Model

Why Draw Instructions Matter for Extension Authors

Coordinate System

Draw Instruction Types

`path`

`circle`

`text`

`svg`

`translate`

`rotate`

`scale`

Arrays of Draw Instructions

Common Fields Reference

Using Draw Instructions in Symbol Extensions

TypeScript Types

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Integrations

Documentation Index

​Why Draw Instructions Matter for Extension Authors

​Coordinate System

​Draw Instruction Types

​path

​circle

​text

​svg

​translate

​rotate

​scale

​Arrays of Draw Instructions

​Common Fields Reference

​Using Draw Instructions in Symbol Extensions

​TypeScript Types

Build docs developers (and LLMs) love

Why Draw Instructions Matter for Extension Authors

Coordinate System

Draw Instruction Types

`path`

`circle`

`text`

`svg`

`translate`

`rotate`

`scale`

Arrays of Draw Instructions

Common Fields Reference

Using Draw Instructions in Symbol Extensions

TypeScript Types