Package com.mapbox.geojson

Class Polygon

java.lang.Object

com.mapbox.geojson.Polygon

All Implemented Interfaces:

CoordinateContainer<List<List<Point>>>, GeoJson, Geometry, Serializable

public final class Polygon
extends Object
implements CoordinateContainer<List<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

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.
List<List<Point>>	coordinates()	Provides the list of Points that make up the Polygon geometry.
boolean	equals(Object obj)
static Polygon	fromJson(String json)	Create a new instance of this class by passing in a formatted valid JSON String.
static Polygon	fromLngLats(List<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(List<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, 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, 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()
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.
String	toJson()	This takes the currently defined values found inside this instance and converts it to a GeoJson string.
String	toString()
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 Details

fromJson

public static Polygon fromJson(@NonNull
 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
 List<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
 List<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
 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
 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 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 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 List<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<List<List<Point>>>

Returns:

a list of points

Since:

3.0.0

toJson

public 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 String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object