README
¶
gOSMonaut
gOSMonaut is a Go library that decodes OpenStreetMap PBF files. Instead of returning the internal PBF data model, which uses reference-IDs of nested OSM entities, it always returns complete entities. E.g. a way contains all child nodes, including tags and coordinates, instead of just the node-IDs.
Installation
$ go get github.com/morbz/gosmonaut
Usage
In order to produce complete entities all nested entites are cached in memory. To keep the used memory low there are two filters that the decoder uses to decide which entites it needs to cache. They are passed to the Start() method of the Gosmonaut object. Only entites that satisfy both filters will be send to the caller:
types OSMTypeSet: Defines which OSM element types are requested (node, way, relation)
funcEntityNeeded func(OSMType, OSMTags) bool: A callback function that the decoder will call during decoding. Based on the element type and tags, this function decides if the entity is needed.
Sample
In this example the program will output all the street names of London:
package main
import (
"io"
"log"
"os"
"github.com/MorbZ/gosmonaut"
)
func main() {
// Open the PBF file
f, err := os.Open("greater-london-140324.osm.pbf")
if err != nil {
log.Fatal(err)
}
defer f.Close()
// Create the Gosmonaut object
g, err := gosmonaut.NewGosmonaut(f)
if err != nil {
log.Fatal(err)
}
// Start decoding
g.Start(
// We only want to receive ways (nodes, ways, relations)
gosmonaut.NewOSMTypeSet(false, true, false),
// Only request highways with a name
func(t gosmonaut.OSMType, tags gosmonaut.OSMTags) bool {
return tags.Has("highway") && tags.Has("name")
},
)
// Receive found entities
for {
if i, err := g.Next(); err == io.EOF {
// Last entity received
break
} else if err != nil {
// Error during encoding
log.Fatal(err)
} else {
// Received entity, print name
tags := i.GetTags()
log.Println(tags.Get("name"))
}
}
}
Configuration
When creating the Gosmonaut object, an optional configuration object can be passed.
Instead of:
gosmonaut.NewGosmonaut(f)
the configuration can be passed by calling:
gosmonaut.NewGosmonaut(
f,
gosmonaut.Config{
PrintWarnings: true,
NumProcessors: 2,
},
)
See the documentation for possible configuration parameters.
Output
All entities can be serialized into the JSON format. The used JSON format is similar to Overpass JSON but it comes with nested entities. Here is an example of how a relation with nested member ways and nodes can look like:
{
"type": "relation",
"id": 8024698,
"tags": {
"addr:city": "Leonberg",
"addr:housenumber": "5",
"addr:postcode": "71229",
"addr:street": "Sellallee",
"building": "apartments",
"type": "multipolygon"
},
"members": [
{
"role": "outer",
"entity": {
"type": "way",
"id": 561602115,
"tags": {},
"nodes": [
{
"type": "node",
"id": 5414987608,
"lat": 48.7994117,
"lon": 9.0173691
},
{
"type": "node",
"id": 5414987609,
"lat": 48.7994205,
"lon": 9.0171999,
"tags": {
"entrance": "main"
}
}
]
}
}
]
}
Documentation
¶
Index ¶
- type BoundingBox
- type Config
- type DecoderType
- type Gosmonaut
- type Header
- type Member
- type Node
- type OSMEntity
- type OSMTags
- func (t *OSMTags) Get(key string) (string, bool)
- func (t *OSMTags) Has(key string) bool
- func (t *OSMTags) HasValue(key, val string) bool
- func (t *OSMTags) Len() int
- func (t *OSMTags) Map() map[string]string
- func (t OSMTags) MarshalJSON() ([]byte, error)
- func (t *OSMTags) Set(key, val string)
- func (t OSMTags) String() string
- type OSMType
- type OSMTypeSet
- type Relation
- type Way
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BoundingBox ¶ added in v1.1.0
BoundingBox defines a rectangular area of coordinates.
type Config ¶ added in v1.2.0
type Config struct {
// DebugMode prints duration and memory info and runs the garbage collector
// after every processing step if enabled.
DebugMode bool
// PrintWarnings prints warnings to stdout if enabled. Possible warnings
// include missing referenced entites or unsupported features.
PrintWarnings bool
// Set the number of processes that are used for decoding.
// If not set the amount of available logical CPUs will be used.
NumProcessors int
// Decoder sets the PBF blob decoder. Defaults to `FastDecoder`.
Decoder DecoderType
}
Config defines the configuration for Gosmonaut.
type DecoderType ¶ added in v1.2.0
type DecoderType int
DecoderType represents the decoder that is used for parsing PBF blob data.
const ( // FastDecoder is a custom implementation of the protobuf format. It is // optimized for decoding of PBF files. Rather than unmarshalling it streams // the entities and thus reduces GC overhead. The fast blob decoder lacks // support of some protobuf features which include groups and unpacked // varint arrays. It is supposed to fail when it encounters a feature it // doesn't support. FastDecoder DecoderType = iota // GoDecoder uses the official Golang Protobuf package. All protobuf // messages will be unmarshalled to temporary objects before processing. GoDecoder )
Order is important: First decoder is the default
type Gosmonaut ¶ added in v1.2.0
type Gosmonaut struct {
// contains filtered or unexported fields
}
Gosmonaut is responsible for decoding an OpenStreetMap pbf file. For creating an instance the NewGosmonaut() function must be used.
func NewGosmonaut ¶ added in v1.2.0
func NewGosmonaut(file io.ReadSeeker, config ...Config) (*Gosmonaut, error)
NewGosmonaut creates a new Gosmonaut instance and parses the meta information (Header) of the given file. Either zero or exactly one `Config` object must be passed.
func (*Gosmonaut) Next ¶ added in v1.2.0
Next returns the next decoded entity (x)or an error. If the error is io.EOF the file has successfully been decoded. If the error is not EOF decoding has been stopped due to another error.
func (*Gosmonaut) Start ¶ added in v1.2.0
func (g *Gosmonaut) Start( types OSMTypeSet, funcEntityNeeded func(OSMType, OSMTags) bool, )
Start starts the decoding process. The function call will block until the previous run has finished. Only types that are enabled in `types` will be sent to the caller. funcEntityNeeded will be called to determine if the caller needs a specific OSM entity. Found entities and encountered errors can be received by polling the Next() method.
type Header ¶ added in v1.1.0
type Header struct {
BoundingBox *BoundingBox
RequiredFeatures []string
OptionalFeatures []string
WritingProgram string
Source string
OsmosisReplicationTimestamp time.Time
OsmosisReplicationSequenceNumber int64
OsmosisReplicationBaseURL string
}
Header contains the meta information of the PBF file.
type Node ¶
Node represents an OSM node element. Lat and Lon have a precision of up to 7 decimals (OSM default).
func (Node) MarshalJSON ¶ added in v1.2.0
MarshalJSON prints the JSON representation of the node.
type OSMTags ¶ added in v1.2.0
type OSMTags []string // Alternating array of keys/values
OSMTags represents a key-value mapping for OSM tags.
func NewOSMTags ¶ added in v1.2.0
NewOSMTags creates new OSMTags and can be used if the number of tags is known.
func NewOSMTagsFromMap ¶ added in v1.2.0
NewOSMTagsFromMap creates new OSMTags that contains the tags from the given map.
func (*OSMTags) Get ¶ added in v1.2.0
Get returns the value for the given key or false if the key does not exist.
func (*OSMTags) HasValue ¶ added in v1.2.0
HasValue return true if the given key exists and its value is val.
func (OSMTags) MarshalJSON ¶ added in v1.2.0
MarshalJSON prints the JSON representation of the tags.
type OSMTypeSet ¶ added in v1.2.0
type OSMTypeSet uint8
OSMTypeSet is used to enable/disable OSM types.
func NewOSMTypeSet ¶ added in v1.2.0
func NewOSMTypeSet(nodes, ways, relations bool) OSMTypeSet
NewOSMTypeSet returns a new OSMTypeSet with the given types enabled/disabled.
func (*OSMTypeSet) Get ¶ added in v1.2.0
func (s *OSMTypeSet) Get(t OSMType) bool
Get returns true if the given type is enabled.
func (*OSMTypeSet) Set ¶ added in v1.2.0
func (s *OSMTypeSet) Set(t OSMType, enabled bool)
Set enables/disables the given type.
type Relation ¶
Relation represents an OSM relation element.
func (Relation) MarshalJSON ¶ added in v1.2.0
MarshalJSON prints the JSON representation of the relation.
type Way ¶
Way represents an OSM way element.
func (Way) MarshalJSON ¶ added in v1.2.0
MarshalJSON prints the JSON representation of the way.
Source Files
Directories