Points

Geo::Index works with points on a spherical body. Points are hash references containing, at a minimum, lat and lon entries which give the point's position in degrees. Additional hash entries can be present and will be both ignored and preserved. The Index(...), IndexPoints(...), Search(...), Closest(...), Farthest(...), Distance(...), DistanceFrom(...), and DistanceTo(...) methods add additional entries in point hashes.

The hash entries used by Geo::Gpx are shown below. Apart from lat and lon these values are created by Geo::Gpx. Unless noted, these values may be read but should not be set, altered, or deleted.

• lat - Point's latitude in degrees [ -90 .. 90 ]

• lon - Point longitude in degrees [ -180 .. 180 )

  These two values may be changed but the altered point should then be re-indexed using Index(...) before further searches are run.

• data - The optional user data supplied when a point was created using the array shorthand. This contents of this field may be freely modified by the user. See Index(...) and IndexPoints(...).

• lat_rad - The point's latitude in radians [ -pi  / 2 .. pi / 2 ]

• lon_rad - The point's longitude in radians [ -pi .. pi )

• circumference - Circumference (in meters) of the circle of latitude that the point falls on. This is computed from the body's equatorial circumference assuming a spherical (not an oblate) body.

• search_result_distance - Distance (in meters) of point from search point of previous search. The distance computation assumes a spherical body and is computed using a ruggedized version of the haversine formula. This value is only generated when Search(...) is called with the radius or sort_results option. See also Distance(...), DistanceFrom(...), and DistanceTo(...).

• antipode_distance - Distance (in meters) of point from search point's antipode as determined by a previous call to Farthest(...). This distance is computed using a ruggedized version of the haversine formula.

As a convenience, most methods allow points to be specified using a shorthand notation [ lat, lon ] or [ lat, lon, data ]. Points given in this notation will be converted to hash-based points. If a point created using this notation is returned as a search result it will be as a reference to the hash constructed by Geo::Index and not as a reference to the original array. To access the data field of a point created using the shorthand notation use $$point{'data'} where $point is a search result point.