pyosmium Documentation

pyosmium is a Python binding for the libosmium C++ library, designed for high-performance processing of OpenStreetMap (OSM) data. To begin using the library, you should follow the structured learning path provided in the user manual, which covers the OSM data model, geometry creation, filtering, and data writing.

Key learning areas include:

• The OSM Data Model: Understanding how pyosmium represents and processes OSM objects.
• Object Data: Inspecting the contents of OSM objects.
• Geometries: Creating points, line strings, and polygons from OSM data.
• Filtering: Selecting specific subsets of data for processing.
• Handlers: Using the callback-based approach for data processing.
• Writing Data: Creating new OSM files.
• Advanced Sources: Working with change files (diffs), history files, and replication tools.

Handler-based processing involves creating a Python class that implements callback methods for different OSM entity types. You then use osmium.apply() to run these handlers against an OSM file.

To create a handler, define a class with methods named after the entity types you want to process:

• node(self, n)
• way(self, w)
• relation(self, r)
• area(self, a)
• changeset(self, c)

Once defined, pass an instance of your handler to osmium.apply(filename, handler_instance).

import osmium

class PrintHandler:
    def node(self, n):
        print(n)

    def way(self, w):
        print(w)

    def relation(self, r):
        print(r)

    def area(self, a):
        print(a)

    def changeset(self, c):
        print(c)

my_handler = PrintHandler()
osmium.apply('buildings.opl', my_handler)

While standard OSM classes are read-only views, pyosmium provides a set of mutable classes if you need to modify OSM data. These classes allow for changes that can be written back to a file:

• osmium.osm.mutable.OSMObject
• osmium.osm.mutable.Node
• osmium.osm.mutable.Way
• osmium.osm.mutable.Relation

pyosmium provides several specialized indexing structures to manage OpenStreetMap data efficiently during processing:

• osmium.IdTracker: Used for tracking IDs of objects as they are processed.
• osmium.index.IdSet: A specialized set for managing and looking up object IDs.
• osmium.index.LocationTable: A table used to associate object IDs with their geographic locations (coordinates).

When working with replication services, you will encounter two types of change files:

• Full change files: Contain every intermediate version of an object if it was changed multiple times within the time span. Use these if you need the exact history of changes.
• Simplified change files: Only keep the latest version of each object. These are typically used for updating a planet file or an extract where intermediate states are irrelevant.

Tools like pyosmium-get-changes can produce either version.

In pyosmium, data processing is driven by a Handler class. You define a class that inherits from osmium.SimpleHandler and implement specific methods (handler functions) that correspond to the OSM elements you want to process (e.g., node, way, relation).

When you run the handler using an osmium.apply() call, the library iterates through the OSM data and calls your implemented methods whenever a matching element is encountered. This event-driven model allows you to perform complex operations like spatial filtering, attribute extraction, or data transformation in a single pass over the data.

Pyosmium object instances (such as an index) are not thread-safe for concurrent modifications. If you are sharing these objects across multiple threads, you must protect write accesses using exclusive locks.

Concurrent read operations are safe and do not require locking. The library functions themselves are reentrant and can be used safely from different threads.

pyosmium provides two primary base classes for interacting with OpenStreetMap data:

1. osmium.BaseHandler: The primary class used to implement custom handlers for processing OSM data (nodes, ways, relations, etc.) as they are parsed.
2. osmium.BaseFilter: Used to define filters that determine which OSM elements should be processed during a parse run.