DOCSEARCHbyAlgolia
Submit Docs

milsymbol

repository·master·Indexed 21 days ago

https://github.com/spatialillusions/milsymbol

A lightweight, pure JavaScript library for generating military unit symbols compliant with MIL-STD-2525 and STANAG APP-6 standards. It supports rendering symbols as SVG, Canvas, or DOM elements and provides tools for customizing SIDC icons, color modes, and symbol modifiers.

Tokens
9.2K
Snippets
33
Records
51
Agent score
73%

What's inside milsymbol

  1. Overview of supported standards and features

    master

    Milsymbol is a pure JavaScript library that generates military unit symbols according to several international standards.

    Supported Standards:

    • NATO/US: MIL-STD-2525C, MIL-STD-2525D, MIL-STD-2525E
    • FM 1-02.2
    • STANAG APP-6: B, D, E

    Note: Since version 3.0, rendering follows MIL-STD-2525E / STANAG APP-6 E / FM 1-02.2 to ensure uniformity across systems.

    Key Features:

    • Filled/unfilled and framed/unframed symbols.
    • Text fields, movement indicators, and outlines.
    • High performance: Can create ~1000 SVG symbols in less than 20ms.
    • No external dependencies; uses building blocks instead of images/fonts.

  2. How military unit symbols work in milsymbol

    master

    Each symbol created in milsymbol is a standalone object. Once a symbol is instantiated, you can update or add properties to that object. The symbol object provides methods to:

    1. Export the symbol in different formats.
    2. Retrieve information about the created symbol.

    Note on Namespacing: While functionality is typically found under the ms namespace, if you have imported the module into a different variable name, use that variable instead of ms.

  3. Use JSON draw instructions to define geometries

    master

    Milsymbol uses a JSON-based drawInstruction format to define symbol components. These instructions are later converted into Canvas or SVG outputs. When creating custom geometries, use an origin of 100,100 and assume the icon octagon has a height and width of 100.

    Instructions can be individual objects or an Array of instructions. Supported types include:

    • path: Uses SVG path data (d).
    • circle: Uses center coordinates (cx, cy) and radius (r).
    • text: Uses text properties like x, y, fontsize, and textanchor.
    • translate: Moves the coordinate system (x, y) for a nested draw instruction.
    • rotate: Rotates around a center (x, y) by a degree for a nested draw instruction.
    • scale: Scales a nested draw instruction by a factor.
    • svg: Embeds a full SVG XML string.

    Common properties for most types include fill, fillopacity, stroke, strokedasharray, and strokewidth.

    // Example of a path draw instruction
{
  type: 'path',
  d: 'M 80,140 50,60 150,60 120,140',
  fill: 'red',
  stroke: 'black',
  strokewidth: 2
}

  4. Create a formal release of milsymbol

    master

    To publish a stable release of the package to npm and GitHub, follow these steps:

    1. Update package.json with the new version number (e.g., 2.0.0).
    2. Update the version string in ms.js to match.
    3. Run npm login to authenticate with the npm registry.
    4. Run npm publish to publish the stable version.
    5. Create a new release on GitHub using the corresponding tag (e.g., v2.0.0).
    npm login
npm publish

  5. Use milsymbol with OpenLayers via ol.style.Icon()

    master

    To use milsymbol symbols as icons in OpenLayers, use the asCanvas() method provided by the milsymbol instance. The output of asCanvas() can be passed directly as the src property in an ol.style.Icon object. This approach is efficient for handling a large number of symbols.

    Note on Performance: If you are using a style function to apply symbols to features, implement a symbol cache to prevent regenerating the canvas for every symbol during map interactions. In the basic implementation shown below, the style is set directly on each feature.

    This pattern is compatible with OpenLayers v4.6.5 and later.

    // Concept: Using milsymbol output as an OpenLayers Icon source
const symbol = new ms.Symbol({
  symbolId: 'SFGP-A',
  // ... other options
});

const iconStyle = new ol.style.Icon({
  src: symbol.asCanvas(), // Use asCanvas() to provide the image source
  // ... other icon options
});

  7. Explore milsymbol usage examples and external integrations

    master

    The milsymbol library can be integrated with various mapping and UI frameworks. While the repository contains local examples, you can find community-driven implementations and deep-dives for the following technologies:

    • Cesium: For 3D geospatial visualization.
    • SAPUI5: For adding military symbols to SAP enterprise applications.
    • Scala: Via the ScalaMS implementation.

    If you are developing your own examples to contribute to the project, it is recommended to follow the bl.ocks structure (similar to Observable/D3 notebooks).

  8. Extend milsymbol with TypeScript type safety

    master

    If you are developing extensions and want to use custom options in a type-safe manner, you can augment the SymbolOptions interface in a declaration file.

    // 1. Define the augmentation in a .d.ts file
// ./your-project/src/milsymbol.d.ts
import "milsymbol";

declare module "milsymbol" {
  export interface SymbolOptions {
    customOptions?: number;
  }
}

// 2. Use it in your extension
import ms from "milsymbol";
import { type DrawInstruction } from "milsymbol";

ms.addSymbolPart(function (ms) {
  const options = this.getOptions();
  const custom = options.customOptions; // This is now type-safe

  const bbox = new ms.BBox();
  const preDrawArray: DrawInstruction[] = [];
  const postDrawArray: DrawInstruction[] = [];

  // ... your drawing logic

  return {
    pre: preDrawArray,
    post: postDrawArray,
    bbox
  };
});

  9. Use milsymbol in a vanilla JavaScript environment

    master

    In a vanilla environment, milsymbol exports a global ms object. Include the script in your HTML and access the Symbol constructor via ms.Symbol.

    <script src="dist/milsymbol.js"></script>
<script>
  var symbol = new ms.Symbol("SFG-UCI----D", { size: 30 });
</script>

  10. Create and render military symbols

    master

    To create a military symbol, instantiate a new ms.Symbol object by providing a SIDC (Symbol Identification Code) string and an optional configuration object.

    Once the symbol object is created, you must call a rendering method to get a usable output:

    • .asSVG(): Returns an XML representation of the symbol as an SVG.
    • .asCanvas(): Returns a HTML <canvas> element containing the symbol.

    You can chain these methods for a concise implementation.

    // Create a symbol with options and render as SVG
new ms.Symbol("130315003611010300000000000000", {
  size: 35,
  quantity: 200,
  staffComments: "for reinforcements".toUpperCase(),
  additionalInformation: "added support for JJ".toUpperCase(),
  direction: (750 * 360) / 6400,
  type: "machine gun".toUpperCase(),
  dtg: "30140000ZSEP97",
  location: "0900000.0E570306.0N",
}).asSVG();

// Or create a simple infantry platoon and render to Canvas
var canvasElement = new ms.Symbol("130310001412110000000000000000").asCanvas();

  11. Create a prerelease of milsymbol

    master

    To publish a prerelease version of the package to npm using the next tag, follow these steps:

    1. Update package.json by setting the version field to a prerelease string (e.g., 2.0.0-rc1).
    2. Update the version string in ms.js to match.
    3. Run npm pack to generate the package tarball.
    4. Publish the package using the next tag: npm publish <package>.tgz --tag next

    To install this prerelease in a project, use: npm install --save <package>@next

    npm pack
npm publish <package>.tgz --tag next
npm install --save <package>@next

  12. Use milsymbol with Dojo

    master

    You can load milsymbol using Dojo's require mechanism. This allows you to use Dojo from an external source (like js.arcgis.com) while loading the milsymbol module locally.

    <html
  <body
    <script src="dojo/dojo.js" data-dojo-config="async: true"></script>
    <script src="app/milsymbol.js"></script>
    <script>
      require(["milsymbol"], function (ms) {
        var symbol = new ms.Symbol("SFG-UCI----D", { size: 30 });
      });
    </script>
  </body>
</html>