Fork me on GitHub

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:

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