Package com.mapbox.geojson

Class Polygon

  • All Implemented Interfaces:
    CoordinateContainer<java.util.List<java.util.List<Point>>>, GeoJson, Geometry, java.io.Serializable
    public final class Polygon
extends java.lang.Object
implements CoordinateContainer<java.util.List<java.util.List<Point>>>
    This class represents a GeoJson Polygon which may or may not include polygon holes.

    To specify a constraint specific to Polygons, it is useful to introduce the concept of a linear ring:

    • A linear ring is a closed LineString with four or more coordinates.
    • The first and last coordinates are equivalent, and they MUST contain identical values; their representation SHOULD also be identical.
    • A linear ring is the boundary of a surface or the boundary of a hole in a surface.
    • A linear ring MUST follow the right-hand rule with respect to the area it bounds, i.e., exterior rings are counterclockwise, and holes are clockwise.
    Note that most of the rules listed above are checked when a Polygon instance is created (the exception being the last rule). If one of the rules is broken, a RuntimeException will occur.

    Though a linear ring is not explicitly represented as a GeoJson geometry TYPE, it leads to a canonical formulation of the Polygon geometry TYPE. When initializing a new instance of this class, a LineString for the outer and optionally an inner are checked to ensure a valid linear ring.

    An example of a serialized polygon with no holes is given below: 

     {
   "TYPE": "Polygon",
   "coordinates": [
     [[100.0, 0.0],
     [101.0, 0.0],
     [101.0, 1.0],
     [100.0, 1.0],
     [100.0, 0.0]]
   ]
 }
    Since:
    1.0.0
    See Also:
    Serialized Form

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      BoundingBox bbox()
      A Feature Collection might have a member named bbox to include information on the coordinate range for it's Features.
      java.util.List<java.util.List<Point>> coordinates()
      Provides the list of Points that make up the Polygon geometry.
      boolean equals​(java.lang.Object obj)  
      static Polygon fromJson​(java.lang.String json)
      Create a new instance of this class by passing in a formatted valid JSON String.
      static Polygon fromLngLats​(java.util.List<java.util.List<Point>> coordinates)
      Create a new instance of this class by defining a list of Points which follow the correct specifications described in the Point documentation.
      static Polygon fromLngLats​(java.util.List<java.util.List<Point>> coordinates, BoundingBox bbox)
      Create a new instance of this class by defining a list of Points which follow the correct specifications described in the Point documentation.
      static Polygon fromOuterInner​(LineString outer, BoundingBox bbox, LineString... inner)
      Create a new instance of this class by passing in an outer LineString and optionally one or more inner LineStrings.
      static Polygon fromOuterInner​(LineString outer, BoundingBox bbox, java.util.List<LineString> inner)
      Create a new instance of this class by passing in an outer LineString and optionally one or more inner LineStrings contained within a list.
      static Polygon fromOuterInner​(LineString outer, LineString... inner)
      Create a new instance of this class by passing in an outer LineString and optionally one or more inner LineStrings.
      static Polygon fromOuterInner​(LineString outer, java.util.List<LineString> inner)
      Create a new instance of this class by passing in an outer LineString and optionally one or more inner LineStrings contained within a list.
      int hashCode()  
      java.util.List<LineString> inner()
      Convenience method to get a list of inner LineStrings defining holes inside the polygon.
      LineString outer()
      Convenience method to get the outer LineString which defines the outer perimeter of the polygon.
      java.lang.String toJson()
      This takes the currently defined values found inside this instance and converts it to a GeoJson string.
      java.lang.String toString()  
      java.lang.String type()
      This describes the TYPE of GeoJson geometry this object is, thus this will always return Polygon.
      static com.google.gson.TypeAdapter<Polygon> typeAdapter​(com.google.gson.Gson gson)
      Gson TYPE adapter for parsing Gson to this class.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • fromJson

        public static Polygon fromJson​(@NonNull
                               java.lang.String json)
        Create a new instance of this class by passing in a formatted valid JSON String. If you are creating a Polygon object from scratch it is better to use one of the other provided static factory methods such as fromOuterInner(LineString, LineString...). For a valid For a valid Polygon to exist, it must follow the linear ring rules and the first list of coordinates are considered the outer ring by default.
        Parameters:
        json - a formatted valid JSON string defining a GeoJson Polygon
        Returns:
        a new instance of this class defined by the values passed inside this static factory method
        Since:
        1.0.0

      • fromLngLats

        public static Polygon fromLngLats​(@NonNull
                                  java.util.List<java.util.List<Point>> coordinates)
        Create a new instance of this class by defining a list of Points which follow the correct specifications described in the Point documentation. Note that the first and last point in the list should be the same enclosing the linear ring.
        Parameters:
        coordinates - a list of a list of points which represent the polygon geometry
        Returns:
        a new instance of this class defined by the values passed inside this static factory method
        Since:
        3.0.0

      • fromLngLats

        public static Polygon fromLngLats​(@NonNull
                                  java.util.List<java.util.List<Point>> coordinates,
                                  @Nullable
                                  BoundingBox bbox)
        Create a new instance of this class by defining a list of Points which follow the correct specifications described in the Point documentation. Note that the first and last point in the list should be the same enclosing the linear ring.
        Parameters:
        coordinates - a list of a list of points which represent the polygon geometry
        bbox - optionally include a bbox definition as a double array
        Returns:
        a new instance of this class defined by the values passed inside this static factory method
        Since:
        3.0.0

      • fromOuterInner

        public static Polygon fromOuterInner​(@NonNull
                                     LineString outer,
                                     @Nullable
                                     LineString... inner)
        Create a new instance of this class by passing in an outer LineString and optionally one or more inner LineStrings. Each of these LineStrings should follow the linear ring rules.

        Note that if a LineString breaks one of the linear ring rules, a RuntimeException will be thrown.

        Parameters:
        outer - a LineString which defines the outer perimeter of the polygon
        inner - one or more LineStrings representing holes inside the outer perimeter
        Returns:
        a new instance of this class defined by the values passed inside this static factory method
        Since:
        3.0.0

      • fromOuterInner

        public static Polygon fromOuterInner​(@NonNull
                                     LineString outer,
                                     @Nullable
                                     BoundingBox bbox,
                                     @Nullable
                                     LineString... inner)
        Create a new instance of this class by passing in an outer LineString and optionally one or more inner LineStrings. Each of these LineStrings should follow the linear ring rules.

        Note that if a LineString breaks one of the linear ring rules, a RuntimeException will be thrown.

        Parameters:
        outer - a LineString which defines the outer perimeter of the polygon
        bbox - optionally include a bbox definition as a double array
        inner - one or more LineStrings representing holes inside the outer perimeter
        Returns:
        a new instance of this class defined by the values passed inside this static factory method
        Since:
        3.0.0

      • fromOuterInner

        public static Polygon fromOuterInner​(@NonNull
                                     LineString outer,
                                     @Nullable
                                     java.util.List<LineString> inner)
        Create a new instance of this class by passing in an outer LineString and optionally one or more inner LineStrings contained within a list. Each of these LineStrings should follow the linear ring rules.

        Note that if a LineString breaks one of the linear ring rules, a RuntimeException will be thrown.

        Parameters:
        outer - a LineString which defines the outer perimeter of the polygon
        inner - one or more LineStrings inside a list representing holes inside the outer perimeter
        Returns:
        a new instance of this class defined by the values passed inside this static factory method
        Since:
        3.0.0

      • fromOuterInner

        public static Polygon fromOuterInner​(@NonNull
                                     LineString outer,
                                     @Nullable
                                     BoundingBox bbox,
                                     @Nullable
                                     java.util.List<LineString> inner)
        Create a new instance of this class by passing in an outer LineString and optionally one or more inner LineStrings contained within a list. Each of these LineStrings should follow the linear ring rules.

        Note that if a LineString breaks one of the linear ring rules, a RuntimeException will be thrown.

        Parameters:
        outer - a LineString which defines the outer perimeter of the polygon
        bbox - optionally include a bbox definition as a double array
        inner - one or more LineStrings inside a list representing holes inside the outer perimeter
        Returns:
        a new instance of this class defined by the values passed inside this static factory method
        Since:
        3.0.0

      • outer

        @NonNull
public LineString outer()
        Convenience method to get the outer LineString which defines the outer perimeter of the polygon.
        Returns:
        a LineString defining the outer perimeter of this polygon
        Since:
        3.0.0

      • inner

        @NonNull
public java.util.List<LineString> inner()
        Convenience method to get a list of inner LineStrings defining holes inside the polygon. It is not guaranteed that this instance of Polygon contains holes and thus, might return a null or empty list.
        Returns:
        a List of LineStrings defining holes inside the polygon
        Since:
        3.0.0

      • type

        @NonNull
public java.lang.String type()
        This describes the TYPE of GeoJson geometry this object is, thus this will always return Polygon.
        Specified by:
        type in interface GeoJson
        Returns:
        a String which describes the TYPE of geometry, for this object it will always return Polygon
        Since:
        1.0.0

      • bbox

        @Nullable
public BoundingBox bbox()
        A Feature Collection might have a member named bbox to include information on the coordinate range for it's Features. The value of the bbox member MUST be a list of size 2*n where n is the number of dimensions represented in the contained feature geometries, with all axes of the most southwesterly point followed by all axes of the more northeasterly point. The axes order of a bbox follows the axes order of geometries.
        Specified by:
        bbox in interface GeoJson
        Returns:
        a list of double coordinate values describing a bounding box
        Since:
        3.0.0

      • coordinates

        @NonNull
public java.util.List<java.util.List<Point>> coordinates()
        Provides the list of Points that make up the Polygon geometry. The first list holds the different LineStrings, first being the outer ring and the following entries being inner holes (if they exist).
        Specified by:
        coordinates in interface CoordinateContainer<java.util.List<java.util.List<Point>>>
        Returns:
        a list of points
        Since:
        3.0.0

      • toJson

        public java.lang.String toJson()
        This takes the currently defined values found inside this instance and converts it to a GeoJson string.
        Specified by:
        toJson in interface GeoJson
        Returns:
        a JSON string which represents this Polygon geometry
        Since:
        1.0.0

      • typeAdapter

        public static com.google.gson.TypeAdapter<Polygon> typeAdapter​(com.google.gson.Gson gson)
        Gson TYPE adapter for parsing Gson to this class.
        Parameters:
        gson - the built Gson object
        Returns:
        the TYPE adapter for this class
        Since:
        3.0.0

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object