Class GeometryEngine

    • Method Detail

      • area

        public static double area​(Envelope envelope)
        Calculates the area for the Envelope passed in. This is a planar measurement to compute area for use on geometries using a projected coordinate system. Use areaGeodetic(Geometry, AreaUnit, GeodeticCurveType) for geodetic measurement.
        Parameters:
        envelope - envelope whose area is to be calculated
        Returns:
        area in units matching the envelope's spatial reference
        Throws:
        NullPointerException - if envelope is null
        Since:
        100.0.0
      • area

        public static double area​(Polygon polygon)
        Calculates the area for the Polygon passed in. This is a planar measurement using 2D Cartesian mathematics to compute the area. Use areaGeodetic(Geometry, AreaUnit, GeodeticCurveType) for geodetic measurement.

        The calculated area is based upon the SpatialReference of the input geometry. Some spatial references are more appropriate than others for measuring area and an 'area preserving' spatial reference would be most appropriate with this method. For more information see this core concepts spatial references topic. If the input geometry to this method is not in an 'area preserving' spatial reference, then there are other options:

        1. use the project(Geometry, SpatialReference) method to project the geometry to one that is better suited for area calculations or
        2. use the areaGeodetic(Geometry, AreaUnit, GeodeticCurveType) method which projects the geometry to a geographic coordinate system to obtain the area.

        The input geometry must be topologically correct to get its accurate area. If the geometry is not topologically correct, then the resultant area from this method could give negative results. Best practice is to simplify(Geometry) geometries before passing to this method. Geometries returned by ArcGIS Server services are always topologically correct. Therefore, if you construct geometries programmatically or using the sketch layer, or if you modify geometries returned by ArcGIS Server, you should always simplify them using simplify(Geometry) first.

        Parameters:
        polygon - polygon whose area is to be calculated
        Returns:
        area in units matching the polygon's spatial reference
        Throws:
        NullPointerException - if polygon is null
        Since:
        100.0.0
      • areaGeodetic

        public static double areaGeodetic​(Geometry geometry,
                                          AreaUnit areaUnit,
                                          GeodeticCurveType curveType)
        Calculates the area of the given geometry using a geodetic curve.

        The term geodesic means calculating the shortest distance between two points on a spheroid. Using geodesic algorithms to calculate distances provides a highly accurate way to obtain length and area of measurements of geographic features. The geodesic algorithm uses the concept of a great circle to obtain the shortest route between two points along the earth’s surface. The area measurement obtained via this method is typically superior to that of the area(Polygon) method, as area(Polygon) is based upon a projection (i.e. a flat 2D representation of a 3D surface) which often introduces distortion depending on the SpatialReference the geometry is in.

        The input geometry must be topologically correct to get its accurate area. If the geometry is not topologically correct, then the resultant area from this method could give negative results. Best practice is to simplify(Geometry) geometries before passing to this method. Geometries returned by ArcGIS Server services are always correct. Therefore, if you construct geometries programmatically or using the sketch layer, or if you modify geometries returned by ArcGIS Server, you should always simplify them using simplify(Geometry) first.

        Parameters:
        geometry - geometry whose area is to be calculated
        areaUnit - unit of measure for the return value. If null, defaults to unit of Id AreaUnitId.SQUARE_METERS
        curveType - type of curve to calculate the geodetic area
        Returns:
        the geodetic area of the given geometry
        Throws:
        IllegalArgumentException - if geometry or curveType is null
        Since:
        100.0.0
      • autoComplete

        public static List<Polygon> autoComplete​(Iterable<Polygon> existingBoundaries,
                                                 Iterable<Polyline> newBoundaries)
        Fills the closed gaps between polygons using polygon boundaries and polylines as the boundary for the new polygons.

        The new polygons are created in the closed empty areas bounded by the edges of the existing polygon boundaries and the new boundary polylines. The newly created polygons do not overlap any existing polygons or polylines, and the boundary of a new polygon must contain at least one edge from the polylines. Only polygons that intersect the input polylines will participate in the operation, so it makes sense to filter the input accordingly.

        The geometries in existingBoundaries and newBoundaries must have consistent spatial references.

        Parameters:
        existingBoundaries - the polygons
        newBoundaries - the polylines
        Returns:
        an unmodifiable list of the new polygons that were created; empty if either existingBoundaries or newBoundaries is empty
        Throws:
        IllegalArgumentException - if existingBoundaries or newBoundaries is null
        ArcGISRuntimeException - if the geometries in existingBoundaries and newBoundaries have inconsistent spatial references
        Since:
        100.1.0
      • boundary

        public static Geometry boundary​(Geometry geometry)
        Calculates the boundary of the given geometry.
        • The boundary of a point is an empty geometry. Points have no boundary.
        • The boundary of a polyline is a multipoint containing the end points of the polyline's parts.
        • The boundary of a polygon is a polyline describing its outer and inner rings.
        Parameters:
        geometry - geometry whose boundary is to be calculated
        Returns:
        the boundary of the given geometry
        Throws:
        IllegalArgumentException - if geometry is null
        Since:
        100.0.0
      • buffer

        public static Polygon buffer​(Geometry geometry,
                                     double distance)
        Creates a buffer polygon at the specified distance around the given geometry. This is a planar buffer operation. Use bufferGeodetic(Geometry, double, LinearUnit, double, GeodeticCurveType) to produce a geodetic buffer.

        The returned polygon is based upon the SpatialReference of the input geometry. For this method, some spatial references are better than others for getting accurate results. To get the most accurate buffer polygons using this method, consider using an 'area preserving' spatial reference such as: Albers, Lambert, Mollweide, Hammer, Sinusoidal, etc. If the input geometry to this method is not based on a good 'area preserving' spatial reference, then there are two options available to produce accurate buffers: (1) use the project(Geometry, SpatialReference) method to project the geometry to a coordinate system that is better suited for buffers or (2) use the bufferGeodetic(Geometry, double, LinearUnit, double, GeodeticCurveType) method which projects the geometry to a geographic coordinate system to obtain the most accurate buffers possible.

        Parameters:
        geometry - geometry to buffer
        distance - buffer distance for the geometry in the same units as the geometry's spatial reference
        Returns:
        a polygon that represents a buffer at the desired distance around the given geometry
        Throws:
        NullPointerException - if geometry is null
        Since:
        100.0.0
      • buffer

        public static List<Polygon> buffer​(Iterable<Geometry> geometries,
                                           Iterable<Double> distances,
                                           boolean unionResult)
        Calculates a buffer or buffers around a collection of geometries. The geometries must have consistent spatial references. This is a planar buffer operation. Use bufferGeodetic(Iterable, Iterable, LinearUnit, double, GeodeticCurveType, boolean) to produce geodetic buffers.

        The polygons returned from this method are based upon the SpatialReference of the input geometry. For this method, some spatial references are better than others for getting accurate results. To get the most accurate buffer polygons using this method, consider using an 'area preserving' SpatialReference such as: Albers, Lambert, Mollweide, Hammer, Sinusoidal, etc. If the input geometry to this method is not based on a good 'area preserving' spatial reference, then there are two options available to produce accurate buffers: (1) use the project(Geometry, SpatialReference) method to project the geometry to a coordinate system that is better suited for buffers or (2) use the buffer(Iterable, Iterable, boolean) method which projects the geometry to a geographic coordinate system to obtain the most accurate buffers possible.

        Parameters:
        geometries - the geometries to buffer
        distances - the buffer distances for the geometries' in the same units as the geometry's spatial reference. If the number of distances is fewer than the number of geometries, the last distance value is used for the rest of the geometries.
        unionResult - true to return a single geometry that buffers all the input geometries, false to return a separate buffer for each of the input geometries
        Returns:
        an unmodifiable list containing either a single polygon or one polygon per input geometry, depending on the value of unionResult
        Throws:
        IllegalArgumentException - if geometries is null, or if distances is null or empty
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent
        Since:
        100.1.0
      • bufferGeodetic

        public static Polygon bufferGeodetic​(Geometry geometry,
                                             double distance,
                                             LinearUnit distanceUnit,
                                             double maxDeviation,
                                             GeodeticCurveType curveType)
        Returns a geometry object that represents a buffer around the given geometry, calculated using a geodetic curve.
        Parameters:
        geometry - the geometry to buffer
        distance - the buffer distance for the geometry
        distanceUnit - the unit of measurement for distance
        maxDeviation - the maximum deviation between points
        curveType - the type of geodetic curve to use
        Returns:
        a polygon that represents a buffer at the desired distance around the given geometry
        Throws:
        IllegalArgumentException - if geometry, distanceUnit or curveType is null
        ArcGISRuntimeException - if the spatial reference of geometry is null
        Since:
        100.1.0
      • bufferGeodetic

        public static List<Polygon> bufferGeodetic​(Iterable<Geometry> geometries,
                                                   Iterable<Double> distances,
                                                   LinearUnit distanceUnit,
                                                   double maxDeviation,
                                                   GeodeticCurveType curveType,
                                                   boolean unionResult)
        Creates a buffer or buffers, calculated using a geodetic curve, around a collection of geometries. The geometries must have consistent spatial references.
        Parameters:
        geometries - the geometries to buffer
        distances - the buffer distances for the geometries. If the number of distances is fewer than the number of geometries, the last distance value is used for the rest of the geometries.
        distanceUnit - the unit of measurement for distances
        maxDeviation - the maximum deviation between points
        curveType - the type of geodetic curve to use
        unionResult - true to return a single geometry that buffers all the input geometries, false to return a separate buffer for each of the input geometries
        Returns:
        an unmodifiable list containing either a single polygon or one polygon per input geometry, depending on the value of unionResult
        Throws:
        IllegalArgumentException - if geometries, distanceUnit or curveType is null, or if distances is null or empty
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent
        Since:
        100.1.0
      • combineExtents

        public static Envelope combineExtents​(Geometry geometry1,
                                              Geometry geometry2)
        Combines the extents of two given geometries. The input geometries must have consistent spatial references.
        Parameters:
        geometry1 - a geometry
        geometry2 - another geometry
        Returns:
        an envelope that covers the extents of the input geometries
        Throws:
        IllegalArgumentException - if geometry1 or geometry2 is null
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent or null
        Since:
        100.1.0
      • combineExtents

        public static Envelope combineExtents​(Iterable<Geometry> geometries)
        Combines the extents of a collection of geometries. The input geometries must have consistent spatial references.
        Parameters:
        geometries - the input geometries
        Returns:
        an envelope that covers the extents of the input geometries
        Throws:
        IllegalArgumentException - if geometries is null or empty
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent
        Since:
        100.1.0
      • contains

        public static boolean contains​(Geometry container,
                                       Geometry within)
        Tests if geometry1 contains geometry2.
        Parameters:
        container - geometry that is tested for the "contains" relationship to within
        within - geometry that is tested for the "within" relationship to container
        Returns:
        true if container contains within, false otherwise
        Throws:
        NullPointerException - if container or within is null
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent or null
        Since:
        100.0.0
      • convexHull

        public static Geometry convexHull​(Geometry geometry)
        Calculates the convex hull of the given geometry. The convex hull of a geometry is the minimal bounding geometry such that all outer angles are convex. If you imagine a rubber band stretched around the input geometry, the rubber band takes the shape of the convex hull.
        Parameters:
        geometry - the input geometry
        Returns:
        the convex hull of the given geometry
        Throws:
        IllegalArgumentException - if geometry is null
        Since:
        100.0.0
      • convexHull

        public static List<Geometry> convexHull​(Iterable<Geometry> geometries,
                                                boolean unionResult)
        Calculates the convex hull or hulls of the geometries in the given collection. The geometries must have consistent spatial references. The convex hull of a geometry is the minimal bounding geometry such that all outer angles are convex. If you imagine a rubber band stretched around the input geometry, the rubber band takes the shape of the convex hull.
        Parameters:
        geometries - the input geometries
        unionResult - true to return a single convex hull that encloses all the input geometries, false to return a separate convex hull for each of the input geometries
        Returns:
        an unmodifiable list containing either a single geometry or one geometry per input geometry, depending on the value of unionResult
        Throws:
        IllegalArgumentException - if geometries is null
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent
        Since:
        100.1.0
      • crosses

        public static boolean crosses​(Geometry geometry1,
                                      Geometry geometry2)
        Tests if geometry1 crosses geometry2.

        This method returns true if an intersection results in a geometry whose dimension is one less than the maximum dimension of the two source geometries and the intersection set is interior to both source geometries. This method only returns true for the following combinations of geometries: Multipoint/Polygon, Multipoint/Polyline, Polyline/Polyline, and Polyline/Polygon comparisons.

        Parameters:
        geometry1 - one of the two geometries
        geometry2 - the other geometry
        Returns:
        true if geometry1 crosses geometry2, false otherwise
        Throws:
        IllegalArgumentException - if geometry1 or geometry2 is null
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent or null
        Since:
        100.0.0
      • cut

        public static List<Geometry> cut​(Geometry geometry,
                                         Polyline cutter)
        Cuts geometry with cutter.

        The cutter and geometry's spatial references must match.

        When cutting a Polyline, all left cuts will be grouped together in the first Geometry, right cuts and co-incident cuts are grouped in the second Geometry, and each undefined cut, along with any uncut parts, are output as separate Polylines. A touch is considered to be a cut.

        When cutting a Polygon, all left cuts are grouped in the first Geometry, all right cuts are in the second Geometry, and each undefined cut, along with any left-over parts after cutting, are output as a separate Geometry.

        If there were no cuts then an empty collection will be returned.

        If the left or right cut does not exist, the returned Geometry will be empty for this type of cut. An undefined cut will only be produced if a left cut or right cut was produced, and there was a part left over after cutting or a cut is bounded to the left and right of the cutter.

        Parameters:
        geometry - geometry to cut
        cutter - polyline that cuts the geometry
        Returns:
        collection of geometries after cut
        Throws:
        IllegalArgumentException - if geometry or cutter is null
        Since:
        100.0.0
      • densify

        public static Geometry densify​(Geometry geometry,
                                       double maxSegmentLength)
        Densifies the given geometry by plotting points between existing vertices in that geometry.
        Parameters:
        geometry - geometry to densify
        maxSegmentLength - the maximum distance between points after densification; must be a positive value. Curves are split into shorter subcurves such that the length of subcurves is shorter than maxSegmentLength. After that the curves are replaced with straight segments. This value should be in the same units as the geometry parameter's spatial reference system.
        Returns:
        the densified geometry
        Throws:
        IllegalArgumentException - if geometry is null
        Since:
        100.0.0
      • densifyGeodetic

        public static Geometry densifyGeodetic​(Geometry geometry,
                                               double maxSegmentLength,
                                               LinearUnit lengthUnit,
                                               GeodeticCurveType curveType)
        Densifies the given geometry using a geodetic curve.
        Parameters:
        geometry - geometry to densify
        maxSegmentLength - the maximum distance between points after densification. Must be a positive value
        lengthUnit - unit of measure for maxSegmentLength. If null, defaults to linear unit of Id LinearUnitId.METERS
        curveType - type of geodetic curve to calculate
        Returns:
        the geodetic densified geometry
        Throws:
        IllegalArgumentException - if geometry or curveType is null
        ArcGISRuntimeException - if the spatial reference of geometry is null
        Since:
        100.0.0
      • difference

        public static Geometry difference​(Geometry geometry1,
                                          Geometry geometry2)
        Constructs the set-theoretic difference between two geometries. This will return a geometry consisting of the parts of geometry1 that are not in geometry2.

        This method performs a spatial subtraction from the two input geometries. This means that the order of the two input geometry arguments of the difference method will have different results if they are switched. Think of the difference equation as:

        A (Difference) B = C
        B (Difference) A = D

        See symmetricDifference(Geometry, Geometry) to get the parts that are in either geometry, but not in both.

        Parameters:
        geometry1 - first geometry
        geometry2 - second geometry
        Returns:
        new geometry object that represents the difference of the two given input geometries
        Throws:
        NullPointerException - if geometry1 or geometry2 is null
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent or null
        Since:
        100.0.0
      • disjoint

        public static boolean disjoint​(Geometry geometry1,
                                       Geometry geometry2)
        Tests whether two geometries are disjoint.
        Parameters:
        geometry1 - geometry1 one of the two geometries
        geometry2 - geometry2 the other geometry
        Returns:
        true if geometry1 and geometry2 do not intersect/overlap, false otherwise
        Throws:
        IllegalArgumentException - if geometry1 or geometry2 are null
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent or null
        Since:
        100.0.0
      • distanceGeodetic

        public static GeodeticDistanceResult distanceGeodetic​(Point point1,
                                                              Point point2,
                                                              LinearUnit distanceUnit,
                                                              AngularUnit azimuthUnit,
                                                              GeodeticCurveType curveType)
        Calculates the distance between two Points, returning the result in the given linear unit of measurement. The distance is calculated by accounting for the curvature of the earth's surface, using the given geodetic curve type. Use this method as an alternative to the distanceBetween(Geometry, Geometry) method for points that have a geographic spatial reference. The returned result includes additional information about the azimuths between the input points, in the given angular units.
        Parameters:
        point1 - the Point to calculate distance from
        point2 - the Point to calculate distance to
        distanceUnit - the linear unit of measurement for the returned result
        azimuthUnit - the angular unit of measurement for the returned result
        curveType - the type of geodetic curve between the two points to use to calculate distance
        Returns:
        the calculated geodetic distance, and other information resulting from the measurement
        Throws:
        IllegalArgumentException - if any of the arguments is null
        ArcGISRuntimeException - if point1 and point2 have different spatial references
        Since:
        100.0.0
      • moveGeodetic

        public static List<Point> moveGeodetic​(List<Point> points,
                                               double distance,
                                               LinearUnit distanceUnit,
                                               double azimuth,
                                               AngularUnit azimuthUnit,
                                               GeodeticCurveType curveType)
        Returns a List of Points, moved by the given distance at the given azimuth (angle) from the given input List of Points. The distance is calculated by accounting for the curvature of the earth's surface, using the given geodetic curve type.

        Each Point must have the same SpatialReference. The returned unmodifiable collection is in the same order as the input, but with new Points at their destination locations.

        Parameters:
        points - the points to use as the starting locations for the returned points
        distance - the distance to move the points
        distanceUnit - the unit of measure of distance. If null, LinearUnitId.METERS will be used.
        azimuth - the azimuth (angle) of the direction of movement
        azimuthUnit - the angular unit of measure of azimuth. If null, AngularUnitId.DEGREES will be used.
        curveType - the type of geodetic curve to move the points along
        Returns:
        an unmodifiable List of new Points, moved by the given distance from the input points
        Throws:
        IllegalArgumentException - if points or curveType is null
        ArcGISRuntimeException - if the spatial references of the input points are inconsistent or null
        Since:
        100.0.0
      • moveGeodetic

        public static Point moveGeodetic​(Point point,
                                         double distance,
                                         LinearUnit distanceUnit,
                                         double azimuth,
                                         AngularUnit azimuthUnit,
                                         GeodeticCurveType curveType)
        Returns a new Point, moved by the given distance at the given azimuth (angle) from the given input Point. The distance is calculated by accounting for the curvature of the earth's surface, using the given geodetic curve type.
        Parameters:
        point - the point to use as starting location for the returned point
        distance - the distance to move the points
        distanceUnit - the unit of measure of distance. If null, LinearUnitId.METERS will be used.
        azimuth - the azimuth (angle) of the direction of movement
        azimuthUnit - the angular unit of measure of azimuth. If null, AngularUnitId.DEGREES will be used.
        curveType - the type of geodetic curve to move the point along
        Returns:
        a new Point moved by the given distance from the input point
        Throws:
        IllegalArgumentException - if point or curveType is null
        ArcGISRuntimeException - if point spatial reference is null
        Since:
        100.0.0
      • ellipseGeodesic

        public static Geometry ellipseGeodesic​(GeodesicEllipseParameters parameters)
        Calculates a geodesic ellipse (or geodesic circle, if semiAxis1Length = semiAxis2Length) centered on a specific point. If this method is used to generate a polygon or a polyline, the result may have more than one part depending on the size of the ellipse and its position relative to the horizon of the coordinate system. When the method generates a polyline or a multipoint, the result vertices lie on the boundary of the ellipse. When a polygon is generated, the interior of the polygon is the interior of the ellipse.

        If the smaller axis is zero, the ellipse will degenerate to a line segment, a point, or an empty geometry (depending on the larger axis and output type). Otherwise, if GeodesicEllipseParameters.getMaxPointCount() < 10, the number of vertices will default to 10.

        Parameters:
        parameters - various options needed to construct the ellipse
        Returns:
        a geodesic ellipse centered on a specific point
        Throws:
        IllegalArgumentException - if parameters is null
        IllegalArgumentException - if the GeodesicEllipseParameters.getGeometryType() is not one of GeometryType.MULTIPOINT, GeometryType.POLYLINE, GeometryType.POLYGON
        ArcGISRuntimeException - if parameters is not valid
        Since:
        100.0.0
      • extend

        public static Polyline extend​(Polyline polyline,
                                      Polyline extender,
                                      ExtendOptions... extendOptions)
        Extends a polyline using a polyline as the extender.

        The output polyline will have the first and last segment of each path extended to the extender if the segments can be interpolated to intersect the extender. In the case that the segments can be extended to multiple segments of the extender, the shortest extension is chosen. Only end points for paths that are not shared by the end points of other paths will be extended.

        Parameters:
        polyline - the polyline to be extended
        extender - the polyline to extend to
        extendOptions - an array or sequence of one or more ExtendOptions, indicating the type of extend operation to perform
        Returns:
        the extended polyline, or null if polyline cannot be extended by extender
        Throws:
        IllegalArgumentException - if polyline, extender or extendOptions is null, or extendOptions is empty
        IllegalArgumentException - if multiple extendOptions are passed and they contain values that are incompatible with each other
        Since:
        100.1.0
      • generalize

        public static Geometry generalize​(Geometry geometry,
                                          double maxDeviation,
                                          boolean removeDegenerateParts)
        Generalizes the given geometry by removing vertices, based on the Douglas-Peucker algorithm. Point and Multipoint geometries cannot be generalized.
        Parameters:
        geometry - geometry to generalize
        maxDeviation - the maximum distance that the generalized geometry can deviate from the original, in the same units as the geometry's spatial reference system
        removeDegenerateParts - if true, degenerate parts of the resulting geometry that are undesired for drawing will be removed
        Returns:
        geometry that represents the generalization of the input geometry
        Throws:
        IllegalArgumentException - if geometry is null
        Since:
        100.0.0
      • intersection

        public static Geometry intersection​(Geometry geometry1,
                                            Geometry geometry2)
        Calculates the intersection of two geometries.

        The result has the same dimensionality as the lower dimensionality of the two intersecting geometries. Returns an empty geometry if there is no intersection with this dimensionality. For example, the intersection of two polygons (geometries with area, so they have dimensionality of 2) or, say, a polygon and an envelope (also an area) is a polygon. Similarly, the intersection of a polyline (a line, so dimensionality of 1) and another polyline is always a polyline. Therefore when computing the intersection of polylines, this function does not return points where they cross, but rather lines of overlap. If there are no lines of overlap, an empty polyline is returned even if the input lines cross. To obtain all intersections, irrespective of dimensionality, see intersections(Geometry, Geometry).

        Parameters:
        geometry1 - first geometry
        geometry2 - second geometry
        Returns:
        geometry object that represents the intersection of the given geometries
        Throws:
        NullPointerException - if geometry1 or geometry2 is null
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent or null
        Since:
        100.0.0
      • intersections

        public static List<Geometry> intersections​(Geometry geometry1,
                                                   Geometry geometry2)
        Calculates the intersections of two geometries.

        The returned list contains one geometry of each dimension for which there are intersections. For example, if both inputs are polylines, the list will contain at most two geometries: the first a multipoint containing the points at which the lines cross, and the second a polyline containing the lines of overlap. If a crossing point lies within a line of overlap, only the line of overlap is present - the result set is not self-intersecting. If there are no crossing points or there are no lines of overlap, the respective geometry will not be present in the list. If the input geometries do not intersect, the list will be empty. The table below shows, for each combination of pairs of input geometry types, the types of geometry that will be contained within the list if there are intersections of that type.

        Set of potential output geometry types for pairs of input geometry types:
        Input type Point/Multipoint Polyline Polygon/Envelope
        Point/Multipoint Multipoint Multipoint Multipoint
        Polyline Multipoint Multipoint, Polyline Multipoint, Polyline
        Polygon/Envelope Multipoint Multipoint, Polyline Multipoint, Polyline, Polygon

        The geometries in the returned list are sorted by ascending dimensionality, for example multipoint (dimension 0) then polyline (dimension 1) then polygon (dimension 2) for the intersection of two geometries with area that have intersections of those types.

        Parameters:
        geometry1 - first geometry
        geometry2 - second geometry
        Returns:
        an unmodifiable list containing geometry objects that represent the intersection of the given geometries
        Throws:
        IllegalArgumentException - if geometry1 or geometry2 is null
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent or null
        Since:
        100.1.0
      • intersects

        public static boolean intersects​(Geometry geometry1,
                                         Geometry geometry2)
        Tests if two geometries intersect.
        Parameters:
        geometry1 - first geometry
        geometry2 - second geometry
        Returns:
        true if the two geometries intersect, false otherwise
        Throws:
        NullPointerException - if geometry1 or geometry2 is null
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent or null
        Since:
        100.0.0
      • labelPoint

        public static Point labelPoint​(Polygon polygon)
        Calculates an interior point for the given polygon. This point can be used by clients to place a label for the polygon.
        Parameters:
        polygon - polygon to calculate the interior point of
        Returns:
        a point that represents the interior point for the given polygon
        Throws:
        IllegalArgumentException - if polygon is null
        Since:
        100.0.0
      • length

        public static double length​(Polyline polyline)
        Calculates the length of the given polyline. This is a planar measurement using 2D Cartesian mathematics to compute the length. Use lengthGeodetic(Geometry, LinearUnit, GeodeticCurveType) for geodetic measurement.

        This length calculation is based upon the SpatialReference of the input geometry. Although some projections are better than others for preserving distance, it will always be distorted in some areas of the map. Distortion may be negligible for large scale maps (small areas) that use a suitable map projection. Make sure you know your data and spatial reference if accurate measurements are required. For more accurate results, consider using the lengthGeodetic(Geometry, LinearUnit, GeodeticCurveType) operation.

        Parameters:
        polyline - polyline to calculate the length of
        Returns:
        the length of the given geometry in the same units as the polyline's spatial reference
        Throws:
        NullPointerException - if polyline is null
        Since:
        100.0.0
      • lengthGeodetic

        public static double lengthGeodetic​(Geometry geometry,
                                            LinearUnit lengthUnit,
                                            GeodeticCurveType curveType)
        Calculates the geodetic length of the geometry. Geodesic length is calculated using only the vertices of the geometry and defines the lines between vertices as geodesic segments independent of the actual shape of the geometry. A geodesic segment is the shortest path between two points on an ellipsoid.
        Parameters:
        geometry - geometry to calculate the geodetic length of
        lengthUnit - unit of measure for the return value. If null, defaults to linear unit of Id LinearUnitId.METERS
        curveType - geodetic curve type to calculate the length
        Returns:
        the geodetic length of the given geometry
        Throws:
        IllegalArgumentException - if geometry or curveType is null
        ArcGISRuntimeException - if the spatial reference of geometry is null
        Since:
        100.0.0
      • nearestCoordinate

        public static ProximityResult nearestCoordinate​(Geometry geometry,
                                                        Point point)
        Finds the nearest coordinate in the given geometry to the given point.

        If the specified geometry is a polyline or polygon, the nearest coordinate is the closest point on or along the line segment that comprises the geometry; it may not necessarily be the closest vertex of the line segment. If you want to obtain the closest vertex in the polyline or polygon use the nearestVertex(Geometry, Point) method instead.

        Parameters:
        geometry - geometry on which to find the nearest coordinate. Envelope is not supported
        point - point to calculate the nearest coordinate from
        Returns:
        result containing the nearest coordinate
        Throws:
        IllegalArgumentException - if geometry or point is null
        IllegalArgumentException - if geometry is of type Envelope
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent or null
        Since:
        100.0.0
      • nearestVertex

        public static ProximityResult nearestVertex​(Geometry geometry,
                                                    Point point)
        Finds the nearest vertex in the given geometry to the given point.

        If the specified geometry is a polyline or polygon, the nearest vertex is the closest end point of the line segment that comprises the geometry; it may not necessarily be the closest point along the line segment. If you want to obtain the closest point in the polyline or polygon use the nearestCoordinate(Geometry, Point) method instead.

        Parameters:
        geometry - geometry on which to find the nearest vertex. Envelope is not supported
        point - point to calculate the nearest vertex from
        Returns:
        result containing the nearest vertex
        Throws:
        IllegalArgumentException - if geometry or point is null
        IllegalArgumentException - if geometry is of type Envelope
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent or null
        Since:
        100.0.0
      • normalizeCentralMeridian

        public static Geometry normalizeCentralMeridian​(Geometry geometry)
        Returns a copy of the input geometry that does not intersect the antimeridian. You may wish to use this method to normalize geometries before passing them to methods that require coordinates within the spatial reference domain, for example geodatabase editing methods or geocoding services.

        The returned geometry may have multiple parts, in order to ensure each part does not intersect the antimeridian. The returned geometry is the same type as the input geometry, except in the case of an Envelope in which case the returned geometry is a Polygon.

        Parameters:
        geometry - the geometry to be normalized
        Returns:
        the normalized geometry
        Throws:
        NullPointerException - if geometry is null
        Since:
        100.0.0
      • offset

        public static Geometry offset​(Geometry geometry,
                                      double distance,
                                      GeometryOffsetType offsetType,
                                      double bevelRatio,
                                      double flattenError)
        Creates an offset version of the input geometry.

        The offset operation creates a geometry that is a constant distance from the input geometry. It is similar to buffering, but produces a one sided result. If offset distance is greater than 0, then the offset geometry is constructed to the right of the oriented input geometry, otherwise it is constructed to the left. For a simple polygon, the orientation of outer rings is clockwise and for inner rings it is counterclockwise. So the "right side" of a simple polygon is always its inside. The bevelRatio is multiplied by the offset distance and the result determines how far a mitered offset intersection can be from the input curve before it is beveled.

        Parameters:
        geometry - geometry to create the offset from
        distance - offset distance for the geometry result. If distance is greater than 0, then the offset geometry is constructed to the right of the input geometry, otherwise it is constructed to the left
        offsetType - offset type of the geometry result
        bevelRatio - the ratio used to produce a bevel join instead of a miter join (used only when the offset type is GeometryOffsetType.MITERED)
        flattenError - the maximum distance of the resulting segments compared to the true circular arc (used only when the offset type is GeometryOffsetType.ROUNDED). The algorithm never produces more than around 180 vertices for each round join.
        Returns:
        an offset version of the input geometry
        Throws:
        IllegalArgumentException - if geometry or offsetType is null
        Since:
        100.0.0
      • overlaps

        public static boolean overlaps​(Geometry geometry1,
                                       Geometry geometry2)
        Tests if two geometries overlap.
        Parameters:
        geometry1 - one of the two geometries
        geometry2 - the other geometry
        Returns:
        true if the two geometries overlap, false otherwise
        Throws:
        IllegalArgumentException - if geometry1 or geometry2 is null
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent or null
        Since:
        100.0.0
      • project

        public static Geometry project​(Geometry geometry,
                                       SpatialReference spatialReference)
        Projects the given geometry from its current spatial reference into the given spatial reference, using the default geographic transformation. If the given geometry has a null spatial reference, no projection occurs; instead, a copy of the geometry with the given spatialReference is returned.

        You can use the TransformationCatalog.getTransformation(SpatialReference, SpatialReference) method to find out which transformation is used by default for the given spatial references.

        For more information about geographic transformations, see the Spatial references topic in the developer Guide.

        Parameters:
        geometry - geometry to project
        spatialReference - spatial reference to project geometry to
        Returns:
        geometry projected into the given spatial reference
        Throws:
        NullPointerException - if geometry or spatialReference is null
        Since:
        100.0.0
      • project

        public static Geometry project​(Geometry geometry,
                                       SpatialReference spatialReference,
                                       DatumTransformation datumTransformation)
        Projects the given geometry from its current spatial reference into the given spatial reference using the given datum transformation. Use this method to project geometries when the default transformation is not appropriate for your requirements.
         // Create a geometry located in London, UK, with British National Grid spatial reference
         Point britishNationalGridPt = new Point(538985.355, 177329.516, SpatialReference.create(27700));
         // Create a GeographicTransformation with a single step using WKID for OSGB_1936_To_WGS_1984_NGA_7PAR transformation
         GeographicTransformation transform = GeographicTransformation.create(GeographicTransformationStep.create(108336));
         // Project the point to WGS84, using the transformation
         Point wgs84Pt = (Point) GeometryEngine.project(britishNationalGridPt, SpatialReferences.getWgs84(), transform);
         
        Parameters:
        geometry - the geometry to project
        spatialReference - the spatial reference to project geometry to
        datumTransformation - the datum transformation to apply to the projection; if null, then the default transformation is used
        Returns:
        a geometry projected into the given spatial reference
        Throws:
        IllegalArgumentException - if geometry or spatialReference is null
        ArcGISRuntimeException - if the datumTransformation's DatumTransformation.isMissingProjectionEngineFiles() method returns true
        Since:
        100.2.0
      • relate

        public static boolean relate​(Geometry geometry1,
                                     Geometry geometry2,
                                     String relation)
        Compares the spatial relationship of two geometries. Can compare interior, boundary and exterior of two geometries based on a DE-9IM encoded string.
        Parameters:
        geometry1 - one of the two geometries
        geometry2 - the other geometry
        relation - the DE-9IM string to be evaluated. Strings such as "T*****FF*" are accepted.
        Returns:
        true if the two geometries are related by the given relation, false otherwise
        Throws:
        IllegalArgumentException - if geometry1 or geometry2 is null
        IllegalArgumentException - if relation is null or empty
        ArcGISRuntimeException - if relation is not valid
        Since:
        100.0.0
      • removeM

        public static Geometry removeM​(Geometry geometry)
        Creates a copy of a geometry with its m-values removed. If the given geometry has no m-values, the given geometry itself is returned. The resulting geometry will have Geometry.hasM() false.
        Parameters:
        geometry - the input geometry
        Returns:
        a copy of the input geometry with its m-values removed, or the input geometry itself if it already has no m-values
        Throws:
        IllegalArgumentException - if geometry is null
        Since:
        100.1.0
      • removeZ

        public static Geometry removeZ​(Geometry geometry)
        Creates a copy of a geometry with its z-values removed. If the given geometry has no z-values, the given geometry itself is returned. The resulting geometry will have Geometry.hasZ() false.
        Parameters:
        geometry - the input geometry
        Returns:
        a copy of the input geometry with its z-values removed, or the input geometry itself if it already has no z-values
        Throws:
        IllegalArgumentException - if geometry is null
        Since:
        100.1.0
      • removeZAndM

        public static Geometry removeZAndM​(Geometry geometry)
        Creates a copy of a geometry with its z- and m-values removed. If the given geometry has no z- or m-values, the given geometry itself is returned. The resulting geometry will have Geometry.hasZ() and Geometry.hasM() false.
        Parameters:
        geometry - the input geometry
        Returns:
        a copy of the input geometry with its z- and m-values removed, or the input geometry itself if it already has no z- or m-values
        Throws:
        IllegalArgumentException - if geometry is null
        Since:
        100.1.0
      • reshape

        public static Multipart reshape​(Multipart geometry,
                                        Polyline reshaper)
        Reshapes a polygon or polyline using a single path polyline as the reshaper. The output geometry takes the shape of the input geometry where it first intersects the reshaper to the last intersection. The first and last intersection points of the reshaper are chosen closest to the end points of the reshaper in the case that multiple intersections are found. For polygons, only individual paths can be reshaped. However, polylines can be reshaped across paths.
        Parameters:
        geometry - the polygon or polyline to be reshaped
        reshaper - the single path polyline reshaper
        Returns:
        the reshaped polygon or polyline, or null if the input geometry cannot be reshaped by the reshaper
        Throws:
        IllegalArgumentException - if geometry or reshaper is null
        Since:
        100.1.0
      • sectorGeodesic

        public static Geometry sectorGeodesic​(GeodesicSectorParameters parameters)
        Creates a sector as a polygon, polyline or multipoint geometry. A geodesic sector is defined by a geodesic elliptical arc and two radii extending from the center point of the arc to the points where they each intersect the arc. The arc is a portion of an ellipse. The ellipse is defined by a center point, the lengths of its semi-major and semi-minor axes, and the direction of its semi-major axis. The first radius of the sector is defined by the start direction angle relative to the direction of the semi-major axis. The second radius is the sum of the start direction and the sector angle.
        Parameters:
        parameters - options for constructing the sector
        Returns:
        a geometry representing the geodesic sector
        Throws:
        IllegalArgumentException - if parameters is null
        IllegalArgumentException - if the GeodesicEllipseParameters.getGeometryType() is not one of GeometryType.MULTIPOINT, GeometryType.POLYLINE, GeometryType.POLYGON
        ArcGISRuntimeException - if parameters is not valid
        Since:
        100.0.0
      • setM

        public static Geometry setM​(Geometry geometry,
                                    double m)
        Creates a copy of a geometry with its m-values set to the given value. If the given geometry already has m-values, they will be replaced within the resulting geometry by the given m-value. The resulting geometry will have Geometry.hasM() true.
        Parameters:
        geometry - the input geometry
        m - the m-value to set
        Returns:
        a copy of the input geometry with its m-values set to the given value
        Throws:
        IllegalArgumentException - if geometry is null
        Since:
        100.1.0
      • setZ

        public static Geometry setZ​(Geometry geometry,
                                    double z)
        Creates a copy of a geometry with its z-values set to the given value. If the given geometry already has z-values, they will be replaced within the resulting geometry by the given z-value. The resulting geometry will have Geometry.hasZ() true.
        Parameters:
        geometry - the input geometry
        z - the z-value to set
        Returns:
        a copy of the input geometry with its z-values set to the given value
        Throws:
        IllegalArgumentException - if geometry is null
        Since:
        100.1.0
      • setZAndM

        public static Geometry setZAndM​(Geometry geometry,
                                        double z,
                                        double m)
        Creates a copy of a geometry with its z- and m-values set to the given values. If the given geometry already has z- or m-values, they will be replaced within the resulting geometry by the given values. The resulting geometry will have Geometry.hasZ() and Geometry.hasM() true.
        Parameters:
        geometry - the input geometry
        z - the z-value to set
        m - the m-value to set
        Returns:
        a copy of the input geometry with its z- and m-values set to the given values
        Throws:
        IllegalArgumentException - if geometry is null
        Since:
        100.1.0
      • simplify

        public static Geometry simplify​(Geometry geometry)
        Simplifies the given geometry to make it topologically consistent according to its geometry type. For instance, it rectifies polygons that may be self-intersecting, or contain incorrect ring orientations.

        Many of the methods in the geometry engine only work on geometry that is simple, and only simple geometries can be stored in a geodatabase.

        Parameters:
        geometry - geometry to simplify
        Returns:
        simplified geometry
        Throws:
        NullPointerException - if geometry is null
        Since:
        100.0.0
      • symmetricDifference

        public static Geometry symmetricDifference​(Geometry geometry1,
                                                   Geometry geometry2)
        Calculates the symmetric difference (exclusive or) of the two geometries.
        Parameters:
        geometry1 - one of the two geometries
        geometry2 - the other geometry
        Returns:
        the symmetric difference of the two geometries
        Throws:
        IllegalArgumentException - if geometry1 or geometry2 is null
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent or null
        Since:
        100.0.0
      • touches

        public static boolean touches​(Geometry geometry1,
                                      Geometry geometry2)
        Test if the two geometries touch on their borders.
        Parameters:
        geometry1 - does this geometry touch geometry2?
        geometry2 - does this geometry touch geometry1?
        Returns:
        true if the two geometries have at least one boundary point in common, but no interior points. False otherwise.
        Throws:
        NullPointerException - if geometry1 or geometry2 is null
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent or null
        Since:
        100.0.0
      • union

        public static Geometry union​(Geometry geometry1,
                                     Geometry geometry2)
        Calculates the union of the two geometries.

        Returns those parts of the two input geometries which overlap, combined into a single geometry. This means that the order of the input parameters of the GeometryEngine.Intersection is irrelevant. Think of the union equation as:

        A (Union) B = C
        B (Union) A = C

        Parameters:
        geometry1 - first geometry
        geometry2 - second geometry
        Returns:
        the union of the two geometries
        Throws:
        NullPointerException - if geometry1 or geometry2 is null
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent or null
        Since:
        100.0.0
      • union

        public static Geometry union​(Iterable<Geometry> geometries)
        Calculates the union of a collection of geometries.

        If the collection contains geometries of differing dimensionality, returns the union of the subset of geometries with the highest dimensionality. For example, given a collection of polygons, polylines and points, returns the union of the polygons.

        The input geometries must have consistent spatial references.

        Parameters:
        geometries - the input geometries
        Returns:
        the union of the input geometries
        Throws:
        IllegalArgumentException - if geometries is null or empty
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent
        Since:
        100.1.0
      • within

        public static boolean within​(Geometry within,
                                     Geometry container)
        Tests if within is within container.
        Parameters:
        within - geometry that is tested for the "within" relationship to container
        container - geometry that is tested for the "contains" relationship to within
        Returns:
        true if within lies in the interior of the container, false otherwise. The boundary and interior of within is not allowed to intersect the exterior of the container and within may not equal the container.
        Throws:
        NullPointerException - if within or container is null
        ArcGISRuntimeException - if the spatial references of the input geometries are inconsistent or null
        Since:
        100.0.0
      • clip

        public static Geometry clip​(Geometry geometry,
                                    Envelope envelope)
        Returns a geometry created by clipping the given Geometry with the given Envelope. If no part of the Geometry lies within the Envelope, then the returned Geometry will be empty.
        Parameters:
        geometry - the geometry to be clipped by the given envelope
        envelope - the extent at which to clip the given geometry
        Returns:
        the clipped geometry
        Throws:
        IllegalArgumentException - if geometry or envelope is null
        ArcGISRuntimeException - if geometry and envelope arguments have different spatial references
        Since:
        100.0.0
        See Also:
        intersection(Geometry, Geometry)
      • isSimple

        public static boolean isSimple​(Geometry geometry)
        Indicates if this Geometry is topologically simple (in other words, is topologically correct).

        Point geometries are always simple.

        Multipoint geometries cannot have any points with exactly equal x and y values.

        Polylines can have no degenerate segments.

        For Polygons, the following must be true for the polygon to be considered simple:

        • Exterior rings must be clockwise, and holes must be counterclockwise.
        • Rings can touch other rings only at a finite number of vertices.
        • Rings can be self tangent only at a finite number of vertices.
        • Segments with a length less than zero are not allowed.
        • Each path must contain at least three non-coincident vertices.
        • Paths must not be empty.
        Parameters:
        geometry - the geometry to be tested if it is simple
        Returns:
        true if the provided geometry is simple, false otherwise
        Throws:
        IllegalArgumentException - if the geometry is null
        Since:
        100.0.0
      • createPointAlong

        public static Point createPointAlong​(Polyline polyline,
                                             double distance)
        Calculates the point at a given distance along a line.

        If the distance is less than or equal to zero, the point returned is coincident with the start of the line. If the distance is greater than or equal to the line's length, the point returned is coincident with the end of the line. If the line has multiple parts (notes: the gap does not count as part of line, it is ignored), and the distance falls exactly on a boundary between two parts, the returned point will be coincident with either the end of one part or the start of the next – which is undetermined.

        As an example to illustrate the returned point you expect to obtain, suppose that you have a polyline with two parts, one is from [0, 0] to [10, 0], the other from [30, 0] to [50, 0], here is the table for the returned point at a given distance:

        Distance Point returned Comments
        0 [0, 0] Start of part 0
        5 [5, 0] Midpoint of part 0
        10 [10, 0] End of part 0
        10 [30, 0] OR start of part 1
        20 [40, 0] Midpoint of part 1
        30 [50, 0] end of part 1
        Parameters:
        polyline - the polyline from which the point is created
        distance - the distance along the polyline, in the units of the polyline, where to create the point
        Returns:
        the point at the given distance along the line
        Throws:
        IllegalArgumentException - if polyline is null
        Since:
        100.3.0