Skip to main content Link Search Menu Expand Document (external link)

Feature Libraries

A feature library stores the worldwide OpenStreetMap dataset (or regional subset) as a single self-contained .gol file. Internally, .gol files are divided into tiles that contain the features within specific square bounding boxes.

  • Create a feature library from OpenStreetMap data (as .osm.pbf file) using gol build.

  • Alternatively, import tiles from an existing feature repository using gol load.

  • A feature library does not need to contain the complete set of tiles, but only those that are touched by the bounding boxes of queries. If you neither build nor load your library, you can instruct it to programmatically import tiles as needed (see below).

Opening a library

Create a FeatureLibrary object, with the path of the .gol file as argument:

FeatureLibrary world = new FeatureLibrary("world.gol");

To automatically download missing tiles as they are needed, specify the URL of the feature repository as the second constructor argument:

FeatureLibrary world = new FeatureLibrary(
    "world.gol", "https://data.geodesk.com/world");

  • If the library file does not exist, but you’ve specified a repository URL, the .gol file is automatically created.

  • A repository can also reside locally — in that case, use the file:// protocol (e.g. file:///home/george/geodata/planet)

  • FeatureLibrary is threadsafe; however, you may only create one instance for the same .gol file per process (.gol files can be safely shared among multiple processes).

Querying

FeatureLibrary offers multiple methods to select the features it contains. See next chapter for details.

Closing a library

Once you are done querying a library, close it to release its resources:

world.close();

The “GOL-den” Rule

Do not call the methods of any objects (collections, Feature, Tags) you’ve retrieved from a FeatureLibrary after having closed it. These lightweight objects are little more than pointers into a memory-mapped file — and closing it renders that memory area invalid.

If you violate this rule, you may get undefined results, or even trigger a segmentation fault.

Troubleshooting

The Rollback Journal

To prevent the feature library from becoming corrupted in case a process writing to it (by downloading tiles) terminates abnormally (process killed, loss of power, etc.), all write operations maintain a rollback journal that enables the file to be restored to a consistent state the next time it is opened after a crash.

This binary file has the same name as its corresponding library, with .journal added to its name.

You’re unlikely to encounter a journal file during normal operation. However, if you come across it, do not delete the journal, and do not separate the journal and its corresponding library (by moving/renaming one but not the other). Doing so risks leaving the library in an inconsistent state.

When in doubt, run gol check.