-
Notifications
You must be signed in to change notification settings - Fork 36
Developer's Guide
MIL SYMBOLOGY JAVA RENDERER
DEVELOPER’S GUIDE
Revision History
Release Date
Initial Document 12/18/2012
Updated 02/24/2014
Updated 03/19/2014 - Added Section 5, Render library usage in an application.
Updated 12/03/2018 - Updated broken links, made some small corrections.
1 Overview
1.1 Features
1.2 System Requirements
2 Setting up the Mil Symbology Web Application
2.1 What is Included in the Mil-Symbology-Renderer.war FILE
2.2 Deploying the Mil Symbology Renderer Service on Tomcat
3 Using the Rest Service for Requesting Icons
3.1 Overview
3.2 Single Coordinate Icon Based Symbology
3.3 Additional Parameters for IMAGES
3.4 Additional Parameters for KML
3.5 Getting Extent information for Single Point Images
4 Using the Rest Service for Generating Multipoint Symbology KML
4.1 Overview
4.2 Multiple Coordinate KML Based Symbology
4.3 Required Parameters for Multipoint Symbology
4.4 Additional Parameters for Multipoint Symbology
5 Running the Web Service as a local desktop service
6 Using the Rendering Libraries in an Application
The Mil Symbology Renderer is both a developer’s toolkit as well as a ready to use deployable web application. The goal of this project is to provide a single distributable solution that can support as many use cases as possible for military symbology rendering. The current features available are:
• Use as a REST web service
• Single Point rendering as PNG
• Multi Point rendering as KML
• Modern browser
• Java JRE or JDK 1.6 update 23 or newer
• Web server that supports Java Servlets and WAR file deployment
The Mil-symbology-service.war file contains:
- Mil Symbology REST Service
- Test pages multiPoints.html & singlePoints.html to demonstrate usage.
Place the mil-sym-service.war file into the webapps directory of your Tomcat web application server. When Tomcat runs, it will decompress the war file and a mil-sym-service directory with the source code will appear. At this point no further configuration is required and the REST web service can be used. There is no known limitation to only use Tomcat and any Java servlet container should be able to run the WAR file, but this is currently only tested in Tomcat configurations.
To set the default rendering standard, update the symStd value in the prop.properties file which is located inside the war file at: "WEB-INF/classes/properties/prop.properties"
The REST web service provided as part of the WAR file supports generation of PNG formatted image icons as well as KML representations of single coordinate MIL-STD-2525 symbols.
Once the WAR file has been placed on the web server, using the single point rendering REST service is as simple as calling a URL. There are two formats that are supported by the service: PNG images and KML. You can add modifiers via URL parameters. When building the URL you must use the coded modifier names a described in the MIL-STD-2525 document (such as “T” or “T1”).
Sample URL for a KML request (generates a KML placemark):
http://[server]/mil-sym-service/renderer/kml/SFGPUCDM---M---?id=1234&name=myKML&lon=44.5&lat=33.5&alt=1000
Sample URL for an image request:
http://[server]/mil-sym-service/renderer/image/SFGPUCDM---M---
Sample URL with some modifiers as parameters:
http://[server]/mil-sym-service/renderer/image/SFGPUCDM---M---?V=35&T=TFOO&H=HFOO
You can also adjust properties such as:
“Size = 35”, (default size 35) size of the core symbol (not modifiers) will fit within a 35x35 pixel space.
alpha=0-255, 0 is completely transparent, 255 is totally visible.
lineColor, fillColor and iconColor, if you want to override the default affiliation colors, do something like: “linecolor=0xFF0000”
keepUnitRatio=true, (defaults true) If true, the symbols will have proper proportions in relation to each other (see chart below). 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.
meta=true, (default is false) adds 4-6ms to image creation but embeds position info into the PNG. If you can pull this information out of the header, it will look like this:
<javax_imageio_png_1.0>
<tEXt>
<tEXtEntry keyword="centerPoint" value="x=17,y=60"/>
<tEXtEntry keyword="bounds" value="x=1.0,y=1.0,width=32.0,height=60.0"/>
<tEXtEntry keyword="imageExtent" value="width=32,height=60"/>
</tEXt>
</javax_imageio_png_1.0>
Typically you would center an image on the related map point. However, not all graphics center on the center of the image. Check Point would center on the bottom middle of the image. This is where the information provided in the header of the PNG becomes useful. You know what point of the image should be centered on the location. The “bounds” value shows the bounding rectangle of the symbol (minus any modifiers) in the image which is potentially useful for hit testing. Also, modifiers can change the center of the image.
symStd= “2525B” or “2525C”. This parameter (symbology standard) determines which rendering standard to use. “2525B” represents 2525Bch2 with USAS 13-14. “2525C” represents 2525C with USAS 13-14.
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.
When requesting KML instead of a PNG icon some additional parameters are required to create valid KML. These have no effect the how the symbol looks. An example of a simple URL to request a KML representation is below
http://[server]/mil-sym-service/renderer/kml/SFGPUCDM---M---?id=1234&name=myKML&lon=44.5&lat=33.5&alt=1000
Additional parameters for the MIL-STD-2525 symbol modifiers can be added to further adjust the visual representation of the symbol.
Id = unique ID for the symbol. This will populate the id parameter of the placemark node in the KML.
Name = a name for the symbol. This will populate the name node of the KML.
Lon = longitude in degrees decimal format (33.477543). This will be used in the geometry section of the placemark of the KML.
Lat = latitude in degrees decimal format (53.41943). This will be used in the geometry section of the placemark of the KML.
Alt = altitude as an integer representing meters (5000). This will be used in the geometry section of the placemark of the KML.
It is possible to query the web service to get extents of the single point image via a POST request. You can look at the function batchInfoTest() in singlePoints.html inside the war for more detail but below is a code snippet.
var http = new XMLHttpRequest();
var url = "renderer/spbi";
var params = "iconURLs=" + encodeURIComponent("{\"iconURLs\":[\"SFGP------*****?size=35&T=Hello\",\"SHGPE-----*****?size=50\"]}");
http.open("POST",url,true);
http.setRequestHeader("Content-type","application/x-www-form-urlencoded; charset=UTF-8,");
http.setRequestHeader("Content-length",params.length);
http.onreadystatechange = function(){/* your state change handling code where you receive your extent info as a JSON formatted string */};
http.send(params);
The returned JSON string will look something like this:
{"singlepoints":[{"x":52.0,"y":13.0,"boundsx":35.0,"boundsy":0.0,"boundswidth":34.0,"boundsheight":26.0,"iconwidth":69.0,"iconheight":33.0},{"x":24.0,"y":24.0,"boundsx":0.0,"boundsy":0.0,"boundswidth":48.0,"boundsheight":48.0,"iconwidth":48.0,"iconheight":48.0}]}
Alternatively, you could use the JavaScript renderer to get the dimensions. There may be minimal differences in measurements based on what browser you use. Sometimes there’s a 1 pixel difference between IE and FireFox.
The REST web service provided as part of the WAR file supports generation of KML to represent multipoint Mil-Std 2525 symbology for use on 3D maps.
Once the WAR file has been placed on the web server, using the multipoint rendering REST service is as simple as making an http POST. There are two formats that are supported by the service: KML and JSON for use on 2D or 3D maps. The KML output can be fed directly to a 3D map that supports the format, like Google Earth. In the POST URL you specify if you’d like a rendering based on a 2D or 3D map followed by the symbol ID. Sample URL for a KML POST request:
http://[server]/mil-sym-service/renderer/mp3d/GFFPAXS-------X (3d map)
http://[server]/mil-sym-service/renderer/mp2d/GFFPAXS-------X (2d map)
The JavaScript code snippet below shows how parameters can be sent. For more detail, look at “multipoints.html” in the WAR. When building the parameter string, you must use the coded modifier names a described in the MIL-STD-2525 document (such as “T” or “T1”). Modifiers “AM”, “AN” & “X” take values as an array. Other Mil-Std modifier values can be set as strings.
var url = “renderer/mp3d/GFFPAXS-------X”;
var params = “ID=ID&NAME=Name&DESCRIPTION=Description&CONTROLPOINTS=66.26700036208742,30.62755038706961&ALTITUDEMODE=clampToGround&SCALE=50000&BBOX=66.25,30.627,66.27,30.63&MODIFIERS={\"AM\":[3000,10000],\"AN\":[315,45],\"X\":[0]}&FORMAT=0&SYMSTD=0”;
http.open("POST",url,true);
http.setRequestHeader("Content-type","application/x-www-form-urlencoded; charset=UTF-8,");
http.setRequestHeader("Content-length",params.length);
http.onreadystatechange = function(){/* your state change handling code where you receive your rendered KML */};
http.send(params);
id = a unique identifier used to identify the symbol by Google map. The id will be the folder name that contains the graphic.
name = a string used to display to the user as the name of the graphic being created.
description = a brief description about the graphic being made and what it represents.
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]]...".
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).
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.
pixelWidth & pixelHeight = represents the width & height in pixels of the visible map area of a 2D map.
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"
modifiers = a JSON string representing all the possible symbol modifiers represented in the MIL-STD-2525C. Format of the string will be {"attributeName":"value"[,"attributeNameN":"valueN"]...}. The quotes are literal in the above notation. Example: {"C":"4","Z":"300","AN":[100,200]}
format = an enumeration: 0 for KML, 1 for JSON, 2 for GeoJSON.
symStd = a Mil-Std symbology enumeration: 0 for 2525Bch2, 1 for 2525C.
lineColor and fillColor = are used to override the default affiliation colors. Example: “lineColor=0xFF0000”
The local service mirrors the behavior of the web service. But instead of calling "http://[server]/mil-sym-service/renderer/image/SFGPUCDM---M---", you'd call "http://127.0.0.1:6789/mil-sym-service/renderer/image/SFGPUCDM---M---".
The local service can be started with the following command:
"java -cp [location of jar files] sec.web.renderer.portable.PortableWrapper [args]"
So assuming your’re starting in the folder with all the jars and java.exe is on the path, you could use:
“java -cp * sec.web.renderer.portable.PortableWrapper -spport:6789 -mpport:6790”
-? print the help message.
-symstd specifies which symbology standard to assume. (default "2525B")
-spon starts the single point service. (default true)
-spport desired port for the single point service. (default 6789)
-spbacklog desired backlog for the single point service. (default 0, lets system decide)
-mpon starts the multi point service. (default true)
-mpport desired port for the multi point service. (default 6790)
-mpbacklog desired backlog for the single point service. (default 0, lets system decide)
Usage like: java -cp [location of jar files] sec.web.renderer.portable.PortableWrapper -spport:#### -spbacklog:### -mpport:#### -mpbacklog:### -symstd:2525C
Or, if launching using the JNLP file, these values can be configured from within that file.
You can reference "mil-sym-renderer-jar-with-dependencies.jar" to get all the classes in one jar file or you can reference them individually:
JavaRendererUtils-#.#.#.jar
JavaLineArray-#.#.#.jar
JavaRendererServer-#.#.#.jar
JavaRenderer-#.#.#.jar
RendererPluginInterface-#.#.#.jar
mil-sym-renderer-#.#.#.jar
A code sample is available here.
ArmyC2.C2SD.Utilties.RendererSettings is home to most of your rendering options.
You can set them as follows:
RendererSettings.getInstance().setSymbologyStandard(RendererSettings.Symbology_2525C);
RendererSettings.getInstance().setTextOutlineWidth(1);
Below is a usage snippet. Refer to DrawUnit() and DrawTG() in the sample code for more detail.
SECRenderer sr = sec.web.renderer.SECRenderer.getInstance();
String symbolID = "SFGP-----------";
Map<String,String> params = new HashMap<String, String>();
params.put(ModifiersUnits.T_UNIQUE_DESIGNATION_1, "T modifier");
//If Tactical Graphic
//params.put(ModifiersTG.T_UNIQUE_DESIGNATION_1, "T modifier");
params.put(MilStdAttributes.PixelSize,"50");
PNGInfo pi = sr.getMilStdSymbolImage(symolID, params);
Once you have a PNGInfo object, you can get the BufferedImage object, save the image to a file, get a squared version of the image (good for icons or tree nodes) and get the point of the image that should be the anchor when placing it on a map.
Other objects of interest are MilStdAttributes, ModifiersUnits, ModifiersTG, and SECRenderer.
Refer to generateAmbushKML() and generateSectorRangeFanKML() in the sample code for more detail.
private void generateAmbushKML() {
try {
String modifiers = "";
//AMBUSH EXAMPLE
String symbolCode = "GHGPSLA-------X";//ambush
//var symbolCode = "GHGPGAA-------X"; //assembly area
String controlPoints = "66.26700036208742,30.62755038706961 66.27555681517738,30.64727776502703 66.25654247497746,30.64632704801704";
//String controlPoints = "66.26700036208742,30.62755038706961 66.27555681517738,30.64727776502703";
String bbox = "66.25,30.60,66.28,30.65";
//var bbox = "-180.0,-90.0,180.0,90.0";
double scale = 50000.0;
int formatGeoJSON = 2;
int formatJSON = 1;
int formatKML = 0;
int pixelWidth = 800;
int pixelHeight = 600;
//change this to format JSON to see the different output.
int format = formatGeoJSON;
//var format = formatKML;
// Let's user choose between 2525Bch2 and 2525C.
int ms2525Bch2 = RendererSettings.Symbology_2525Bch2_USAS_13_14;// 0;
int ms2525C = RendererSettings.Symbology_2525C;// 1;
int symStd = ms2525C;
String kml = SECRenderer.getInstance().RenderMultiPointSymbol("ID","Name","Description",
symbolCode, controlPoints, "clampToGround",scale, bbox, modifiers,format,symStd);
System.out.println(kml);
} catch (Exception exc) {
ErrorLogger.LogException("gui", "generateAmbushKML", exc);
}
}
The SymbolDefTable object will provide information about the tactical & METOC graphics that can be drawn. (Appendix B in the MilStd 2525)
armyc2.c2sd.renderer.utilities.SymbolDefTable.getInsatnce().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.
armyc2.c2sd.renderer.utilities.SymbolDefTable.getInsatnce().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.
This function will return a SymbolDef object with the following properties:
symbolID – a basic 15 character symbol ID code stripped of affiliation, status & modifiers.
minPoints – the minimum # of points the symbol can have.
maxPoints – the max # of points the symbol can have. Assume any value over 100 means infinite.
modifiers – a string like “T.T1.W.” which shows which modifiers the symbol can have.
drawCategory – an integer representing the type of symbol that is being drawn. These constants can be found in SymbolDef.java. 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.