sm

package module
v0.0.0-...-deb85ab Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 25, 2021 License: MIT Imports: 25 Imported by: 0

README

PkgGoDev Go Report Card golang/static License MIT

go-staticmaps

A go (golang) library and command line tool to render static map images using OpenStreetMap tiles.

What?

go-staticmaps is a golang library that allows you to create nice static map images from OpenStreetMap tiles, along with markers of different size and color, as well as paths and colored areas.

go-staticmaps comes with a command line tool called create-static-map for use in shell scripts, etc.

Static map of the Berlin Marathon

How?

Installation

Installing go-staticmaps is as easy as

go get -u github.com/flopp/go-staticmaps

For the command line tool, use

go get -u github.com/flopp/go-staticmaps/create-static-map

Of course, your local Go installation must be setup up properly.

Library Usage

Create a 400x300 pixel map with a red marker:

import (
  "image/color"

  "github.com/flopp/go-staticmaps"
  "github.com/fogleman/gg"
  "github.com/golang/geo/s2"
)

func main() {
  ctx := sm.NewContext()
  ctx.SetSize(400, 300)
  ctx.AddMarker(sm.NewMarker(s2.LatLngFromDegrees(52.514536, 13.350151), color.RGBA{0xff, 0, 0, 0xff}, 16.0))

  img, err := ctx.Render()
  if err != nil {
    panic(err)
  }

  if err := gg.SavePNG("my-map.png", img); err != nil {
    panic(err)
  }
}

See PkgGoDev for a complete documentation and the source code of the command line tool for an example how to use the package.

Command Line Usage
Usage:
  create-static-map [OPTIONS]

Creates a static map

Application Options:
      --width=PIXELS       Width of the generated static map image (default: 512)
      --height=PIXELS      Height of the generated static map image (default: 512)
  -o, --output=FILENAME    Output file name (default: map.png)
  -t, --type=MAPTYPE       Select the map type; list possible map types with '--type list'
  -c, --center=LATLNG      Center coordinates (lat,lng) of the static map
  -z, --zoom=ZOOMLEVEL     Zoom factor
  -b, --bbox=NW_LATLNG|SE_LATLNG
                           Set the bounding box (NW_LATLNG = north-western point of the
                           bounding box, SW_LATLNG = southe-western point of the bounding
                           box)
  --background=COLOR       Background color (default: transparent)
  -u, --useragent=USERAGENT
                           Overwrite the default HTTP user agent string
  -m, --marker=MARKER      Add a marker to the static map
  -p, --path=PATH          Add a path to the static map
  -a, --area=AREA          Add an area to the static map
  -C, --circle=CIRCLE      Add a circle to the static map

Help Options:
  -h, --help               Show this help message
General

The command line interface tries to resemble Google's Static Maps API. If neither --bbox, --center, nor --zoom are given, the map extent is determined from the specified markers, paths and areas.

--background lets you specify a color used for map areas that are not covered by map tiles (areas north of 85°/south of -85°).

Markers

The --marker option defines one or more map markers of the same style. Use multiple --marker options to add markers of different styles.

--marker MARKER_STYLES|LATLNG|LATLNG|...

LATLNG is a comma separated pair of latitude and longitude, e.g. 52.5153,13.3564.

MARKER_STYLES consists of a set of style descriptors separated by the pipe character |:

  • color:COLOR - where COLOR is either of the form 0xRRGGBB, 0xRRGGBBAA, or one of black, blue, brown, green, orange, purple, red, yellow, white (default: red)
  • size:SIZE - where SIZE is one of mid, small, tiny, or some number > 0 (default: mid)
  • label:LABEL - where LABEL is an alpha numeric character, i.e. A-Z, a-z, 0-9; (default: no label)
  • labelcolor:COLOR - where COLOR is either of the form 0xRRGGBB, 0xRRGGBBAA, or one of black, blue, brown, green, orange, purple, red, yellow, white (default: black or white, depending on the marker color)
Paths

The --path option defines a path on the map. Use multiple --path options to add multiple paths to the map.

--path PATH_STYLES|LATLNG|LATLNG|...

or

--path PATH_STYLES|gpx:my_gpx_file.gpx

PATH_STYLES consists of a set of style descriptors separated by the pipe character |:

  • color:COLOR - where COLOR is either of the form 0xRRGGBB, 0xRRGGBBAA, or one of black, blue, brown, green, orange, purple, red, yellow, white (default: red)
  • weight:WEIGHT - where WEIGHT is the line width in pixels (defaut: 5)
Areas

The --area option defines a closed area on the map. Use multiple --area options to add multiple areas to the map.

--area AREA_STYLES|LATLNG|LATLNG|...

AREA_STYLES consists of a set of style descriptors separated by the pipe character |:

  • color:COLOR - where COLOR is either of the form 0xRRGGBB, 0xRRGGBBAA, or one of black, blue, brown, green, orange, purple, red, yellow, white (default: red)
  • weight:WEIGHT - where WEIGHT is the line width in pixels (defaut: 5)
  • fill:COLOR - where COLOR is either of the form 0xRRGGBB, 0xRRGGBBAA, or one of black, blue, brown, green, orange, purple, red, yellow, white (default: none)
Circles

The --circles option defines one or more circles of the same style. Use multiple --circle options to add circles of different styles.

--circle CIRCLE_STYLES|LATLNG|LATLNG|...

LATLNG is a comma separated pair of latitude and longitude, e.g. 52.5153,13.3564.

CIRCLE_STYLES consists of a set of style descriptors separated by the pipe character |:

  • color:COLOR - where COLOR is either of the form 0xRRGGBB, 0xRRGGBBAA, or one of black, blue, brown, green, orange, purple, red, yellow, white (default: red)
  • fill:COLOR - where COLOR is either of the form 0xRRGGBB, 0xRRGGBBAA, or one of black, blue, brown, green, orange, purple, red, yellow, white (default: no fill color)
  • radius:RADIUS - where RADIUS is te circle radius in meters (default: 100.0)
  • weight:WEIGHT - where WEIGHT is the line width in pixels (defaut: 5)

Examples

Basic Maps

Centered at "N 52.514536 E 13.350151" with zoom level 10:

$ create-static-map --width 600 --height 400 -o map1.png -c "52.514536,13.350151" -z 10

Example 1

A map with a marker at "N 52.514536 E 13.350151" with zoom level 14 (no need to specify the map's center - it is automatically computed from the marker(s)):

$ create-static-map --width 600 --height 400 -o map2.png -z 14 -m "52.514536,13.350151"

Example 2

A map with two markers (red and green). If there are more than two markers in the map, a good zoom level can be determined automatically:

$ create-static-map --width 600 --height 400 -o map3.png -m "color:red|52.514536,13.350151" -m "color:green|52.516285,13.377746"

Example 3

Create a map of the Berlin Marathon
create-static-map --width 800 --height 600 \
  --marker "color:green|52.5153,13.3564" \
  --marker "color:red|52.5160,13.3711" \
  --output "berlin-marathon.png" \
  --path "color:blue|weight:2|gpx:berlin-marathon.gpx"

Static map of the Berlin Marathon

Create a map of the US capitals
create-static-map --width 800 --height 400 \
  --output "us-capitals.png" \
  --marker "color:blue|size:tiny|32.3754,-86.2996|58.3637,-134.5721|33.4483,-112.0738|34.7244,-92.2789|\
    38.5737,-121.4871|39.7551,-104.9881|41.7665,-72.6732|39.1615,-75.5136|30.4382,-84.2806|33.7545,-84.3897|\
    21.2920,-157.8219|43.6021,-116.2125|39.8018,-89.6533|39.7670,-86.1563|41.5888,-93.6203|39.0474,-95.6815|\
    38.1894,-84.8715|30.4493,-91.1882|44.3294,-69.7323|38.9693,-76.5197|42.3589,-71.0568|42.7336,-84.5466|\
    44.9446,-93.1027|32.3122,-90.1780|38.5698,-92.1941|46.5911,-112.0205|40.8136,-96.7026|39.1501,-119.7519|\
    43.2314,-71.5597|40.2202,-74.7642|35.6816,-105.9381|42.6517,-73.7551|35.7797,-78.6434|46.8084,-100.7694|\
    39.9622,-83.0007|35.4931,-97.4591|44.9370,-123.0272|40.2740,-76.8849|41.8270,-71.4087|34.0007,-81.0353|\
    44.3776,-100.3177|36.1589,-86.7821|30.2687,-97.7452|40.7716,-111.8882|44.2627,-72.5716|37.5408,-77.4339|\
    47.0449,-122.9016|38.3533,-81.6354|43.0632,-89.4007|41.1389,-104.8165"

Static map of the US capitals

Create a map of Australia

...where the Northern Territory is highlighted and the capital Canberra is marked.

create-static-map --width 800 --height 600 \
  --center="-26.284973,134.303764" \
  --output "australia.png" \
  --marker "color:blue|-35.305200,149.121574" \
  --area "color:0x00FF00|fill:0x00FF007F|weight:2|-25.994024,129.013847|-25.994024,137.989677|-16.537670,138.011649|\
    -14.834820,135.385917|-12.293236,137.033866|-11.174554,130.398124|-12.925791,130.167411|-14.866678,129.002860"

Static map of Australia

Acknowledgements

Besides the go standard library, go-staticmaps uses

Contributors

  • Kooper: fixed library usage examples
  • felix: added more tile servers
  • wiless: suggested to add user definable marker label colors
  • noki: suggested to add a user definable bounding box
  • digitocero: reported and fixed type mismatch error
  • bcicen: reported and fixed syntax error in examples
  • pshevtsov: fixed drawing of empty attribution strings
  • Luzifer: added overwritable user agent strings to comply with the OSM tile usage policy
  • Jason Fox: added RenderWithBounds function
  • Alexander A. Kapralov: initial circles implementation
  • tsukumaru: added NewArea and NewPath functions

License

Copyright 2016, 2017 Florian Pigorsch & Contributors. All rights reserved.

Use of this source code is governed by a MIT-style license that can be found in the LICENSE file.

Documentation

Overview

Package sm (~ static maps) renders static map images from OSM tiles with markers, paths, and filled areas.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CanDisplay 

func CanDisplay(pos s2.LatLng) bool

CanDisplay checks if pos is generally displayable (i.e. its latitude is in [-85,85])

func CreateBBox 

func CreateBBox(nwlat float64, nwlng float64, selat float64, selng float64) (*s2.Rect, error)

CreateBBox creates a bounding box from a north-western point (lat/lng in degrees) and a south-eastern point (lat/lng in degrees). Note that you can create a bounding box wrapping over the antimeridian at lng=+-/180° by nwlng > selng.

func GetTileProviders 

func GetTileProviders() map[string]*TileProvider

GetTileProviders returns a map of all available TileProviders

func Luminance 

func Luminance(col color.Color) float64

Luminance computes the luminance (~ brightness) of the given color. Range: 0.0 for black to 1.0 for white.

func ParseColorString 

func ParseColorString(s string) (color.Color, error)

ParseColorString parses hex color strings (i.e. `0xRRGGBB`, `#RRGGBB`, `0xRRGGBBAA`, `#RRGGBBAA`), and names colors (e.g. 'black', 'blue', ...)

Types

type Area 

type Area struct {
	MapObject
	Positions []s2.LatLng
	Color     color.Color
	Fill      color.Color
	Weight    float64
}

Area represents a area or area on the map

func NewArea 

func NewArea(positions []s2.LatLng, col color.Color, fill color.Color, weight float64) *Area

NewArea creates a new Area

func ParseAreaString 

func ParseAreaString(s string) (*Area, error)

ParseAreaString parses a string and returns an area

func (*Area) Bounds 

func (p *Area) Bounds() s2.Rect

func (*Area) Draw 

func (p *Area) Draw(gc *gg.Context, trans *Transformer)

func (*Area) ExtraMarginPixels 

func (p *Area) ExtraMarginPixels() float64

type Circle 

type Circle struct {
	MapObject
	Position s2.LatLng
	Color    color.Color
	Fill     color.Color
	Weight   float64
	Radius   float64 // in m.
}

Circle represents a circle on the map

func NewCircle 

func NewCircle(pos s2.LatLng, col, fill color.Color, radius, weight float64) *Circle

NewCircle creates a new circle

func ParseCircleString 

func ParseCircleString(s string) (circles []*Circle, err error)

ParseCircleString parses a string and returns an array of circles

func (*Circle) Bounds 

func (m *Circle) Bounds() s2.Rect

func (*Circle) Draw 

func (m *Circle) Draw(gc *gg.Context, trans *Transformer)

func (*Circle) ExtraMarginPixels 

func (m *Circle) ExtraMarginPixels() float64

type Context 

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

Context holds all information about the map image that is to be rendered

func NewContext 

func NewContext() *Context

NewContext creates a new instance of Context

func (*Context) AddArea 

func (m *Context) AddArea(area *Area)

AddArea adds an area to the Context

func (*Context) AddCircle 

func (m *Context) AddCircle(circle *Circle)

AddCircle adds an circle to the Context

func (*Context) AddCustomObject 

func (m *Context) AddCustomObject(object MapObject)

AddCustomObject adds a custom object to the Context

func (*Context) AddMarker 

func (m *Context) AddMarker(marker *Marker)

AddMarker adds a marker to the Context

func (*Context) AddOverlay 

func (m *Context) AddOverlay(overlay *TileProvider)

AddOverlay adds an overlay to the Context

func (*Context) AddPath 

func (m *Context) AddPath(path *Path)

AddPath adds a path to the Context

func (*Context) ClearAreas 

func (m *Context) ClearAreas()

ClearAreas removes all areas from the Context

func (*Context) ClearCircles 

func (m *Context) ClearCircles()

ClearCircles removes all circles from the Context

func (*Context) ClearCustomObjects 

func (m *Context) ClearCustomObjects()

ClearCustomObjects removes all custom objects from the Context

func (*Context) ClearMarkers 

func (m *Context) ClearMarkers()

ClearMarkers removes all markers from the Context

func (*Context) ClearOverlays 

func (m *Context) ClearOverlays()

ClearOverlays removes all overlays from the Context

func (*Context) ClearPaths 

func (m *Context) ClearPaths()

ClearPaths removes all paths from the Context

func (*Context) DetermineBounds 

func (m *Context) DetermineBounds() s2.Rect

func (*Context) OverrideAttribution 

func (m *Context) OverrideAttribution(attribution string)

OverrideAttribution sets a custom attribution string (or none if empty)

Pay attention you might be violating the terms of usage for the selected map provider - only use the function if you are aware of this!

func (*Context) Render 

func (m *Context) Render() (image.Image, error)

Render actually renders the map image including all map objects (markers, paths, areas)

func (*Context) RenderWithBounds 

func (m *Context) RenderWithBounds() (image.Image, s2.Rect, error)

RenderWithBounds actually renders the map image including all map objects (markers, paths, areas). The returned image covers requested area as well as any tiles necessary to cover that area, which may be larger than the request.

Specific bounding box of returned image is provided to support image registration with other data

func (*Context) RenderWithTransformer 

func (m *Context) RenderWithTransformer() (image.Image, *Transformer, error)

RenderWithTransformer actually renders the map image including all map objects (markers, paths, areas). The returned image covers requested area as well as any tiles necessary to cover that area, which may be larger than the request.

A Transformer is returned to support image registration with other data.

func (*Context) SetBackground 

func (m *Context) SetBackground(col color.Color)

SetBackground sets the background color (used as a fallback for areas without map tiles)

func (*Context) SetBoundingBox 

func (m *Context) SetBoundingBox(bbox s2.Rect)

SetBoundingBox sets the bounding box

func (*Context) SetCache 

func (m *Context) SetCache(cache TileCache)

SetCache takes a nil argument to disable caching

func (*Context) SetCenter 

func (m *Context) SetCenter(center s2.LatLng)

SetCenter sets the center coordinates

func (*Context) SetSize 

func (m *Context) SetSize(width, height int)

SetSize sets the size of the generated image

func (*Context) SetTileProvider 

func (m *Context) SetTileProvider(t *TileProvider)

SetTileProvider sets the TileProvider to be used

func (*Context) SetUserAgent 

func (m *Context) SetUserAgent(a string)

SetUserAgent sets the HTTP user agent string used when downloading map tiles

func (*Context) SetZoom 

func (m *Context) SetZoom(zoom int)

SetZoom sets the zoom level

func (*Context) Transformer 

func (m *Context) Transformer() (*Transformer, error)

Transformer returns an initialized Transformer instance.

type MapObject 

type MapObject interface {
	Bounds() s2.Rect
	ExtraMarginPixels() float64
	Draw(dc *gg.Context, trans *Transformer)
}

MapObject is the interface for all objects on the map

type Marker 

type Marker struct {
	MapObject
	Position   s2.LatLng
	Color      color.Color
	Size       float64
	Label      string
	LabelColor color.Color
}

Marker represents a marker on the map

func NewMarker 

func NewMarker(pos s2.LatLng, col color.Color, size float64) *Marker

NewMarker creates a new Marker

func ParseMarkerString 

func ParseMarkerString(s string) ([]*Marker, error)

ParseMarkerString parses a string and returns an array of markers

func (*Marker) Bounds 

func (m *Marker) Bounds() s2.Rect

func (*Marker) Draw 

func (m *Marker) Draw(gc *gg.Context, trans *Transformer)

func (*Marker) ExtraMarginPixels 

func (m *Marker) ExtraMarginPixels() float64

func (*Marker) SetLabelColor 

func (m *Marker) SetLabelColor(col color.Color)

SetLabelColor sets the color of the marker's text label

type Path 

type Path struct {
	MapObject
	Positions []s2.LatLng
	Color     color.Color
	Weight    float64
}

Path represents a path or area on the map

func NewPath 

func NewPath(positions []s2.LatLng, col color.Color, weight float64) *Path

NewPath creates a new Path

func ParsePathString 

func ParsePathString(s string) ([]*Path, error)

ParsePathString parses a string and returns a path

func (*Path) Bounds 

func (p *Path) Bounds() s2.Rect

func (*Path) Draw 

func (p *Path) Draw(gc *gg.Context, trans *Transformer)

func (*Path) ExtraMarginPixels 

func (p *Path) ExtraMarginPixels() float64

type TileCache 

type TileCache interface {
	// Root path to store cached tiles in with no trailing slash.
	Path() string
	// Permission to set when creating missing cache directories.
	Perm() os.FileMode
}

TileCache provides cache information to the tile fetcher

type TileCacheStaticPath 

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

TileCacheStaticPath provides a static path to the tile fetcher.

func NewTileCache 

func NewTileCache(rootPath string, perm os.FileMode) *TileCacheStaticPath

NewTileCache stores cache files in a static path.

func NewTileCacheFromUserCache 

func NewTileCacheFromUserCache(perm os.FileMode) *TileCacheStaticPath

NewTileCacheFromUserCache stores cache files in a user-specific cache directory.

func (*TileCacheStaticPath) Path 

func (c *TileCacheStaticPath) Path() string

Path to the cache.

func (*TileCacheStaticPath) Perm 

func (c *TileCacheStaticPath) Perm() os.FileMode

Perm instructs the permission to set when creating missing cache directories.

type TileFetcher 

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

TileFetcher downloads map tile images from a TileProvider

func NewTileFetcher 

func NewTileFetcher(tileProvider *TileProvider, cache TileCache) *TileFetcher

NewTileFetcher creates a new Tilefetcher struct

func (*TileFetcher) Fetch 

func (t *TileFetcher) Fetch(zoom, x, y int) (image.Image, error)

Fetch download (or retrieves from the cache) a tile image for the specified zoom level and tile coordinates

func (*TileFetcher) SetUserAgent 

func (t *TileFetcher) SetUserAgent(a string)

SetUserAgent sets the HTTP user agent string used when downloading map tiles

type TileProvider 

type TileProvider struct {
	Name           string
	Attribution    string
	IgnoreNotFound bool
	TileSize       int
	URLPattern     string // "%[1]s" => shard, "%[2]d" => zoom, "%[3]d" => x, "%[4]d" => y
	Shards         []string
}

TileProvider encapsulates all infos about a map tile provider service (name, url scheme, attribution, etc.)

func NewTileProviderArcgisWorldImagery 

func NewTileProviderArcgisWorldImagery() *TileProvider

NewTileProviderArcgisWorldImagery creates a TileProvider struct for Arcgis' WorldImagery tiles

func NewTileProviderCartoDark 

func NewTileProviderCartoDark() *TileProvider

NewTileProviderCartoDark creates a TileProvider struct for Carto's tile service (dark variant)

func NewTileProviderCartoLight 

func NewTileProviderCartoLight() *TileProvider

NewTileProviderCartoLight creates a TileProvider struct for Carto's tile service (light variant)

func NewTileProviderOpenCycleMap 

func NewTileProviderOpenCycleMap() *TileProvider

NewTileProviderOpenCycleMap creates a TileProvider struct for OpenCycleMap's tile service

func NewTileProviderOpenStreetMaps 

func NewTileProviderOpenStreetMaps() *TileProvider

NewTileProviderOpenStreetMaps creates a TileProvider struct for OSM's tile service

func NewTileProviderOpenTopoMap 

func NewTileProviderOpenTopoMap() *TileProvider

NewTileProviderOpenTopoMap creates a TileProvider struct for opentopomap's tile service

func NewTileProviderStamenTerrain 

func NewTileProviderStamenTerrain() *TileProvider

NewTileProviderStamenTerrain creates a TileProvider struct for stamens' 'terrain' tile service

func NewTileProviderStamenToner 

func NewTileProviderStamenToner() *TileProvider

NewTileProviderStamenToner creates a TileProvider struct for stamens' 'toner' tile service

func NewTileProviderThunderforestLandscape 

func NewTileProviderThunderforestLandscape() *TileProvider

NewTileProviderThunderforestLandscape creates a TileProvider struct for thundeforests's 'landscape' tile service

func NewTileProviderThunderforestOutdoors 

func NewTileProviderThunderforestOutdoors() *TileProvider

NewTileProviderThunderforestOutdoors creates a TileProvider struct for thundeforests's 'outdoors' tile service

func NewTileProviderThunderforestTransport 

func NewTileProviderThunderforestTransport() *TileProvider

NewTileProviderThunderforestTransport creates a TileProvider struct for thundeforests's 'transport' tile service

func NewTileProviderWikimedia 

func NewTileProviderWikimedia() *TileProvider

NewTileProviderWikimedia creates a TileProvider struct for Wikimedia's tile service

type Transformer 

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

Transformer implements coordinate transformation from latitude longitude to image pixel coordinates.

func (*Transformer) LatLngToXY 

func (t *Transformer) LatLngToXY(ll s2.LatLng) (float64, float64)

LatLngToXY transforms a latitude longitude pair into image x, y coordinates.

func (*Transformer) Rect 

func (t *Transformer) Rect() (bbox s2.Rect)

Rect returns an s2.Rect bounding box around the set of tiles described by Transformer.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.