Skip to content

Developer's Guide

Jump to bottom
Michael Spinelli edited this page Mar 27, 2015 · 68 revisions

MIL SYMBOLOGY JAVASCRIPT RENDERER

DEVELOPER’S GUIDE

Revision History
Initial Document 12/18/2012
Updated 02/24/2014
Updated 03/17/2014 - New ImageInfo function documented.
Updated 03/25/2014 - System Requirements section updated.
Updated 04/25/2014 - Added info on new ICON attribute. Updated 08/03/2014 - Added info on new LookAtTag attribute.
Updated 10/31/2014 - Added GeoJSON format and noted new toSVG function off of the ImageInfo object

1 Overview
1.1 Features
1.2 System Requirements
2 Setting up the JavaScript Renderer for Use
2.1 Compile the mil-sym-js project
2.2 Loading the JavaScript Renderer in your page
3 Rendering
3.1 Configuring the Renderer for your Needs
3.2 Singlepoint Icon Symbology
3.2.1 Setting Modifiers
3.2.2 Setting Attributes
3.2.3 Getting your Image (ImageInfo)
3.2.4 Rendering Your Image via HTML5 Canvas
3.2.5 Rendering Your Image via Data URL
3.2.6 Rendering Your Image via jQuery plugin
3.2.7 Make Sure The Fonts Are Loaded Before Trying To Render
3.3 Multipoint Symbology
3.3.1 Required Parameters for Multipoint Symbology
4 SymbolUtilties
4.1 getBasicSymbolID()
4.2 hasModifier()
4.3 isMultiPoint()
5 The Symbol Definition Table
5.1 hasSymbolDef()
5.2 getSymbolDef()

1 OVERVIEW

##1.1 FEATURES
The JavaScript versions of the Mil-Std Symbology Renderer supports rendering of single & multi point symbology. Single points as an html5 canvas object or a data url. Multi points as kml.

##1.2 System Requirements

###1.2.1 Single Point Requirements
Only IE & Firefox are tested on a regular basis but the other browsers listed seem to work well.
Windows 7: IE 9+ or Firefox 16+ or Chrome 32+ or Opera 21+
OS X: Chrome 14+, Opera 11.6+, Safari 7
Debian 6: Opera 12+, Firefox 12+, Chrome 30+
IOS 7.1: Safari
Android 4.3: Chrome 33+
Windows Phone 8: IE

See compatibility chart for more detail: Single Point Rendering Web Browser Compatibility Chart

###1.2.2 Multi Point Requirements
Should work on any current browser

#2 SETTING UP THE JAVASCRIPT RENDERER FOR USE

##2.1 COMPILE THE MIL-SYM-JS PROJECT
This project builds with Ant resulting in two JavaScript files. One has all of the JS code combined into one file. The other is a minified version of the first file. (i.e. sm-bc.js & sm-bc.min.js) Open a command prompt to the root folder of the repository on your local machine and enter:
ant clean
ant concat sm-bc minify samples
"sm-bc" represents what you rendering capabilities you want.
• s: singlepoint (jquery plugin for singlepoint rendering only available in singlepoint only builds)
• m: multipoints
• sm: both
• b: 2525B support
• c: 2525C support
• bc: both
• allFlavors: every variation will be generated

Running "ant concat sm-bc minify samples" would result in the following files being placed in the "dist" folder:
• fonts (contains fonts needed for singlepoint rendering)
• renderer.css (to load the font files)
• jquery-[version].min.js
• multiPointTester1.html (renders kml for a couple multipoint symbols)
• multiPointTester2.html (renders kml for a couple multipoint symbols in a loop to test performance)
• singlePointTester.html (renders a couple of singlepoint symbols to the page)
• single-point-plugin.html (show sample usage with jQuery)
• sm-bc.js (concatenated renderer code)
• sm-bc.min.js (concatenated & minified renderer code)

##2.2 LOADING THE JAVASCRIPT RENDERER IN YOUR PAGE
The top of your html page should look similar to the snippet below:

<!DOCTYPE html>
<html>  
<head>  
<!-- Meta line required for IE-->
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<title>single point tester</title>
<link rel="stylesheet" href="renderer.css" type="text/css" charset="utf-8" />
<script src="sm-bc.min.js" type="text/javascript" ></script>

This loads the required font files via the css file and pulls in the concatenated JavaScript renderer file.

#3 RENDERING

##3.1 CONFIGURING THE RENDERER FOR YOUR NEEDS
The “RendererSettings” object will let you set some default rendering values. It is accessible at "armyc2.c2sd.renderer.utilities.RendererSettings”.

RendererSettings.setSymbologyStandard(RendererSettings.Symbology_2525C);  
RendererSettings.setTextOutlineWidth(1);

##3.2 SINGLEPOINT ICON SYMBOLOGY Singlepoint rendering is provided by the MilStdIconRenderer object
You would typically render a single point via the code snippet below:

var ii = armyc2.c2sd.renderer.MilStdIconRenderer.Render("SUGDUSAT----***",modifiers);

###3.2.1 SETTING MODIFIERS
“modifiers” is an object which can contain Mil-Std modifiers and rendering attributes. The modifiers can be set like this:

var mu = armyc2.c2sd.renderer.utilities.ModifiersUnits  
var modifiers = {};  
modifiers[mu.C_QUANTITY]=10;  
modifiers[mu.H_ADDITIONAL_INFO_1] = "H";  
modifiers[mu.H1_ADDITIONAL_INFO_2] = "H1";  
//or like this for Single Point Tactical Graphics:  
modifiers[armyc2.c2sd.renderer.utilities.ModifiersTG.H2_ADDITIONAL_INFO_3] = "H2";

ModifiersUnits.js and ModifiersTG.js contain all the modifier key constants for units and tactical graphics.

###3.2.2 SETTING ATTRIBUTES
Attributes will override any defaults set in RendererSettings.

var msa = armyc2.c2sd.renderer.utilities.MilStdAttributes;  
modifiers[msa.PixelSize]=60;  
modifiers[msa.KeepUnitRatio]=true;  
modifiers[msa.SymbologyStandard] = RendererSettings.Symbology_2525Bch2_USAS_13_14;

MilStdAttributes.js contains all the modifier key constants for the attributes that can be applied to rendering.

####3.2.2.1 SIZE
PixelSize = Default size 35. This is the size of the core symbol (not including modifiers) which will fit within a 35x35 pixel space.

####3.2.2.2 LINECOLOR / FILLCOLOR
LineColor and FillColor, if you want to override the default affiliation colors, do something like:

modifiers[msa.LineColor]="#FF0000”

no alpha value supported at the moment.

####3.2.2.3 KEEPUNITRATIO
KeepUnitRatio If true (defaults true), the symbols will have proper proportions in relation to each other (see table VIII in the MilStd 2525C). Hostile airspace, with a size of 35, will end up being 25.667 wide by 30.333 high, hostile unit will be 33.6x33.6 ((35/1.5)*1.44). If false, image will fill the pixel space as much as it can without distorting the shape.

####3.2.2.4 SYMBOLOGY STANDARD
SymbologyStandard Takes RendererSettings.Symbology_2525Bch2_USAS_13_14 or RendererSettings.Symbology_2525C for a value. This parameter determines which rendering standard to use. “2525B” represents 2525Bch2 with USAS 13-14. “2525C” represents 2525C with USAS 13-14.

####3.2.2.5 ICON ICON=true, will result in a symbol that is stripped of display & text modifiers so that you get just the core symbol. This is useful for use as tree-node icons. If you had all the detail, the symbols would be so small it would be hard for the user to determine what symbol they're looking at.

####3.2.2.6 LOOKATTAG LookAtTag=true, will generate and add a "" tag to multipoint kml.

###3.2.3 GETTING YOUR IMAGE (IMAGEINFO)
Looking back at the call to render, you’ll see you get an object back. This object contains the image along with some information about the image.

var ii = armyc2.c2sd.renderer.MilStdIconRenderer.Render("SUGDUSAT----***",modifiers);

What is returned is the “ImageInfo” object (armyc2.c2sd.renderer.utilities.ImageInfo). It has the following functions available.

####3.2.3.1 GETIMAGE()
“getImage()” returns an HTML5 canvas object which you can use to draw to another canvas.

####3.2.3.2 TODATAURL()
“toDataUrl()” returns a base64 string that represents the image.

####3.2.3.3 GETCENTERPOINT() “getCenterPoint()” returns a point object that represents where the image should be centered if rendered on a coordinate based map. {x:Number,y:Number}

####3.2.3.4 GETSYMBOLBOUNDS()
“getSymbolBounds()” returns a rectangle object that represents to area in the image that the core symbol (not including any modifiers) exists. {x:Number,y:Number,width:Number,height:Number}

####3.2.3.5 GETIMAGEBOUNDS()
“getImageBounds()” returns a rectangle object that represents the size of the entire image. {x:Number,y:Number,width:Number,height:Number}

####3.2.3.6 GETSQUAREICON()
“getSquareIcon()” returns an HTML5 canvas object where space is added as necessary to make the image a square so that it will fit nicely in a tree node or for any other situation where consistent image size is important. So if you draw a friendly ground unit and the resultant image is 16x10, this function will return a version that is 16x16.

####3.2.3.7 GETCENTEREDIMAGE() “getCenteredImage()” will return an image such that the anchor point or center point of the symbol is placed in the center of the overall image. So as long as the image is centered on the desired location, the symbol will be placed properly. Not recommended. It would be better to use “getImage()” with “getCenterPoint()” so that you can properly place the symbol using offsets.

####3.2.3.8 toSVG()
"toSVG()" will return a string containing an SVG tag. The image is embedded as a dataurl within the SVG. No actual vector data is present.

###3.2.4 RENDERING YOUR IMAGE VIA HTML5 CANVAS
In your html you’ll need a canvas object.

<canvas id="preview" width="650" height="200"></canvas>

In your JavaScript, you can use the following code to render.

var preview = document.getElementById("preview");
var ctx = preview.getContext('2d');
ctx.drawImage(ii.getImage(), 0, 0);

###3.2.5 RENDERING YOUR IMAGE VIA DATA URL
Have an image tag somewhere in your html:

<img id="urlexample" src="" alt="test" height="35" width="35">;

Modify the image tag with this JavaScript code:

//render via Data Url
modifiers = new Object(); 
modifiers[msa.PixelSize]=60;
ii = armyc2.c2sd.renderer.MilStdIconRenderer.Render("SHAPWMSA-------",modifiers);
var width = ii.getImageBounds().getWidth();
var height = ii.getImageBounds().getHeight();

var img = document.getElementById("urlexample");
img.src = ii.toDataUrl();
img.width = width;
img.height = height;

###3.2.6 RENDERING YOUR IMAGE VIA JQUERY PLUGIN
Note that this only works with the single point only compilations of the JavaScript renderer.

<html>
<head>
    <title>Renderer jQuery Plugin Example</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <link rel="stylesheet" href="renderer.css" type="text/css" charset="utf-8" >
    <script src="jquery-1.10.2.min.js" type="text/javascript"></script>
    <script src="s-b.min.js" type="text/javascript"></script>
    <script type="text/javascript">
        $(window).bind("load", function() {
            // Invoke render2525() on jQuery objects that match canvas tags
            // when symbols on a canvas need to be drawn or re-drawn
            $("canvas").render2525();
        });
    </script>
</head>
<body>
    <!--    
        To display a symbol, canvas elements must contain a valid
        15-character symbol code in the data-symbol-code attribute.

        The optional data-pixel-size attribute controls the size of
        the symbol.
    -->
    <canvas data-symbol-code="SHAPCF---------" data-pixel-size="64"></canvas>
</body>
</html>

###3.2.7 Make sure the fonts are loaded before trying to render
Depending how things are loaded, the fonts may not be ready in time for your first render attempt. The following sample code will check to make sure the milstd fonts are loaded. You may need to modify this code to meet your needs. This code was taken from singlePointTester2.html

var fontCheckTimer = null;  
var retries = 15;
var attempts = 0;
var fontsLoaded = false;

function checkFonts()
{
    if(armyc2.c2sd.renderer.utilities.RendererUtilities.fontsLoaded())
    {
        console.log("fonts loaded");
        fontsLoaded = true;
    }
    else if(attempts < retries)
    {
        attempts++;
        fontCheckTimer = setTimeout(checkFonts, 1000);
        console.log("fonts loading...");
        //sometimes font won't register until after a render attempt
        armyc2.c2sd.renderer.MilStdIconRenderer.Render("SHAPWMSA-------",{});
    }
    else
    {
        console.log("fonts didn't load or status couldn't be determined for " + retries + " seconds.");
        //Do actions to handle font failure to load scenario
    }
}

if(armyc2.c2sd.renderer.utilities.RendererUtilities.fontsLoaded()){
    console.log("fonts loaded fast");
    fontsLoaded = true;
}
else
{
    fontCheckTimer = setTimeout(checkFonts, 1000);
}

##3.3 MULTIPOINT SYMBOLOGY

Multipoint rendering is provided by the SECWebRenderer object
KML rendering example:

var formatJSON = 1;
var formatKML = 0;
var rendererMP = sec.web.renderer.SECWebRenderer;
var pixelWidth = 800;
var pixelHeight = 600;

//SECTOR RANGE FAN EXAMPLE/////////////////////////////////

var symbolCode3 = "GFFPAXS---****X"; //sector range fan
var kml3=null;
var json3=null;
var controlPoints3 = "66.26700036208742,30.62755038706961";// point format “x,y x,y x,y…”

/*bbox The viewable area of the map.  Passed in the format of a string "lowerLeftX,lowerLeftY,upperRightX,upperRightY." Not required but can speed up rendering in some cases.//*/
var bbox3 = "66.25,30.627,66.27,30.63";//whole symbol will be calculated

var scale3 = 50000.0;

//distance (AM), azimuth (AN), and altitudeDepth (X) can all have multiple values so they are enclosed in brackets.
//you can set with the string constants from “ModifiersTG”.
var mtg = armyc2.c2sd.renderer.utilities.ModifiersTG;
modifiers = {};
modifiers[mtg.AM_DISTANCE] = [300,1000];//AM, AN, & X are the only modifiers that are passed as arrays
modifiers[mtg.AN_AZIMUTH] = [315,45];	//The rest of the modifiers are String or Number values.
modifiers[mtg.X_ALTITUDE_DEPTH] = [0]; 
var msa = armyc2.c2sd.renderer.utilities.MilStdAttributes;
modifiers[msa.LineWidth]=8;

format = formatKML;


//RenderSymbol for Google Earth.  KML format recommended.
kml3 = rendererMP.RenderSymbol("ID","Name","Description", symbolCode3, controlPoints3, "clampToGround",scale3, bbox3, modifiers,format);

format = formatJSON;
//RenderSymbol2D for 2D maps, JSON Recommended for simpler output.
			json3 = rendererMP.RenderSymbol2D("ID","Name","Description", symbolCode3, controlPoints3, pixelWidth, pixelHeight, bbox3, modifiers,format);

###3.3.1 REQUIRED PARAMETERS FOR MULTIPOINT SYMBOLOGY

####3.3.1.1 ID (FOR 3D & 2D)
id = a unique identifier used to identify the symbol by Google map. The id will be the folder name that contains the graphic.

####3.3.1.2 NAME (FOR 3D & 2D)
name = a string used to display to the user as the name of the graphic being created.

####3.3.1.3 DESCRIPTION (FOR 3D & 2D)
description = a brief description about the graphic being made and what it represents.

####3.3.1.4 CONTROL POINTS (FOR 3D & 2D)
controlPoints = the vertices of the graphics that make up the graphic. They are passed in the format of a string, using decimal degrees separating lat and lon by a comma, separating coordinates by a space. The following format shall be used "x1,y1[,z1] [xn,yn[,zn]]...".

####3.3.1.5 ALTITUDE MODE (FOR 3D)
altitudeMode = indicates whether the symbol should interpret altitudes as above sea level or above ground level. Options are "clampToGround", "relativeToGround" (from surface of earth), "absolute" (sea level), "relativeToSeaFloor" (from the bottom of major bodies of water).

####3.3.1.6 SCALE (FOR 3D)
scale = a number corresponding to how many meters one meter of our map represents. A value "50000" would mean 1:50K which means for every meter of our map it represents 50000 meters of real world distance. ####3.3.1.7 PIXELWIDTH & PIXELHEIGHT (FOR 2D)
pixelWidth & pixelHeight = represents the width & height in pixels of the visible map area of a 2D map.

####3.3.1.8 BOUNDING BOX (FOR 3D & 2D)
bbox = the viewable area of the map. Passed in the format of a string "lowerLeftX,lowerLeftY,upperRightX,upperRightY." example: "-50.4,23.6,-42.2,24.2"

####3.3.1.9 MODIFIERS (FOR 3D & 2D)
modifiers = a JSON string representing all the possible symbol modifiers represented in the MIL-STD-2525C. Format of the string will be {"modifiers": {"attributeName":"value"[,"attributeNameN":"valueN"]...}}. The quotes are literal in the above notation. Example: {"modifiers": {"C":"4","Z":"300","AN":[100,200]}}
ModifiersTG.js contains all the modifier key constants for tactical graphics.

####3.3.1.10 FORMAT (FOR 3D & 2D)
format = an enumeration: 0 for KML, 1 for JSON, 2 for GeoJSON, 3 for GeoCanvas, 4 for DataURL.
KML and GeoJSON are specifications for drawing shapes and text on a globe.

The GeoCanvas is just an object with a canvas and two geo coordinates (top left and bottom right) used to place the image on the map. DataURL returns those same two points but with a DataURL representation of the image instead of a canvas. Generating a DataURL is expensive so it is recommended to use the "GeoCanvas" output over the DataURL when possible.

//GeoCanvas
{image, geoTL, geoBR, width, height}//canvas, geocoord, geocoord, pixel width, pixel height
//DataURL
{dataURL, geoTL, geoBR, width, height}//canvas, geocoord, geocoord, pixel width, pixel height

####3.3.1.11 SYMBOLOGY STANDARD (FOR 3D & 2D)
symStd = a Mil-Std symbology enumeration: 0 for 2525Bch2, 1 for 2525C.

#4 SYMBOLUTILITIES
armyc2.c2sd.renderer.utilities.SymbolUtilities is an object with various utility functions used to process symbolIDs. The two a user is most likely to use are below. Please look at the class for other functions that may be of use.

##4.1 GETBASICSYMBOLID
“getBasicSymbolID(symbolID)” will be used often with the other objects in the renderer. It will take a symbolID like “SFGPUCI----K***” and turn it into “SGUCI---*****”. Object like SymbolDefTable & UnitDefTable use the basic symbol ID for lookups.

##4.2 HASMODIFIER
“hasModifier(symbolID, modifier)” will tell you if the modifier is valid for a specific symbolID.
symbolID – a 15 character symbol code.
modifier – Can be one of the constants from the ModifiersUnits or ModifiersTG object. Returns true or false.

Use like: Var SymbolUtilities = armyc2.c2sd.renderer.utilities.SymbolUtilities; var result = SymbolUtilities.hasModifier(symbolID, ModifiersUnits.B_ECHELON);

##4.3 ISMULTIPOINT “isMultiPoint(symbolID, symStd)” will tell you if the modifier is valid for a specific symbolID.
symbolID – a 15 character symbol code.
symStd – a Mil-Std symbology enumeration: 0 for 2525Bch2, 1 for 2525C. Will use renderer default if not provided. Returns true or false.

#5 THE SYMBOL DEFINITION TABLE The SymbolDefTable object will provide information about the tactical graphics that can be drawn. (Appendix B in the MilStd 2525)

##5.1 HASSYMBOLDEF armyc2.c2sd.renderer.utilities.SymbolDefTable.getSymbolDef(symbolID, symStd) This function takes the following parameters: symbolID – a basic 15 character symbol ID code stripped of affiliation, status & modifiers.
symStd – 0 or 1 depending if you want a definition based on 2525B or 2525C. Returns true if a symbol definition exists for the passed basic symbolID and symbology standard.

##5.2 GETSYMBOLDEF armyc2.c2sd.renderer.utilities.SymbolDefTable.getSymbolDef(symbolID, symStd)

###5.2.1 PARAMETERS This function takes the following parameters: symbolID – a basic 15 character symbol ID code stripped of affiliation, status & modifiers. symStd – 0 or 1 depending if you want a definition based on 2525B or 2525C.

###5.2.2 RETURN OBJECT This function will return an object with the following properties:
####5.2.2.1 SYMBOLID symbolID – a basic 15 character symbol ID code stripped of affiliation, status & modifiers.

####5.2.2.2 MINPOINTS minPoints – the minimum # of points the symbol can have.

####5.2.2.3 MAXPOINTS maxPoints – the max # of points the symbol can have. Assume any value over 100 means infinite.

####5.2.2.4 MODIFIERS modifiers – a string like “T.T1.W.” which shows which modifiers the symbol can have.

####5.2.2.5 DRAWCATEGORY drawCategory – an integer representing the type of symbol that is being drawn. These constants can be found in the SymbolDefTable.js. Based on these constants, you’ll know what symbols have required modifiers. For instance, DRAW_CATEGORY_TWO_POINT_RECT_PARAMETERED_AUTOSHAPE: 20, is a symbol that requires one AM value. These requirements are described in SymbolDefTable.js as well.

Clone this wiki locally