NAME

Geo::SpatialDB - Generic reverse-geocoding engine on top of key/value storage

VERSION

version 0.000_001

DESCRIPTION

THIS API IS NOT FINALIZED. If you use it, please don't blindly upgrade. I'm releasing it primarily for feedback on the design.

Geo::SpatialDB provides reverse geocoding services on top of a simple key/value database. It is designed primarily for reverse-geocoding 2D areas for map rendering, with some limited forward-geocoding ability to find things near a specified location. It does *NOT* yet support calculation of the best route between two points, but I intend to eventually add that.

By using a simple key/value back-end, Geo::SpatialDB can use static data from a read-only filesystem, which is currently not supported by more advanced engines like Postgres. The current version focuses on the "LMDB" library, which has a great design with excellent performance.

The current version is tuned for personal navigation purposes, but could be made more generic or configurable to efficiently support wider fields of view and custom classification of entities.

ENTITIES

Sources like OpenStreetMaps have things encoded generically as "Ways" and "Relations", with tags to give meaning to them. This module aims for a stronger taxonomy, to help diagnose things without an exhaustive investigation of free-form tags.

The contents of the Geo::SpatialDB are divided into the following basic categories:

Location

Locations are logical "points on the map" which can be anything from road junctions (including exit ramps) to business addresses to logical centers of wider landmarks like "Niagra Falls". Locations are simply a (lat,lon) coordinate and optional radius. Being a logical entity, multiple locations may be stacked on the same coordinates. Locations that share coordinates do not contain references to eachother.

RouteSegment

Route segments are the basic unit of navigable paths across the map. It could be a piece of a road, foot path, water way, railroad, etc. A route references one or more Path objects to form an un-broken sequence of coordinates. Segments are broken at any intersection (but not overpass). Multiple logical routes (like a highway which merges with a local street as it passes through town) may share the physical route segments of the map.

If you are building a routing algorithm, all the relevant data you need should be contained in RouteSegment objects. You would then consult the related Route objects to determine how to describe the physical route to the user.

Route

Route objects represent a logical named route. They may be discontinuous, and redundant with other routes. Any metadata not needed for calculating a physical route goes here.

Area

Areas are 2D spaces. Any space on the map that you think of as "passing into" rather than "going to" is classified as an area. States, Counties, Parks, zip codes, and etc are all stored as Areas. An area will provide both a bounding path and circles of approximation, for quick collision tests.

Path

Paths are an implementation detail to prevent repeating sequences of coordinates. Paths may be used by one or more other entities. Paths have no metadata of their own. In a future version, paths might be replaced with an automatic coordinate compression/decompression system, so try not to write code that depends on them.

find_at

AUTHOR

Michael Conrad <mike@nrdvana.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Michael Conrad.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.