A library provides spatial data and geometric algorithms.

# Geoos
Our organization `spatial-go` is officially established! The first open source project `Geoos`(Using `Golang`) provides spatial data and geometric algorithms.
All comments and suggestions are welcome!

## Guides

http://www.spatial-go.com

## Contents
  - [Guides](#guides)
  - [Contents](#contents)
  - [Structure](#structure)
  - [Documentation](#documentation)
  - [Maintainer](#maintainer)
  - [Contributing](#contributing)
  - [License](#license)



## Structure
1.algorithm
Package algorithm defines Specifies Computational Geometric and algorithm err.
2.clusters
Package clusters is a spatial clustering algorithm.
3.coordtransform
Package coordtransform is for transform coord.
4.example
Example This is an example .
5.geoencoding
Package geoencoding is a library for encoding and decoding into Go structs using the geometries.
6.grid
Package grid is used to generate grid data.
7.index
Package index define spatial index interface.
8.planar
Package planar provides support for the implementation of spatial operations and geometric algorithms.
9.space
Package space A representation of a linear vector geometry.
10.utils
Package utils A functions of utils.

## Documentation
How to use `Geoos`:
Example: Calculating `area` via `Geoos`
```
package main

import (
	"bytes"
	"fmt"

	"github.com/spatial-go/geoos/geoencoding"
	"github.com/spatial-go/geoos/planar"
)

func main() {
	// First, choose the default algorithm.
	strategy := planar.NormalStrategy()
	// Secondly, manufacturing test data and convert it to geometry
	const polygon = `POLYGON((-1 -1, 1 -1, 1 1, -1 1, -1 -1))`
	// geometry, _ := wkt.UnmarshalString(polygon)

	buf0 := new(bytes.Buffer)
	buf0.Write([]byte(polygon))
	geometry, _ := geoencoding.Read(buf0, geoencoding.WKT)

	// Last， call the Area () method and get result.
	area, e := strategy.Area(geometry)
	if e != nil {
		fmt.Printf(e.Error())
	}
	fmt.Printf("%f", area)
	// get result 4.0
}
```
Example: geoencoding
[example_encoding.go](https://github.com/spatial-go/geoos/example/example_encoding.go)

## Maintainer

[@spatial-go](https://github.com/spatial-go)。

## Contributing

We will also uphold the concept of "openness, co-creation, and win-win" to contribute in the field of space computing.

Welcome to join us ！[please report an issue](https://github.com/spatial-go/geoos/issues/new)

Email Address： [geoos@changjing.ai](mailto:geoos@changjing.ai)

## License
`Geoos` is licensed under the:
[LGPL-2.1 ](LICENSE)

geoos

geoserver Is a Go Package For Manipulating a GeoServer Instance via the GeoServer REST API.

geoserver

Go bindings for H3, a hierarchical hexagonal geospatial indexing system.

<img align="right" src="https://uber.github.io/img/h3Logo-color.svg" alt="H3 Logo" width="200">

![Build](https://github.com/uber/h3-go/workflows/Build/badge.svg?branch=master)
[![Coverage Status](https://coveralls.io/repos/github/uber/h3-go/badge.svg)](https://coveralls.io/github/uber/h3-go)
[![Go Report Card](https://goreportcard.com/badge/github.com/uber/h3-go)](https://goreportcard.com/report/github.com/uber/h3-go)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![GoDoc](http://img.shields.io/badge/go-doc-blue.svg)](https://godoc.org/github.com/uber/h3-go)
[![H3 Version](https://img.shields.io/badge/h3-v3.7.0-blue.svg)](https://github.com/uber/h3/releases/tag/v3.7.0)

<h1 align="center">H3-Go is looking for a maintainer familiar with Go, C, and H3. Volunteers welcome! Please get in touch with us on the <a href="https://join.slack.com/t/h3-core/shared_invite/zt-g6u5r1hf-W_~uVJmfeiWtMQuBGc1NNg">H3 Slack</a>.</h1>

# H3-Go

This library provides Golang bindings for the
[H3 Core Library](https://github.com/uber/h3). For API reference, see the
[H3 Documentation](https://uber.github.io/h3/).

**This is v4 of this library, supporting H3 v4.**

Check out [v3](https://github.com/uber/h3-go/tree/v3.7.1) or checkout the git tag for the version you need.

**Migrating from v3?**

Check out [v3 to v4 migration guide](https://h3geo.org/docs/library/migrating-3.x).
There have been no breaking changes to the format of H3 indexes.  Indexes
generated by older versions can be parsed in v4, and vice-versa.

# Usage

## Prerequisites

H3-Go requires [CGO](https://golang.org/cmd/cgo/) (`CGO_ENABLED=1`) in order to
be built. Go should do the right thing when including this library:

> The cgo tool is enabled by default for native builds on systems where it is
> expected to work. It is disabled by default when cross-compiling. You can
> control this by setting the CGO_ENABLED environment variable when running the go
> tool: set it to 1 to enable the use of cgo, and to 0 to disable it. The go tool
> will set the build constraint "cgo" if cgo is enabled. The special import "C"
> implies the "cgo" build constraint, as though the file also said "// +build
> cgo". Therefore, if cgo is disabled, files that import "C" will not be built by
> the go tool. (For more about build constraints see
> <https://golang.org/pkg/go/build/#hdr-Build_Constraints>).

If you see errors/warnings like _"build constraints exclude all Go files..."_,
then the `cgo` build constraint is likely disabled; try setting `CGO_ENABLED=1`
environment variable in your `go build` step.

## Installation

```bash
go get github.com/uber/h3-go/v4
```

## Quickstart

```go
import "github.com/uber/h3-go/v4"

func ExampleLatLngToCell() {
 latLng := h3.NewLatLng(37.775938728915946, -122.41795063018799)
 resolution := 9 // between 0 (biggest cell) and 15 (smallest cell)

 cell := h3.LatLngToCell(latLng, resolution)

 fmt.Printf("%s", cell)
 // Output:
 // 8928308280fffff
}

```

# C API

## Notes

* `LatLng` returns `Lat` and `Lng` as degrees, instead of radians.
* H3 C API function prefixes of `get` have been dropped in support of Golang's
 `Getter` [naming style](https://golang.org/doc/effective_go.html#Getters).
* Convenience methods have been added to various types where that type was the
  main or only argument.

## Bindings

| C API                        | Go API                                             |
| ---------------------------- | -------------------------------------------------- |
| `latLngToCell`               | `LatLngToCell`, `LatLng#Cell`                      |
| `cellToLatLng`               | `CellToLatLng`, `Cell#LatLng`                      |
| `cellToBoundary`             | `CellToBoundary`, `Cell#Boundary`                  |
| `gridDisk`                   | `GridDisk`, `Cell#GridDisk`                        |
| `gridDiskDistances`          | `GridDiskDistances`, `Cell#GridDiskDistances`      |
| `gridRingUnsafe`             | N/A                                                |
| `polygonToCells`             | `PolygonToCells`, `GeoPolygon#Cells`               |
| `cellsToMultiPolygon`        | `CellsToMultiPolygon`
| `degsToRads`                 | `DegsToRads`                                       |
| `radsToDegs`                 | `RadsToDegs`                                       |
| `greatCircleDistance`        | `GreatCircleDistance* (3/3)`                       |
| `getHexagonAreaAvg`          | `HexagonAreaAvg* (3/3)`                            |
| `cellArea`                   | `CellArea* (3/3)`                                  |
| `getHexagonEdgeLengthAvg`    | `HexagonEdgeLengthAvg* (2/2)`                      |
| `exactEdgeLength`            | `EdgeLength* (3/3)`                                |
| `getNumCells`                | `NumCells`                                         |
| `getRes0Cells`               | `Res0Cells`                                        |
| `getPentagons`               | `Pentagons`                                        |
| `getResolution`              | `Resolution`                                       |
| `getBaseCellNumber`          | `BaseCellNumber`, `Cell#BaseCellNumber`            |
| `stringToH3`                 | `IndexFromString`, `Cell#UnmarshalText`            |
| `h3ToString`                 | `IndexToString`, `Cell#String`, `Cell#MarshalText` |
| `isValidCell`                | `Cell#IsValid`                                     |
| `cellToParent`               | `Cell#Parent`, `Cell#ImmediateParent`              |
| `cellToChildren`             | `Cell#Children` `Cell#ImmediateChildren`           |
| `cellToCenterChild`          | `Cell#CenterChild`                                 |
| `compactCells`               | `CompactCells`                                     |
| `uncompactCells`             | `UncompactCells`                                   |
| `isResClassIII`              | `Cell#IsResClassIII`                               |
| `isPentagon`                 | `Cell#IsPentagon`                                  |
| `getIcosahedronFaces`        | `Cell#IcosahedronFaces`                            |
| `areNeighborCells`           | `Cell#IsNeighbor`                                  |
| `cellsToDirectedEdge`        | `Cell#DirectedEdge`                                |
| `isValidDirectedEdge`        | `DirectedEdge#IsValid`                             |
| `getDirectedEdgeOrigin`      | `DirectedEdge#Origin`                              |
| `getDirectedEdgeDestination` | `DirectedEdge#Destination`                         |
| `directedEdgeToCells`        | `DirectedEdge#Cells`                               |
| `originToDirectedEdges`      | `Cell#DirectedEdges`                               |
| `directedEdgeToBoundary`     | `DirectedEdge#Boundary`                            |
| `cellToVertex`               | `CellToVertex`                                     |
| `cellToVertexes`             | `CellToVertexes`                                   |
| `vertexToLatLng`             | `VertexToLatLng`                                   |
| `isValidVertex`              | `IsValidVertex`                                    |
| `gridDistance`               | `GridDistance`, `Cell#GridDistance`                |
| `gridPathCells`              | `GridPath`, `Cell#GridPath`                        |
| `cellToLocalIj`              | `CellToLocalIJ`                                    |
| `localIjToCell`              | `LocalIJToCell`                                    |

## CGO

The H3 C source code and header files are copied into this project to optimize
for portability. `h3-go` can be imported into any Go project for any platform
that CGO supports.

# Contributing

Pull requests and Github issues are welcome.  Please read our [contributing
guide](./CONTRIBUTING.md) for more information.

## Legal and Licensing

H3-Go is licensed under the [Apache 2.0 License](./LICENSE).


Conversion utilities between H3 indexes and GeoJSON.

# go-geojson2h3

[![Coverage Status](https://coveralls.io/repos/github/mmadfox/go-geojson2h3/badge.svg?branch=main&n=1)](https://coveralls.io/github/mmadfox/go-geojson2h3?branch=main&n=1)
[![Documentation](https://godoc.org/github.com/mmadfox/go-geojson2h3?status.svg)](https://pkg.go.dev/github.com/mmadfox/go-geojson2h3)
[![Go Report Card](https://goreportcard.com/badge/github.com/mmadfox/go-geojson2h3)](https://goreportcard.com/report/github.com/mmadfox/go-geojson2h3)

The `geojson2h3` library includes a set of utilities for conversion between GeoJSON Objects: 
* Point, MultiPoint,
* LineString, MultiLineString
* Polygon,MultiPolygon
* GeometryCollection
* Feature,FeatureCollection
* Circle

and [H3 hexagon indexes](https://h3geo.org), 
using:
    [H3-GO](https://github.com/uber/h3-go) and
    [GeoJSON](https://github.com/tidwall/geojson)

## Installation
```shell
$ go get github.com/mmadfox/go-geojson2h3
```

## API
```go
// ToH3 converts a GeoJSON objects to a list of hexagons with specified resolution.
ToH3(resolution int, o geojson.Object) (indexes []h3.H3Index, err error)

// ToFeatureCollection converts a set of hexagons to a GeoJSON `FeatureCollection`
// with the set outline(s). The feature's geometry type will be `Polygon`.
ToFeatureCollection(indexes []h3.H3Index) (*geojson.FeatureCollection, error)
```

## Examples

* [Point, MultiPoint](examples/point.go)
* [LineString, MultiLineString](examples/line.go)
* [Polygon,MultiPolygon](examples/polygon.go)
* [GeometryCollection](examples/collection.go)
* [Feature,FeatureCollection](examples/feature.go)
* [Circle](examples/circle.go)
* [Rect](examples/rect.go)

```go
package main

import (
	"fmt"

	"github.com/mmadfox/go-geojson2h3"
	"github.com/tidwall/geojson"
	"github.com/uber/h3-go/v3"
)

func main() {
	resolution := 9
	object, err := geojson.Parse(`{"type":"FeatureCollection","features":[{"type":"Feature","properties":{"shape":"Polygon","name":"Unnamed Layer","category":"default"},"geometry":{"type":"Polygon","coordinates":[[[-73.901303,40.756892],[-73.893924,40.743755],[-73.871476,40.756278],[-73.863378,40.764175],[-73.871444,40.768467],[-73.879852,40.760014],[-73.885515,40.764045],[-73.891522,40.761054],[-73.901303,40.756892]]]},"id":"a6ca1b7e-9ddf-4425-ad07-8a895f7d6ccf"}]}`, nil)
	if err != nil {
		panic(err)
	}

	indexes, err := geojson2h3.ToH3(resolution, object)
	if err != nil {
		panic(err)
	}
	for _, index := range indexes {
		fmt.Printf("h3index: %s\n", h3.ToString(index))
	}

	featureCollection, err := geojson2h3.ToFeatureCollection(indexes)
	if err != nil {
		panic(err)
	}
	fmt.Println("Polyfill:")
	fmt.Println(featureCollection.JSON())
}
```

## Contributing
Pull requests and [Github issues](https://github.com/mmadfox/go-geojson2h3/issues) are welcome. Please include tests for new work, and keep the library test coverage at 90-100%. 


H3 GeoJSON

Distribution of Uber H3geo cells by virtual nodes.

# H3-geo distributed cells 

[![Documentation](https://godoc.org/github.com/mmadfox/go-h3geo-dist?status.svg)](https://pkg.go.dev/github.com/mmadfox/go-h3geo-dist)
[![Coverage Status](https://coveralls.io/repos/github/mmadfox/go-h3geo-dist/badge.svg?branch=main)](https://coveralls.io/github/mmadfox/go-h3geo-dist?branch=main&1)
[![Go Report Card](https://goreportcard.com/badge/github.com/mmadfox/go-h3geo-dist)](https://goreportcard.com/report/github.com/mmadfox/go-h3geo-dist)

Distribution of [Uber H3geo](https://h3geo.org/) cells by nodes 

Prerequisites
-------
[H3-Go requires CGO ](https://github.com/uber/h3-go#prerequisites)

Install
-------
With a correctly configured Go env:

```
go get github.com/mmadfox/go-h3geo-dist
```

Examples
--------
```go
package main

import (
	"fmt"

	h3geodist "github.com/mmadfox/go-h3geo-dist"
	"github.com/uber/h3-go/v3"
)

func main() {
	level := h3geodist.Level1
	h3dist, err := h3geodist.New(level)
	if err != nil {
		panic(err)
	}

	_ = h3dist.Add("127.0.0.1")
	_ = h3dist.Add("127.0.0.2")
	_ = h3dist.Add("127.0.0.3")

	// iterate over all cells level one
	h3geodist.Iter(level, func(index uint, cell h3.H3Index) {
		// find a node by h3geo cell
		dcell, ok := h3dist.Lookup(cell)
		fmt.Printf("h3dist.Lookup: cell=%v, host=%s, found=%v\n", cell, dcell.Host, ok)
	})

	h3dist.LookupMany([]h3.H3Index{
		h3.FromString("821fa7fffffffff"),
		h3.FromString("821f9ffffffffff"),
		h3.FromString("81973ffffffffff"),
		h3.FromString("81f07ffffffffff"),
	}, func(c h3geodist.Cell) bool {
		fmt.Printf("h3dist.LookupMany: cell=%v, host=%s\n", c.H3ID, c.Host)
		return true
	})

	h3dist.Remove("127.0.0.1")
	h3dist.Remove("127.0.0.2")
	h3dist.Remove("127.0.0.3")
}
```

H3GeoDist

A simple Go-based server for map tiles stored in mbtiles format.

mbtileserver

Library for reading, writing and working with OpenStreetMap data and APIs.

# osm [![CI](https://github.com/paulmach/osm/workflows/CI/badge.svg)](https://github.com/paulmach/osm/actions?query=workflow%3ACI+event%3Apush) [![Go Report Card](https://goreportcard.com/badge/github.com/paulmach/osm)](https://goreportcard.com/report/github.com/paulmach/osm) [![Go Reference](https://pkg.go.dev/badge/github.com/paulmach/osm.svg)](https://pkg.go.dev/github.com/paulmach/osm)

This package is a general purpose library for reading, writing and working
with [OpenStreetMap](https://osm.org) data in Go (golang). It has the ability to:

-   read/write [OSM XML](https://wiki.openstreetmap.org/wiki/OSM_XML)
-   read/write [OSM JSON](https://wiki.openstreetmap.org/wiki/OSM_JSON),
    a format returned by the Overpass API.
-   efficiently parse [OSM PBF](https://wiki.openstreetmap.org/wiki/PBF_Format) data files available at
    [planet.osm.org](https://planet.osm.org/)

Made available by the package are the following types:

-   Node
-   Way
-   Relation
-   Changeset
-   Note
-   User

And the following “container” types:

-   OSM - container returned via API
-   Change - used by the replication API
-   Diff - corresponds to [Overpass Augmented Diffs](https://wiki.openstreetmap.org/wiki/Overpass_API/Augmented_Diffs)

## List of sub-package utilities

-   [`annotate`](annotate) - adds lon/lat, version, changeset and orientation data to way and relation members
-   [`osmapi`](osmapi) - supports all the v0.6 read/data endpoints
-   [`osmgeojson`](osmgeojson) - OSM to GeoJSON conversion compatible with [osmtogeojson](https://github.com/tyrasd/osmtogeojson)
-   [`osmpbf`](osmpbf) - stream processing of `*.osm.pbf` files
-   [`osmxml`](osmxml) - stream processing of `*.osm` xml files
-   [`replication`](replication) - fetch replication state and change files

## Concepts

This package refers to the core OSM data types as **Objects**. The Node, Way,
Relation, Changeset, Note and User types implement the `osm.Object` interface
and can be referenced using the `osm.ObjectID` type. As a result it is possible
to have a slice of `[]osm.Object` that contains nodes, changesets and users.

Individual versions of the core OSM Map Data types are referred to as **Elements**
and the set of versions for a give Node, Way or Relation is referred to as a
**Feature**. For example, an `osm.ElementID` could refer to "Node with id 10 and
version 3" and the `osm.FeatureID` would refer to "all versions of node with id 10."
Put another way, features represent a road and how it's changed over time and an
element is a specific version of that feature.

A number of helper methods are provided for dealing with features and elements.
The idea is to make it easy to work with a Way and its member nodes, for example.

## Scanning large data files

For small data it is possible to use the `encoding/xml` package in the
Go standard library to marshal/unmarshal the data. This is typically done using the
`osm.OSM` or `osm.Change` "container" structs.

For large data the package defines the `Scanner` interface implemented in both the [osmxml](osmxml)
and [osmpbf](osmpbf) sub-packages.

```go
type osm.Scanner interface {
	Scan() bool
	Object() osm.Object
	Err() error
	Close() error
}
```

This interface is designed to mimic the [bufio.Scanner](https://golang.org/pkg/bufio/#Scanner)
interface found in the Go standard library.

Example usage:

```go
f, err := os.Open("./delaware-latest.osm.pbf")
if err != nil {
	panic(err)
}
defer f.Close()

scanner := osmpbf.New(context.Background(), f, 3)
defer scanner.Close()

for scanner.Scan() {
	o := scanner.Object()
	// do something
}

scanErr := scanner.Err()
if scanErr != nil {
	panic(scanErr)
}
```

**Note:** Scanners are **not** safe for parallel use. One should feed the
objects into a channel and have workers read from that.

## Working with JSON

This library supports reading and writing [OSM JSON](https://wiki.openstreetmap.org/wiki/OSM_JSON).
This format is returned by the Overpass API and can be optionally returned by the
[OSM API](https://wiki.openstreetmap.org/wiki/API_v0.6#JSON_Format).

If performance is important, this library supports third party "encoding/json" replacements
such as [github.com/json-iterator/go](https://github.com/json-iterator/go).

They can be enabled with something like this:

```go
import (
  jsoniter "github.com/json-iterator/go"
  "github.com/paulmach/osm"
)

var c = jsoniter.Config{
  EscapeHTML:              true,
  SortMapKeys:             false,
  MarshalFloatWith6Digits: true,
}.Froze()

osm.CustomJSONMarshaler = c
osm.CustomJSONUnmarshaler = c
```

The above change can have dramatic performance implications, see the benchmarks below
on a large OSM Change object.

```
benchmark                            old ns/op     new ns/op     delta
BenchmarkChange_MarshalJSON-12       604496        461349        -23.68%
BenchmarkChange_UnmarshalJSON-12     1633834       1051630       -35.63%

benchmark                            old allocs    new allocs    delta
BenchmarkChange_MarshalJSON-12       1277          1081          -15.35%
BenchmarkChange_UnmarshalJSON-12     5133          8580          +67.15%

benchmark                            old bytes     new bytes     delta
BenchmarkChange_MarshalJSON-12       180583        162727        -9.89%
BenchmarkChange_UnmarshalJSON-12     287707        317723        +10.43%
```

## CGO and zlib

OSM PBF data comes in blocks, each block is zlib compressed. Decompressing this
data takes about 33% of the total read time. [DataDog/czlib](https://github.com/DataDog/czlib) is
used to speed this process.
See [osmpbf/README.md](osmpbf#using-cgoczlib-for-decompression) for more details.

As a result, a C compiler is necessary to install this module. On macOS this may require
installing pkg-config using something like `brew install pkg-config`

CGO can be disabled at build time using the `CGO_ENABLED` ENV variable.
For example, `CGO_ENABLED=0 go build`. The code will fallback to the stdlib implementation of zlib.


OpenStreetMap PBF golang encoder/decoder.

# pbf
OpenStreetMap PBF golang encoder/decoder

[![Build Status](https://github.com/maguro/pbf/actions/workflows/ci.yml/badge.svg)](https://github.com/maguro/pbf/actions/workflows/ci.yml)
[![Go Report Card](https://goreportcard.com/badge/github.com/maguro/pbf)](https://goreportcard.com/report/github.com/maguro/pbf) 
[![Documentation](https://godoc.org/github.com/maguro/pbf?status.svg)](http://godoc.org/github.com/maguro/pbf) 
[![codecov.io](https://codecov.io/github/maguro/pbf/coverage.svg?branch=master)](https://codecov.io/github/maguro/pbf?branch=master)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

A golang based OpenStreetMap PBF encoder/decoder with a handy command line utility, `pbf`.

## pbf Command Line Utility

The `pbf` CLI can be installed using the `go install` command:

    $ go install m4o.io/pbf/cmd/pbf

### pbf info

The `pbf` CLI can be used to obtain summary and extended information about an
OpenStreetMap PBF file:

    $ pbf info -i testdata/greater-london.osm.pbf
    BoundingBox: [-0.511482, 51.28554, 0.335437, 51.69344]
    RequiredFeatures: OsmSchema-V0.6, DenseNodes
    OptionalFeatures: 
    WritingProgram: Osmium (http://wiki.openstreetmap.org/wiki/Osmium)
    Source: 
    OsmosisReplicationTimestamp: 2014-03-24T21:55:02Z
    OsmosisReplicationSequenceNumber: 0
    OsmosisReplicationBaseURL: 

JSON output can be obtained by adding the `-j` option:

    $ pbf info -j -i testdata/greater-london.osm.pbf | jq
    {
      "BoundingBox": {
        "Left": -0.511482,
        "Right": 0.33543700000000004,
        "Top": 51.69344,
        "Bottom": 51.285540000000005
      },
      "RequiredFeatures": [
        "OsmSchema-V0.6",
        "DenseNodes"
      ],
      "OptionalFeatures": null,
      "WritingProgram": "Osmium (http://wiki.openstreetmap.org/wiki/Osmium)",
      "Source": "",
      "OsmosisReplicationTimestamp": "2014-03-24T14:55:02-07:00",
      "OsmosisReplicationSequenceNumber": 0,
      "OsmosisReplicationBaseURL": ""
    }

Here, [jq](https://stedolan.github.io/jq/) is used to pretty print the compact
JSON.

Extended information about the OpenStreetMap PBF file can be obtained
by using the `-e` option.  This causes the entire file to be scanned, which can
take a very long time; a progress bar is displayed on `stderr`.

    $ pbf info -e -i testdata/greater-london.osm.pbf
    BoundingBox: [-0.511482, 51.28554, 0.335437, 51.69344]
    RequiredFeatures: OsmSchema-V0.6, DenseNodes
    OptionalFeatures: 
    WritingProgram: Osmium (http://wiki.openstreetmap.org/wiki/Osmium)
    Source: 
    OsmosisReplicationTimestamp: 2014-03-24T21:55:02Z
    OsmosisReplicationSequenceNumber: 0
    OsmosisReplicationBaseURL: 
    NodeCount: 2,729,006
    WayCount: 459,055
    RelationCount: 12,833

Finally, `pbf` can read an OpenStreetMap PBF file from `stdin`:

    $ cat testdata/greater-london.osm.pbf | pbf info -e

In this case, a progress bar is not displayed since there is no way to know,
a priori, what the size of the PBF file is.


Convert geojson to s2 cells & demonstrating some S2 geometry features on map.

[![Build Status](https://travis-ci.com/pantrif/s2-geojson.svg?branch=develop)](https://travis-ci.com/pantrif/s2-geojson)
[![GoDoc](https://godoc.org/github.com/pantrif/s2-geojson?status.png)](http://godoc.org/github.com/pantrif/s2-geojson)
[![Go Report Card](https://goreportcard.com/badge/github.com/pantrif/s2-geojson)](https://goreportcard.com/report/github.com/pantrif/s2-geojson)
[![codecov](https://codecov.io/gh/pantrif/s2-geojson/branch/develop/graph/badge.svg)](https://codecov.io/gh/pantrif/s2-geojson)


## Preview
<img width="1645" alt="preview" src="https://user-images.githubusercontent.com/9129280/77917392-31dca180-72a3-11ea-9e93-27c331731196.png">


## Summary

Draw a polygon on the map or paste a geoJSON and explore how the s2.RegionCoverer covers it with S2 cells depending on the min and max levels.
Drop a marker and inspect the corresponding S2 cell.

- Display s2 cells on leaflet map using the region coverer. 
- Convert geojson features to cell unions depending on the min and max levels (supported only Polygons and Points).
- Draw points and polygons.
- Check point & circle intersection with the geoJSON features.


## Quick start
```
 go run cmd/s2-geojson/main.go
```

## Docker 
```
docker run -p 8080:8080 --rm lmaroulis/s2-geojson
```



## License

This project is licensed under the MIT License - see [the LICENSE file](LICENSE) for details.

S2 geojson

# Overview

S2 is a library for spherical geometry that aims to have the same robustness,
flexibility, and performance as the best planar geometry libraries.

This is a library for manipulating geometric shapes. Unlike many geometry
libraries, S2 is primarily designed to work with *spherical geometry*, i.e.,
shapes drawn on a sphere rather than on a planar 2D map. (In fact, the name S2
is derived from the mathematical notation for the unit sphere *S²*.) This makes
it especially suitable for working with geographic data.

More details about S2 in general are available on the S2 Geometry Website
[s2geometry.io](https://s2geometry.io/).

## Scope

The library provides the following:

*   Representations of angles, intervals, latitude-longitude points, unit
    vectors, and so on, and various operations on these types.

*   Geometric shapes over the unit sphere, such as spherical caps ("discs"),
    latitude-longitude rectangles, polylines, and polygons. These are
    collectively known as "regions".

*   A hierarchical decomposition of the sphere into regions called "cells". The
    hierarchy starts with the six faces of a projected cube and recursively
    subdivides them in a quadtree-like fashion.

*   Robust constructive operations (e.g., union) and boolean predicates (e.g.,
    containment) for arbitrary collections of points, polylines, and polygons.

*   Fast in-memory indexing of collections of points, polylines, and polygons.

*   Algorithms for measuring distances and finding nearby objects.

*   Robust algorithms for snapping and simplifying geometry (with accuracy and
    topology guarantees).

*   A collection of efficient yet exact mathematical predicates for testing
    relationships among geometric objects.

*   Support for spatial indexing, including the ability to approximate regions
    as collections of discrete "S2 cells". This feature makes it easy to build
    large distributed spatial indexes.

On the other hand, the following are outside the scope of S2:

*   Planar geometry.

*   Conversions to/from common GIS formats.

### Robustness

What do we mean by "robust"?

In the S2 library, the core operations are designed to be 100% robust. This
means that each operation makes strict mathematical guarantees about its output,
and is implemented in such a way that it meets those guarantees for all possible
valid inputs. For example, if you compute the intersection of two polygons, not
only is the output guaranteed to be topologically correct (up to the creation of
degeneracies), but it is also guaranteed that the boundary of the output stays
within a user-specified tolerance of true, mathematically exact result.

Robustness is very important when building higher-level algorithms, since
unexpected results from low-level operations can be very difficult to handle. S2
achieves this goal using a combination of techniques from computational
geometry, including *conservative error bounds*, *exact geometric predicates*,
and *snap rounding*.

The implementation attempts to be precise both in terms of mathematical
definitions (e.g. whether regions include their boundaries, and how degeneracies
are handled) and numerical accuracy (e.g. minimizing cancellation error).

Note that the intent of this library is to represent geometry as a mathematical
abstraction. For example, although the unit sphere is obviously a useful
approximation for the Earth's surface, functions that are specifically related
to geography are not part of the core library (e.g. easting/northing
conversions, ellipsoid approximations, geodetic vs. geocentric coordinates,
etc).

See http://godoc.org/github.com/golang/geo for specific package documentation.

For an analogous library in C++, see https://github.com/google/s2geometry, in
Java, see https://github.com/google/s2-geometry-library-java, and Python, see
https://github.com/google/s2geometry/tree/master/src/python

# Status of the Go Library

This library is principally a port of the
[C++ S2 library](https://github.com/google/s2geometry), adapting to Go idioms
where it makes sense. We detail the progress of this port below relative to that
C++ library.

Legend:

*   ✅ - Feature Complete
*   🟡 - Mostly Complete
*   ❌ - Not available

## [ℝ¹](https://godoc.org/github.com/golang/geo/r1) - One-dimensional Cartesian coordinates

C++ Type   | Go
:--------- | ---
R1Interval | ✅

## [ℝ²](https://godoc.org/github.com/golang/geo/r2) - Two-dimensional Cartesian coordinates

C++ Type | Go
:------- | ---
R2Point  | ✅
R2Rect   | ✅

## [ℝ³](https://godoc.org/github.com/golang/geo/r3) - Three-dimensional Cartesian coordinates

C++ Type      | Go
:------------ | ---
R3Vector      | ✅
R3ExactVector | ✅
Matrix3x3     | ✅

## [S¹](https://godoc.org/github.com/golang/geo/s1) - Circular Geometry

C++ Type     | Go
:----------- | ---
S1Angle      | ✅
S1ChordAngle | ✅
S1Interval   | ✅

## [S²](https://godoc.org/github.com/golang/geo/s2) - Spherical Geometry

### Basic Types

C++ Type             | Go
:------------------- | ---
S2Cap                | ✅
S2Cell               | ✅
S2CellId             | ✅
S2CellIdVector       | ❌
S2CellIndex          | 🟡
S2CellUnion          | ✅
S2Coords             | ✅
S2DensityTree        | ❌
S2DistanceTarget     | ✅
S2EdgeVector         | ✅
S2LatLng             | ✅
S2LatLngRect         | ✅
S2LaxLoop            | 🟡
S2LaxPolygon         | 🟡
S2LaxPolyline        | 🟡
S2Loop               | ✅
S2PaddedCell         | ✅
S2Point              | ✅
S2PointIndex         | ❌
S2PointSpan          | ❌
S2PointRegion        | ❌
S2PointVector        | ✅
S2Polygon            | 🟡
S2Polyline           | ✅
S2R2Rect             | ❌
S2Region             | ✅
S2RegionCoverer      | ✅
S2RegionIntersection | ❌
S2RegionUnion        | ✅
S2Shape              | ✅
S2ShapeIndex         | ✅
S2ShapeIndexRegion   | ❌
EncodedLaxPolygon    | ❌
EncodedLaxPolyline   | ❌
EncodedShapeIndex    | ❌
EncodedStringVector  | ❌
EncodedUintVector    | ❌
IdSetLexicon         | ❌
ValueSetLexicon      | ❌
SequenceLexicon      | ❌
LaxClosedPolyline    | ❌
VertexIDLaxLoop      | ❌

### Query Types

C++ Type             | Go
:------------------- | ---
S2ChainInterpolation | ❌
S2ClosestCell        | ❌
S2FurthestCell       | ❌
S2ClosestEdge        | ✅
S2FurthestEdge       | ✅
S2ClosestPoint       | ❌
S2FurthestPoint      | ❌
S2ContainsPoint      | ✅
S2ContainsVertex     | ✅
S2ConvexHull         | ✅
S2CrossingEdge       | ✅
S2HausdorffDistance  | ❌
S2ShapeNesting       | ❌

### Supporting Types

C++ Type                         | Go
:------------------------------- | ---
S2BooleanOperation               | ❌
S2BufferOperation                | ❌
S2Builder                        | ❌
S2BuilderClosedSetNormalizer     | ❌
S2BuilderFindPolygonDegeneracies | ❌
S2BuilderGraph                   | ❌
S2BuilderLayers                  | ❌
S2BuilderSnapFunctions           | ❌
S2BuilderTesting                 | ❌
S2Builderutil\*                  | ❌
S2Coder                          | ❌
S2EdgeClipping                   | ✅
S2EdgeCrosser                    | ✅
S2EdgeCrossings                  | ✅
S2EdgeDistances                  | ✅
S2EdgeTessellator                | ✅
S2LoopMeasures                   | ❌
S2Measures                       | ✅
S2MemoryTracker                  | ❌
S2Metrics                        | ❌
S2PointUtil                      | 🟡
S2PolygonBuilder                 | ❌
S2PolylineAlignment              | ❌
S2PolylineMeasures               | ✅
S2PolylineSimplifier             | ❌
S2Predicates                     | ✅
S2Projections                    | ❌
S2rectBounder                    | ❌
S2RegionTermIndexer              | ❌
S2ShapeIndexMeasures             | ❌
S2ShapeIndexUtil\*               | 🟡
S2ShapeMeasures                  | ❌
S2ShapeUtil\*                    | 🟡
S2Stats                          | ❌
S2Testing                        | ✅
S2TextFormat                     | ✅
S2WedgeRelations                 | ✅
S2WindingOperation               | ❌

### Encode/Decode

Encoding and decoding of S2 types is fully implemented and interoperable with
C++ and Java.


S2 geometry

simplesfeatures is a 2D geometry library that provides Go types that model geometries, as well as algorithms that operate on them.

# Simple Features

[![Documentation](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat)](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom?tab=doc)
[![Build Status](https://github.com/peterstace/simplefeatures/workflows/build/badge.svg)](https://github.com/peterstace/simplefeatures/actions)
[![Go Report
Card](https://goreportcard.com/badge/github.com/peterstace/simplefeatures)](https://goreportcard.com/report/github.com/peterstace/simplefeatures)
[![Coverage
Status](https://coveralls.io/repos/github/peterstace/simplefeatures/badge.svg?branch=master)](https://coveralls.io/github/peterstace/simplefeatures?branch=master)

Simple Features is a 2D geometry library that provides Go types that model
geometries, as well as algorithms that operate on them.

It's a pure Go Implementation of the OpenGIS Consortium's Simple
Feature Access Specification (which can be found
[here](http://www.opengeospatial.org/standards/sfa)). This is the same
specification that [GEOS](https://trac.osgeo.org/geos),
[JTS](https://locationtech.github.io/jts/), and [PostGIS](https://postgis.net/)
implement, so the Simple Features API will be familiar to developers who have
used those libraries before.

#### Table of Contents

- [Geometry Types](#geometry-types)
- [Marshalling and Unmarshalling](#marshalling-and-unmarshalling)
- [Geometry Algorithms](#geometry-algorithms)
- [GEOS Wrapper](#geos-wrapper)
- [Examples](#examples)

### Geometry Types

<table>

<thead>
<tr>
<th>Type</th>
<th>Example</th>
<th>Description</th>
</tr>
</thead>

<tr>
<td><a href="https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Point">Point</a></td>
<td><a href="https://commons.wikimedia.org/wiki/File:SFA_Point.svg"><img width=51 height=51 src="https://upload.wikimedia.org/wikipedia/commons/c/c2/SFA_Point.svg"></a></td>
<td>Point is a single location in space.</td>
</tr>

<tr>
<td><a href="https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#MultiPoint">MultiPoint</a></td>
<td><a href="https://commons.wikimedia.org/wiki/File:SFA_MultiPoint.svg"><img width=51 height=51  src="https://upload.wikimedia.org/wikipedia/commons/d/d6/SFA_MultiPoint.svg"></a></td>
<td>MultiPoint is collection of points in space.</td>
</tr>

<tr>
<td><a href="https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#LineString">LineString</a></td>
<td><a href="https://commons.wikimedia.org/wiki/File:SFA_LineString.svg"><img width=51 height=51  src="https://upload.wikimedia.org/wikipedia/commons/b/b9/SFA_LineString.svg"></a></td>
<td>LineString is curve defined by linear interpolation between a set of
control points.</td>
</tr>

<tr>
<td><a href="https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#MultiLineString">MultiLineString</a></td>
<td><a href="https://commons.wikimedia.org/wiki/File:SFA_MultiLineString.svg"><img width=51 height=51  src="https://upload.wikimedia.org/wikipedia/commons/8/86/SFA_MultiLineString.svg"></a></td>
<td>MultiLineString is a collection of LineStrings.</td>
</tr>

<tr>
<td><a href="https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Polygon">Polygon</a></td>
<td><a href="https://commons.wikimedia.org/wiki/File:SFA_Polygon.svg"><img width=51 height=51  src="https://upload.wikimedia.org/wikipedia/commons/5/55/SFA_Polygon_with_hole.svg"></a></td>
<td>Polygon is a planar surface geometry that bounds some area. It may have holes.</td>
</tr>

<tr>
<td><a href="https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#MultiPolygon">MultiPolygon</a></td>
<td><a href="https://commons.wikimedia.org/wiki/File:SFA_MultiPolygon.svg"><img width=51 height=51  src="https://upload.wikimedia.org/wikipedia/commons/3/3b/SFA_MultiPolygon_with_hole.svg"></a></td>
<td>MultiPolygon is collection of Polygons (with some constraints on how the Polygons interact with each other).</td>
</tr>

<tr>
<td><a href="https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#GeometryCollection">GeometryCollection</a></td>
<td><a href="https://commons.wikimedia.org/wiki/File:SFA_GeometryCollection.svg"><img width=51 height=51  src="https://upload.wikimedia.org/wikipedia/commons/1/1d/SFA_GeometryCollection.svg"></a></td>
<td>GeometryCollection is an unconstrained collection of geometries.</td>
</tr>

<tr>
<td><a href="https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Geometry">Geometry</a></td>
<td><a href="https://commons.wikimedia.org/wiki/File:SFA_Polygon.svg"><img width=51 height=51  src="https://upload.wikimedia.org/wikipedia/commons/5/55/SFA_Polygon_with_hole.svg"></a></td>
<td>Geometry holds any type of geometry (Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, or GeometryCollection). It's the type that the Simple Features library uses when it needs to represent geometries in a generic way.</td>
</tr>

<tr>
<td><a href="https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Envelope">Envelope</a></td>
<td><img src="./.ci/assets/envelope.svg"></td>
<td>Envelope is an axis aligned bounding box typically used to describe the spatial extent of other geometric entities.</td>
</tr>

</table>

### Marshalling and Unmarshalling

Simple features supports the following external geometry representation formats:

| Format  | Example                                                              | Description                                                                                                                                                                                                                                                                                                                                                        |
| ---     | ---                                                                  | ---                                                                                                                                                                                                                                                                                                                                                                |
| WKT     | `POLYGON((0 0,0 1,1 1,1 0,0 0))`                                     | [Well Known Text](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) is a human readable format for storing geometries. It's often the lowest common denominator geometry format, and is useful for integration with other GIS applications.                                                                                                |
| WKB     | `<binary>`                                                           | [Well Known Binary](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Well-known_binary) is a machine readable format that is efficient for computers to use (both from a processing and storage space perspective). WKB is a good choice for transferring geometries to and from PostGIS and other databases that support geometric types. |
| GeoJSON | `{"type":"Polygon","coordinates":[[[0,0],[0,1],[1,1],[1,0],[0,0]]]}` | [GeoJSON](https://en.wikipedia.org/wiki/GeoJSON) represents geometries in a similar way to WKB, but is based on the JSON format. This makes it ideal to use with web APIs or other situations where JSON would normally be used.                                                                                                                                   |
| TWKB    | `<binary>`                                                           | [Tiny Well Known Binary](https://github.com/TWKB/Specification) is a multi-purpose compressed binary format for serialising vector geometries into a stream of bytes. It emphasises minimising the size of the serialised representation. It's a good choice when space is at a premium (e.g. for storage within a web token).                                     |

### Geometry Algorithms

The following algorithms are supported:

| Miscellaneous Algorithms                                                                               | Description                                                                            |
| ---                                                                                                    | ---                                                                                    |
| [Area](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Geometry.Area)                     | Finds the area of the geometry (for Polygons and MultiPolygons).                       |
| [Centroid](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Geometry.Centroid)             | Finds the centroid of the geometry.                                                    |
| [ConvexHull](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Geometry.ConvexHull)         | Finds the convex hull of the geometry.                                                 |
| [Distance](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Distance)                      | Finds the shortest distance between two geometries.                                    |
| [Envelope](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Geometry.Envelope)             | Finds the smallest axis-aligned bounding-box that surrounds the geometry.              |
| [ExactEquals](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#ExactEquals)                | Determines if two geometries are structurally equal.                                   |
| [Length](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Geometry.Length)                 | Finds the length of the geometry (for LineStrings and MultiLineStrings).               |
| [PointOnSurface](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Geometry.PointOnSurface) | Finds a point that lies inside the geometry.                                           |
| [Relate](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Relate)                          | Calculates the DE-9IM intersection describing the relationship between two geometries. |
| [Simplify](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Simplify)                      | Simplifies a geometry using the Ramer–Douglas–Peucker algorithm.                       |

| Set Operations                                                                                          | Description                                                               |
| ---                                                                                                     | ---                                                                       |
| [Union](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Union)                             | Joins the parts from two geometries together.                             |
| [Intersection](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Intersection)               | Finds the parts of two geometries that are in common.                     |
| [Difference](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Difference)                   | Finds the parts of a geometry that are not also part of another geometry. |
| [SymmetricDifference](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#SymmetricDifference) | Finds the parts of two geometries that are not in common.                 |


| Named Spatial Predicates                                                              | Description                                             |
| ---                                                                                   | ---                                                     |
| [Equals](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Equals)         | Determines if two geometries are topologically equal.   |
| [Intersects](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Intersects) | Determines if two geometries intersect with each other. |
| [Disjoint](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Disjoint)     | Determines if two geometries have no common points.     |
| [Contains](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Contains)     | Determines if one geometry contains another.            |
| [CoveredBy](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#CoveredBy)   | Determines if one geometry is covered by another.       |
| [Covers](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Covers)         | Determines if one geometry covers another.              |
| [Overlaps](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Overlaps)     | Determines if one geometry overlaps another.            |
| [Touches](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Touches)       | Determines if one geometry touches another.             |
| [Within](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Within)         | Determines if one geometry is within another.           |
| [Crosses](https://pkg.go.dev/github.com/peterstace/simplefeatures/geom#Crosses)       | Determines if one geometry crosses another.             |

### GEOS Wrapper

A [GEOS](https://www.osgeo.org/projects/geos/) CGO wrapper is also provided,
giving access to functionality not yet implemented natively in Go. The [wrapper
is implemented in a separate
package](https://pkg.go.dev/github.com/peterstace/simplefeatures/geos?tab=doc),
meaning that library users who don't need this additional functionality don't
need to expose themselves to CGO.

### Examples

The following examples show some common operations (errors are omitted for
brevity).

#### WKT

Encoding and decoding WKT:

```go
// Unmarshal from WKT
input := "POLYGON((0 0,0 1,1 1,1 0,0 0))"
g, _ := geom.UnmarshalWKT(input)

// Marshal to WKT
output := g.AsText()
fmt.Println(output) // Prints: POLYGON((0 0,0 1,1 1,1 0,0 0))
```

#### WKB

Encoding and decoding WKB directly:

```go
// Marshal as WKB
coords := geom.Coordinates{XY: geom.XY{1.5, 2.5}}
pt := geom.NewPoint(coords)
wkb := pt.AsBinary()
fmt.Println(wkb) // Prints: [1 1 0 0 0 0 0 0 0 0 0 248 63 0 0 0 0 0 0 4 64]

// Unmarshal from WKB
fromWKB, _ := geom.UnmarshalWKB(wkb)
fmt.Println(fromWKB.AsText()) // POINT(1.5 2.5)
```

Encoding and decoding WKB for integration with PostGIS:

```go
db, _ := sql.Open("postgres", "postgres://...")

db.Exec(`
    CREATE TABLE my_table (
        my_geom geometry(geometry, 4326),
        population double precision
    )`,
)

// Insert our geometry and population data into PostGIS via WKB.
coords := geom.Coordinates{XY: geom.XY{-74.0, 40.7}}
nyc := geom.NewPoint(coords)
db.Exec(`
    INSERT INTO my_table
    (my_geom, population)
    VALUES (ST_GeomFromWKB($1, 4326), $2)`,
    nyc, 8.4e6,
)

// Get the geometry and population data back out of PostGIS via WKB.
var location geom.Geometry
var population float64
db.QueryRow(`
    SELECT ST_AsBinary(my_geom), population
    FROM my_table LIMIT 1`,
).Scan(&location, &population)
fmt.Println(location.AsText(), population) // Prints: POINT(-74 40.7) 8.4e+06
```

#### GeoJSON

Encoding and decoding GeoJSON directly:

```go
// Unmarshal geometry from GeoJSON.
raw := `{"type":"Point","coordinates":[-74.0,40.7]}`
var g geom.Geometry
json.NewDecoder(strings.NewReader(raw)).Decode(&g)
fmt.Println(g.AsText()) // Prints: POINT(-74 40.7)

// Marshal back to GeoJSON.
enc := json.NewEncoder(os.Stdout)
enc.Encode(g) // Prints: {"type":"Point","coordinates":[-74,40.7]}
```

Geometries can also be part of larger structs:

```go
type CityPopulation struct {
    Location   geom.Geometry `json:"loc"`
    Population int           `json:"pop"`
}

// Unmarshal geometry from GeoJSON.
raw := `{"loc":{"type":"Point","coordinates":[-74.0,40.7]},"pop":8400000}`
var v CityPopulation
json.NewDecoder(strings.NewReader(raw)).Decode(&v)
fmt.Println(v.Location.AsText()) // Prints: POINT(-74 40.7)
fmt.Println(v.Population)        // Prints: 8400000

// Marshal back to GeoJSON.
enc := json.NewEncoder(os.Stdout)
enc.Encode(v) // Prints: {"loc":{"type":"Point","coordinates":[-74,40.7]},"pop":8400000}
```


simplefeatures

Geolocation DB with spatial index and realtime geofencing.

<p align="center">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="/.github/images/logo-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="/.github/images/logo-light.svg">
  <img alt="Tile38" src="/.github/images/logo-light.svg" width="284">
</picture>
</p>
<p align="center">
<a href="https://tile38.com/slack/"><img src="https://img.shields.io/badge/slack-channel-orange.svg" alt="Slack Channel"></a>
<a href="https://hub.docker.com/r/tile38/tile38"><img src="https://img.shields.io/docker/pulls/tile38/tile38.svg" alt="Docker Pulls"></a>
</p>

Tile38 is an open source (MIT licensed), in-memory geolocation data store, spatial index, and realtime geofencing server.
It supports a variety of object types including lat/lon points, bounding boxes, XYZ tiles, Geohashes, and GeoJSON. 

<p align="center">
<i>This README is quick start document. You can find detailed documentation at <a href="https://tile38.com">https://tile38.com</a>.</i><br><br>
<a href="#searching"><img src="/.github/images/search-nearby.png" alt="Nearby" border="0" width="120" height="120"></a>
<a href="#searching"><img src="/.github/images/search-within.png" alt="Within" border="0" width="120" height="120"></a>
<a href="#searching"><img src="/.github/images/search-intersects.png" alt="Intersects" border="0" width="120" height="120"></a>
<a href="https://tile38.com/topics/geofencing"><img src="/.github/images/geofence.gif" alt="Geofencing" border="0" width="120" height="120"></a>
<a href="https://tile38.com/topics/roaming-geofences"><img src="/.github/images/roaming.gif" alt="Roaming Geofences" border="0" width="120" height="120"></a>
</p>

## Features

- Spatial index with [search](#searching) methods such as Nearby, Within, and Intersects.
- Realtime [geofencing](#geofencing) through [webhooks](https://tile38.com/commands/sethook) or [pub/sub channels](#pubsub-channels).
- Object types of [lat/lon](#latlon-point), [bbox](#bounding-box), [Geohash](#geohash), [GeoJSON](#geojson), [QuadKey](#quadkey), and [XYZ tile](#xyz-tile).
- Support for lots of [Clients Libraries](#tile38-client-libraries) written in many different languages.
- Variety of protocols, including [http](#http) (curl), [websockets](#websockets), [telnet](#telnet), and the [Redis RESP](https://redis.io/topics/protocol).
- Server responses are [RESP](https://redis.io/topics/protocol) or [JSON](https://www.json.org).
- Full [command line interface](#cli).
- Leader / follower [replication](#replication).
- In-memory database that persists on disk.

## Components
- tile38-server: The server
- tile38-cli: Command line interface tool
- tile38-benchmark: Server benchmark tool

## Getting Started

### Getting Tile38

Perhaps the easiest way to get the latest Tile38 is to use one of the pre-built release binaries which are available for OSX, Linux, FreeBSD, and Windows. Instructions for using these binaries are on the GitHub [releases page](https://github.com/tidwall/tile38/releases).

### Docker 

To run the latest stable version of Tile38:

```
docker pull tile38/tile38
docker run -p 9851:9851 tile38/tile38
```

Visit the [Tile38 hub page](https://hub.docker.com/r/tile38/tile38/) for more information.

### Homebrew (macOS)

Install Tile38 using [Homebrew](https://brew.sh/)

```sh
brew install tile38
tile38-server
```

### Building Tile38 

Tile38 can be compiled and used on Linux, OSX, Windows, FreeBSD, and probably others since the codebase is 100% Go. We support both 32 bit and 64 bit systems. [Go](https://golang.org/dl/) must be installed on the build machine.

To build everything simply:
```
$ make
```

To test:
```
$ make test
```

### Running 
For command line options invoke:
```
$ ./tile38-server -h
```

To run a single server:

```
$ ./tile38-server

# The tile38 shell connects to localhost:9851
$ ./tile38-cli
> help
```

#### Prometheus Metrics
Tile38 can natively export Prometheus metrics by setting the `--metrics-addr` command line flag (disabled by default). This example exposes the HTTP metrics server on port 4321:
```
# start server and enable Prometheus metrics, listen on local interface only
./tile38-server --metrics-addr=127.0.0.1:4321

# access metrics
curl http://127.0.0.1:4321/metrics
```
If you need to access the `/metrics` endpoint from a different host you'll have to set the flag accordingly, e.g. set it to `0.0.0.0:<<port>>` to listen on all interfaces.

Use the [redis_exporter](https://github.com/oliver006/redis_exporter) for more advanced use cases like extracting key values or running a lua script.


## <a name="cli"></a>Playing with Tile38

Basic operations:
```
$ ./tile38-cli

# add a couple of points named 'truck1' and 'truck2' to a collection named 'fleet'.
> set fleet truck1 point 33.5123 -112.2693   # on the Loop 101 in Phoenix
> set fleet truck2 point 33.4626 -112.1695   # on the I-10 in Phoenix

# search the 'fleet' collection.
> scan fleet                                 # returns both trucks in 'fleet'
> nearby fleet point 33.462 -112.268 6000    # search 6 kilometers around a point. returns one truck.

# key value operations
> get fleet truck1                           # returns 'truck1'
> del fleet truck2                           # deletes 'truck2'
> drop fleet                                 # removes all 
```

Tile38 has a ton of [great commands](https://tile38.com/commands).

## Fields
Fields are extra data that belongs to an object. A field is always a double precision floating point. There is no limit to the number of fields that an object can have. 

To set a field when setting an object:
```
> set fleet truck1 field speed 90 point 33.5123 -112.2693             
> set fleet truck1 field speed 90 field age 21 point 33.5123 -112.2693
```

To set a field when an object already exists:
```
> fset fleet truck1 speed 90
```

To get a field when an object already exists:
```
> fget fleet truck1 speed
```

## Searching

Tile38 has support to search for objects and points that are within or intersects other objects. All object types can be searched including Polygons, MultiPolygons, GeometryCollections, etc.

<img src="/.github/images/search-within.png" width="200" height="200" border="0" alt="Search Within" align="left">

#### Within 
WITHIN searches a collection for objects that are fully contained inside a specified bounding area.
<BR CLEAR="ALL">

<img src="/.github/images/search-intersects.png" width="200" height="200" border="0" alt="Search Intersects" align="left">

#### Intersects
INTERSECTS searches a collection for objects that intersect a specified bounding area.
<BR CLEAR="ALL">

<img src="/.github/images/search-nearby.png" width="200" height="200" border="0" alt="Search Nearby" align="left">

#### Nearby
NEARBY searches a collection for objects that intersect a specified radius.
<BR CLEAR="ALL">

### Search options
**WHERE** - This option allows for filtering out results based on [field](#fields) values. For example<br>```nearby fleet where speed 70 +inf point 33.462 -112.268 6000``` will return only the objects in the 'fleet' collection that are within the 6 km radius **and** have a field named `speed` that is greater than `70`. <br><br>Multiple WHEREs are concatenated as **and** clauses. ```WHERE speed 70 +inf WHERE age -inf 24``` would be interpreted as *speed is over 70 <b>and</b> age is less than 24.*<br><br>The default value for a field is always `0`. Thus if you do a WHERE on the field `speed` and an object does not have that field set, the server will pretend that the object does and that the value is Zero.

**MATCH** - MATCH is similar to WHERE except that it works on the object id instead of fields.<br>```nearby fleet match truck* point 33.462 -112.268 6000``` will return only the objects in the 'fleet' collection that are within the 6 km radius **and** have an object id that starts with `truck`. There can be multiple MATCH options in a single search. The MATCH value is a simple [glob pattern](https://en.wikipedia.org/wiki/Glob_(programming)).

**CURSOR** - CURSOR is used to iterate though many objects from the search results. An iteration begins when the CURSOR is set to Zero or not included with the request, and completes when the cursor returned by the server is Zero.

**NOFIELDS** - NOFIELDS tells the server that you do not want field values returned with the search results.

**LIMIT** - LIMIT can be used to limit the number of objects returned for a single search request.


## Geofencing

<img src="/.github/images/geofence.gif" width="200" height="200" border="0" alt="Geofence animation" align="left">
A <a href="https://en.wikipedia.org/wiki/Geo-fence">geofence</a> is a virtual boundary that can detect when an object enters or exits the area. This boundary can be a radius, bounding box, or a polygon. Tile38 can turn any standard search into a geofence monitor by adding the FENCE keyword to the search. 

*Tile38 also allows for [Webhooks](https://tile38.com/commands/sethook) to be assigned to Geofences.*

<br clear="all">

A simple example:
```
> nearby fleet fence point 33.462 -112.268 6000
```
This command opens a geofence that monitors the 'fleet' collection. The server will respond with:
```
{"ok":true,"live":true}
```
And the connection will be kept open. If any object enters or exits the 6 km radius around `33.462,-112.268` the server will respond in realtime with a message such as:

```
{"command":"set","detect":"enter","id":"truck02","object":{"type":"Point","coordinates":[-112.2695,33.4626]}}
```

The server will notify the client if the `command` is `del | set | drop`. 

- `del` notifies the client that an object has been deleted from the collection that is being fenced.
- `drop` notifies the client that the entire collection is dropped.
- `set` notifies the client that an object has been added or updated, and when it's position is detected by the fence.

The `detect` may be one of the following values.

- `inside` is when an object is inside the specified area.
- `outside` is when an object is outside the specified area.
- `enter` is when an object that **was not** previously in the fence has entered the area.
- `exit` is when an object that **was** previously in the fence has exited the area.
- `cross` is when an object that **was not** previously in the fence has entered **and** exited the area.

These can be used when establishing a geofence, to pre-filter responses. For instance, to limit responses to `enter` and `exit` detections:

```
> nearby fleet fence detect enter,exit point 33.462 -112.268 6000
```

### Pub/sub channels

Tile38 supports delivering geofence notifications over pub/sub channels. 

To create a static geofence that sends notifications when a bus is within 200 meters of a point and sends to the `busstop` channel:

```
> setchan busstop nearby buses fence point 33.5123 -112.2693 200
```

Subscribe on the `busstop` channel:

```
> subscribe busstop
```

## Object types

All object types except for XYZ Tiles and QuadKeys can be stored in a collection. XYZ Tiles and QuadKeys are reserved for the SEARCH keyword only.

#### Lat/lon point
The most basic object type is a point that is composed of a latitude and a longitude. There is an optional `z` member that may be used for auxiliary data such as elevation or a timestamp.
```
set fleet truck1 point 33.5123 -112.2693     # plain lat/lon
set fleet truck1 point 33.5123 -112.2693 225 # lat/lon with z member
```

#### Bounding box
A bounding box consists of two points. The first being the southwestern most point and the second is the northeastern most point.
```
set fleet truck1 bounds 30 -110 40 -100
```
#### Geohash
A [geohash](https://en.wikipedia.org/wiki/Geohash) is a string representation of a point. With the length of the string indicating the precision of the point. 
```
set fleet truck1 hash 9tbnthxzr # this would be equivalent to 'point 33.5123 -112.2693'
```

#### GeoJSON
[GeoJSON](https://tools.ietf.org/html/rfc7946) is an industry standard format for representing a variety of object types including a point, multipoint, linestring, multilinestring, polygon, multipolygon, geometrycollection, feature, and featurecollection.

<i>* All ignored members will not persist.</i>

**Important to note that all coordinates are in Longitude, Latitude order.**

```
set city tempe object {"type":"Polygon","coordinates":[[[0,0],[10,10],[10,0],[0,0]]]}
```

#### XYZ Tile
An XYZ tile is rectangle bounding area on earth that is represented by an X, Y coordinate and a Z (zoom) level.
Check out [maptiler.org](http://www.maptiler.org/google-maps-coordinates-tile-bounds-projection/) for an interactive example.

#### QuadKey
A QuadKey used the same coordinate system as an XYZ tile except that the string representation is a string characters composed of 0, 1, 2, or 3. For a detailed explanation checkout [The Bing Maps Tile System](https://msdn.microsoft.com/en-us/library/bb259689.aspx).

## Network protocols

It's recommended to use a [client library](#tile38-client-libraries) or the [Tile38 CLI](#running), but there are times when only HTTP is available or when you need to test from a remote terminal. In those cases we provide an HTTP and telnet options.

#### HTTP
One of the simplest ways to call a tile38 command is to use HTTP. From the command line you can use [curl](https://curl.haxx.se/). For example:

```
# call with request in the body
curl --data "set fleet truck3 point 33.4762 -112.10923" localhost:9851

# call with request in the url path
curl localhost:9851/set+fleet+truck3+point+33.4762+-112.10923
```

#### Websockets
Websockets can be used when you need to Geofence and keep the connection alive. It works just like the HTTP example above, with the exception that the connection stays alive and the data is sent from the server as text websocket messages.

#### Telnet
There is the option to use a plain telnet connection. The default output through telnet is [RESP](https://redis.io/topics/protocol).

```
telnet localhost 9851
set fleet truck3 point 33.4762 -112.10923
+OK

```

The server will respond in [JSON](https://json.org) or [RESP](https://redis.io/topics/protocol) depending on which protocol is used when initiating the first command.

- HTTP and Websockets use JSON. 
- Telnet and RESP clients use RESP.

## Tile38 Client Libraries

The following clients are built specifically for Tile38.  
Clients that support most Tile38 features are marked with a ⭐️.

- ⭐️ Go: [xjem/t38c](https://github.com/xjem/t38c)
- ⭐️ Node.js: [node-tile38](https://github.com/phulst/node-tile38) ([example code](https://github.com/tidwall/tile38/wiki/Node.js-example-(node-tile38)))
- ⭐️ Python: [pyle38](https://github.com/iwpnd/pyle38)
- ⭐️ TypeScript: [tile38-ts](https://github.com/iwpnd/tile38-ts)
- Go: [cjkreklow/t38c](https://github.com/cjkreklow/t38c)
- Python: [pytile38](https://github.com/mitghi/pytile38)
- Rust: [nazar](https://github.com/younisshah/nazar)
- Swift: [Talon](https://github.com/mikekinney/Talon)
- Java: [tile38-client-java](https://github.com/jamshidrostami/tile38-client-java)
- Java: [tile38-client](https://github.com/HkMoyun/tile38-client)

## Redis Client Libraries

Tile38 uses the [Redis RESP](https://redis.io/topics/protocol) protocol natively. 
Therefore most clients that support basic Redis commands will also support Tile38.

- C: [hiredis](https://github.com/redis/hiredis)
- C#: [StackExchange.Redis](https://github.com/StackExchange/StackExchange.Redis)
- C++: [redox](https://github.com/hmartiro/redox)
- Clojure: [carmine](https://github.com/ptaoussanis/carmine)
- Common Lisp: [CL-Redis](https://github.com/vseloved/cl-redis)
- Erlang: [Eredis](https://github.com/wooga/eredis)
- Go: [go-redis](https://github.com/go-redis/redis) ([example code](https://github.com/tidwall/tile38/wiki/Go-example-(go-redis)))
- Go: [redigo](https://github.com/gomodule/redigo) ([example code](https://github.com/tidwall/tile38/wiki/Go-example-(redigo)))
- Haskell: [hedis](https://github.com/informatikr/hedis)
- Java: [lettuce](https://github.com/mp911de/lettuce) ([example code](https://github.com/tidwall/tile38/wiki/Java-example-(lettuce)))
- Node.js: [node_redis](https://github.com/NodeRedis/node_redis) ([example code](https://github.com/tidwall/tile38/wiki/Node.js-example-(node-redis)))
- Perl: [perl-redis](https://github.com/PerlRedis/perl-redis)
- PHP: [tinyredisclient](https://github.com/ptrofimov/tinyredisclient) ([example code](https://github.com/tidwall/tile38/wiki/PHP-example-(tinyredisclient)))
- PHP: [phpredis](https://github.com/phpredis/phpredis)
- Python: [redis-py](https://github.com/andymccurdy/redis-py) ([example code](https://github.com/tidwall/tile38/wiki/Python-example))
- Ruby: [redic](https://github.com/amakawa/redic) ([example code](https://github.com/tidwall/tile38/wiki/Ruby-example-(redic)))
- Ruby: [redis-rb](https://github.com/redis/redis-rb) ([example code](https://github.com/tidwall/tile38/wiki/Ruby-example-(redis-rb)))
- Rust: [redis-rs](https://github.com/mitsuhiko/redis-rs)
- Scala: [scala-redis](https://github.com/debasishg/scala-redis)
- Swift: [Redbird](https://github.com/czechboy0/Redbird)

## Contact

Josh Baker [@tidwall](https://twitter.com/tidwall)

## License

Tile38 source code is available under the MIT [License](/LICENSE).


Tile38

Library for Coordinate Conversion and Transformation (ETRS89, OSGB36, NAD83, RGF93, Web Mercator, UTM).

## WGS84 - Coordinate Transformations

```
github.com/wroge/wgs84/v2
```  


I am currently in the process of rewriting the package. Some things will change and some new features will be added. One of these features is the support of NTv2 grid transformations and other projections, such as Krovak. If you would like to help or have any comments, please report them in the issues.

### Web Mercator

```go
package main

import (
	"fmt"

	"github.com/wroge/wgs84/v2"
)

func main() {
	transform := wgs84.Transform(wgs84.EPSG(4326), wgs84.EPSG(3857)).Round(3)

	east, north, _ := transform(10, 50, 0)

	fmt.Println(east, north)
	// 1.113194908e+06 6.446275841e+06

	// echo 10 50 | cs2cs +init=epsg:4326 +to +init=epsg:3857 -d 3
	// 1113194.908     6446275.841
}
```

### OSGB

```go
package main

import (
	"fmt"

	"github.com/wroge/wgs84/v2"
)

func main() {
	transform := wgs84.Transform(wgs84.EPSG(4326), wgs84.EPSG(27700)).Round(3)

	east, north, h := transform(-2.25, 52.25, 0)

	fmt.Println(east, north, h)
	// 383029.296 261341.615 0

	// echo -2.25 52.25 | cs2cs +init=epsg:4326 +to +init=epsg:27700 -d 3
	// 383029.296 261341.615 0.000
}
```


The Best Go Libraries For Geographic (13)