README
¶
#tiles 
A map tiling library written in pure Go with no external dependencies outside of the golang stdlib. Converts between WGS84 coordinates to Slippy Map Tiles and Quadkeys. Includes a TileIndex that can be used to aggregate data into parent tiles.
go get github.com/buckhx/tiles
The godoc has good documentation and a couple examples, but here are a few as well
Coordinate/Tile conversion
// Empire State Build coordinates and zoom level 18
z := 18
lat := 40.7484
lon := -73.9857
// Basic usage
t1 := tiles.FromCoordinate(lat, lon, z)
// If you want a little more granularity
x := tiles.Coordinate{Lat: lat, Lon: lon}
p := x.ToPixel(z)
t2, _ := p.ToTile()
// t1 == t2
TileIndex
The TileIndex allows for data to be indexed by tiles and aggregated up to their parents when requested
idx := tiles.NewTileIndex()
esb := tiles.FromCoordinate(40.7484, -73.9857, 18)
sol := tiles.FromCoordinate(40.6892, -74.0445, 18)
bbn := tiles.FromCoordinate(51.5007, -0.1246, 18)
idx.Add(esb, "EmpireStateBuilding")
idx.Add(sol, "StatueOfLiberty")
idx.Add(bbn, "BigBen")
nyc := tiles.Tile{X: 75, Y: 96, Z: 8}
den := tiles.Tile{X: 106, Y: 194, Z: 9}
fmt.Println("ESB Tile: ", idx.Values(esb))
fmt.Println("SOL Tile: ", idx.Values(sol))
fmt.Println("NYC Tile: ", idx.Values(nyc)) //contains esb & sol values!
fmt.Println("DENVER Tile: ", idx.Values(den)) //contains no values!
Benchmarks
Here are some microbenchmarks for converting a location at zoom level 18. There's nothing really to compare them to, but should give a sense of op time on a 2.3 GHz core i7 MBP.
$ go test -bench=. -benchmem -benchtime 10s
BenchmarkTileFromCoordinate-8 100000000 165 ns/op 0 B/op 0 allocs/op
BenchmarkTileFromQuadkey-8 300000000 43.7 ns/op 0 B/op 0 allocs/op
BenchmarkQuadkeyFromTile-8 200000000 95.4 ns/op 32 B/op 1 allocs/op
Documentation
¶
Overview ¶
Package tiles is a collection of conversion utilities to go between geo/pixel/tile/quadkey space This package uses WGS84 coordinates and a mercator projection There is also a TileIndex which can be used to store data in a single place and aggregate when needed
Index ¶
Examples ¶
Constants ¶
const ( MinLat float64 = -85.05112878 MaxLat float64 = 85.05112878 MinLon float64 = -180 MaxLon float64 = 180 EarthRadiusM float64 = 6378137 )
Earth Parameters
const ZMax = 23
ZMax is the maximum Z coordinate for a tile as well as quadkey level
Variables ¶
var TileSize = 256
TileSize is the size in pixels of each tile. It can be tuned at the package level.
Functions ¶
This section is empty.
Types ¶
type Coordinate ¶
type Coordinate struct {
Lat, Lon float64
}
Coordinate is a simple struct for hold WGS-84 Lat Lon coordinates in degrees
func ClippedCoords ¶
func ClippedCoords(lat, lon float64) Coordinate
ClippedCoords that have been clipped to Max/Min Lat/Lon This can be used as a constructor to assert bad values will be clipped
func (Coordinate) Equals ¶
func (c Coordinate) Equals(that Coordinate) bool
Equals checks if these coords are equal avoiding some float precision
func (Coordinate) String ¶
func (c Coordinate) String() string
func (Coordinate) ToPixel ¶
func (c Coordinate) ToPixel(zoom int) Pixel
ToPixel gets the Pixel of the coord at the zoom level
type KeysetIndex ¶
KeysetIndex is a TileIndex implementation that uses a sorted keyset. A trie would be more efficient, but KeysetIndex mirrors the range queries of boltdb which could be dropped in if the entire index won't fit in memory. KeysetIndex is thread safe
func (*KeysetIndex) Add ¶
func (idx *KeysetIndex) Add(t Tile, val ...interface{})
Add adds a value, but will not be indexed
func (*KeysetIndex) TileRange ¶
func (idx *KeysetIndex) TileRange(zmin, zmax int) <-chan Tile
TileRange returns a channel of all tiles in the index in the zoom range If zmax is greater than the deepest tile level, the deepest tile level returns Acquires a readlock for duration of returned channel being open
func (*KeysetIndex) Values ¶
func (idx *KeysetIndex) Values(t Tile) (vals []interface{})
Values returns a list of values aggregated under the requested tile
type Pixel ¶
type Pixel struct {
X, Y, Z int
}
Pixel in a WGS84 Mercator map projection with a NW origin (0,0) of the projection
type Quadkey ¶
type Quadkey string
Quadkey represents a Bing Maps quadkey It can also be used as a quadtree data structure
func (Quadkey) Children ¶
Children returns a slice of the the Quadkeys in the next level of this tree
func (Quadkey) HasParent ¶
HasParent returns a true if o is a parent of q. If q == o, it return false
type SuffixIndex ¶
type SuffixIndex struct {
// contains filtered or unexported fields
}
SuffixIndex is a TileIndex that uses a suffixarray to lookup values It IS NOT currently safe for concurrent access.
func (*SuffixIndex) Add ¶
func (idx *SuffixIndex) Add(t Tile, v ...interface{})
Add adds a tile and values associated with it
func (*SuffixIndex) TileRange ¶
func (idx *SuffixIndex) TileRange(zmin, zmax int) <-chan Tile
TileRange returns all the tiles available in this index. It currently DOES NOT return unique values
func (*SuffixIndex) Values ¶
func (idx *SuffixIndex) Values(t Tile) (vals []interface{})
Values returns all the values aggregated under the given tile
type Tile ¶
type Tile struct {
X, Y, Z int
}
Tile is a simple struct for holding the XYZ coordinates for use in mapping
func FromCoordinate ¶
FromCoordinate take float lat/lons and a zoom and return a tile Clips the coordinates if they are outside of Min/MaxLat/Lon
Example ¶
package main
import (
"fmt"
"github.com/buckhx/tiles"
)
func main() {
esbLat := 40.7484
esbLon := -73.9857
tile := tiles.FromCoordinate(esbLat, esbLon, 18)
fmt.Println(tile)
}
Output:
func FromQuadkeyString ¶
FromQuadkeyString returns a tile that represents the given quadkey string. Returns an error if quadkey string is invalid.
func (Tile) Quadkey ¶
Quadkey returns the string representation of a Bing Maps quadkey. See more https://msdn.microsoft.com/en-us/library/bb259689.aspx Panics if the tile is invalid or if it can't write to the internal buffer
func (Tile) ToPixelWithOffset ¶
ToPixelWithOffset returns a pixel at the origin with an offset added. Useful for getting the center pixel of a tile or another non-origin pixel.
type TileIndex ¶
type TileIndex interface {
TileRange(zmin, zmax int) <-chan Tile
Values(t Tile) (vals []interface{})
Add(t Tile, val ...interface{})
}
TileIndex stores indexes values by tile. If a deep level of tile is added and a shallower one is requested, the values are aggregated up.
Example ¶
idx := NewTileIndex()
esb := FromCoordinate(40.7484, -73.9857, 18)
sol := FromCoordinate(40.6892, -74.0445, 18)
bbn := FromCoordinate(51.5007, -0.1246, 18)
idx.Add(esb, "EmpireStateBuilding")
idx.Add(sol, "StatueOfLiberty")
idx.Add(bbn, "BigBen")
nyc := Tile{X: 75, Y: 96, Z: 8}
den := Tile{X: 106, Y: 194, Z: 9}
fmt.Println("ESB Tile: ", idx.Values(esb))
fmt.Println("SOL Tile: ", idx.Values(sol))
fmt.Println("NYC Tile: ", idx.Values(nyc)) //contains both values!
fmt.Println("DENVER Tile: ", idx.Values(den)) //contains no values!
Output: ESB Tile: [EmpireStateBuilding] SOL Tile: [StatueOfLiberty] NYC Tile: [EmpireStateBuilding StatueOfLiberty] DENVER Tile: []
Source Files