Envinsa 4.3 Java Edition API Specification

com.mapinfo.miaware.clientsdk.utils
Class GeometryUtils

java.lang.Object
  extended bycom.mapinfo.miaware.clientsdk.utils.GeometryUtils

public class GeometryUtils
extends java.lang.Object

This class defines utilities to create geometry objects. It also provides utility methods to:

  • Expand an arc sector into a polygon
  • Expand a circle into a polygon
  • Expand an ellipse into a polygon
  • Get the center point of an Envelope
  • Get the zoom level of an Envelope
  • Get the inner radius of an Envelope
  • The following geometries can be created by directly using this class:

  • Point
  • Envelope
  • All the other geometries can be created by using the xlsGMLFactory instance. An instance of this class is created by using the getXLSGMLFactory() method.

    Since:
    v3.0

    Field Summary
    static short ANGULAR_UNIT_DEGREE
              Degree angular unit code.
    static short ANGULAR_UNIT_RADIAN
              Radians angular unit code.
    static short DISTANCEUNIT_DECAMETERS
              Decameter distance unit code --> 1 DM = 10 M.
    static short DISTANCEUNIT_FEET
              Foot distance unit code.
    static short DISTANCEUNIT_KILOMETERS
              Kilometer distance unit code.
    static short DISTANCEUNIT_METERS
              Meter distance unit code.
    static short DISTANCEUNIT_MILES
              Mile distance unit code.
    static short DISTANCEUNIT_UNKNOWN
              Unknown unit code.
    static short DISTANCEUNIT_YARD
              Yard distance unit code
     
    Constructor Summary
    GeometryUtils()
               
     
    Method Summary
    static java.util.Vector expandArcSector(double cx, double cy, double inRadius, double outRadius, short distUnit, double startAngle, double endAngle, short angUnit, com.mapinfo.coordsys.CoordSys coordsys, java.util.Locale loc)
              This method expands an arc sector into a polygon.
    static java.util.Vector expandArcSector(double cx, double cy, double inRadius, double outRadius, short distUnit, double startAngle, double endAngle, short angUnit, int numVertexes, com.mapinfo.coordsys.CoordSys coordsys, java.util.Locale loc)
              This method expands an arc sector into a polygon.
    static java.util.Vector expandCircle(double cx, double cy, double radius, short distUnit, com.mapinfo.coordsys.CoordSys coordsys, java.util.Locale loc)
              This method expands a circle into a polygon.
    static java.util.Vector expandCircle(double cx, double cy, double radius, short distUnit, int numVertexes, com.mapinfo.coordsys.CoordSys coordsys, java.util.Locale loc)
              This method expands a circle into a polygon.
    static java.util.Vector expandEllipse(double cx, double cy, double majorAxis, double minorAxis, short distUnit, double rotateAng, short angUnit, com.mapinfo.coordsys.CoordSys coordsys, java.util.Locale loc)
              This method expands an ellipse into a polygon.
    static java.util.Vector expandEllipse(double cx, double cy, double majorAxis, double minorAxis, short distUnit, int numVertexes, double rotateAng, short angUnit, com.mapinfo.coordsys.CoordSys coordsys, java.util.Locale loc)
              This method expands an ellipse into a polygon.
    static Point getCentrePoint(Envelope envelope)
              Gets the center point of a envelope.
    static Distance getRadius(Envelope envelope)
              Gets the inner radius of a envelope.
    static xlsGMLFactory getXLSGMLFactory()
              Returns the GML factory of the XLS implementation.
    static Distance getZoomLevel(Envelope envelope)
              Gets the zoom level of an envelope.
    static Envelope newEnvelope(double x1, double y1, double x2, double y2, java.lang.String srs)
              Returns a new envelope with the specified boundaries and spatial reference system (SRS) name.
    static Envelope newEnvelope(Point centrePoint, Distance zoomlevel, double width, double height)
              Creates the envelope from the given zoom level and center point.
    static Point newPoint(double x, double y, java.lang.String srsName)
              Returns the new two-dimensional point with the specified coordinates and spatial reference system (SRS) name.
     
    Methods inherited from class java.lang.Object
    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
     

    Field Detail

    DISTANCEUNIT_DECAMETERS

    public static final short DISTANCEUNIT_DECAMETERS
    Decameter distance unit code --> 1 DM = 10 M.

    See Also:
    Constant Field Values

    DISTANCEUNIT_FEET

    public static final short DISTANCEUNIT_FEET
    Foot distance unit code.

    See Also:
    Constant Field Values

    DISTANCEUNIT_KILOMETERS

    public static final short DISTANCEUNIT_KILOMETERS
    Kilometer distance unit code.

    See Also:
    Constant Field Values

    DISTANCEUNIT_METERS

    public static final short DISTANCEUNIT_METERS
    Meter distance unit code.

    See Also:
    Constant Field Values

    DISTANCEUNIT_MILES

    public static final short DISTANCEUNIT_MILES
    Mile distance unit code.

    See Also:
    Constant Field Values

    DISTANCEUNIT_UNKNOWN

    public static final short DISTANCEUNIT_UNKNOWN
    Unknown unit code.

    See Also:
    Constant Field Values

    DISTANCEUNIT_YARD

    public static final short DISTANCEUNIT_YARD
    Yard distance unit code

    See Also:
    Constant Field Values

    ANGULAR_UNIT_RADIAN

    public static final short ANGULAR_UNIT_RADIAN
    Radians angular unit code.

    See Also:
    Constant Field Values

    ANGULAR_UNIT_DEGREE

    public static final short ANGULAR_UNIT_DEGREE
    Degree angular unit code.

    See Also:
    Constant Field Values
    Constructor Detail

    GeometryUtils

    public GeometryUtils()
    Method Detail

    getXLSGMLFactory

    public static xlsGMLFactory getXLSGMLFactory()
    Returns the GML factory of the XLS implementation.

    Returns:
    the GML factory.

    newPoint

    public static Point newPoint(double x,
                                 double y,
                                 java.lang.String srsName)
    Returns the new two-dimensional point with the specified coordinates and spatial reference system (SRS) name.

    Parameters:
    x - the X coordinate of the point.
    y - the Y coordinate of the point.
    srsName - the SRS to which the data will be projected in EPSG:XXXX format.
    Returns:
    a new point with the specified coordinates.

    newEnvelope

    public static Envelope newEnvelope(double x1,
                                       double y1,
                                       double x2,
                                       double y2,
                                       java.lang.String srs)
                                throws InvalidMessageException
    Returns a new envelope with the specified boundaries and spatial reference system (SRS) name.

    Parameters:
    x1 - the lower left X coordinate of the envelope.
    y1 - the lower left Y coordinate of the envelope.
    x2 - the upper right X coordinate of the envelope.
    y2 - the upper right Y coordinate of the envelope.
    srs - the SRS to which the data will be projected in EPSG:XXXX format.
    Returns:
    a new envelope with the specified coordinates.
    Throws:
    InvalidMessageException

    expandArcSector

    public static java.util.Vector expandArcSector(double cx,
                                                   double cy,
                                                   double inRadius,
                                                   double outRadius,
                                                   short distUnit,
                                                   double startAngle,
                                                   double endAngle,
                                                   short angUnit,
                                                   int numVertexes,
                                                   com.mapinfo.coordsys.CoordSys coordsys,
                                                   java.util.Locale loc)
                                            throws java.lang.Exception
    This method expands an arc sector into a polygon. All points are in WGS84 longitude/latitude. The input and output points can be either in latitude/longitude or Cartesian (dependent on the value of coordsys). For a lat/long space, a spherical model of Earth is assumed. The Earth radius is chosen to be 6378137 meters in accordance with WGS84 and NAD83.

    Parameters:
    cx - the X coordinate of the center (position).
    cy - the Y coordinate of the center (position).
    inRadius - the radius of the inner circle in distUnit.
    outRadius - the radius of the outer circle in distUnit. If a value less than inRadius is specified, an exception is thrown. If a value equal to inRadius is specified, just a line string representing the arc is returned with the number of vertexes equal to numVertexes/2.
    distUnit - the distance unit. Accepted values are:
    DISTANCEUNIT_KILOMETERS
    DISTANCEUNIT_METERS
    DISTANCEUNIT_MILES
    DISTANCEUNIT_FEET
    DISTANCEUNIT_YARD
    DISTANCEUNIT_DECAMETERS
    Anything else leads to an exception.
    numVertexes - the vertex resolution (number of vertexes to be generated). Should be an even number greater than or equal to MIN_NUM_VERTEX_ARC (6). Each of inner and outer arcs will have numVertexes/2 vertexes. The small vertex resolution leads to greater approximation.
    startAngle - the starting angle in angUnit. Should be less than endAngle and less than or equal to 360 degrees (or 2Pi). The angle is measured clockwise from North (or Y axis).
    endAngle - the ending angle in angUnit. Should be greater than startAngle and less than or equal to 360 degrees (or 2Pi). The angle is measured clockwise from North (or Y axis).
    Note: All angles are from horizontal axes in anticlockwise direction.
    angUnit - the angular unit. The accepted values are:
    ANGULAR_UNIT_DEGREE
    ANGULAR_UNIT_RADIAN
    Anything else leads to an exception.
    coordsys - the coordinate system.
    loc - the Locale object for localization. If null, the default Locale is used.
    Returns:
    A Vector of array elements representing the vertexes of the polygon. Each element of the resultant vector object is a three-element array of double values representing respectively, the X and Y coordinates of the vertexes and the 'angle' (in degrees) of each vertex from X axis in anticlockwise direction. The resultant polygon will have numVertexes+1 vertexes as the first vertex will be added as the last element in conformance with the notion of a closed polygon. If no result is returned, the resultant vector object will be empty (not null).
    Throws:
    java.lang.Exception - The implementation of this method throws an Exception exception. The caller is responsible for catching and handling the exception.

    expandCircle

    public static java.util.Vector expandCircle(double cx,
                                                double cy,
                                                double radius,
                                                short distUnit,
                                                com.mapinfo.coordsys.CoordSys coordsys,
                                                java.util.Locale loc)
                                         throws java.lang.Exception
    This method expands a circle into a polygon. The input and output points can be either in latitude/longitude or Cartesian (dependent on the value of coordsys). For a lat/long space, a spherical model of Earth is assumed. The Earth radius is chosen to be 6378137 meters in accordance with WGS84 and NAD83. The resultant polygon will have an optimized number of vertices, with the first vertex being the same as the last in conformance with the notion of a closed polygon. The optimized number of vertexes depends on the radius. The minimum number of vertexes is GeomUtilities.MIN_VERTEX (32) and the maximum is GeomUtilities.MAX_VERTEX (500).

    Parameters:
    cx - the X coordinate of the center (position).
    cy - the Y coordinate of the center (position).
    radius - the radius of the circle in distUnit.
    distUnit - the distance unit. Accepted values are:
    DISTANCEUNIT_KILOMETERS
    DISTANCEUNIT_METERS
    DISTANCEUNIT_MILES
    DISTANCEUNIT_FEET
    DISTANCEUNIT_YARD
    DISTANCEUNIT_DECAMETERS
    Anything else leads to an exception.
    coordsys - the coordinate system.
    loc - the Locale object for localization. If null, the default Locale is used.
    Returns:
    A Vector of array elements of double values. Each element of the resultant vector object is a three-element array of double values representing respectively, the X and Y coordinates of the vertexes and the 'angle' (in degrees) of each vertex from X axis in anticlockwise direction. The first and the last elements of the resultant vector are identical to conform with the notion of a closed polygon. If no result is returned, the resultant vector object will be empty (not null).
    Throws:
    java.lang.Exception - The implementation of this method throws an Exception exception. The caller is responsible for catching and handling the exception.

    expandCircle

    public static java.util.Vector expandCircle(double cx,
                                                double cy,
                                                double radius,
                                                short distUnit,
                                                int numVertexes,
                                                com.mapinfo.coordsys.CoordSys coordsys,
                                                java.util.Locale loc)
                                         throws java.lang.Exception
    This method expands a circle into a polygon. The input and output points can be either in latitude/longitude or Cartesian (dependent on the value of coordsys). For a lat/long space, a spherical model of Earth is assumed. The Earth radius is chosen to be 6378137 meters in accordance with WGS84 and NAD83. The resultant polygon will have numVertexes+1 vertices, with the first vertex being the same as the last in conformance with the notion of a closed polygon.

    Parameters:
    cx - the X coordinate of the center (position).
    cy - the Y coordinate of the center (position).
    radius - the radius of the circle in distUnit.
    distUnit - the distance unit. Accepted values are:
    DISTANCEUNIT_KILOMETERS
    DISTANCEUNIT_METERS
    DISTANCEUNIT_MILES
    DISTANCEUNIT_FEET
    DISTANCEUNIT_YARD
    DISTANCEUNIT_DECAMETERS
    Anything else leads to an exception.
    numVertexes - the vertex resolution (number of vertexes to be generated). The small vertex resolution leads to greater approximation.
    coordsys - the coordinate system.
    loc - the Locale object for localization. If null, the default Locale is used.
    Returns:
    A Vector of array elements of double values. Each element of the resultant vector object is a three-element array of double values representing respectively, the X and Y coordinates of the vertexes and the 'angle' (in degrees) of each vertex from X axis in anticlockwise direction. The first and the last elements of the resultant vector are identical to conform with the notion of a closed polygon. If no result is returned, the resultant vector object will be empty (not null).
    Throws:
    java.lang.Exception - The implementation of this method throws an Exception exception. The caller is responsible for catching and handling the exception.

    expandEllipse

    public static java.util.Vector expandEllipse(double cx,
                                                 double cy,
                                                 double majorAxis,
                                                 double minorAxis,
                                                 short distUnit,
                                                 double rotateAng,
                                                 short angUnit,
                                                 com.mapinfo.coordsys.CoordSys coordsys,
                                                 java.util.Locale loc)
                                          throws java.lang.Exception
    This method expands an ellipse into a polygon. The input and output points can be either in latitude/longitude or Cartesian (dependent on the value of coordsys). For a lat/long space, a spherical model of Earth is assumed. The Earth radius is chosen to be 6378137 meters in accordance with WGS84 and NAD83. The resultant polygon will have an optimized number of vertices, with the first vertex being the same as the last in conformance with the notion of a closed polygon. The optimized number of vertexes depends on the majorAxis. The minimum number of vertexes is GeomUtilities.MIN_VERTEX (32) and the maximum is GeomUtilities.MAX_VERTEX (500).

    Parameters:
    cx - the X coordinate of the center (position).
    cy - the Y coordinate of the center (position).
    majorAxis - the major axis in distUnit.
    minorAxis - the minor axis in distUnit.
    distUnit - the distance unit. Accepted values are:
    DISTANCEUNIT_KILOMETERS
    DISTANCEUNIT_METERS
    DISTANCEUNIT_MILES
    DISTANCEUNIT_FEET
    DISTANCEUNIT_YARD
    DISTANCEUNIT_DECAMETERS
    Anything else leads to an exception.
    rotateAng - The angle in angUnit to rotate the ellipse about its center point anticlockwise. Should be between -360 degrees (or -2Pi radians) and 360 degrees (or 2Pi radians), otherwise an exception is thrown.
    angUnit - the angular unit. The accepted values are:
    ANGULAR_UNIT_DEGREE
    ANGULAR_UNIT_RADIAN
    Anything else leads to an exception.
    coordsys - the coordinate system.
    loc - the Locale object for localization. If null, the default Locale is used.
    Returns:
    A Vector of array elements of double values. Each element of the resultant vector object is a three-element array of double values representing respectively, the X and Y coordinates of the vertexes and the 'angle' (in degrees) of each vertex from X axis in anticlockwise direction. The first and the last elements of the resultant vector are identical to conform with the notion of a closed polygon. If no result is returned, the resultant vector object will be empty (not null).
    Throws:
    java.lang.Exception - The implementation of this method throws an Exception exception. The caller is responsible for catching and handling the exception.

    expandEllipse

    public static java.util.Vector expandEllipse(double cx,
                                                 double cy,
                                                 double majorAxis,
                                                 double minorAxis,
                                                 short distUnit,
                                                 int numVertexes,
                                                 double rotateAng,
                                                 short angUnit,
                                                 com.mapinfo.coordsys.CoordSys coordsys,
                                                 java.util.Locale loc)
                                          throws java.lang.Exception
    This method expands an ellipse into a polygon. The input and output points can be either in latitude/longitude or Cartesian (dependent on the value of coordsys). For a lat/long space, a spherical model of Earth is assumed. The Earth radius is chosen to be 6378137 meters in accordance with WGS84 and NAD83. The resultant polygon will have numVertexes+1 vertices, with the first vertex being the same as the last in conformance with the notion of a closed polygon.

    Parameters:
    cx - the X coordinate of the center (position).
    cy - the Y coordinate of the center (position).
    majorAxis - the major axis in distUnit.
    minorAxis - the minor axis in distUnit.
    distUnit - the distance unit. Accepted values are:
    DISTANCEUNIT_KILOMETERS
    DISTANCEUNIT_METERS
    DISTANCEUNIT_MILES
    DISTANCEUNIT_FEET
    DISTANCEUNIT_YARD
    DISTANCEUNIT_DECAMETERS
    Anything else leads to an exception.
    numVertexes - the vertex resolution (number of vertexes to be generated). The small vertex resolution leads to greater approximation.
    rotateAng - The angle in angUnit to rotate the ellipse about its center point anticlockwise. Should be between -360 degrees (or -2pi) and 360 degrees (or 2Pi), otherwise an exception is thrown.
    angUnit - the angular unit. The accepted values are:
    ANGULAR_UNIT_DEGREE
    ANGULAR_UNIT_RADIAN
    Anything else leads to an exception.
    coordsys - the coordinate system.
    loc - the Locale object for localization. If null, the default Locale is used.
    Returns:
    A Vector of array elements of double values. Each element of the resultant vector object is a three-element array of double values representing respectively, the X and Y coordinates of the vertexes and the 'angle' (in degrees) of each vertex from X axis in anticlockwise direction. The first and the last elements of the resultant vector are identical to conform with the notion of a closed polygon. If no result is returned, the resultant vector object will be empty (not null).
    Throws:
    java.lang.Exception - The implementation of this method throws an Exception exception. The caller is responsible for catching and handling the exception.

    expandArcSector

    public static java.util.Vector expandArcSector(double cx,
                                                   double cy,
                                                   double inRadius,
                                                   double outRadius,
                                                   short distUnit,
                                                   double startAngle,
                                                   double endAngle,
                                                   short angUnit,
                                                   com.mapinfo.coordsys.CoordSys coordsys,
                                                   java.util.Locale loc)
                                            throws java.lang.Exception
    This method expands an arc sector into a polygon. The input and output points can be either in latitude/longitude or Cartesian (dependent on the value of coordsys). For a lat/long space, a spherical model of Earth is assumed. The Earth radius is chosen to be 6378137 meters in accordance with WGS84 and NAD83.

    Parameters:
    cx - the X coordinate of the center (position).
    cy - the Y coordinate of the center (position).
    inRadius - the radius of the inner circle in distUnit.
    outRadius - the radius of the outer circle in distUnit. If a value less than inRadius is specified, an exception is thrown. If a value equal to inRadius is specified, just a line string representing the arc is returned.
    distUnit - the distance unit. Accepted values are:
    DISTANCEUNIT_KILOMETERS
    DISTANCEUNIT_METERS
    DISTANCEUNIT_MILES
    DISTANCEUNIT_FEET
    DISTANCEUNIT_YARD
    DISTANCEUNIT_DECAMETERS
    Anything else leads to an exception.
    startAngle - the starting angle in angUnit. Should be less than endAngle and less than or equal to 360 (or 2Pi) degrees. The angle is measured clockwise from North (or Y axis).
    endAngle - the ending angle in angUnit. Should be greater than startAngle and less than or equal to 360 degrees (or 2Pi). The angle is measured clockwise from North (or Y axis).
    Note: All angles are from horizontal axes in anticlockwise direction.
    coordsys - the coordinate system.
    angUnit - the angular unit. The accepted values are:
    ANGULAR_UNIT_DEGREE
    ANGULAR_UNIT_RADIAN
    Anything else leads to an exception.
    loc - the Locale object for localization. If null, the default Locale is used.
    Returns:
    A Vector of array elements representing the vertexes of the polygon. Each element of the resultant vector object is a three-element array of double values representing respectively, the X and Y coordinates of the vertexes and the 'angle' (in degrees) of each vertex from X axis in anticlockwise direction. The resultant polygon will have an optimized number of vertices, with the first vertex being the same as the last in conformance with the notion of a closed polygon. The optimized number of vertexes depends on the outRadius. The minimum number of vertexes is GeomUtilities.MIN_VERTEX (32) and the maximum is GeomUtilities.MAX_VERTEX (500). If no result is returned, the resultant vector object will be empty (not null).
    Throws:
    java.lang.Exception - The implementation of this method throws an Exception exception. The caller is responsible for catching and handling the exception.

    getCentrePoint

    public static Point getCentrePoint(Envelope envelope)
                                throws java.lang.Exception
    Gets the center point of a envelope.

    Parameters:
    envelope - a given envelope object; if no SRS is specified, the default "EPSG:4326" will be used.
    Returns:
    the center point if the envelope is valid, or null for not valid envelope.
    Throws:
    java.lang.Exception

    getZoomLevel

    public static Distance getZoomLevel(Envelope envelope)
                                 throws java.lang.Exception
    Gets the zoom level of an envelope.

    Parameters:
    envelope - a given envelope object; if no SRS is specified, the default "EPSG:4326" will be used.
    Returns:
    the zoom level.
    Throws:
    java.lang.Exception

    getRadius

    public static Distance getRadius(Envelope envelope)
                              throws java.lang.Exception
    Gets the inner radius of a envelope.

    Parameters:
    envelope - a given envelope object; if no SRS specified, the default "EPSG:4326" will be used.
    Returns:
    the inner radius.
    Throws:
    java.lang.Exception

    newEnvelope

    public static Envelope newEnvelope(Point centrePoint,
                                       Distance zoomlevel,
                                       double width,
                                       double height)
                                throws java.lang.Exception
    Creates the envelope from the given zoom level and center point.

    Parameters:
    centrePoint - the centre point in real world; if no SRS is specified, the default "EPSG:4326" will be used.
    zoomlevel - the zoomlevel distance.
    width - the screen width.
    height - the screen height.
    Returns:
    the bounds in same coordsys with the centre point.
    Throws:
    java.lang.Exception

    v4.3

    Pitney Bowes MapInfo Corporation Copyright[2008]. All rights reserved