Skip to content

Commit

Permalink
update README to new GeoInterface based API
Browse files Browse the repository at this point in the history
  • Loading branch information
@visr
visr committed Jun 2, 2017
1 parent 5522c4f commit 6919649
Showing 1 changed file with 19 additions and 68 deletions.
87 changes: 19 additions & 68 deletions README.md
View file
Expand Up @@ -8,7 +8,7 @@ This library is developed independently of, but is heavily influenced in design

- Functions for encoding and decoding GeoJSON formatted data
- a type hierarchy (according to the [GeoJSON specification](http://geojson.org/geojson-spec.html))
- An implementation of the [__geo_interface__](https://gist.github.com/sgillies/2217756), a GeoJSON-like protocol for geo-spatial (GIS) vector data.
- An implementation of the [\__geo_interface\__](https://gist.github.com/sgillies/2217756), a GeoJSON-like protocol for geo-spatial (GIS) vector data.

## Installation
```julia
Expand All @@ -19,9 +19,9 @@ Pkg.test("GeoJSON")
```

## Basic Usage
Although we introduce types for representing GeoJSON objects, it works in tandem with the [JSON.jl](https://github.com/JuliaLang/JSON.jl) package, for parsing and printing objects. Here are some examples of its functionality:
Although we use GeoInterface types for representing GeoJSON objects, it works in tandem with the [JSON.jl](https://github.com/JuliaIO/JSON.jl) package, for parsing ~~and printing~~ objects. Here are some examples of its functionality:

- Parses a JSON String or IO stream into a GeoJSON object
- Parses a GeoJSON String or IO stream into a GeoInterface object
```julia
julia> using GeoJSON
julia> osm_buildings = """{
Expand Down Expand Up @@ -50,87 +50,38 @@ julia> osm_buildings = """{
}
}]
}"""
julia> buildings = GeoJSON.parse(osm_buildings) # GeoJSON.parse -- string or stream to AbstractGeoJSON types
FeatureCollection([Feature(Polygon({{{13.42634,52.49533},{13.4266,52.49524},{13.42619,52.49483},{13.42583,52.49495},{13.4259,52.49501},{13.42611,52.49494},{13.4264,52.49525},{13.4263,52.49529},{13.42634,52.49533}}},#undef,#undef),["height"=>150,"color"=>"rgb(255,200,150)"],#undef,#undef,#undef)],#undef,#undef)
julia> buildings = GeoJSON.parse(osm_buildings) # GeoJSON.parse -- parse a GeoJSON string or stream
GeoInterface.FeatureCollection{GeoInterface.Feature}(GeoInterface.Feature[GeoInterface.Feature(GeoInterface.Polygon(Array{Array{Float64,1},1}[Array{Float64,1}[[13.4263,52.4953],[13.4266,52.4952],[13.4262,52.4948],[13.4258,52.495],[13.4259,52.495],[13.4261,52.4949],[13.4264,52.4952],[13.4263,52.4953],[13.4263,52.4953]]]),Dict{String,Any}(Pair{String,Any}("height",150),Pair{String,Any}("color","rgb(255,200,150)")))],nothing,nothing)
```
Use `GeoJSON.parsefile("tech_square.geojson")` to read GeoJSON files from disk.

- Transforms a GeoJSON object into a nested Array or Dict
- Transforms a GeoInterface object into a nested Array or Dict

```julia
julia> GeoJSON.geojson2dict(buildings) # geojson2dict -- AbstractGeoJSON to Dict/Array-representation
julia> dict = geo2dict(buildings) # geo2dict -- GeoInterface object to Dict/Array-representation
Dict{String,Any} with 2 entries:
"features" => [["geometry"=>["coordinates"=>{{{13.42634,52.49533},{13.4266,52.49524},{13.42619,52.49483},{13.42583,52.49495},{13.4259,52.49…
"features" => Dict{String,Any}[Dict{String,Any}(Pair{String,Any}("geometry",Dict{String,Any}(Pair{String,Any}("coordi…
"type" => "FeatureCollection"
julia> JSON.parse(osm_buildings) # should be comparable (if not the same)
Dict{String,Any} with 2 entries:
"features" => {["geometry"=>["coordinates"=>{{{13.42634,52.49533},{13.4266,52.49524},{13.42619,52.49483},{13.42583,52.49495},{13.4259,52.49…
"features" => Any[Dict{String,Any}(Pair{String,Any}("geometry",Dict{String,Any}(Pair{String,Any}("coordinates",Any[An…
"type" => "FeatureCollection"
```
- Transforms from a nested Array/Dict to a GeoJSON object
- Transforms from a nested Array/Dict to a GeoInterface object
```julia
julia> GeoJSON.dict2geojson(GeoJSON.geojson2dict(buildings))
FeatureCollection([Feature(Polygon({{{13.42634,52.49533},{13.4266,52.49524},{13.42619,52.49483},{13.42583,52.49495},{13.4259,52.49501},{13.42611,52.49494},{13.4264,52.49525},{13.4263,52.49529},{13.42634,52.49533}}},#undef,#undef),["height"=>150,"color"=>"rgb(255,200,150)"],#undef,#undef,#undef)],#undef,#undef)
julia> dict2geo(dict)
GeoInterface.FeatureCollection{GeoInterface.Feature}(GeoInterface.Feature[GeoInterface.Feature(GeoInterface.Polygon(Array{Array{Float64,1},1}[Array{Float64,1}[[13.4263,52.4953],[13.4266,52.4952],[13.4262,52.4948],[13.4258,52.495],[13.4259,52.495],[13.4261,52.4949],[13.4264,52.4952],[13.4263,52.4953],[13.4263,52.4953]]]),Dict{String,Any}(Pair{String,Any}("height",150),Pair{String,Any}("color","rgb(255,200,150)")))],nothing,nothing)
julia> GeoJSON.parse(osm_buildings) # the original object (for comparison)
FeatureCollection([Feature(Polygon({{{13.42634,52.49533},{13.4266,52.49524},{13.42619,52.49483},{13.42583,52.49495},{13.4259,52.49501},{13.42611,52.49494},{13.4264,52.49525},{13.4263,52.49529},{13.42634,52.49533}}},#undef,#undef),["height"=>150,"color"=>"rgb(255,200,150)"],#undef,#undef,#undef)],#undef,#undef)
GeoInterface.FeatureCollection{GeoInterface.Feature}(GeoInterface.Feature[GeoInterface.Feature(GeoInterface.Polygon(Array{Array{Float64,1},1}[Array{Float64,1}[[13.4263,52.4953],[13.4266,52.4952],[13.4262,52.4948],[13.4258,52.495],[13.4259,52.495],[13.4261,52.4949],[13.4264,52.4952],[13.4263,52.4953],[13.4263,52.4953]]]),Dict{String,Any}(Pair{String,Any}("height",150),Pair{String,Any}("color","rgb(255,200,150)")))],nothing,nothing)
```
- Returns a compact JSON representation as a String
- Writing back GeoJSON strings is not yet implemented
```julia
julia> geojson(buildings) # AbstractGeoJSON to a string
"{\"features\":[{\"geometry\":{\"coordinates\":[[[13.42634,52.49533],[13.4266,52.49524],[13.42619,52.49483],[13.42583,52.49495],[13.4259,52.49501],[13.42611,52.49494],[13.4264,52.49525],[13.4263,52.49529],[13.42634,52.49533]]],\"type\":\"Polygon\"},\"properties\":{\"height\":150,\"color\":\"rgb(255,200,150)\"},\"type\":\"Feature\"}],\"type\":\"FeatureCollection\"}"

julia> JSON.json(JSON.parse(osm_buildings)) # compared with the JSON parser
"{\"features\":[{\"geometry\":{\"coordinates\":[[[13.42634,52.49533],[13.4266,52.49524],[13.42619,52.49483],[13.42583,52.49495],[13.4259,52.49501],[13.42611,52.49494],[13.4264,52.49525],[13.4263,52.49529],[13.42634,52.49533]]],\"type\":\"Polygon\"},\"properties\":{\"height\":150,\"color\":\"rgb(255,200,150)\"},\"type\":\"Feature\"}],\"type\":\"FeatureCollection\"}"
```
- Writes a compact (no extra whitespace or identation) JSON representation to the supplied IO.
```julia
GeoJSON.print(io::IO, obj::AbstractGeoJSON)
```
## GeoJSON Objects
This library implements the following [GeoJSON Objects](http://www.geojson.org/geojson-spec.html#geojson-objects) described in The GeoJSON Format Specification.
- `CRS`
- `Position`
- `Geometry <: AbstractGeoJSON`
- `Point <: Geometry`
- `MultiPoint <: Geometry`
- `LineString <: Geometry`
- `MultiLineString <: Geometry`
- `Polygon <: Geometry`
- `MultiPolygon <: Geometry`
- `GeometryCollection <: Geometry`
- `Feature <: AbstractGeoJSON`
- `FeatureCollection <: AbstractGeoJSON`
The following methods are implemented for all AbstractGeoJSON objects:
```julia
hasbbox(obj::AbstractGeoJSON) # returns true if obj has a "bbox" key
hascrs(obj::AbstractGeoJSON) # returns true if obj has a "crs" key
bbox(obj::AbstractGeoJSON) # returns the boundingbox of obj
crs(obj::AbstractGeoJSON) # returns the coordinate reference system
```
In addition, the `Feature` object also implements ```hasid(obj::Feature)```.
### GeoJSON Attributes (GEO_Interface)
In accordance with the [GeoJSON format](http://geojson.org/geojson-spec.html) (and the [__geo_interface__](https://gist.github.com/sgillies/2217756)), the following methods are implemented for each of the GeoJSON objects:
```julia
# GeoJSON (methods,)
# --------------------------------------------
((MultiPolygon, (coordinates,)),
(Polygon, (coordinates,)),
(MultiLineString, (coordinates,)),
(LineString, (coordinates,)),
(MultiPoint, (coordinates,)),
(Point, (coordinates,)),
(GeometryCollection, (geometries,)),
(Feature, (geometry, properties, id)),
(FeatureCollection, (features,)))
```
## GeoInterface
This library implements the [GeoInterface](https://github.com/JuliaGeo/GeoInterface.jl).
For more information on the types that are returned by this package, and the methods that can be
used on them, refer to the documentation of the GeoInterface package.

0 comments on commit 6919649

Please sign in to comment.