TacticalSymbol (NASA World Wind)

Overview

Package

Class

Use

Tree

Index

Help

NASA World Wind

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

gov.nasa.worldwind.symbology
Interface TacticalSymbol

All Superinterfaces:: AVList, EventListener, Highlightable, MessageListener, PropertyChangeListener, Renderable, WWObject

All Known Implementing Classes:: AbstractTacticalSymbol, EchelonSymbol, ForwardEdgeOfBattleArea.FEBASymbol, LimitedAccessSymbol, MilStd2525TacticalSymbol, TacticalGraphicSymbol

public interface TacticalSymbol
extends WWObject, Renderable, Highlightable
extends WWObject, Renderable, Highlightable

TacticalSymbol provides a common interface for displaying tactical point symbols from symbology sets. A tactical symbol displays graphic and textual information about an object at a single geographic position at a particular point in time. See the Tactical Symbol Usage Guide for instructions on using TacticalSymbol in an application.

Construction

Implementations of this interface provide support for symbols belonging to a specific symbology set. For example, class MilStd2525TacticalSymbol provides support for tactical symbols from the MIL-STD-2525 symbology specification.

To create a tactical symbol, instantiate a concrete implementation appropriate for the desired symbology set. Pass a string identifier, the desired geographic position, and (optionally) one or more symbol modifier key-value pairs to the symbol's constructor. The tactical symbol creates a graphic appropriate for the string identifier and optional symbol modifiers, and draws that graphic at the specified position when its render method is called. For example, a symbol implementation may display a 3D object at the position, or display a screen space icon who's screen location tracks the position. MIL-STD-2525 tactical symbols display a screen space icon with graphic and text modifiers surrounding the icon.

The format of the string identifier and the modifier key-value pairs are implementation dependent. For MIL-STD-2525, the string identifier must be a 15-character alphanumeric symbol identification code (SIDC), and the modifier keys must be one of the constants defined in MilStd2525TacticalSymbol's documentation.

Since TacticalSymbol extends the Renderable interface, a tactical symbol is displayed either by adding it to a layer, or by calling its render method from within a custom layer or renderable object. The simplest way to display a tactical symbol is to add it to a RenderableLayer. Here's an example of creating and displaying a tactical symbol for a MIL-STD-2525 friendly ground unit using a RenderableLayer:

 // Create a tactical symbol for a MIL-STD-2525 friendly ground unit. Since the SIDC specifies a ground symbol, the
 // tactical symbol's altitude mode is automatically configured as WorldWind.CLAMP_TO_GROUND.
 TacticalSymbol symbol = new MilStd2525TacticalSymbol("SFGPU---------G", Position.fromDegrees(40, -120, 0));

 // Create a renderable layer to display the tactical symbol. This example adds only a single symbol, but many
 // symbols can be added to a single layer.
 RenderableLayer symbolLayer = new RenderableLayer();
 symbolLayer.addRenderable(symbol);

 // Add the layer to the world window's model and request that the window redraw itself. The world window draws the
 // symbol on the globe at the specified position. Interactions between the symbol and the cursor are returned in the
 // world window's picked object list, and reported to the world window's select listeners.
 WorldWindow wwd = ... // A reference to your application's WorldWindow instance.
 wwd.getModel().getLayers().add(symbolLayer);
 wwd.redraw();

Position

A symbol's geographic position defines where the symbol displays its graphic. Either the graphic's geometric center is displayed at the position, or a specific location within the graphic (such as the bottom of a leader line) is displayed at the position. This behavior depends on the symbol implementation, the string identifier, and the symbol modifiers (if any).

A symbol's altitude mode defines how the altitude component if the position is interpreted. Altitude mode may be specified by calling setAltitudeMode(int). Recognized modes are:

WorldWind.CLAMP_TO_GROUND -- the symbol graphic is placed on the terrain at the latitude and longitude of its position.
WorldWind.RELATIVE_TO_GROUND -- the symbol graphic is placed above the terrain at the latitude and longitude of its position and the distance specified by its elevation.
WorldWind.ABSOLUTE -- the symbol graphic is placed at its specified position.

Tactical symbol implementations configure the altitude mode from the string identifier specified during construction. For example, specifying the MIL-STD-2525 SIDC "SFGPU---------G" specifies a friendly ground unit symbol, and causes a tactical symbol to configure the altitude mode as WorldWind.CLAMP_TO_GROUND. The automatically configured mode can be overridden by calling setAltitudeMode.

Modifiers

Symbols modifiers are optional attributes that augment or change a symbol's graphic. Modifiers can be specified at construction by passing a list of key-value pairs, or after construction by calling setModifier(String, Object) with the modifier key and value. Which modifier keys are recognized by a tactical symbol and how they affect the symbol's graphic is implementation dependent. Here's an example of setting the the heading (direction of movement) modifier at construction for a MIL-STD-2525 friendly ground unit:

 // Create a tactical symbol for a MIL-STD-2525 friendly ground unit, specifying the optional Direction of Movement
 // modifier by passing in a list of key-value pairs.
 AVList modifiers = new AVListImpl();
 modifiers.setValue(SymbologyConstants.DIRECTION_OF_MOVEMENT, Angle.fromDegrees(45));
 TacticalSymbol symbol = new MilStd2525TacticalSymbol("SFGPU---------G", Position.fromDegrees(40, -120, 0),
     modifiers);

Here's an example of setting the same modifier after construction:

 // Create a tactical symbol for a MIL-STD-2525 friendly ground unit.
 TacticalSymbol symbol = new MilStd2525TacticalSymbol("SFGPU---------G", Position.fromDegrees(40, -120, 0));

 // Set the heading (direction of movement) modifier.
 symbol.setModifier(SymbologyConstants.DIRECTION_OF_MOVEMENT, Angle.fromDegrees(45));

Tactical symbol implementations apply modifiers from the string identifier specified during construction. For example, given a MIL-STD-2525 symbol representing units, installation, or equipment, SIDC positions 11-12 specify the echelon and task force modifiers (See MIL-STD-2525C, Appendix A). Here's an example of setting the echelon and task force modifiers at construction for a MIL-STD-2525 friendly ground unit:

 // Create a tactical symbol for a MIL-STD-2525 friendly ground unit. Specify the echelon modifier and task force
 // modifiers by setting the SIDC characters 11-12 to "EA". This indicates that the ground unit is a Task Force with
 // a Team/Crew Echelon (see MIL-STD-2525C, Appendix A, Table A-II).
 TacticalSymbol symbol = new MilStd2525TacticalSymbol("SFGPU-----EA--G", Position.fromDegrees(40, -120, 0));

Method Summary
`int`	`getAltitudeMode()` Indicates this symbol's altitude mode.
`TacticalSymbolAttributes`	`getAttributes()` Returns this symbol's normal (as opposed to highlight) attributes.
`Object`	`getDelegateOwner()` Indicates the delegate owner of this symbol.
`TacticalSymbolAttributes`	`getHighlightAttributes()` Returns this symbol's highlight attributes.
`String`	`getIdentifier()` Indicates a string identifier for this symbol.
`Object`	`getModifier(String modifier)` Indicates the current value of a text or graphic modifier.
`Position`	`getPosition()` Indicates this symbol's geographic position.
`UnitsFormat`	`getUnitsFormat()` Indicates the unit format used to format values in text modifiers.
`boolean`	`isShowGraphicModifiers()` Indicates whether this symbol draws its supplemental graphic modifiers.
`boolean`	`isShowHostileIndicator()` Indicates whether or not to display an indicator when the symbol represents a hostile entity.
`boolean`	`isShowLocation()` Indicates whether or not to display this symbol's location as a text modifier.
`boolean`	`isShowTextModifiers()` Indicates whether this symbol draws its supplemental text modifiers.
`boolean`	`isVisible()` Indicates whether this symbol is drawn when in view.
`void`	`setAltitudeMode(int altitudeMode)` Specifies this symbol's altitude mode.
`void`	`setAttributes(TacticalSymbolAttributes normalAttrs)` Specifies this symbol's normal (as opposed to highlight) attributes.
`void`	`setDelegateOwner(Object owner)` Specifies the delegate owner of this symbol.
`void`	`setHighlightAttributes(TacticalSymbolAttributes highlightAttrs)` Specifies this symbol's highlight attributes.
`void`	`setModifier(String modifier, Object value)` Specifies the value of a text or graphic modifier.
`void`	`setPosition(Position position)` Specifies this symbol's geographic position.
`void`	`setShowGraphicModifiers(boolean showGraphicModifiers)` Specifies whether to draw this symbol's supplemental graphic modifiers.
`void`	`setShowHostileIndicator(boolean show)` Specifies whether or not to display an indicator when the symbol represents a hostile entity.
`void`	`setShowLocation(boolean show)` Specifies whether or not to display this symbol's location as a text modifier.
`void`	`setShowTextModifiers(boolean showTextModifiers)` Specifies whether to draw this symbol's supplemental text modifiers.
`void`	`setUnitsFormat(UnitsFormat unitsFormat)` Specifies the unit format used to format values in text modifiers.
`void`	`setVisible(boolean visible)` Specifies whether this symbol is drawn when in view.

Methods inherited from interface gov.nasa.worldwind.avlist.AVList
`addPropertyChangeListener, addPropertyChangeListener, clearList, copy, firePropertyChange, firePropertyChange, getEntries, getStringValue, getValue, getValues, hasKey, removeKey, removePropertyChangeListener, removePropertyChangeListener, setValue, setValues`

Methods inherited from interface java.beans.PropertyChangeListener
`propertyChange`

Methods inherited from interface gov.nasa.worldwind.event.MessageListener
`onMessage`

Methods inherited from interface gov.nasa.worldwind.render.Renderable
`render`

Methods inherited from interface gov.nasa.worldwind.render.Highlightable
`isHighlighted, setHighlighted`

Method Detail

getAltitudeMode

int getAltitudeMode()

Indicates this symbol's altitude mode. See setAltitudeMode(int) for a description of the valid altitude modes.

Returns:: this symbol's altitude mode.

getAttributes

TacticalSymbolAttributes getAttributes()

Returns this symbol's normal (as opposed to highlight) attributes.

Returns:: this symbol's normal attributes. May be null, indicating that the default highlight attributes are used.

getDelegateOwner

Object getDelegateOwner()

Indicates the delegate owner of this symbol. If non-null, the returned object replaces the symbol as the pickable object returned during picking. If null, the symbol itself is the pickable object returned during picking.

Returns:: the object used as the pickable object returned during picking, or null to indicate the the symbol is returned during picking.

getHighlightAttributes

TacticalSymbolAttributes getHighlightAttributes()

Returns this symbol's highlight attributes.

Returns:: this symbol's highlight attributes. May be null, indicating that the default attributes are used.

getIdentifier

String getIdentifier()

Indicates a string identifier for this symbol. The format of the identifier depends on the symbol set to which this symbol belongs. For symbols belonging to the MIL-STD-2525 symbol set, this returns a 15-character alphanumeric symbol identification code (SIDC).

Returns:: an identifier for this symbol.

getModifier

Object getModifier(String modifier)

Indicates the current value of a text or graphic modifier. See setModifier(String, Object) for a description of how modifiers values are interpreted.

Parameters:: modifier - the modifier key.
Returns:: the modifier value. May be null, indicating that this symbol does not display the specified modifier.
Throws:: IllegalArgumentException - if the modifier is null.

getPosition

Position getPosition()

Indicates this symbol's geographic position. See setPosition(gov.nasa.worldwind.geom.Position) for a description of how tactical symbols interpret their position.

Returns:: this symbol's current geographic position.

getUnitsFormat

UnitsFormat getUnitsFormat()

Indicates the unit format used to format values in text modifiers.

Returns:: Units format used to format text modifiers.

isShowGraphicModifiers

boolean isShowGraphicModifiers()

Indicates whether this symbol draws its supplemental graphic modifiers.

Returns:: true if this symbol draws its graphic modifiers, otherwise false.

isShowHostileIndicator

boolean isShowHostileIndicator()

Indicates whether or not to display an indicator when the symbol represents a hostile entity. See comments on setShowHostileIndicator for more information.

Returns:: true if an indicator will be drawn when this symbol represents a hostile entity, if supported by the symbol specification.

isShowLocation

boolean isShowLocation()

Indicates whether or not to display this symbol's location as a text modifier. Not all symbols support the location modifier.

Returns:: true if the symbol will display the location modifier. Note that not some symbols may not support this modifier.

isShowTextModifiers

boolean isShowTextModifiers()

Indicates whether this symbol draws its supplemental text modifiers.

Returns:: true if this symbol draws its text modifiers, otherwise false.

isVisible

boolean isVisible()

Indicates whether this symbol is drawn when in view.

Returns:: true if this symbol is drawn when in view, otherwise false.

setAltitudeMode

void setAltitudeMode(int altitudeMode)

Specifies this symbol's altitude mode. Altitude mode defines how the altitude component of this symbol's position is interpreted. Recognized modes are:

WorldWind.CLAMP_TO_GROUND -- this symbol's graphic is placed on the terrain at the latitude and longitude of its position.
WorldWind.RELATIVE_TO_GROUND -- this symbol's graphic is placed above the terrain at the latitude and longitude of its position and the distance specified by its elevation.
WorldWind.ABSOLUTE -- this symbol's graphic is placed at its specified position.

This symbol assumes the altitude mode WorldWind.ABSOLUTE if the specified mode is not recognized.

Parameters:: altitudeMode - this symbol's new altitude mode.

setAttributes

void setAttributes(TacticalSymbolAttributes normalAttrs)

Specifies this symbol's normal (as opposed to highlight) attributes.

Parameters:: normalAttrs - the normal attributes. May be null, in which case default attributes are used.

setDelegateOwner

void setDelegateOwner(Object owner)

Specifies the delegate owner of this symbol. If non-null, the delegate owner replaces the symbol as the pickable object returned during picking. If null, the symbol itself is the pickable object returned during picking.

Parameters:: owner - the object to use as the pickable object returned during picking, or null to return the symbol.

setHighlightAttributes

void setHighlightAttributes(TacticalSymbolAttributes highlightAttrs)

Specifies this symbol's highlight attributes.

Parameters:: highlightAttrs - the highlight attributes. May be null, in which case default highlight attributes are used.

setModifier

void setModifier(String modifier,
                 Object value)

Specifies the value of a text or graphic modifier. Which modifier keys are recognized how they affect the symbol's graphic is implementation dependent. If the modifier has an implicit value and only needs to be enabled (e.g. the MIL-STD-2525 location modifier), specify true as the modifier value. If the specified value is null, the modifier is removed from this symbol.

If the specified modifier represents a graphic or text modifier, its display is suppressed if isShowGraphicModifiers or isShowTextModifiers, respectively, returns false.

Parameters:: modifier - the modifier key.; value - the modifier value. May be null, indicating that the modifier should be removed from this symbol.
Throws:: IllegalArgumentException - if the modifier is null.

setPosition

void setPosition(Position position)

Specifies this symbol's geographic position. The specified position must be non-null, and defines where on the globe this symbol displays its graphic. The position's altitude component is interpreted according to the altitudeMode. The type of graphic this symbol displays at the position is implementation dependent.

Parameters:: position - this symbol's new position.
Throws:: IllegalArgumentException - if the position is null.

setShowGraphicModifiers

void setShowGraphicModifiers(boolean showGraphicModifiers)

Specifies whether to draw this symbol's supplemental graphic modifiers.

Parameters:: showGraphicModifiers - true if this symbol should draw its graphic modifiers, otherwise false.

setShowHostileIndicator

void setShowHostileIndicator(boolean show)

Specifies whether or not to display an indicator when the symbol represents a hostile entity. The indicator is determined by the symbology set, and may not apply to all symbols in the symbol set. In the case of MIL-STD-2525C, the indicator is the letters "ENY" displayed at the lower right corner of the symbol.

Parameters:: show - true if this symbol will display an indicator when this symbol represents a hostile entity and the symbol specification supports such an indicator.

setShowLocation

void setShowLocation(boolean show)

Specifies whether or not to display this symbol's location as a text modifier. Not all symbols support the location modifier. Setting showLocation on a symbol that does not support the modifier will have no effect.

Parameters:: show - true if the symbol will display the location modifier. Note that not some symbols may not support this modifier.

setShowTextModifiers

void setShowTextModifiers(boolean showTextModifiers)

Specifies whether to draw this symbol's supplemental text modifiers.

Parameters:: showTextModifiers - true if this symbol should draw its text modifiers, otherwise false.

setUnitsFormat

void setUnitsFormat(UnitsFormat unitsFormat)

Specifies the unit format used to format values in text modifiers.

Parameters:: unitsFormat - Format used to format text modifiers.

setVisible

void setVisible(boolean visible)

Specifies whether this symbol is drawn when in view.

Parameters:: visible - true if this symbol should be drawn when in view, otherwise false.