This guide uses the APP-6A symbology to describe the military symbology functionality. The functionality available for MIL-STD 2525b is exactly the same.

You just need to substitute APP6A with MS2525b in all class names and method names, and app6a with milstd2525b in all package names.

In addition, the LuciadLightspeed support for APP-6B, APP-6C, APP-6D, MIL-STD 2525c and MIL-STD 2525d standards relies on the same APIs as its support for the APP-6A and MIL-STD 2525b standards. This means that you can use the APP-6A API in the same way for APP-6B, APP-6C and APP-6D symbology, and that you can use the MIL-STD 2525b API for MIL-STD 2525c and MIL-STD 2525d symbology.

This guide focuses on the use of military symbols in a Lightspeed view. To visualize an ILcdModel containing MIL-STD 2525 or APP-6 objects in a view, you must create a layer. Visualizing military symbols in a Lightspeed view explains how to create such a layer for a Lightspeed view. Styling military symbols in a Lightspeed view explains how to configure a default rendering style for a Lightspeed layer. Creating and editing symbols in a Lightspeed view describes how to interact with a symbology layer, and create and edit symbols in a Lightspeed view

Visualizing military symbols in a Lightspeed view

To visualize an ILcdModel in a Lightspeed view, you must create a layer of type ILspLayer for your model. The API provides a layer builder that creates such a layer with the appropriate painters and editors: see TLspMilitarySymbologyLayerBuilder. The following snippet shows how to use this layer builder. 

// Use the layer builder to create a layer for the model
ILspLayer layer = TLspMilitarySymbologyLayerBuilder.newBuilder()
                                                   .model(aMilitarySymbologyLayer)
                                                   .build();

Styling military symbols in a Lightspeed view

You can define a style object and use it to configure the rendering of military symbols on the map. You can associate the style object with one or more military symbols by defining an implementation of ILcdStyledMilitarySymbol in the domain object.

Additionally, you can configure it as default style on the TLspMilitarySymbologyLayerBuilder class mentioned in Visualizing military symbols in a Lightspeed view. his default style will then be used for all symbols that do not have an associated style.

Configuring a style on a military symbol or layer is optional. If styles have not been defined explicitly, the implementation uses default style settings based on the military symbology standards.

Creating and editing symbols in a Lightspeed view

To allow application users to modify and create domain object properties by interacting with the GUI, an ILspLayer needs to have one or more ILspEditor instances. The military symbology layer builder TLspMilitarySymbologyLayerBuilder takes care of setting up the correct editor for each symbol type.

To support the creation of new symbols by application users, connect a TLspCreateController to an implementation of ALspCreateControllerModel. The controller model only needs to provide the relevant layer and an uninitialized military symbol. The samples provide a convenience controller model that adds the given symbol to the topmost compatible layer, and an action that sets up and enables a TLspCreateController. The action could be connected to a toolbar button or search field. Program: Connecting a search widget to an action that creates a new military symbol shows an example of the latter: a search widget is configured to create and trigger the action whenever the user selects a symbol. The symbology samples also show a favorites toolbar (refer to the FavoritesToolbar class) to rapidly create an often-used symbol. This widget is configured similarly.

Program: Connecting a search widget to an action that creates a new military symbol (from samples/symbology/lightspeed/LspSymbologyCreationBar) 
/**
 * Lets the user create and insert a military symbol by typing in a search field
 * or by clicking on a button that opens a symbol hierarchy tree.
 */
public class LspSymbologyCreationBar extends SymbolSelectionBar {

  /**
   * Called when the user selects a symbol from the symbol hierarchy.
   * @param aSIDC the hierarchy code of the symbol
   */
  @Override
  protected void symbolSelected(String aSIDC) {
    new LspCreateAction(
        LspMilitarySymbolCreateControllerModel.newInstanceForHierarchy(aSIDC),
        fViews,
        fUndoManager
    ).actionPerformed(null);
  }

Customizing symbols through styling

TLspMilitarySymbologyLayerBuilder leverage the API for styling in Lightspeed views to allow you to customize symbology layers in various ways. This section explains symbology customization for MIL-STD 2525 symbols, but APP-6 equivalents exist for everything that is discussed here.

A MIL-STD 2525 symbol is typically defined as an ILcdMS2525bShape, which is an extension of ILcdMS2525bCoded, and optionally as an ILcdStyledMilitarySymbol. If your domain objects implement these interfaces, the MIL-STD 2525 layer builder will pick them up automatically and display the correct symbols.

The link between a domain object and the corresponding MIL-STD 2525 symbol is actually made by the stylers assigned to your layer. By default, this is a TLspMS2525bSymbolStyler. This class will check if incoming domain objects implement the aforementioned interfaces. If that is the case, the styler will produce a TLspMS2525bSymbolStyle, which is itself a combination of an ILcdMS2525bCoded and a TLcdMilitarySymbolStyle.

The bodyStyler() and labelStyler() methods of the layer builders allow you to assign a custom styler to your layer. Such a custom styler can extend or replace the default implementation. The use of a custom styler opens up a number of possibilities for customization of your symbology layer, the most important of which are described in the following sections. All these concepts are also demonstrated in the How to use military symbology styling for custom domain objects on a Lightspeed view article.

Defining custom domain objects

As mentioned above, the standard TLspMS2525bSymbolStyler will only recognize your domain objects if they implement ILcdMS2525bShape. A custom styler, however, allows you to map any domain object onto a TLspMS2525bSymbolStyle. You must be able to provide appropriate geometry for the symbol, like a polyline or a buffer. You can do this by using an ALspStyleTargetProvider, or by letting your domain objects implement the required ILcdShape descendant. For more information about using style target providers, see the LuciadLightspeed developer’s guide.

Furthermore, your styler must output a TLspMS2525bSymbolStyle that contains the symbol code you wish to assign to your domain object. Optionally, the TLspMS2525bSymbolStyle can also contain a TLcdMilitarySymbolStyle that will be used to paint the symbol.

The How to use military symbology styling for custom domain objects on a Lightspeed view article contains an example illustrating this.

Adding decorations to symbols

LuciadLightspeed allows you to decorate symbols by adapting symbol colors, or adding icons and labels to the symbols.

TLspMilitarySymbologyLayerBuilder acts as a facade for TLspShapeLayerBuilder. In addition to TLspMS2525bSymbolStyle objects, it is therefore also valid to output standard line, fill, icon or label styles from a styler used on a symbology layer. In the custom symbology sample, the FIPS country code is extracted from the SIDC code and used to add a country flag icon as a label to each shape. This is done by submitting a TLspIconStyle in addition to the TLspMS2525bSymbolStyle. Note that the symbology standard can define both line, fill and icon styles for the visualization of a particular code. So for example combining a TLspMS2525bSymbolStyle with a line style can result in 2 outlines.

custom symbols
Figure 1. Custom domain objects decorated with country flags

Overriding the visualization of symbols

If you want to change some aspect of how symbols are visualized, you can intercept the affected symbols in your styler and treat them as a special styling case. In the custom symbology sample, symbols are replaced by a dot in the symbol’s affiliation color when you zoom out, to reduce clutter on the map.

The symbols are changed to a dot at a certain scale level by listening to changes in the view’s scale, and firing a style change event when the scale threshold is crossed. When the style() method is invoked, it checks whether the view is above or below the scale threshold, and outputs either the full symbol geometry with a TLspMS2525bSymbolStyle or the symbol’s focus point with a TLspIconStyle.

Defining new symbols

You can also use a custom styler to extend the standard symbol set with new symbols. After determining whether an incoming domain object is a standard or a custom symbol, you can either submit a TLspMS2525bSymbolStyle or use standard line, fill and icon styles to describe your custom symbol. The custom symbology sample contains an example of a custom symbol in the styleCustomSymbol() method of SymbolBodyStyler. In Figure 1, “Custom domain objects decorated with country flags”, this symbol is the buffer-shaped symbol at the bottom.