Spherical Geometry Library in PHP by Túbal Martín

This library provides classes and functions for the computation of geometric data on the surface of the Earth.

This library ports a small but useful subset of classes from the Google Maps Javascript API version 3.

Tested against Google Maps API versions 3.5 to 3.9.

How to use

Include the spherical-geometry.class.php file in your code and use the API!

Notes:

The API is nearly identical to the Google Maps Javascript API.
All computed lengths are returned in meters.

API

Classes and libraries ported from the Google Maps Javascript API:

SphericalGeometry class (static)

Utility functions for computing geodesic angles, distances and areas. The default radius is Earth's radius of 6378137 meters.

If you don't know how to use some of these methods read this excellent article by Gabriel Svennerberg: Calculating Distances and Areas in Google Maps API 3

Static Methods

Methods	Return Value	Description
`getEarthRadius()`	`number`	Gets the Earth's radius.
`computeArea(loop:Array.<LatLng>)`	`number`	Computes the area of the given loop. Loops must be closed.
`computeBounds(center:LatLng, radius:number)`	`LatLngBounds`	Computes a bounding rectangle from a LatLng point and a given radius (radius must be given in meters). See this page for more info.
`computeDistanceBetween(from:LatLng, to:LatLng)`	`number`	Computes the distance between two LatLngs.
`computeHeading(from:LatLng, to:LatLng)`	`number`	Computes the heading from one LatLng to another LatLng.
`computeLength(path:Array.<LatLng>)`	`number`	Computes the length of the given path.
`computeOffset(from:LatLng, distance:number, heading:number)`	`LatLng`	Computes the LatLng produced by starting from a given LatLng and heading a given distance.
`computeSignedArea(loop:Array.<LatLng>)`	`number`	Computes the signed area of the given loop. Loops must be closed. The signed area may be used to determine the orientation of a loop.
`interpolate(from:LatLng, to:LatLng, fraction:number)`	`LatLng`	Travels a fraction of the way from one LatLng to another LatLng.

LatLng class

LatLng is a point in geographical coordinates, latitude and longitude.

Notice that although usual map projections associate longitude with the x-coordinate of the map, and latitude with the y-coordinate, the latitude coordinate is always written first, followed by the longitude.

Notice also that you cannot modify the coordinates of a LatLng. If you want to compute another point, you have to create a new one.

Constructor

Constructor	Description
`LatLng(lat:number, lng:number, noWrap?:boolean)`	Notice the ordering of latitude and longitude. If the noWrap flag is true, then the numbers will be used as passed, otherwise latitude will be clamped to lie between -90 degrees and +90 degrees, and longitude will be wrapped to lie between -180 degrees and +180 degrees.

Methods

Methods	Return Value	Description
`equals(other:LatLng)`	`boolean`	Comparison function.
`getLat()`	`number`	Returns the latitude in degrees.
`getLng()`	`number`	Returns the longitude in degrees.
`toString()`	`string`	Converts to string representation.
`toUrlValue(precision?:number)`	`string`	Returns a string of the form "lat,lng" for this LatLng. We round the lat/lng values to 6 decimal places by default.

LatLngBounds class

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

Constructor

Constructor	Description
`LatLngBounds(sw?:LatLng, ne?:LatLng)`	Constructs a rectangle from the points at its south-west and north-east corners.

Methods

Methods	Return Value	Description
`contains(latLng:LatLng)`	`boolean`	Returns true if the given lat/lng is in this bounds.
`equals(other:LatLngBounds)`	`boolean`	Returns true if this bounds approximately equals the given bounds.
`extend(point:LatLng)`	`LatLngBounds`	Extends this bounds to contain the given point.
`getCenter()`	`LatLng`	Computes the center of this LatLngBounds
`getNorthEast()`	`LatLng`	Returns the north-east corner of this bounds.
`getSouthWest()`	`LatLng`	Returns the south-west corner of this bounds.
`intersects(other:LatLngBounds)`	`boolean`	Returns true if this bounds shares any points with this bounds.
`isEmpty()`	`boolean`	Returns if the bounds are empty.
`toSpan()`	`LatLng`	Converts the given map bounds to a lat/lng span.
`toString()`	`string`	Converts to string.
`toUrlValue(precision?:number)`	`string`	Returns a string of the form "lat_lo,lng_lo,lat_hi,lng_hi" for this bounds, where "lo" corresponds to the southwest corner of the bounding box, while "hi" corresponds to the northeast corner of that box.
`union(other:LatLngBounds)`	`LatLngBounds`	Extends this bounds to contain the union of this and the given bounds.

Tests

You can view the tests located in the tests folder.

To run the tests, download the project and upload it to a server with PHP installed. Open your browser and enter the absolute URL to the tests folder in your server.

License

Dual licensed under the MIT or GPL Version 2 licenses.

Authors

Túbal Martín (tubalmartin at gmail dot com)

Download

You can download this project in either zip or tar formats.

You can also clone the project with Git by running:

$ git clone git://github.com/tubalmartin/spherical-geometry-php