Package com.luciad.symbology.military

Class MilitarySymbol

java.lang.Object
com.luciad.symbology.military.MilitarySymbol
All Implemented Interfaces:
AutoCloseable
public final class MilitarySymbol extends Object implements AutoCloseable
Allows retrieving and manipulating modifiers of a military symbol, without having to worry whether the properties are encoded in the symbol code or in textual modifiers.

The modifiers of a military symbol are partly encoded in its symbol code (e.g. the MIL-STD 2525b symbology encodes the affiliation in the second digit of the symbol code) and partly encoded as additional metadata called text modifiers (usually a key-value map). This class exposes all these modifiers and a generic way to retrieve and set modifier values.

Example usages Link icon

// 1) create a MIL-STD 2525b "rescue" symbol based on the code from the specification or a MilitarySymbologyNode
var standard = MilitarySymbology.Standard.MilStd2525b;
MilitarySymbol codedRescueSymbol = MilitarySymbol.create(standard, "G*G*GPAR--****X");
// codedRescueSymbol has properties for all applicable code and text modifiers.
// Mask characters have been replaced from the symbol code. Hence, the following statement is true:
assertEquals(codedRescueSymbol.getCode(), "GUG-GPAR------X");
 
// 2) query the available modifiers
System.out.println("available modifiers:");
 
for (MilitarySymbol.Modifier modifier : codedRescueSymbol.getModifiers()) {
  System.out.println(modifier); // this outputs, among others, MilitarySymbol.Modifier.Affiliation and "AdditionalInformation".
}
 
// 3) query the possible values of the MilitarySymbol.Modifier.Affiliation modifier
codedRescueSymbol.getPossibleValues(MilitarySymbol.Modifier.Affiliation); // returns an array containing, among others, the value "Friend"
 
// 4) change the MilitarySymbol.Modifier.Affiliation modifier.
codedRescueSymbol.putValue(MilitarySymbol.Modifier.Affiliation, "Friend");
// The properties of a MilitarySymbol object are read-write and immediately update the values for the code and
// text modifiers. The MilitarySymbol.Modifier.Affiliation modifier is encoded in the symbol code, so the following statement is true:
assertEquals(codedRescueSymbol.getCode(), "GFG-GPAR------X");
 
// 5) change the "additional information" modifier.
codedRescueSymbol.putValue(MilitarySymbol.Modifier.AdditionalInformation, "This is an example symbol.");
// the "additional information" modifier is stored as a text modifier

  • Method Details Link icon

    • finalize Link icon

      protected void finalize()
      Overrides:
      finalize in class Object

    • close Link icon

      public void close()
      Specified by:
      close in interface AutoCloseable

    • create Link icon

      @NotNull public static MilitarySymbol create(@NotNull MilitarySymbology.Standard standard, @NotNull String sidc) throws IllegalArgumentException
      Creates an returns a military symbol with the given standard and SIDC.
      Parameters:
      standard - the standard of the military symbol.
      sidc - the sidc of the military symbol.
      Returns:
      a new military symbol with the given standard and SIDC.
      Throws:
      IllegalArgumentException - if the SIDC code is not valid.

    • create Link icon

      @NotNull public static MilitarySymbol create(@NotNull Feature feature) throws IllegalArgumentException
      Creates an editable military symbol based on the given Feature.
      Parameters:
      feature - the feature whose SIDC and modifiers should be used
      Returns:
      a new symbol with the same SIDC and text modifiers as the given feature
      Throws:
      IllegalArgumentException - if the military standard or code cannot be derived from the feature.
      See Also:

    • getAffiliation Link icon

      @NotNull public MilitarySymbol.Affiliation getAffiliation()
      Returns the affiliation of this symbol.

      This is a convenience method for directly retrieving the affiliation as an enum instance, as opposed to using getValue.

      Returns:
      the symbol's affiliation.

    • getCode Link icon

      @NotNull public String getCode()
      Returns the SIDC code of the symbol.

      The code represents the type of the symbol and any configured modifiers.

      Returns:
      the SIDC code.

    • getStandard Link icon

      @NotNull public MilitarySymbology.Standard getStandard()
      Returns the symbology standard of this symbol.
      Returns:
      the symbology standard of this symbol.

    • getNode Link icon

      @NotNull public MilitarySymbologyNode getNode()
      Returns the symbology node that is represented by this symbol.
      Returns:
      the symbology node that is represented by this symbol.

    • getModifiers Link icon

      @NotNull public List<@NotNull MilitarySymbol.Modifier> getModifiers()
      Returns the modifiers of this shape symbol that can have a value associated with it.
      Returns:
      the modifiers of this shape symbol that can have a value associated with it.

    • getTextModifiers Link icon

      @NotNull public List<@NotNull MilitarySymbol.Modifier> getTextModifiers()
      Returns the collection of the possible text modifiers of this symbol.

      There are the modifiers that are not encoded in the symbol code.

      Returns:
      the collection of the possible text modifiers of this symbol.

    • getSIDCModifiers Link icon

      @NotNull public List<@NotNull MilitarySymbol.Modifier> getSIDCModifiers()
      Returns the collection of the possible SIDC modifiers of this symbol, e.g.

      the affiliation, status, and so on.

      Returns:
      the collection of the possible SIDC modifiers of this symbol, e.g. the affiliation, status, and so on.

    • getPossibleValues Link icon

      @Nullable public List<@NotNull String> getPossibleValues(@NotNull MilitarySymbol.Modifier modifier)
      Returns the possible values for a given modifier, if applicable.
      Parameters:
      modifier - the modifier whose values to return
      Returns:
      the possible values for a given modifier, or null if the possible values cannot be enumerated.

    • getModifierType Link icon

      @NotNull public MilitarySymbol.ModifierType getModifierType(@NotNull MilitarySymbol.Modifier modifier) throws IllegalArgumentException
      Returns the constraints on a text modifier value.
      Parameters:
      modifier - the modifier whose constraints are requested.
      Returns:
      the type of constraints on this modifier.
      Throws:
      IllegalArgumentException - when the modifier is invalid (the modifier is not part of the symbology)
      Since:
      2024.0.6

    • getValueMaximumLength Link icon

      public long getValueMaximumLength(@NotNull MilitarySymbol.Modifier modifier) throws IllegalArgumentException
      Returns the maximum amount in characters of the string that is allowed when invoking MilitarySymbol#putValue.

      If you invoke MilitarySymbol#putValue with a string longer than the maximum length, then additional characters are discarded.

      Parameters:
      modifier - the modifier whose maximum length is requested.
      Returns:
      the maximum amount of characters that is allowed.
      Throws:
      IllegalArgumentException - when the modifier is invalid (the modifier is not part of the symbology)
      Since:
      2024.1

    • putValue Link icon

      public void putValue(@NotNull MilitarySymbol.Modifier modifier, @NotNull String value) throws IllegalArgumentException
      Sets the given (modifier,value) pair.

      Accepts both SIDC and text modifiers.

      Multi-valued modifiers should be specified by joining the values with a colon character. For instance "value1" and "value2" should be combined as "value1:value2". If the amount of characters is bigger than specified by MilitarySymbol#getValueMaximumLength, then additional characters are discarded.

      Parameters:
      modifier - the key that identifies the text modifier
      value - the value that will be associated with the text modifier
      Throws:
      IllegalArgumentException - when the modifier is invalid (the modifier is not part of the symbology or the value is not part of the acceptable values).

    • resetValue Link icon

      public void resetValue(@NotNull MilitarySymbol.Modifier modifier) throws IllegalArgumentException
      Resets the value associated with the given modifier.

      If the modifier denotes an SIDC modifier, the value is reset to the default value, while for text modifiers, the associated value is simply removed (if any).

      Parameters:
      modifier - the key that identifies the text modifier.
      Throws:
      IllegalArgumentException - when the modifier is invalid (the modifier is not part of the symbology).

    • getValue Link icon

      @Nullable public String getValue(@NotNull MilitarySymbol.Modifier modifier) throws IllegalArgumentException
      Returns the value for the given modifier.

      Accepts both SIDC and text modifiers.

      Parameters:
      modifier - the modifier for which the value needs to be returned
      Returns:
      the value associated to the given modifier (or null if no value is associated with it)
      Throws:
      IllegalArgumentException - when the modifier is invalid (the modifier is not part of the symbology).

    • copyAndChangeCode Link icon

      @NotNull public MilitarySymbol copyAndChangeCode(@NotNull String newCode) throws IllegalArgumentException
      Creates a new military symbol based on the given code.

      Modifiers of the current symbol are retained if they are still applicable and not overridden by the given code.

      For example, applying this function to an existing MIL-STD 2525b space track with code
      SUPP------MYBEX
      by passing the code
      SFA*------*****
      will return a new MIL-STD 2525b air track with code
      SFAP------MYBEX.

      Parameters:
      newCode - code representing the new symbol type
      Returns:
      a new military symbol of the given type, with the same modifiers as the current symbol (if not overridden)
      Throws:
      IllegalArgumentException - when using an invalid code.

    • copyToFeature Link icon

      @NotNull public Feature copyToFeature(@NotNull Feature feature, @Nullable Geometry geometry)
      Creates a new feature based on this military symbol and the given feature.
      Parameters:
      feature - the feature to apply the geometry to. The feature's data type should be the MilitaryDataModel#getSymbolType.
      geometry - the geometry of the feature
      Returns:
      a new military feature, or null if the feature does not yet have a geometry
      See Also:

    • toIcon Link icon

      @NotNull public IIcon toIcon(@NotNull MilitarySymbolStyle style) throws IllegalStateException, NullPointerException
      Creates an icon based on this military symbol and the given style.

      Once this military symbol icon is created, its Image can be easily obtained using an IIconPainter. The following snippet shows an example: 

      		String code = "SFSPCLCC-------";
      		MilitarySymbology.Standard standard = MilitarySymbology.Standard.App6b;
      		MilitarySymbol symbol = MilitarySymbol.create(standard, code);
      		MilitarySymbolStyle defaultStyle = MilitarySymbolStyle.newBuilder().build();
      		var symbolType = symbol.getNode().getSymbolType();
      		 
      		if (symbolType == MilitarySymbologyNode.SymbolType.Icon) {
      		  IIcon icon = symbol.toIcon(defaultStyle);
      		  IIconPainter painter = icon.createPainter(new IconPainterContext(1.0));
      		  Image image = painter.paint();
      		  Bitmap bitmap = image.asBitmap();
      		 
      		  // ...
      		 
      		}
      Parameters:
      style - the styling settings for visualizing this military symbol.
      Returns:
      this military symbol icon.
      Throws:
      IllegalStateException - when this military symbol is not an MilitarySymbologyNode.SymbolType#Icon.
      NullPointerException - when passing null for the style.
      Since:
      2023.0