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.util.measure
Class MeasureTool

java.lang.Object
  extended by gov.nasa.worldwind.avlist.AVListImpl
      extended by gov.nasa.worldwind.util.measure.MeasureTool
All Implemented Interfaces:
AVList, Disposable
public class MeasureTool
extends AVListImpl
implements Disposable

A utility class to interactively draw shapes and measure distance and area across the terrain. When armed, the class monitors mouse events to allow the definition of a measure shape that can be one of SHAPE_LINE, SHAPE_PATH, SHAPE_POLYGON, SHAPE_CIRCLE, SHAPE_ELLIPSE, SHAPE_SQUARE or SHAPE_QUAD.

In order to allow user interaction with the measuring shape, a controller must be set by calling setController(MeasureToolController) with a new instance of a MeasureToolController.

The interaction sequence for drawing a shape and measuring is as follows:

  • Set the measure shape.
  • Arm the MeasureTool object by calling its setArmed(boolean) method with an argument of true.
  • Click on the terrain to add points.
  • Disarm the MeasureTool object by calling its setArmed(boolean) method with an argument of false.
  • Read the measured length or area by calling the MeasureTool getLength() or getArea() method. Note that the length and area can be queried at any time during or after the process.

While entering points or after the measure tool has been disarmed, dragging the control points allow to change the initial points positions and alter the measure shape.

While the MeasureTool is armed, pressing and immediately releasing mouse button one while also pressing the control key (Ctl) removes the last point entered.

Arming and disarming the MeasureTool does not change the contents or attributes of the measure tool's layer. Note that the measure tool will NOT disarm itself after the second point of a line or a regular shape has been entered - the MeasureToolController has that responsability.

Setting the measure shape from the application

The application can set the measure shape to an arbitrary list of positions using setPositions(java.util.ArrayList). If the provided list contains two positions, the measure shape will be set to SHAPE_LINE. If more then two positions are provided, the measure shape will be set to SHAPE_PATH if the last position differs from the first (open path), or SHAPE_POLYGON if the path is closed.

The application can also set the measure shape to a predefined regular shape by calling setMeasureShape(String, Position, double, double, Angle), providing a shape type (one of SHAPE_CIRCLE, SHAPE_ELLIPSE, SHAPE_SQUARE or SHAPE_QUAD), a center position, a wdth, a height (in meters) and a heading angle.

Finally, the application can use an existing Polyline or SurfaceShape by using setMeasureShape(Polyline) or setMeasureShape(SurfaceShape). The surface shape can be one of SurfacePolygon, SurfaceQuad, SurfaceSquare, SurfaceEllipse or SurfaceCircle.

Measuring

The application can read the measured length or area by calling the MeasureTool getLength() or getArea() method. These methods will return -1 when no value is available.

Regular shapes are defined by a center position, a width a height and a heading angle. Those attributes can be accessed by calling the getCenterPosition(), getWidth(), getHeight() and getOrientation() methods.

Events

The MeasureTool will send events on several occasions: when the position list has changed - EVENT_POSITION_ADD, EVENT_POSITION_REMOVE or EVENT_POSITION_REPLACE, when metrics has changed EVENT_METRIC_CHANGED or when the tool is armed or disarmed EVENT_ARMED.

Events will also be fired at the start and end of a rubber band operation during shape creation: EVENT_RUBBERBAND_START and EVENT_RUBBERBAND_STOP.

See MeasureToolPanel for some events usage.

Several instances of this class can be used simultaneously. However, each instance should be disposed of after usage by calling the dispose() method.

See Also:
MeasureToolController

Nested Class Summary
 class MeasureTool.ControlPoint
           
protected  class MeasureTool.CustomRenderableLayer
           
 
Field Summary
protected  ScreenAnnotation annotation
           
protected  AnnotationAttributes annotationAttributes
           
protected  RenderableLayer applicationLayer
           
protected  MeasureToolController controller
           
protected  ArrayList<Renderable> controlPoints
           
protected  AnnotationAttributes controlPointsAttributes
           
protected  MeasureTool.CustomRenderableLayer controlPointsLayer
           
static String EVENT_ARMED
           
static String EVENT_METRIC_CHANGED
           
static String EVENT_POSITION_ADD
           
static String EVENT_POSITION_REMOVE
           
static String EVENT_POSITION_REPLACE
           
static String EVENT_RUBBERBAND_START
           
static String EVENT_RUBBERBAND_STOP
           
protected  Color fillColor
           
protected  boolean followTerrain
           
protected  MeasureTool.CustomRenderableLayer layer
           
protected  Polyline line
           
protected  Color lineColor
           
protected  double lineWidth
           
protected  String measureShape
           
protected  String pathType
           
protected  ArrayList<Position> positions
           
static String SHAPE_CIRCLE
           
static String SHAPE_ELLIPSE
           
static String SHAPE_LINE
           
static String SHAPE_PATH
           
static String SHAPE_POLYGON
           
static String SHAPE_QUAD
           
static String SHAPE_SQUARE
           
protected  Position shapeCenterPosition
           
protected  int shapeIntervals
           
protected  MeasureTool.CustomRenderableLayer shapeLayer
           
protected  Angle shapeOrientation
           
protected  Rectangle2D.Double shapeRectangle
           
protected  boolean showAnnotation
           
protected  boolean showControlPoints
           
protected  SurfaceShape surfaceShape
           
protected  WorldWindow wwd
           
 
Fields inherited from class gov.nasa.worldwind.avlist.AVListImpl
changeSupport
 
Constructor Summary
MeasureTool(WorldWindow wwd)
          Construct a new measure tool drawing events from the specified WorldWindow.
MeasureTool(WorldWindow wwd, RenderableLayer applicationLayer)
          Construct a new measure tool drawing events from the specified WorldWindow and using the given RenderableLayer.
 
Method Summary
 void addControlPoint()
          Add a control point to the current measure shape at the cuurrent WorldWindow position.
protected  void addControlPoint(Position position, String key, Object value)
           
 void clear()
          Removes all positions from the shape, clear attributes.
protected  Position computeSurfacePosition(LatLon latLon)
           
protected  MeasureTool.CustomRenderableLayer createCustomRenderableLayer()
           
 void dispose()
           
protected  String formatArea(double value)
           
protected  String formatLength(double value)
           
 AnnotationAttributes getAnnotationAttributes()
          Get the attributes associated with the tool tip annotation.
 RenderableLayer getApplicationLayer()
          Returns the applilcation layer passed to the constructor.
 double getArea()
           
 Position getCenterPosition()
           
 MeasureToolController getController()
          Get the MeasureToolController for this measure tool.
 ArrayList<Renderable> getControlPoints()
          Get the list of control points associated with the current measure shape.
 AnnotationAttributes getControlPointsAttributes()
          Get the attributes associated with the control points.
 Color getFillColor()
           
 double getHeight()
           
 RenderableLayer getLayer()
          Returns the measure tool layer.
 double getLength()
           
 Polyline getLine()
          Returns the polyline currently used to display lines and path.
 Color getLineColor()
           
 double getLineWidth()
           
 String getMeasureShape()
          Get the measure shape type.
 Angle getOrientation()
           
 String getPathType()
           
protected  String getPathType(List<? extends Position> positions)
           
 ArrayList<? extends Position> getPositions()
          Get the list of positions that define the current measure shape.
 SurfaceShape getSurfaceShape()
          Returns the surface shape currently used to display polygons.
 double getWidth()
           
 WorldWindow getWwd()
           
 boolean isArmed()
          Identifies whether the measure tool controller is armed.
 boolean isFollowTerrain()
           
 boolean isMeasureShape(Object o)
           
 boolean isRegularShape()
           
protected  boolean isRegularShape(String shape)
           
 boolean isShowAnnotation()
           
 boolean isShowControlPoints()
           
protected static String keyFromPolylinePathType(int type)
           
 void moveControlPoint(MeasureTool.ControlPoint point)
          Update the current measure shape according to a given control point position.
 void moveMeasureShape(Angle azimuth, Angle distance)
          Move the current measure shape along a great circle arc at a given azimuth Angle for a given distance Angle.
protected static int polylinePathTypeFromKey(String type)
           
 void removeControlPoint()
          Remove the last control point from the current measure shape.
 void setArmed(boolean state)
          Arms and disarms the measure tool controller.
 void setController(MeasureToolController controller)
          Set the controller object for this measure tool - can be null.
 void setFillColor(Color color)
           
 void setFollowTerrain(boolean followTerrain)
           
 void setLineColor(Color color)
           
 void setLineWidth(double width)
           
 void setMeasureShape(Polyline line)
          Set the measure shape to an existing Polyline.
 void setMeasureShape(String shape)
          Set the measure shape type.
 void setMeasureShape(String shape, Position centerPosition, double radius)
          Set and initialize the measure shape to one of the regular shapes SHAPE_CIRCLE, SHAPE_ELLIPSE, SHAPE_SQUARE or SHAPE_QUAD.
 void setMeasureShape(String shape, Position centerPosition, double width, double height, Angle orientation)
          Set and initialize the measure shape to one of the regular shapes SHAPE_CIRCLE, SHAPE_ELLIPSE, SHAPE_SQUARE or SHAPE_QUAD.
 void setMeasureShape(SurfaceShape surfaceShape)
          Set the measure shape to an existing SurfaceShape.
 void setPathType(String type)
           
 void setPositions(ArrayList<? extends Position> newPositions)
          Set the measure shape to an arbitrary list of positions using setPositions(java.util.ArrayList).
 void setShowAnnotation(boolean state)
           
 void setShowControlPoints(boolean state)
           
 void updateAnnotation(Position pos)
          Move or disable the tool tip annotation.
protected  void updateMeasureShape()
           
protected  void updatePositionsFromShape()
           
protected  void updateShapeControlPoints()
           
protected  void updateShapeProperties(String control, Position newPosition)
           
 
Methods inherited from class gov.nasa.worldwind.avlist.AVListImpl
addPropertyChangeListener, addPropertyChangeListener, clearList, copy, firePropertyChange, firePropertyChange, getDoubleValue, getDoubleValue, getEntries, getIntegerValue, getIntegerValue, getLongValue, getLongValue, getStringValue, getStringValue, getStringValue, getValue, getValues, hasKey, removeKey, removePropertyChangeListener, removePropertyChangeListener, setValue, setValues
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

annotation

protected ScreenAnnotation annotation

annotationAttributes

protected AnnotationAttributes annotationAttributes

applicationLayer

protected RenderableLayer applicationLayer

controller

protected MeasureToolController controller

controlPoints

protected ArrayList<Renderable> controlPoints

controlPointsAttributes

protected AnnotationAttributes controlPointsAttributes

controlPointsLayer

protected MeasureTool.CustomRenderableLayer controlPointsLayer

EVENT_ARMED

public static final String EVENT_ARMED
See Also:
Constant Field Values

EVENT_METRIC_CHANGED

public static final String EVENT_METRIC_CHANGED
See Also:
Constant Field Values

EVENT_POSITION_ADD

public static final String EVENT_POSITION_ADD
See Also:
Constant Field Values

EVENT_POSITION_REMOVE

public static final String EVENT_POSITION_REMOVE
See Also:
Constant Field Values

EVENT_POSITION_REPLACE

public static final String EVENT_POSITION_REPLACE
See Also:
Constant Field Values

EVENT_RUBBERBAND_START

public static final String EVENT_RUBBERBAND_START
See Also:
Constant Field Values

EVENT_RUBBERBAND_STOP

public static final String EVENT_RUBBERBAND_STOP
See Also:
Constant Field Values

fillColor

protected Color fillColor

followTerrain

protected boolean followTerrain

layer

protected MeasureTool.CustomRenderableLayer layer

line

protected Polyline line

lineColor

protected Color lineColor

lineWidth

protected double lineWidth

measureShape

protected String measureShape

pathType

protected String pathType

positions

protected ArrayList<Position> positions

SHAPE_CIRCLE

public static final String SHAPE_CIRCLE
See Also:
Constant Field Values

SHAPE_ELLIPSE

public static final String SHAPE_ELLIPSE
See Also:
Constant Field Values

SHAPE_LINE

public static final String SHAPE_LINE
See Also:
Constant Field Values

SHAPE_PATH

public static final String SHAPE_PATH
See Also:
Constant Field Values

SHAPE_POLYGON

public static final String SHAPE_POLYGON
See Also:
Constant Field Values

SHAPE_QUAD

public static final String SHAPE_QUAD
See Also:
Constant Field Values

SHAPE_SQUARE

public static final String SHAPE_SQUARE
See Also:
Constant Field Values

shapeCenterPosition

protected Position shapeCenterPosition

shapeIntervals

protected int shapeIntervals

shapeLayer

protected MeasureTool.CustomRenderableLayer shapeLayer

shapeOrientation

protected Angle shapeOrientation

shapeRectangle

protected Rectangle2D.Double shapeRectangle

showAnnotation

protected boolean showAnnotation

showControlPoints

protected boolean showControlPoints

surfaceShape

protected SurfaceShape surfaceShape

wwd

protected final WorldWindow wwd
Constructor Detail

MeasureTool

public MeasureTool(WorldWindow wwd)
Construct a new measure tool drawing events from the specified WorldWindow.

Parameters:
wwd - the WorldWindow to draw events from.

MeasureTool

public MeasureTool(WorldWindow wwd,
                   RenderableLayer applicationLayer)
Construct a new measure tool drawing events from the specified WorldWindow and using the given RenderableLayer.

Parameters:
wwd - the WorldWindow to draw events from.
applicationLayer - the RenderableLayer to use - can be null.
Method Detail

addControlPoint

public void addControlPoint()
Add a control point to the current measure shape at the cuurrent WorldWindow position.

addControlPoint

protected void addControlPoint(Position position,
                               String key,
                               Object value)

clear

public void clear()
Removes all positions from the shape, clear attributes.

computeSurfacePosition

protected Position computeSurfacePosition(LatLon latLon)

createCustomRenderableLayer

protected MeasureTool.CustomRenderableLayer createCustomRenderableLayer()
Returns:
Instance of the custom renderable layer to use of our internal layers

dispose

public void dispose()
Specified by:
dispose in interface Disposable

formatArea

protected String formatArea(double value)

formatLength

protected String formatLength(double value)

getAnnotationAttributes

public AnnotationAttributes getAnnotationAttributes()
Get the attributes associated with the tool tip annotation.

Returns:
the attributes associated with the tool tip annotation.

getApplicationLayer

public RenderableLayer getApplicationLayer()
Returns the applilcation layer passed to the constructor.

Returns:
the layer containing the measure shape and control points.

getArea

public double getArea()

getCenterPosition

public Position getCenterPosition()

getController

public MeasureToolController getController()
Get the MeasureToolController for this measure tool.

Returns:
the MeasureToolController for this measure tool.

getControlPoints

public ArrayList<Renderable> getControlPoints()
Get the list of control points associated with the current measure shape.

Returns:
the list of control points associated with the current measure shape.

getControlPointsAttributes

public AnnotationAttributes getControlPointsAttributes()
Get the attributes associated with the control points.

Returns:
the attributes associated with the control points.

getFillColor

public Color getFillColor()

getHeight

public double getHeight()

getLayer

public RenderableLayer getLayer()
Returns the measure tool layer.

Returns:
the layer containing the measure shape and control points.

getLength

public double getLength()

getLine

public Polyline getLine()
Returns the polyline currently used to display lines and path.

Returns:
the polyline currently used to display lines and path.

getLineColor

public Color getLineColor()

getLineWidth

public double getLineWidth()

getMeasureShape

public String getMeasureShape()
Get the measure shape type. can be one of SHAPE_LINE, SHAPE_PATH, SHAPE_POLYGON, SHAPE_CIRCLE, SHAPE_ELLIPSE, SHAPE_SQUARE or SHAPE_QUAD.

Returns:
the measure shape type.

getOrientation

public Angle getOrientation()

getPathType

public String getPathType()

getPathType

protected String getPathType(List<? extends Position> positions)

getPositions

public ArrayList<? extends Position> getPositions()
Get the list of positions that define the current measure shape.

Returns:
the list of positions that define the current measure shape.

getSurfaceShape

public SurfaceShape getSurfaceShape()
Returns the surface shape currently used to display polygons.

Returns:
the surface shape currently used to display polygons.

getWidth

public double getWidth()

getWwd

public WorldWindow getWwd()

isArmed

public boolean isArmed()
Identifies whether the measure tool controller is armed.

Returns:
true if armed, false if not armed.

isFollowTerrain

public boolean isFollowTerrain()

isMeasureShape

public boolean isMeasureShape(Object o)

isRegularShape

public boolean isRegularShape()

isRegularShape

protected boolean isRegularShape(String shape)

isShowAnnotation

public boolean isShowAnnotation()

isShowControlPoints

public boolean isShowControlPoints()

keyFromPolylinePathType

protected static String keyFromPolylinePathType(int type)

moveControlPoint

public void moveControlPoint(MeasureTool.ControlPoint point)
Update the current measure shape according to a given control point position.

Parameters:
point - one of the shape control points.

moveMeasureShape

public void moveMeasureShape(Angle azimuth,
                             Angle distance)
Move the current measure shape along a great circle arc at a given azimuth Angle for a given distance Angle.

Parameters:
azimuth - the azimuth Angle.
distance - the distance Angle.

polylinePathTypeFromKey

protected static int polylinePathTypeFromKey(String type)

removeControlPoint

public void removeControlPoint()
Remove the last control point from the current measure shape.

setArmed

public void setArmed(boolean state)
Arms and disarms the measure tool controller. When armed, the controller monitors user input and builds the shape in response to user actions. When disarmed, the controller ignores all user input.

Parameters:
state - true to arm the controller, false to disarm it.

setController

public void setController(MeasureToolController controller)
Set the controller object for this measure tool - can be null.

Parameters:
controller - the controller object for this measure tool.

setFillColor

public void setFillColor(Color color)

setFollowTerrain

public void setFollowTerrain(boolean followTerrain)

setLineColor

public void setLineColor(Color color)

setLineWidth

public void setLineWidth(double width)

setMeasureShape

public void setMeasureShape(Polyline line)
Set the measure shape to an existing Polyline.

Parameters:
line - a Polyline instance.

setMeasureShape

public void setMeasureShape(String shape)
Set the measure shape type. can be one of SHAPE_LINE, SHAPE_PATH, SHAPE_POLYGON, SHAPE_CIRCLE, SHAPE_ELLIPSE, SHAPE_SQUARE or SHAPE_QUAD. This will reset the measure tool and clear the current measure shape.

Parameters:
shape - the measure shape type.

setMeasureShape

public void setMeasureShape(String shape,
                            Position centerPosition,
                            double radius)
Set and initialize the measure shape to one of the regular shapes SHAPE_CIRCLE, SHAPE_ELLIPSE, SHAPE_SQUARE or SHAPE_QUAD.

Parameters:
shape - the shape type.
centerPosition - ther shape center position.
radius - the shape radius of half width/height.

setMeasureShape

public void setMeasureShape(String shape,
                            Position centerPosition,
                            double width,
                            double height,
                            Angle orientation)
Set and initialize the measure shape to one of the regular shapes SHAPE_CIRCLE, SHAPE_ELLIPSE, SHAPE_SQUARE or SHAPE_QUAD.

Parameters:
shape - the shape type.
centerPosition - ther shape center position.
width - the shape width.
height - the shape height.
orientation - the shape orientation or azimuth angle - clockwise from north.

setMeasureShape

public void setMeasureShape(SurfaceShape surfaceShape)
Set the measure shape to an existing SurfaceShape. Can be one of SurfacePolygon, SurfaceQuad, SurfaceSquare, SurfaceEllipse or SurfaceCircle.

Parameters:
surfaceShape - a SurfaceShape instance.

setPathType

public void setPathType(String type)

setPositions

public void setPositions(ArrayList<? extends Position> newPositions)
Set the measure shape to an arbitrary list of positions using setPositions(java.util.ArrayList). If the provided list contains two positions, the measure shape will be set to SHAPE_LINE. If more then two positions are provided, the measure shape will be set to SHAPE_PATH if the last position differs from the first (open path), or SHAPE_POLYGON if the path is closed.

Parameters:
newPositions - the shape position list.

setShowAnnotation

public void setShowAnnotation(boolean state)

setShowControlPoints

public void setShowControlPoints(boolean state)

updateAnnotation

public void updateAnnotation(Position pos)
Move or disable the tool tip annotation.

Parameters:
pos - the new position for the tool tip annotation. If null the annotation id turned off.

updateMeasureShape

protected void updateMeasureShape()

updatePositionsFromShape

protected void updatePositionsFromShape()

updateShapeControlPoints

protected void updateShapeControlPoints()

updateShapeProperties

protected void updateShapeProperties(String control,
                                     Position newPosition)
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
Hosted by docs.bugaco.com