photoprism-client-go/vendor/github.com/paulmach/go.geojson/README.md

109 lines
4.1 KiB
Markdown
Raw Normal View History

go.geojson
==========
Go.geojson is a package for **encoding and decoding** [GeoJSON](http://geojson.org/) into Go structs.
Supports both the [json.Marshaler](http://golang.org/pkg/encoding/json/#Marshaler) and [json.Unmarshaler](http://golang.org/pkg/encoding/json/#Unmarshaler)
interfaces as well as [sql.Scanner](http://golang.org/pkg/database/sql/#Scanner) for directly scanning PostGIS query results.
The package also provides helper functions such as `UnmarshalFeatureCollection`, `UnmarshalFeature` and `UnmarshalGeometry`.
### Important
This package is best for lightweight interaction with GeoJSON. If you want to actually do
stuff with the geometry take a look at [orb/geojson](https://github.com/paulmach/orb/tree/master/geojson) which
decodes the geometries into [orb](https://github.com/paulmach/orb) types which you can do all sorts of things with.
#### To install
go get github.com/paulmach/go.geojson
#### To use, imports as package name `geojson`:
import "github.com/paulmach/go.geojson"
[![Build Status](https://travis-ci.org/paulmach/go.geojson.svg?branch=master)](https://travis-ci.org/paulmach/go.geojson)
[![Godoc Reference](https://godoc.org/github.com/paulmach/go.geojson?status.svg)](https://godoc.org/github.com/paulmach/go.geojson)
## Examples
* #### Unmarshalling (JSON -> Go)
go.geojson supports both the [json.Marshaler](http://golang.org/pkg/encoding/json/#Marshaler) and [json.Unmarshaler](http://golang.org/pkg/encoding/json/#Unmarshaler) interfaces as well as helper functions such as `UnmarshalFeatureCollection`, `UnmarshalFeature` and `UnmarshalGeometry`.
// Feature Collection
rawFeatureJSON := []byte(`
{ "type": "FeatureCollection",
"features": [
{ "type": "Feature",
"geometry": {"type": "Point", "coordinates": [102.0, 0.5]},
"properties": {"prop0": "value0"}
}
]
}`)
fc1, err := geojson.UnmarshalFeatureCollection(rawFeatureJSON)
fc2 := geojson.NewFeatureCollection()
err := json.Unmarshal(rawJSON, fc2)
// Geometry
rawGeometryJSON := []byte(`{"type": "Point", "coordinates": [102.0, 0.5]}`)
g, err := geojson.UnmarshalGeometry(rawGeometryJSON)
g.IsPoint() == true
g.Point == []float64{102.0, 0.5}
* #### Marshalling (Go -> JSON)
g := geojson.NewPointGeometry([]float64{1, 2})
rawJSON, err := g.MarshalJSON()
fc := geojson.NewFeatureCollection()
fc.AddFeature(geojson.NewPointFeature([]float64{1,2}))
rawJSON, err := fc.MarshalJSON()
* #### Scanning PostGIS query results
row := db.QueryRow("SELECT ST_AsGeoJSON(the_geom) FROM postgis_table)
var geometry *geojson.Geometry
row.Scan(&geometry)
* #### Dealing with different Geometry types
A geometry can be of several types, causing problems in a statically typed language.
Thus there is a separate attribute on Geometry for each type.
See the [Geometry object](https://godoc.org/github.com/paulmach/go.geojson#Geometry) for more details.
g := geojson.UnmarshalGeometry([]byte(`
{
"type": "LineString",
"coordinates": [
[102.0, 0.0], [103.0, 1.0], [104.0, 0.0], [105.0, 1.0]
]
}`))
switch {
case g.IsPoint():
// do something with g.Point
case g.IsLineString():
// do something with g.LineString
}
## Feature Properties
GeoJSON [Features](http://geojson.org/geojson-spec.html#feature-objects) can have properties of any type.
This can cause issues in a statically typed language such as Go.
So, included are some helper methods on the Feature object to ease the pain.
// functions to do the casting for you
func (f Feature) PropertyBool(key string) (bool, error) {
func (f Feature) PropertyInt(key string) (int, error) {
func (f Feature) PropertyFloat64(key string) (float64, error) {
func (f Feature) PropertyString(key string) (string, error) {
// functions that hide the error and let you define default
func (f Feature) PropertyMustBool(key string, def ...bool) bool {
func (f Feature) PropertyMustInt(key string, def ...int) int {
func (f Feature) PropertyMustFloat64(key string, def ...float64) float64 {
func (f Feature) PropertyMustString(key string, def ...string) string {