ai.nextbillion.kits.geojson

Class Polygon

java.lang.Object

ai.nextbillion.kits.geojson.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]]
   ]
 }
 

See Also:

Serialized Form

Method Summary

Modifier and Type	Method and 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

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

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

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

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

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

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

outer

@Nullable
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

inner

@Nullable
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

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

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

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

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

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

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