Package gov.nasa.worldwind.util.measure

Class 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. Once the MeasureTool is disarmed, a measure shape of type SHAPE_POLYGON can be moved by dragging a control point while pressing the alt/option key.

    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 responsibility.

    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 setMeasureShapeType(String, Position, double, double, Angle), providing a shape type (one of SHAPE_CIRCLE, SHAPE_ELLIPSE, SHAPE_SQUARE or SHAPE_QUAD), a center position, a width, a height (in meters) and a heading angle.

    Finally, the application can use an existing Path or SurfaceShape by using setMeasureShape(Path) or setMeasureShape(SurfaceShape). The surface shape can be one of SurfacePolyline, 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.

    The measurements are displayed in units specified in the measure tool's UnitsFormat object. Access to the units format is via the method getUnitsFormat().

    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

    • 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. May be null. If specified, the caller is responsible for adding the layer to the model and enabling it.

    • Method Detail

      • setInitialLabels

        protected void setInitialLabels()

      • getUnitsFormat

        public UnitsFormat getUnitsFormat()
        Return the UnitsFormat instance governing the measurement value display units and format.
        Returns:
        the tool's units format instance.

      • setUnitsFormat

        public void setUnitsFormat​(UnitsFormat unitsFormat)
        Set the measure tool's @{link UnitsFormat} instance that governs measurement value display units and format.
        Parameters:
        unitsFormat - the units format instance.
        Throws:
        java.lang.IllegalArgumentException - if the units format instance is null.

      • createCustomRenderableLayer

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

      • 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.

      • setLabel

        public void setLabel​(java.lang.String labelName,
                     java.lang.String label)

      • getLabel

        public java.lang.String getLabel​(java.lang.String labelName)

      • getController

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

      • 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.

      • isArmed

        public boolean isArmed()
        Identifies whether the measure tool controller is armed.
        Returns:
        true if armed, false if not armed.

      • getLayer

        public RenderableLayer getLayer()
        Returns the measure tool layer.
        Returns:
        the layer containing the measure shape and control points.

      • getApplicationLayer

        public RenderableLayer getApplicationLayer()
        Returns the application layer passed to the constructor.
        Returns:
        the layer containing the measure shape and control points.

      • getLine

        public Path getLine()
        Returns the path currently used to display lines and path.
        Returns:
        the path currently used to display lines and path.

      • getSurfaceShape

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

      • getPositions

        public java.util.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.

      • setPositions

        public void setPositions​(java.util.ArrayList<? extends Position> newPositions)
        Set the measure shape to an arbitrary list of positions. 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.

      • getControlPoints

        public java.util.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.

      • getAnnotationAttributes

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

      • setLineColor

        public void setLineColor​(java.awt.Color color)

      • getLineColor

        public java.awt.Color getLineColor()

      • setFillColor

        public void setFillColor​(java.awt.Color color)

      • getFillColor

        public java.awt.Color getFillColor()

      • setLineWidth

        public void setLineWidth​(double width)

      • getLineWidth

        public double getLineWidth()

      • getPathType

        public java.lang.String getPathType()

      • setPathType

        public void setPathType​(java.lang.String type)

      • isShowControlPoints

        public boolean isShowControlPoints()

      • setShowControlPoints

        public void setShowControlPoints​(boolean state)

      • isShowAnnotation

        public boolean isShowAnnotation()

      • setShowAnnotation

        public void setShowAnnotation​(boolean state)

      • clear

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

      • isMeasureShape

        public boolean isMeasureShape​(java.lang.Object o)

      • setMeasureShapeType

        public void setMeasureShapeType​(java.lang.String shapeType,
                                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:
        shapeType - the shape type.
        centerPosition - the shape center position.
        radius - the shape radius of half width/height.

      • setMeasureShapeType

        public void setMeasureShapeType​(java.lang.String shapeType,
                                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:
        shapeType - the shape type.
        centerPosition - the 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​(Path line)
        Set the measure shape to an existing Path.
        Parameters:
        line - a Path instance.

      • getPathType

        protected java.lang.String getPathType​(java.util.List<? extends Position> positions)

      • 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.

      • isRegularShape

        public boolean isRegularShape()

      • isRegularShape

        protected boolean isRegularShape​(java.lang.String shape)

      • isFollowTerrain

        public boolean isFollowTerrain()

      • setFollowTerrain

        public void setFollowTerrain​(boolean followTerrain)

      • getLength

        public double getLength()

      • getArea

        public double getArea()

      • getWidth

        public double getWidth()

      • getHeight

        public double getHeight()

      • getOrientation

        public Angle getOrientation()

      • getCenterPosition

        public Position getCenterPosition()

      • addControlPoint

        public Position addControlPoint()
        Add a control point to the current measure shape at the current WorldWindow position.
        Returns:
        The position of the new control point, or null if the control point could not be added.

      • removeControlPoint

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

      • 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.

      • moveControlPoint

        public void moveControlPoint​(MeasureTool.ControlPoint point,
                             java.lang.String mode)
        Update the current measure shape according to a given control point position and shape edition mode.
        Parameters:
        point - one of the shape control points.
        mode - the shape edition mode.

      • 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.

      • computeSurfacePosition

        protected Position computeSurfacePosition​(LatLon latLon)

      • getShapeInitialControl

        public java.lang.String getShapeInitialControl​(Position position)

      • getShapeInitialHeading

        protected Angle getShapeInitialHeading()

      • updateShapeProperties

        protected void updateShapeProperties​(java.lang.String control,
                                     Position newPosition,
                                     java.lang.String mode)

      • updateShapeCenter

        protected void updateShapeCenter​(java.lang.String control,
                                 Position newPosition)

      • updateShapeOrientation

        protected void updateShapeOrientation​(java.lang.String control,
                                      Position newPosition)

      • updateShapeSize

        protected void updateShapeSize​(java.lang.String control,
                               Position newPosition)

      • computeCornerControl

        protected java.lang.String computeCornerControl​(Position position)

      • swapEdgeControls

        protected void swapEdgeControls​(java.lang.String control,
                                Position position)

      • swapCornerControls

        protected void swapCornerControls​(java.lang.String control,
                                  Position position)

      • computeControlPointLocation

        protected LatLon computeControlPointLocation​(java.lang.String control,
                                             Globe globe,
                                             Angle heading,
                                             LatLon center,
                                             double width,
                                             double height)

      • computeQuadEdgeMidpointLocation

        protected LatLon computeQuadEdgeMidpointLocation​(java.lang.String control,
                                                 Globe globe,
                                                 Angle heading,
                                                 LatLon center,
                                                 double width,
                                                 double height)

      • computeControlPointAzimuth

        protected Angle computeControlPointAzimuth​(java.lang.String control,
                                           double width,
                                           double height)

      • computeControlPointAzimuthInShapeCoordinates

        protected Angle computeControlPointAzimuthInShapeCoordinates​(java.lang.String control,
                                                             Angle azimuth)

      • computeControlPointPathLength

        protected Angle computeControlPointPathLength​(java.lang.String control,
                                              double width,
                                              double height,
                                              double globeRadius)

      • computeNormalizedHeading

        protected static Angle computeNormalizedHeading​(Angle heading)

      • updateShapeControlPoints

        protected void updateShapeControlPoints()

      • updateMeasureShape

        protected void updateMeasureShape()

      • updatePositionsFromShape

        protected void updatePositionsFromShape()

      • dispose

        public void dispose()
        Description copied from interface: Disposable
        Disposes of any internal resources allocated by the object.
        Specified by:
        dispose in interface Disposable

      • addControlPoint

        protected void addControlPoint​(Position position,
                               java.lang.String key,
                               java.lang.Object value)

      • addControlPointWithLeader

        protected void addControlPointWithLeader​(Position position,
                                         java.lang.String controlKey,
                                         java.lang.Object control,
                                         java.lang.String leaderKey,
                                         java.lang.Object leader)

      • updateAnnotation

        public void updateAnnotation​(Position pos)

      • getDisplayString

        protected java.lang.String getDisplayString​(Position pos)

      • formatCircleMeasurements

        protected java.lang.String formatCircleMeasurements​(Position pos)

      • formatEllipseMeasurements

        protected java.lang.String formatEllipseMeasurements​(Position pos)

      • formatSquareMeasurements

        protected java.lang.String formatSquareMeasurements​(Position pos)

      • formatQuadMeasurements

        protected java.lang.String formatQuadMeasurements​(Position pos)

      • formatPolygonMeasurements

        protected java.lang.String formatPolygonMeasurements​(Position pos)

      • formatLineMeasurements

        protected java.lang.String formatLineMeasurements​(Position pos)

      • computeAccumulatedLength

        protected java.lang.Double computeAccumulatedLength​(LatLon pos)

      • computePathLength

        protected double computePathLength()

      • lengthsEssentiallyEqual

        protected boolean lengthsEssentiallyEqual​(java.lang.Double l1,
                                          java.lang.Double l2)

      • areLocationsRedundant

        protected boolean areLocationsRedundant​(LatLon locA,
                                        LatLon locB)