com.tomtom.speedtools.geometry

Class GeoArea

java.lang.Object

com.tomtom.speedtools.geometry.GeoObject

com.tomtom.speedtools.geometry.GeoArea

All Implemented Interfaces:

JsonRenderable

Direct Known Subclasses:

GeoCircle, GeoRectangle

@Immutable
public abstract class GeoArea
extends GeoObject

A geo area is an expression which has the following format:

     GeoArea      := Primitive
                  |  Inverse
                  |  Union
                  |  Difference

     Primitive    := GeoRectangle
                  |  GeoCircle

     Inverse      := invert(GeoArea)

     Union        := add(GeoArea, GeoArea)

     Difference   := subtract(GeoArea, GeoArea)

     Intersection := intersect(GeoArea, GeoArea)
 

Primitives are specified using GeoPoint objects, which can contain latitude/longitude values. As latitudes/longitudes do not project easily to a Carthesian coordinates, the operations for union, intersect, contains, etc. are subject to the following known restrictions: They are only accurate for relatively small areas, such as 200x200km. They are may do NOT work properly around the 180th degree longitude (http://en.wikipedia.org/wiki/180th_meridian). Definitions of operators: Union({1, 2, 3}, {3, 4, 5}) == {1, 2, 3, 4, 5} Difference({ 1, 2, 3}, {3, 4, 5}) == {1, 2} Intersection({ 1, 2, 3}, {3, 4, 5}) == {3}

Constructor Summary

Constructors

Constructor and Description
GeoArea()

Method Summary

Modifier and Type	Method and Description
GeoArea	add(GeoArea op) Binary operator: add(this, other).
abstract GeoRectangle	boundingBox() Return a rectangle bounding box for the entire expression.
abstract boolean	contains(GeoArea area) Returns whether another geo area is fully contained within 'this' geo area.
abstract boolean	contains(GeoPoint point) See contains(GeoArea).
static GeoArea	fromAreas(Collection<? extends GeoArea> areas) Convenience function to create a GeoArea from a list of areas.
GeoPoint	getCenter() Center point of the geo object.
GeoPoint	getOrigin() Reference point of the geo object.
abstract boolean	isCompound() Return whether this area is singular of compound.
abstract GeoArea	moveTo(GeoPoint origin) Move a geo object to specific origin.
protected GeoArea	optimize() Return an optimized version of 'this' geo area.
abstract boolean	overlaps(GeoArea area) Returns whether 'this' geo area overlaps with another geo area.
abstract Collection<GeoRectangle>	pixelate() Return a flat list of GeoRectangles that approximate the shape of the GeoArea, much like pixelation of a shape.
abstract GeoArea	translate(GeoVector vector) Translate a geo object with an Easting and Northing value.

Methods inherited from class com.tomtom.speedtools.geometry.GeoObject

canEqual, hashCodeSuper, toJson, toString, translate, translate

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

GeoArea

public GeoArea()

Method Detail

getOrigin

@Nonnull
public GeoPoint getOrigin()

Description copied from class: GeoObject

Reference point of the geo object. The origin is the base point for operations like GeoObject.translate(GeoVector) and GeoObject.moveTo(GeoPoint). The origin is always one of the used GeoPoints in the object.

Specified by:

getOrigin in class GeoObject

Returns:

Origin of the geo object.

getCenter

@Nonnull
public GeoPoint getCenter()

Description copied from class: GeoObject

Center point of the geo object. The center is not always the origin of the object. It may also not be a GeoPoint used in the object itself (such as the center point of a GeoLine which is defined by its end points only). The elevation of the center point is an average value of other GeoPoints in the object. It is always defined as being between the minimum and maximum elevations of other points.

Specified by:

getCenter in class GeoObject

Returns:

Center of the geo object.

fromAreas

@Nonnull
public static GeoArea fromAreas(@Nonnull
                                         Collection<? extends GeoArea> areas)

Convenience function to create a GeoArea from a list of areas. The areas will be Union-ed. This function can be used in combination with pixelate(), which produces a list of GeoRectangles as an approximation for the GeoArea surface.

Parameters:

areas - Collection of areas to union. The list must contain at least 1 area.

Returns:

New geo area.

add

@Nonnull
public final GeoArea add(@Nonnull
                                  GeoArea op)

Binary operator: add(this, other).

Parameters:

op - Area to add to 'this'.

Returns:

Union of 'this' and other geo area.

overlaps

public abstract boolean overlaps(@Nonnull
                                 GeoArea area)

Returns whether 'this' geo area overlaps with another geo area. Area B overlaps with A if there are points within B that are als contained in A. Note that this may be an approximation! For example, 2 circles close together may return overlap=true where they actually do not really overlap. Overlap is symmetric: a.overlap(b) == b.overlaps(a).

Parameters:

area - Area to check if overlaps.

Returns:

True if overlaps.

contains

public abstract boolean contains(@Nonnull
                                 GeoArea area)

Returns whether another geo area is fully contained within 'this' geo area. Area B is contained within A if all points that are contained in B are also contained in A. The following holds: a.contains(b) AND b.contains(a) iff a.equals(b)

Parameters:

area - Area to check if it is contained.

Returns:

True if contains.

contains

public abstract boolean contains(@Nonnull
                                 GeoPoint point)

See contains(GeoArea).

Parameters:

point - Point.

Returns:

True if points is contained within area.

boundingBox

@Nonnull
public abstract GeoRectangle boundingBox()

Return a rectangle bounding box for the entire expression.

Returns:

Rectangular bounding box with a surface > 0.

pixelate

@Nonnull
public abstract Collection<GeoRectangle> pixelate()

Return a flat list of GeoRectangles that approximate the shape of the GeoArea, much like pixelation of a shape. The resolution of the pixelation is fixed. The individual rectangles may or may not overlap. The individual "pixels" (GeoRectangles) are never "wrapped", meaning their south-west longitude is always <= north-east longitude. Wrapped shapes in the area will be divided into separate GeoRectangles by this function. This makes it easier for, for example, database to execute queries on them.

Returns:

List of 'pixelation rectangles' for this area.

translate

@Nonnull
public abstract GeoArea translate(@Nonnull
                                           GeoVector vector)

Description copied from class: GeoObject

Translate a geo object with an Easting and Northing value.

Specified by:

translate in class GeoObject

Parameters:

vector - Translation vector (along latitude and longitude).

Returns:

Translated object.

moveTo

@Nonnull
public abstract GeoArea moveTo(GeoPoint origin)

Move a geo object to specific origin. Note that the definition of the origin of an object is defined in derived classes.

Specified by:

moveTo in class GeoObject

Parameters:

origin - New origin of object.

Returns:

Translated object.

isCompound

public abstract boolean isCompound()

Return whether this area is singular of compound.

Returns:

True if compound.

optimize

@Nonnull
protected GeoArea optimize()

Return an optimized version of 'this' geo area. For example, if an expression consists of 2 unioned rectangles A and B, and B is fully contained within A, then the flattened version of 'this' would be A. Note that the implementation of flatten is not REQUIRED to produce an optimized expression. It IS required to produce an expression with exactly the same geo characteristics though.

Returns:

Normalized expression.