Level Map/Software Support

From OpenStreetMap Wiki
Jump to: navigation, search

Introduction

Although level maps are very compatible with level map unaware software, so that many programs (including all graphical 2D renderers) would not even benefit from a full support, other software (in particular routing software) should be level map aware if we decide to actually create and use level maps.

In order to make it easy for developers to add the functionality as needed, there should be a library (let's call it "liblevelmap") to support their tasks. The library must be as versatile as possible, to help as much as possible.

Along with the library, there should be some tools that can be used to add the functionality to unaware software indirectly if needed.

The purpose of this page is to discuss the requirements for software support, shaping the design of liblevelmap.

Requirement list for liblevelmap

Functional

Name Description Benefit Priority
Expansion Must be able to expand level maps into instances, pushing as much information from the level maps as possible to where it is needed. Vertical ways must be created as ways. All connections (junctions) must be provided. The output must be valid OSM data. The main purpose Essential
Expansion: Keeping Memberships Level maps should be maintained in the expanded data. On top of their original members, the relations should also contain the instances they have produced (that are regular OSM objects now). Ease of use, reversibility High
Expansion: Reversibility The expansion output should be reversible in a way that the source of all additional objects generated during the expansion can be clearly identified (from which "main" instance it is instantiated and which instance number). Tools can run on persistent databases High
Expansion: Minimum Change
  • The main instance should keep the object ID of the original OSM object that is instantiated.
  • If the expansion finds that an instance is needed and the original data contains the instance already, the identity of that instance should be maintained.
  • Write actions to the instance should take place only when a change is needed.
Tools can run on persistent databases High
Cleanup: Unused The library should be able to remove instances from previous runs that are no longer used. Tools can run on persistent databases High
Cleanup: All The library should be able to remove all instances from previous runs, reversing all expansion effects completely. Tools can run on persistent databases High
Streaming Should work on-the-fly, being called from the input component of an OSM data consumer application Call the hook and forget about it High
Static Data Should be able to work on OSM data stores somehow (databases, OSM files, PBF files, etc.) Do an expansion/update before using the data High
Expanded Data Format A common data format for expanded level maps (common tags) should be used for expanded level map data Different programs can share one expansion Medium
Performance The library must work as fast as possible while being as compatible as possible. If needed, different operation modes must be supported and chosen automatically. For example, if there is not enough memory, switch over to a two-pass mode. Acceptance Medium
Calculating Relative Heights Calculate relative heights from the level map definitions, assuming a 4.5 m height per level by default. 4.5 m seems to be a good trade-off between the height of structures we are usually mapping (from at least 3.0 m for residential blocks, up to 6 m for bigger structures, including high road bridges). Input for 3D rendering Medium
Calculating Elevations If original OSM elements have got ele=* and/or height=* tags, new ele=* tags should be calculated accordingly. Completeness Nice to have

Platform

Name Description Benefit Priority
Minimum Dependencies The library should be based on as few requirements as possible Flexibility Essential
Java Support Java must be supported at least as a binding for the library, because many consumers are written in that language Usability Essential

Tools

Name Description Benefit Priority
Standalone Tool Functionality Implementing expansion and cleanup support at least on whole .osm, .osm.gz and .pbf files Usability Important
Standalone Tool on Java The standalone tool should be a native binary for ... One common implementation Essential
Standalone Tool as a tarball The standalone tool should be a available for user compiles and as required by GPL. One common implementation Essential
Standalone Tool on .NET / MONO The standalone tool should be a native binary for ... One common implementation Alternative for others
Standalone Tool on win32 (compatible with basic Win98 through Win7, plus WINE) The standalone tool should be a native binary for ... Usability Important
Standalone Tool on Linux i686 The standalone tool should be a native binary for ... Usability Important
Standalone Tool on win64 The standalone tool should be a native binary for ... Usability Nice to have
Standalone Tool on Linux x86_64 The standalone tool should be a native binary for ... Usability Nice to have
Standalone Tool on MacOS ??? The standalone tool should be a native binary for ... Usability  ???
Osmosis plugin Implementing expansion and cleanup support as a plugin for osmosis Flexibility Important

Licensing

Which licence would be optimal for the library?

  • LGPLv2+?

Which licence for the tool?

Design Ideas

Java Implementation

Nothing here yet.

Level Map Expanded Data Format

This is a list of tags that instantiated OSM objects should be given

Tag Required for/when Explanation
lm_expansion:is_generated=* every object that is created by level map expansion Identifies the objects as eligible for a level map cleanup
lm_expansion:is_generated=direct ... created due to a direct membership of the main instance in a level map A membership is direct if the object is a level map member itself. It is indirect if it is part of a member (such as a node in a member way or a member of a member relation). Attributes from a direct membership always override attributes from an indirect membership, so this distinction may be needed by software working on databases.
lm_expansion:is_generated=indirect ... created due to an indirect membership of the main instance in a level map
lm_expansion:source_id=[type:]ID every instance, including main instances contains the ID of the object it was instantiated from. If the type differs, the ID must be prefixed with the original type. Usually the main instance's ID. vways are an exception, because they are ways, instantiated from a node. So vways have "node:vway_node_id" here.
lm_expansion:instance_no=instance_number every instance, including main instances contains a relative number of in the list of instances of this particular object. The main instance always is number 0. Instances below the main instance have negative numbers, instances above the main instance have positive numbers. Every set of instances has its own set of counters. There are no gaps.
lm_expansion:instance_min=instance_number every instance, including main instances contains the number of the lowest instance of this set. The number of existing instances is instance_max-instance_min+1.
lm_expansion:instance_max=instance_number every instance, including main instances contains the number of the highest instance of this set. The number of existing instances is instance_max-instance_min+1.
lm_expansion:level=level_name every instance, including main instances the short level name
lm_expansion:level_long=long_name if defined for the level the long level name
lm_expansion:level:language_code=foreign_level_name if defined for the level the short foreign language level name
lm_expansion:level_long:language_code=foreign_long_name if defined for the level the long foreign language level name
lm_expansion:above_ground=relative_elevation every instance, including main instances Relative elevation above the ground level assumed or defined in a level map.
lm_expansion:ele=absolute_elevation if the original node had an elevation Calculated during expansion.