routingkit

Documentation

Overview

Package routingkit provides measures that calculate the cost of travelling between points on road networks. It relies on Open Street Map (OSM) files without the need for a server.

Example (CustomProfile)

The following code example shows how to create your own vehicle profile and use it with routingkit. It customizes the vehicle speed and makes it depend on the tags present. In this example the speed is fixed to a single value (defined in `customVehicleSpeedMapper`). Furthermore, only ways are allowed to be used by the `customVehicle` which have the highway tag and its value is motorway (defined in `customVehicleTagMapFilter`). Please refer to the OpenStreetMaps [documentation on ways][osm-docs] to learn more about [tags and their values][osm-ways]. [osm-docs]: https://wiki.openstreetmap.org/wiki/Way [osm-ways]: https://wiki.openstreetmap.org/wiki/Key:highway

package main

import (
	"fmt"

	goroutingkit "github.com/nextmv-io/go-routingkit/routingkit"
	"github.com/nextmv-io/sdk/route"
	"github.com/nextmv-io/sdk/route/routingkit"
)

func main() {
	fallbackMeasure := route.ScaleByPoint(route.HaversineByPoint(), 2.1)

	// Restricts ways to defined OSM way tags.
	filter := func(id int, tags map[string]string) bool {
		highway := tags["highway"]
		return highway == "motorway"
	}

	// Defines a speed per OSM way tag.
	speedMapper := func(_ int, tags map[string]string) int {
		return 10
	}

	// Defines the custom profile.
	p := goroutingkit.NewProfile(
		"customVehicle", // Profile name
		// TransportationMode, other values: BikeMode, PedestrianMode.
		goroutingkit.VehicleMode,
		// Prevent left turns, only for TransportationMode "VehicleMode".
		false,
		// Prevent U-turns, only for TransportationMode "VehicleMode".
		false,
		filter,
		speedMapper,
	)

	// Defines a routingkit measure using the custom profile.
	m, err := routingkit.DurationByPoint(
		"testdata/maryland.osm.pbf",
		1000,
		1<<30,
		p,
		fallbackMeasure,
	)
	if err != nil {
		panic(err)
	}
	cost := m.Cost(
		route.Point{-123.1041788, 43.9965908},
		route.Point{-123.0774532, 44.044393},
	)
	fmt.Println(int(cost))
}

Output:

12030

Index

• Variables
• func ByPoint(mapFile string, radius float64, cacheSize int64, profile routingkit.Profile, ...) (route.ByPoint, error)
• func DurationByPoint(mapFile string, radius float64, cacheSize int64, profile routingkit.Profile, ...) (route.ByPoint, error)
• func DurationMatrix(mapFile string, radius float64, srcs []route.Point, dests []route.Point, ...) (route.ByIndex, error)
• func Matrix(mapFile string, radius float64, srcs []route.Point, dests []route.Point, ...) (route.ByIndex, error)
• type ByIndexLoader
  • func (l ByIndexLoader) MarshalJSON() ([]byte, error)
  • func (l *ByIndexLoader) To() route.ByIndex
  • func (l *ByIndexLoader) UnmarshalJSON(b []byte) error
• type ByPointLoader
  • func (l ByPointLoader) MarshalJSON() ([]byte, error)
  • func (l *ByPointLoader) To() route.ByPoint
  • func (l *ByPointLoader) UnmarshalJSON(b []byte) error
• type ProfileLoader
  • func (l ProfileLoader) MarshalJSON() ([]byte, error)
  • func (l *ProfileLoader) To() routingkit.Profile
  • func (l *ProfileLoader) UnmarshalJSON(b []byte) error

Examples

• Package (CustomProfile)
• ByPoint
• DurationByPoint
• DurationMatrix
• Matrix

Variables

var Bike = routingkit.Bike

Bike constructs a bike routingkit profile.

var Car = routingkit.Car

Car constructs a car routingkit profile.

var Pedestrian = routingkit.Pedestrian

Pedestrian constructs a pedestrian routingkit profile.

var Truck = routingkit.Truck

Truck constructs a truck routingkit profile.

Functions

func ByPoint

func ByPoint(
	mapFile string,
	radius float64,
	cacheSize int64,
	profile routingkit.Profile,
	m route.ByPoint,
) (route.ByPoint, error)

ByPoint constructs a route.ByPoint that computes the road network distance connecting any two points found within the provided mapFile. It needs a radius in which points can be snapped to the road network, a cache size in bytes (1 << 30 = 1 GB), a profile and a measure that is used in case no travel time can be computed.

Example

package main

import (
	"fmt"

	"github.com/nextmv-io/sdk/route"
	"github.com/nextmv-io/sdk/route/routingkit"
)

func main() {
	carProfile := routingkit.Car()
	fallbackMeasure := route.ScaleByPoint(route.HaversineByPoint(), 1.3)
	byPointDistance, err := routingkit.ByPoint(
		"testdata/maryland.osm.pbf",
		1000,
		1<<30,
		carProfile,
		fallbackMeasure,
	)
	if err != nil {
		panic(err)
	}
	cost := byPointDistance.Cost(
		route.Point{-123.1041788, 43.9965908},
		route.Point{-123.0774532, 44.044393},
	)
	fmt.Println(int(cost))
}

Output:

7447

func DurationByPoint

func DurationByPoint(
	mapFile string,
	radius float64,
	cacheSize int64,
	profile routingkit.Profile,
	m route.ByPoint,
) (route.ByPoint, error)

DurationByPoint is a measure that uses routingkit to calculate car travel times between given points. It needs a .osm.pbf map file, a radius in which points can be snapped to the road network, a cache size in bytes (1 << 30 = 1 GB), a profile and a measure that is used in case no travel time can be computed.

Example

package main

import (
	"fmt"

	"github.com/nextmv-io/sdk/route"
	"github.com/nextmv-io/sdk/route/routingkit"
)

func main() {
	carProfile := routingkit.Car()
	fallbackMeasure := route.ScaleByPoint(route.HaversineByPoint(), 1.2)
	byPointDuration, err := routingkit.DurationByPoint(
		"testdata/maryland.osm.pbf",
		1000,
		1<<30,
		carProfile,
		fallbackMeasure,
	)
	if err != nil {
		panic(err)
	}
	cost := byPointDuration.Cost(
		route.Point{-123.1041788, 43.9965908},
		route.Point{-123.0774532, 44.044393},
	)
	fmt.Println(int(cost))
}

Output:

6874

func DurationMatrix

func DurationMatrix(
	mapFile string,
	radius float64,
	srcs []route.Point,
	dests []route.Point,
	profile routingkit.Profile,
	m route.ByPoint,
) (route.ByIndex, error)

DurationMatrix uses the provided mapFile to construct a route.ByIndex that can find the road network durations between any point in srcs and any point in dests. In addition to the mapFile, srcs and dests it needs a radius in which points can be snapped to the road network, a profile and a measure that is used in case no travel durations can be computed.

Example

package main

import (
	"fmt"

	"github.com/nextmv-io/sdk/route"
	"github.com/nextmv-io/sdk/route/routingkit"
)

func main() {
	srcs := []route.Point{
		{-123.1041788, 43.9965908},
		{-123.1117056, 44.0568198},
	}
	dests := []route.Point{
		{-123.0774532, 44.044393},
		{-123.0399395, 44.0276874},
	}
	fallbackMeasure := route.ScaleByPoint(route.HaversineByPoint(), 1.2)
	byIndexDistance, err := routingkit.DurationMatrix(
		"testdata/maryland.osm.pbf",
		1000,
		srcs,
		dests,
		routingkit.Car(),
		fallbackMeasure,
	)
	if err != nil {
		panic(err)
	}
	cost := byIndexDistance.Cost(0, 1)
	fmt.Println(int(cost))
}

Output:

7431

func Matrix

func Matrix(
	mapFile string,
	radius float64,
	srcs []route.Point,
	dests []route.Point,
	profile routingkit.Profile,
	m route.ByPoint,
) (route.ByIndex, error)

Matrix uses the provided mapFile to construct a route.ByIndex that can find the road network distance between any point in srcs and any point in dests. In addition to the mapFile, srcs and dests it needs a radius in which points can be snapped to the road network, a profile and a measure that is used in case no distances can be computed.

Example

package main

import (
	"fmt"

	"github.com/nextmv-io/sdk/route"
	"github.com/nextmv-io/sdk/route/routingkit"
)

func main() {
	srcs := []route.Point{
		{-123.1041788, 43.9965908},
		{-123.1117056, 44.0568198},
	}
	dests := []route.Point{
		{-123.0774532, 44.044393},
		{-123.0399395, 44.0276874},
	}
	fallbackMeasure := route.ScaleByPoint(route.HaversineByPoint(), 1.3)
	byIndexDistance, err := routingkit.Matrix(
		"testdata/maryland.osm.pbf",
		1000,
		srcs,
		dests,
		routingkit.Car(),
		fallbackMeasure,
	)
	if err != nil {
		panic(err)
	}
	cost := byIndexDistance.Cost(0, 1)
	fmt.Println(int(cost))
}

Output:

8050

Types

type ByIndexLoader

type ByIndexLoader struct {
	// contains filtered or unexported fields
}

ByIndexLoader can be embedded in schema structs and unmarshals a ByIndex JSON object into the appropriate implementation, including a routingkit.ByIndex.

func (ByIndexLoader) MarshalJSON

func (l ByIndexLoader) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON representation for the underlying ByIndex.

func (*ByIndexLoader) To

func (l *ByIndexLoader) To() route.ByIndex

To returns the underlying ByIndex.

func (*ByIndexLoader) UnmarshalJSON

func (l *ByIndexLoader) UnmarshalJSON(b []byte) error

UnmarshalJSON converts the bytes into the appropriate implementation of ByIndex.

type ByPointLoader

type ByPointLoader struct {
	// contains filtered or unexported fields
}

ByPointLoader can be embedded in schema structs and unmarshals a ByPoint JSON object into the appropriate implementation, including a routingkit.ByPoint.

func (ByPointLoader) MarshalJSON

func (l ByPointLoader) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON representation for the underlying ByPoint.

func (*ByPointLoader) To

func (l *ByPointLoader) To() route.ByPoint

To returns the underlying ByPoint.

func (*ByPointLoader) UnmarshalJSON

func (l *ByPointLoader) UnmarshalJSON(b []byte) error

UnmarshalJSON converts the bytes into the appropriate implementation of ByPoint.

type ProfileLoader

type ProfileLoader struct {
	// contains filtered or unexported fields
}

ProfileLoader can be embedded in schema structs and unmarshals a routingkit.Profile JSON object into the appropriate implementation.

func (ProfileLoader) MarshalJSON

func (l ProfileLoader) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON representation for the underlying Profile.

func (*ProfileLoader) To

func (l *ProfileLoader) To() routingkit.Profile

To returns the underlying Profile.

func (*ProfileLoader) UnmarshalJSON

func (l *ProfileLoader) UnmarshalJSON(b []byte) error

UnmarshalJSON converts the bytes into the appropriate implementation of Profile.