spatial_query

Spatial Query - a JQuery like Javascript library for handling spatial maths
Copyright (c) 2009 Chris Zelenak
Spatial Query is freely distributable under the MIT X11 License - see LICENSE file.

A set of functions for initializing array data into spatial objects
(matrix, vectors, polygons and latitude / longitude points) from which
further operations may be made.

Most vector and matrix operations support calculations to any dimension size.
In cases where they are not supported, one of the two following cases will arise:

* The function will be named _2d or _3d to indicate what dimension
the operated data should be in

* The function will throw an error stating that the general case solution has not
been implemented yet. (Matrix inversion, for example)

Examples:

Return a vector at point x:10, y:0, z: 40.

$v([10, 0, 40])

Return a 5 element vector:

$v([10, 0, 40, 21, 32])

Take the vector at x:10, y:20 and project it on the
vector at x:30 y:50, then return the magnitude of that
vector.

$v([10, 20]).project_on([30, 50]).magnitude();

Take the latitude / longitude pair for Indianapolis and convert
it into cartesian (WSG84) coordinates

$ll([39.7670, -86.1563]).vector()

The same as above, but roundtrip convert it back to latitude / longitude.

$ll([39.7670, -86.1563]).vector().latlng()

Generate a polygon

$p([[0,0], [0, 10], [10, 10], [10, 0]])

Compute the area of the polygon

$p([[0,0], [0, 10], [10, 10], [10, 0]]).area_2d()

Compute the centroid point (vector) of the polygon

$p([[0,0], [0, 10], [10, 10], [10, 0]]).centroid_2d()

Compute the convex hull of the polygon

$p([[0,0], [0, 10], [10, 10], [10, 0]]).convex_hull_2d()

Compute the union of the given polygon with another polygon

$p([[0,0], [0, 10], [10, 10], [10, 0]]).union_2d([[5,5], [5, 7], [15, 7], [15, 5]])

Vector: $v([x, y, z, t, etc])
-vector() -> Vector
-latlng() -> LatLng, Convert to Latitude and Longitude
-matrix() -> Matrix
-add(other_vector_or_scalar) -> Vector
-subtract(other_vector_or_scalar) -> Vector
-multiply(other_vector_or_scalar) -> Vector
-dot_product(other_vector) -> Number
-cross_product(other_vector) -> Vector if dimension greater than 2, Number if dimension == 2
-distance(other_vector) -> Number
-midpoint_2d(other_vector) -> Vector
-distance_2d_fast(other_vector) -> Number, A faster vector distance function.
-magnitude() -> Number
-norm(n) -> Number, The nth vectorm norm, defaults to 2.
-angle_between(other_vector) -> Vector
-project_onto(other_vector) -> Vector
-x(), y(), z() -> Number, Convenience functions.
-elm(i) -> Number

Matrix: $m( [[row1a, row1b, row1c], [row2a, row2b, row2c]] )
-matrix() -> Matrix
-elm(i,j) -> Number
-add(matrix_or_scalar) -> Matrix
-subtract(matrix_or_scalar) -> Matrix
-multiply(matrix_or_scalar) -> Matrix
-divide(matrix) -> Matrix
-transpose() -> Matrix
-determinant() -> Number
-inverse() -> Matrix
-rotate() NOT IMPL
-identity() -> Matrix
-normalize() NOT IMPL

Polygon: $p( [ [x1, y1], [x2, y2], [x3, y3], [x4, y4] ] )
-matrix() -> Matrix
-polygon() -> Polygon
-add_point(vector) -> Polygon
-to_point_array() -> Array
-foreach(fn) -> Polygon, Calls fn with each node inside the polygon
-point_inside_2d(vector) -> Boolean
-point_inside_fast_2d(vector) -> Boolean
-clip_2d(polygon) -> Polygon, or null if no operation took place
-union_2d(polygon) -> Polygon, or null if no operation took place
-subtract_2d(polygon) -> Polygon, or null if no operation took place
-area_2d() -> Number
-centroid_2d() -> Vector
-centroid_3d() -> Vector
-convex_hull_2d() -> Polygon
-contains_2d(other_polygon) -> Boolean
-intersects_2d(other_polygon) -> Array of vectors(intersections) or null

LatitudeLongitude: $ll( [latitude, longitude, altitude] )
-vector() -> Vector, convert to WSG84 x/y/z coords
-latlng() -> LatLng
-lat(), lng(), alt() -> Number, convenience functions
-distance_to(latlng) -> Number (meters), Uses the Vincenty eq. for mm precision
-distance_to_miles(latlng) -> Number (miles)
-bearing_between(latlng) -> Number
-destination_given_distance_and_bearing(distance_in_meters, bearing) -> LatLng

Known bugs:

* Math is not my strong suit
* Boolean operations on polygons are still not reliable. There are some kinks in the algorithm.
* Some of the general case operations on a matrix are not yet implemented. It's because they are hard,
and I don't personally need them right now.

Chris Z
For work at www.indy.com
Talked about at www.yeti-factory.org