# Geometry calculations

Position and position series objects introduced by coordinates and the geometry model discussed in simple geometry chapters provide multiple ways to manipulate coordinate data and access some common 2D cartesian geometric calculations.

This chapter guides you how to use the geometry model.

The following `polygon`

geometry object is applied in all samples of this
chapter:

This sample polygon illustrated:

## Bounding box

The previous chapter explained how to access and populate bounding boxes on geometry objects.

As a short recap letâ€™s calculate a bounding box for our sample polygon.

You can calculate also the center point of a bounding box.

Itâ€™s also possible to calculate aligned points inside a bounding box, not only the center point. Here are the aligment attributes:

`x`

= The horizontal distance fraction.- The value -1.0 represents the west side edge of the box.
- The value 0.0 represents the center horizontally.
- The value 1.0 represents the east side edge of the box.

`y`

= The vertical distance fraction.- The value -1.0 represents the south side edge of the box.
- The value 0.0 represents the center vertically.
- The value 1.0 represents the north side edge of the box.

Below `Aligned(x: 0.5, y: 0.5)`

is used.

## Centroid

The *centroid* is - as by definition - *a geometric center of mass of a
geometry*.

The centroid is computed according to dimensionality of a geometry:

*areal*geometries: weighted by the area of areal geometries like polygons.*linear*geometries: computed from midpoints of line segments that are weighted by the length of each line segment.*punctual*geometries: the arithmetic mean of all separate positions.

Note that a centroid do not always locate inside a geometry.

The following sample shows how to calculate it for a polygon.

Also other geometry types provide `centroid2D`

method.

## Polylabel

The problem with centroids for polygons is that they do not always locate inside a geometry.

To counter this issue Mapbox has developed an Open-Source algorithm called
polylabel that is a fast algorithm for
finding polygon *pole of inaccessibility*, the most distant internal point from
the polygon exterior ring.

For more background details please see also the blog post (Aug 2016) by Vladimir Agafonkin introducing the algorithm.

The `geobase`

package has a ported version of this algorithm. Using it is as
easy as calling centroid.

The result position is inside polygon area and you also get a distance from this point to the polygon outline.

## Point-in-polygon

The point-in-polygon algorithm can be used for checking whether a position is inside a polygon:

- polygons without holes: checks whether a position is inside a polygon outer ring
- polygons with holes: checks whether a position is inside a polygon outer ring, but not inside any holes or inner rings

## Distance to point

All geometry classes has also the method `distanceTo2D`

that returns a
distance from a geometry to a destination position calculated in a cartesian 2D
plane.

The distance is computed according to dimensionality of a geometry:

*areal*geometries: a shortest distance to the outline of a polygon*linear*geometries: a distance to the nearest line segment*punctual*geometries: a distance to the nearest position

As noted this functionality is supported for other geometry types too.

## Outline length

Polygons are formed of exactly one exterior or outer ring, and of 0 to N interior or inner rings (holes).

You can calculate outline lengths of these rings too.

Naturally the `length2D`

method can be applied to other geometry types too, like
line strings (polylines). Thereâ€™s also a method called `length3D`

that
calculates lengths in 3D coordinates if a geometry just contain Z or elevation
values.

## Polygon area

Calculating area for polygons is supported too.

## Polygon data structure

Our sample polygon in all previous sample was defined earlier.

There are multiple constructors available on the `Polygon`

class. The `build`

factory is defined in the library code:

Thatâ€™s a lot of definitionâ€¦ But the key idea from this is that each ring
takes `Iterable<double>`

with a list of coordinate values as input and is
transformed to a `PositionSeries`

object when constructing a polygon.

## Position series manipulation

The `PositionSeries`

class is introduced in the
coordinates chapter.

You could create exactly the same polygon as used already also using code below.

Itâ€™s possible to modify position series objects before constructing actual polygon geometry objects.

Other manipulation method shown by definitions.

`PositionSeries`

objects contain 0 to N `Position`

objects.

You can access position coordinate values easily.

## Position manipulation

Position objects can also be manipulated in cartesian coordinate system using operators and functions available.

Other options to apply coordinate transforms on position objects are to use
`transform`

(with a custom transform as a parameter) or `project`

(geospatial
projections, discussed in the separate
chapter).

## Calculations along the Earth surface

Cartesian geometry used in the previous section is not enough when measuring distances between geographic positions located far apart.

The `geobase`

package provides geodesy functions that are based on calculations
on a spherical
earth model (with errors up to 0.3% compared to an ellipsoidal earth model).
Distance, bearing, destination point and midpoint are provided both for
*great circle paths* and *rhumb lines*. Intermediate points, intersections and
areas are available for great circle paths only.

Thereâ€™s a separate chapter about these calculations.