geokit/geokit

Geo-Toolkit for PHP

84 874

184

11

18

v1.3.0 2016-07-11 12:26 UTC

Geokit is a PHP toolkit to solve geo-related tasks like:

• Distance calculations.
• Heading, midpoint and endpoint calculations.
• Rectangular bounding box calculations.

Installation

`composer require geokit/geokit`

Check the Packagist page for all available versions.

Reference

Math

A Math instance can be used to perform geographic calculations on Position and BoundingBox instances.

The World Geodetic System 1984 (WGS84) is exclusively used as the coordinate reference system.

`\$math = new Geokit\Math();`

Distance calculations

A math instance provides two methods to calculate the distance between 2 points on the Earth's surface:

• `distanceHaversine(Geokit\Position \$from, Geokit\Position \$to)`: Calculates the approximate sea level great circle (Earth) distance between two points using the Haversine formula.
• `distanceVincenty(Geokit\Position \$from, Geokit\Position \$to)`: Calculates the geodetic distance between two points using the Vincenty inverse formula for ellipsoids.
```\$distance1 = \$math->distanceHaversine(\$from, \$to);
\$distance2 = \$math->distanceVincenty(\$from, \$to);```

Both methods return a Distance instance.

Transformations

The `circle()` method calculates a closed circle Polygon given a center, radius and steps for precision.

```\$circlePolygon = \$math->circle(
new Geokit\Position(8.50207515, 49.50042565),
Geokit\Distance::fromString('5km'),
32
);```

Other calculations

Other useful methods are:

• `heading(Geokit\Position \$from, Geokit\Position \$to)`: Calculates the (initial) heading from the first point to the second point in degrees.
• `midpoint(Geokit\Position \$from, Geokit\Position \$to)`: Calculates an intermediate point on the geodesic between the two given points.
• `endpoint(Geokit\Position \$start, float \$heading, Geokit\Distance \$distance)`: Calculates the destination point along a geodesic, given an initial heading and distance, from the given start point.

Distance

A Distance instance allows for a convenient representation of a distance unit of measure.

```\$distance = new Geokit\Distance(1000); // Defaults to meters
// or
\$distance = new Geokit\Distance(1, Geokit\Distance::UNIT_KILOMETERS);

\$meters = \$distance->meters();
\$kilometers = \$distance->kilometers();
\$miles = \$distance->miles();
\$yards = \$distance->yards();
\$feet = \$distance->feet();
\$inches = \$distance->inches();
\$nauticalMiles = \$distance->nautical();```

A Distance can also be created from a string with an optional unit.

```\$distance = Geokit\Distance::fromString('1000'); // Defaults to meters
\$distance = Geokit\Distance::fromString('1000m');
\$distance = Geokit\Distance::fromString('1km');
\$distance = Geokit\Distance::fromString('100 miles');
\$distance = Geokit\Distance::fromString('100 yards');
\$distance = Geokit\Distance::fromString('1 foot');
\$distance = Geokit\Distance::fromString('1 inch');
\$distance = Geokit\Distance::fromString('234nm');```

Position

A `Position` is a fundamental construct representing a geographical position in `x` (or `longitude`) and `y` (or `latitude`) coordinates.

Note, that `x`/`y` coordinates are kept as is, while `longitude`/`latitude` are normalized.

• Longitudes range between -180 and 180 degrees, inclusive. Longitudes above 180 or below -180 are normalized. For example, 480, 840 and 1200 will all be normalized to 120 degrees.
• Latitudes range between -90 and 90 degrees, inclusive. Latitudes above 90 or below -90 are normalized. For example, 100 will be normalized to 80 degrees.
```\$position = new Geokit\Position(181, 91);

\$x = \$position->x(); // Returns 181.0
\$y = \$position->y(); // Returns 91.0
\$longitude = \$position->longitude(); // Returns -179.0, normalized
\$latitude = \$position->latitude(); // Returns 89.0, normalized```

BoundingBox

A BoundingBox instance represents a rectangle in geographical coordinates, including one that crosses the 180 degrees longitudinal meridian.

It is constructed from its left-bottom (south-west) and right-top (north-east) corner points.

```\$southWest = new Geokit\Position(2, 1);
\$northEast = new Geokit\Position(2, 1);

\$boundingBox = new Geokit\BoundingBox(\$southWest, \$northEast);

\$southWestPosition = \$boundingBox->southWest();
\$northEastPosition = \$boundingBox->northEast();

\$center = \$boundingBox->center();

\$span = \$boundingBox->span();

\$boolean = \$boundingBox->contains(\$position);

\$newBoundingBox = \$boundingBox->extend(\$position);
\$newBoundingBox = \$boundingBox->union(\$otherBoundingBox);```

With the `expand()` and `shrink()` methods, you can expand or shrink a BoundingBox instance by a distance.

```\$expandedBoundingBox = \$boundingBox->expand(
Geokit\Distance::fromString('10km')
);

\$shrinkedBoundingBox = \$boundingBox->shrink(
Geokit\Distance::fromString('10km')
);```

The `toPolygon()` method converts the BoundingBox to an equivalent Polygon instance.

`\$polygon = \$boundingBox->toPolygon();`

Polygon

A Polygon instance represents a two-dimensional shape of connected line segments and may either be closed (the first and last point are the same) or open.

```\$polygon = new Geokit\Polygon([
new Geokit\Position(0, 0),
new Geokit\Position(1, 0),
new Geokit\Position(1, 1)
]);

\$closedPolygon = \$polygon->close();

/** @var Geokit\Position \$position */
foreach (\$polygon as \$position) {
}

\$polygon->contains(Geokit\Position(0.5, 0.5)); // true

/** @var Geokit\BoundingBox \$boundingBox */
\$boundingBox = \$polygon->toBoundingBox();```