|
1 | | -# GeoInterface.jl |
| 1 | +[](https://juliageo.github.io/GeoInterface.jl/stable) |
| 2 | +[](https://juliageo.github.io/GeoInterface.jl/dev) |
| 3 | +[](https://github.com/JuliaGeo/GeoInterface.jl/actions/workflows/CI.yml?query=branch%3Amain) |
2 | 4 |
|
3 | | -A Julia Protocol for Geospatial Data |
| 5 | +# GeoInterface |
| 6 | +An interface for geospatial vector data in [Julia](https://julialang.org/). |
4 | 7 |
|
5 | | -## Motivation |
6 | | -To support operations or visualization of multiple (but similar) implementations of vector data (across `GeoJSON.jl`, `LibGEOS.jl`, etc). As a starting point, it will follow the [GEO interface](https://gist.github.com/sgillies/2217756) [1] in Python (which in turn borrows its design from the [GeoJSON specification](http://geojson.org/) [2]). |
| 8 | +This Package describe a set of traits based on the [Simple Features standard |
| 9 | +(SF)](https://www.opengeospatial.org/standards/sfa) for geospatial vector data, including |
| 10 | +the SQL/MM extension with support for circular geometry. Using these traits, it should be |
| 11 | +easy to parse, serialize and use different geometries in the Julia ecosystem, without |
| 12 | +knowing the specifics of each individual package. In that regard it is similar to |
| 13 | +[Tables.jl](https://github.com/JuliaData/Tables.jl), but for geometries instead of tables. |
7 | 14 |
|
8 | | -## GEO Interface |
| 15 | +Packages which support the GeoInterface.jl interface can be found in |
| 16 | +[INTEGRATIONS.md](INTEGRATIONS.md). |
9 | 17 |
|
10 | | -### AbstractPosition |
11 | | -A position can be thought of as a tuple of numbers. There must be at least two elements, and may be more. The order of elements must follow `x`, `y`, `z` order (e.g. easting, northing, altitude for coordinates in a projected coordinate reference system, or longitude, latitude, altitude for coordinates in a geographic coordinate reference system). It requires the following methods: |
12 | | - |
13 | | -- `xcoord(::AbstractPosition)::Float64` |
14 | | -- `ycoord(::AbstractPosition)::Float64` |
15 | | -- `zcoord(::AbstractPosition)::Float64` |
16 | | -- `hasz(::AbstractPosition)::Bool` (`false` by default) |
17 | | - |
18 | | -Remark: Although the specification allows the representation of up to 3 dimensions, not all algorithms support require all 3 dimensions. Also, if you are working with an arbitrary `obj::AbstractPosition`, you should call `hasz(obj)` before calling `zcoord(obj)`. |
19 | | - |
20 | | -### AbstractGeometry |
21 | | -Represents vector geometry, and encompasses the following abstract types: `AbstractPoint, AbstractMultiPoint, AbstractLineString, AbstractMultiLineString, AbstractMultiPolygon, AbstractPolygon`. It requires the `coordinates` method, where |
22 | | - |
23 | | -- `coordinates(::AbstractPoint)` returns a single position. |
24 | | -- `coordinates(::AbstractMultiPoint)` returns a vector of positions. |
25 | | -- `coordinates(::AbstractLineString)` returns a vector of positions. |
26 | | -- `coordinates(::AbstractMultiLineString)` returns a vector of linestrings. |
27 | | -- `coordinates(::AbstractPolygon)` returns a vector of linestrings. |
28 | | -- `coordinates(::AbstractMultiPolygon)` returns a vector of polygons. |
29 | | - |
30 | | -### AbstractGeometryCollection |
31 | | -Represents a collection of geometries, and requires the `geometries` method, which returns a vector of geometries. Is also a subtype of `AbstractGeometry`. |
32 | | - |
33 | | -### AbstractFeature |
34 | | -Represents a geometry with additional attributes, and requires the following methods |
35 | | - |
36 | | -- `geometry(::AbstractFeature)::AbstractGeometry` returns the corresponding geometry |
37 | | -- `properties(::AbstractFeature)::Dict{AbstractString,Any}` returns a dictionary of the properties |
38 | | - |
39 | | -Optionally, you can also provide the following methods |
40 | | - |
41 | | -- `bbox(::AbstractFeature)::AbstractGeometry` returns the bounding box for that feature |
42 | | -- `crs(::AbstractFeature)::Dict{AbstractString,Any}` returns the coordinate reference system |
43 | | - |
44 | | -## Geospatial Geometries |
45 | | -If you don't need to provide your own user types, GeoInterface also provides a set of geometries (below), which implements the GEO Interface: |
46 | | - |
47 | | -- `CRS` |
48 | | -- `Position` |
49 | | -- `Geometry <: AbstractGeometry` |
50 | | - - `Point <: AbstractPoint <: AbstractGeometry` |
51 | | - - `MultiPoint <: AbstractMultiPoint <: AbstractGeometry` |
52 | | - - `LineString <: AbstractLineString <: AbstractGeometry` |
53 | | - - `MultiLineString <: AbstractMultiLineString <: AbstractGeometry` |
54 | | - - `Polygon <: AbstractPolygon <: AbstractGeometry` |
55 | | - - `MultiPolygon <: AbstractMultiPolygon <: AbstractGeometry` |
56 | | - - `GeometryCollection <: AbstractGeometryCollection <: AbstractGeometry` |
57 | | -- `Feature <: AbstractFeature` |
58 | | -- `FeatureCollection <: AbstractFeatureCollection` |
59 | | - |
60 | | -## Remarks |
61 | | - |
62 | | -Conceptually, |
63 | | - |
64 | | -- an `::AbstractGeometryCollection` maps to a `DataArray{::AbstractGeometry}`, and |
65 | | -- an `::AbstractFeatureCollection` maps to a `DataFrame`, where each row is an `AbstractFeature` |
66 | | - |
67 | | -The design of the types in GeoInterface differs from the GeoJSON specification in the following ways: |
68 | | - |
69 | | -- Julia Geometries do not provide a `bbox` and `crs` method. If you wish to provide a `bbox` or `crs` attribute, wrap the geometry into a `Feature` or `FeatureCollection`. |
70 | | -- Features do not have special fields for `id`, `bbox`, and `crs`. These are to be provided (or found) in the `properties` field, under the keys `featureid`, `bbox`, and `crs` respectively (if they exist). |
71 | | - |
72 | | -## References |
73 | | - |
74 | | -[1]: A Python Protocol for Geospatial Data ([gist](https://gist.github.com/sgillies/2217756)) |
75 | | - |
76 | | -[2]: GeoJSON Specification ([website](http://geojson.org/)) |
| 18 | +We thank Julia Computing for supporting contributions to this package. |
0 commit comments