Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.geometry

Class Geometry

java.lang.Object
com.esri.arcgisruntime.geometry.Geometry
All Implemented Interfaces:
JsonSerializable
Direct Known Subclasses:
Envelope, Multipart, Multipoint, Point
public abstract class Geometry extends Object implements JsonSerializable
Base class for all classes that represent geometric shapes.

Geometry is the base class for two-dimensional (x,y) and three-dimensional (x,y,z) geometries, such as Point, Multipoint, Polyline, Polygon, and Envelope. It represents real-world objects by defining a shape at a specific geographic location, and is used throughout the API to represent the shapes of features and graphics, layer extents, viewpoints, and GPS locations. It is also used to define the inputs and outputs for spatial analysis and geoprocessing operations, and to measure distances and areas.

All types of geometry have the following characteristics:

  • A SpatialReference indicating the coordinate system used by its coordinates.
  • Can be empty, indicating that they have no specific location or shape.
  • May have z-values and/or m-values to define elevation and measures, respectively.
  • Can be converted to and from JSON to be persisted or to be exchanged directly with REST services.

Immutability

Most geometries are created and not changed for their lifetime. Examples include features created to be stored in a geodatabase or read from a non-editable layer, and features returned from tasks such as a spatial query, geocode operation, network trace, or geoprocessing task. Immutable geometries (geometries that cannot be changed) offer important benefits to your app. They are inherently thread-safe, help prevent inadvertent changes, and allow for certain performance optimizations.

If you want to modify the shape of a Geometry there are two options available:

  • GeometryBuilder. Use a geometry builder if you want to incrementally reshape a geometry. If you want to reshape a Polygon, for example, then pass the polygon to a PolygonBuilder. The polygon builder copies the polygon and provides methods to add, update, and delete the polygon parts and segment vertices. The geometry builder represents the state of a geometry under modification, and you can obtain it at any time using GeometryBuilder.toGeometry().
  • GeometryEditor. Use a geometry editor if you want to allow the user to interactively modify an existing geometry. Start the GeometryEditor by passing the geometry to GeometryEditor.start(Geometry). The start method signals to the geometry editor to start capturing user interaction with the map through mouse or touch gestures.

Note that the GeometryEngine offers a range of topological and spatial transformations that can create a new geometry from an existing geometry. The GeometryEngine allows you to perform actions on an existing geometry, such as a buffer, cut, clip, densify, or project, to produce a new output geometry. See GeometryEngine to explore various supported geometric operations.

Coordinate units

The coordinates that define a geometry are only meaningful in the context of the geometry's SpatialReference. The vertices and spatial reference together allow your app to translate a real-world object from its location on the Earth to its location on your map or scene.

In some cases, a geometry's spatial reference may not be set. For example, a Graphic that does not have a spatial reference is drawn using the same spatial reference as the GeoView to which it was added. If the coordinates are in a different spatial reference, the graphics may not display in the correction location, or at all.

When using GeometryBuilder to create a Polyline or Polygon from a collection of Point, you don't need to set the spatial reference of every point before you add it to the builder, as it will be assigned the spatial reference of the builder itself. In most other cases, such as when using a geometry in geometry operations or when editing a feature table, getSpatialReference() must return a valid spatial reference.

Spatial reference and projection

Changing the coordinates of a geometry to have the same shape and location represented using a different SpatialReference is known as "projection" or sometimes as "reprojection". Because geometries are immutable, they do not have any member methods that project, transform, or otherwise modify their content.

Since:
100.0.0
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    Geometry()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    equals(Geometry geometry, double tolerance)
    Checks if two geometries are approximately the same within the given tolerance.
    boolean
    equals(Object obj)
    Checks if two geometries are exactly equal.
    static Geometry
    fromJson(String json)
    Creates a new Geometry from an ArcGIS JSON geometry representation.
    static Geometry
    fromJson(String json, SpatialReference spatialReference)
    Creates a new Geometry from an ArcGIS JSON geometry representation, and the given SpatialReference.
    GeometryDimension
    getDimension()
    Gets the dimensionality of a Geometry, relating to the number of spatial dimensions in which the geometry may have a size.
    Envelope
    getExtent()
    The minimum enclosing bounding-box (or Envelope) that covers the geometry.
    GeometryType
    getGeometryType()
    Gets the type of this Geometry, indicating the subclass, and the type of geometrical shape it can represent.
    SpatialReference
    getSpatialReference()
    The spatial reference for this geometry.
    Map<String,Object>
    getUnknownJson()
    A Geometry never has any unknown JSON so this returns an empty Map.
    Map<String,Object>
    getUnsupportedJson()
    A Geometry never has any unsupported JSON so this returns an empty Map.
    boolean
    hasCurves()
    True if this geometry contains curve segments, false otherwise.
    int
    hashCode()
    Generates a hash value from the Geometry.
    boolean
    hasM()
    True if the geometry has m values (measure values), false otherwise.
    boolean
    hasZ()
    True if the geometry has z-coordinate values, false otherwise.
    boolean
    isEmpty()
    True if the geometry is empty, false otherwise.
    String
    toJson()
    Returns an ArcGIS JSON geometry representation of this Geometry.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Geometry

      public Geometry()

  • Method Details

    • fromJson

      public static Geometry fromJson(String json)
      Creates a new Geometry from an ArcGIS JSON geometry representation.

      See the ArcGIS REST API help topic on Geometry objects for more information.

      Parameters:
      json - a string containing an ArcGIS JSON representation of a geometry
      Returns:
      a new Geometry constructed from the json string, or null if a geometry couldn't be constructed
      Throws:
      IllegalArgumentException - if json is null or empty
      Since:
      100.0.0

    • fromJson

      public static Geometry fromJson(String json, SpatialReference spatialReference)
      Creates a new Geometry from an ArcGIS JSON geometry representation, and the given SpatialReference.

      Geometry can be serialized and de-serialized to and from JSON. The ArcGIS REST API documentation describes the JSON representation of geometry objects. You can use this encoding and decoding mechanism to exchange geometries with REST Web services or to store them in text files.

      Any SpatialReference defined in the JSON representation will be ignored in favor of the spatialReference parameter of this method.

      Parameters:
      json - a string containing an ArcGIS JSON representation of a geometry
      spatialReference - a SpatialReference to assign to the new geometry
      Returns:
      a new Geometry constructed from the json string, or null if a geometry couldn't be constructed
      Throws:
      IllegalArgumentException - if json is null or empty
      Since:
      100.0.0

    • getSpatialReference

      public SpatialReference getSpatialReference()
      The spatial reference for this geometry.

      This can be null if the geometry is not associated with a SpatialReference.

      Returns:
      the SpatialReference of this Geometry
      Since:
      100.0.0

    • getDimension

      public GeometryDimension getDimension()
      Gets the dimensionality of a Geometry, relating to the number of spatial dimensions in which the geometry may have a size.

      You can use Geometry.getDimension() to work out what kind of symbol can be applied to a specific type of geometry. For example, Point and Multipoint are both zero-dimensional point geometries, and both can be displayed using a type of MarkerSymbol. Polygon and Envelope are both 2-dimensional area geometries that can be displayed using a type of FillSymbol.

      Returns GeometryDimension.UNKNOWN if an error occurs.

      Returns:
      the dimension of this Geometry
      Since:
      100.0.0

    • getExtent

      public Envelope getExtent()
      The minimum enclosing bounding-box (or Envelope) that covers the geometry.
      Returns:
      the extent of this Geometry
      Since:
      100.0.0

    • getGeometryType

      public GeometryType getGeometryType()
      Gets the type of this Geometry, indicating the subclass, and the type of geometrical shape it can represent.
      Returns:
      the type of this Geometry
      Since:
      100.0.0

    • hasM

      public boolean hasM()
      True if the geometry has m values (measure values), false otherwise.

      M is a vertex value that is stored with the geometry. These values typically represent non-spatial measurements or attributes.

      Returns:
      true if this Geometry has m values; false otherwise
      Since:
      100.0.0
      See Also:

    • hasZ

      public boolean hasZ()
      True if the geometry has z-coordinate values, false otherwise.

      Only 3D geometries contain z-coordinate values. These values typically represent elevation, height, or depth.

      Returns:
      true if this Geometry has z values; false otherwise
      Since:
      100.0.0
      See Also:

    • hasCurves

      public boolean hasCurves()
      True if this geometry contains curve segments, false otherwise.

      ArcGIS software supports polygon and polyline geometries that contain curve segments (where Segment.isCurve() is true, sometimes known as true curves or nonlinear segments). Curves may be present in certain types of data, such as Mobile Map Packages (MMPK) or geometry JSON. When connecting to ArcGIS feature services that support curves (see ArcGISFeatureServiceInfo.isSupportsTrueCurve()), this API retrieves densified versions of curve feature geometries by default.

      If a polygon or polyline geometry contains curve segments, this property returns true. You can use curve segments when using a MultipartBuilder to create or edit polygon and polyline geometries, and also get curve segments when iterating through the segments of existing Multipart geometries when this property returns true. You can also choose to return true curves from feature services by using ArcGISRuntimeEnvironment.getServiceCurveGeometryMode().

      Returns:
      true if this Geometry contains curved segments; false otherwise
      Since:
      100.0.0
      See Also:

    • isEmpty

      public boolean isEmpty()
      True if the geometry is empty, false otherwise.

      A geometry is empty if it does not have valid geographic coordinates, even if the SpatialReference is specified. An empty Geometry is a valid object that has no location in space.

      Returns:
      true if this Geometry is empty; false otherwise
      Since:
      100.0.0

    • toJson

      public String toJson()
      Returns an ArcGIS JSON geometry representation of this Geometry.

      See the ArcGIS REST API help topic on Geometry objects for more information.

      Specified by:
      toJson in interface JsonSerializable
      Returns:
      a string containing the JSON representation of this geometry
      Since:
      100.0.0

    • getUnknownJson

      public Map<String,Object> getUnknownJson()
      A Geometry never has any unknown JSON so this returns an empty Map.
      Specified by:
      getUnknownJson in interface JsonSerializable
      Returns:
      an empty unmodifiable Map
      Since:
      100.0.0

    • getUnsupportedJson

      public Map<String,Object> getUnsupportedJson()
      A Geometry never has any unsupported JSON so this returns an empty Map.
      Specified by:
      getUnsupportedJson in interface JsonSerializable
      Returns:
      an empty unmodifiable Map
      Since:
      100.0.0

    • hashCode

      public int hashCode()
      Generates a hash value from the Geometry.
      Overrides:
      hashCode in class Object
      Returns:
      a hash value based on the current Geometry
      Since:
      100.0.0

    • equals

      public boolean equals(Object obj)
      Checks if two geometries are exactly equal. The types of geometry, order of points, all values, and the SpatialReference must all be equal.

      This method provides a strict comparison of two geometries to ensure that they are identical. For a slightly more relaxed comparison (one that does not take coordinate order into account), use GeometryEngine.equals(Geometry, Geometry).

      Overrides:
      equals in class Object
      Parameters:
      obj - the second geometry
      Returns:
      true if the comparison succeeds and the objects are equal, false otherwise

    • equals

      public boolean equals(Geometry geometry, double tolerance)
      Checks if two geometries are approximately the same within the given tolerance.

      This function performs a lightweight comparison of two geometries that might be useful when writing test code. It uses the tolerance to compare each of x, y, and any other values the geometries possess (such as z or m) independently in the manner: abs(value1 - value2) <= tolerance. The single tolerance value is used even if the x, y, z or m units differ. This function does not respect modular arithmetic of spatial references which wrap around, so longitudes of -180 and +180 degrees are considered to differ by 360 degrees.

      Returns true if the difference of each is within the tolerance and all other properties of the geometries are exactly equal (such as spatial reference and vertex count). Returns false if an error occurs.

      For topological equality, use a relational operator such as GeometryEngine.equals(Geometry, Geometry).

      Parameters:
      geometry - the geometry to check
      tolerance - the tolerance
      Returns:
      true if the geometries are equal, within the tolerance, otherwise false
      Since:
      100.1.0
      See Also: