Geospatial data structures (coordinates, geometries, features, metadata), spherical geodesy, projections and tiling schemes. Vector data format support for GeoJSON, WKT and WKB.

## Features

✨ New (2024-05-26): The new documentation website (geospatial.navibyte.dev) for the geobase package documentation published along with the stable version 1.2.0.

✨ New (2024-04-22): Support for Newline-delimited GeoJSON, EWKT and EWKB added. Check out the blog post.

✨ New (2023-10): The stable version 1.0.0 is now ready. See also the article Geospatial tools for Dart - version 1.0 published at Medium.

✨ New (2023-07): Spherical geodesy functions (distance, bearing, destination point, etc.) for *great circle* and *rhumb line* paths.

Key features:

- 🌐 geographic (longitude-latitude) and projected positions and bounding boxes
- 📐 spherical geodesy functions for
*great circle*and*rhumb line*paths - 🧩 simple geometries (point, line string, polygon, multi point, multi line string, multi polygon, geometry collection)
- 🔷 features (with id, properties and geometry) and feature collections
- 📅 temporal data structures (instant, interval) and spatial extents
- 📃 vector data formats supported (GeoJSON, Newline-delimited GeoJSON, WKT, WKB )
- 🗺️ coordinate projections (web mercator + based on the external proj4dart library)
- 🔢 tiling schemes and tile matrix sets (web mercator, global geodetic)

## Documentation

Comprehensive guidance on how to use this package and about
*Geospatial tools for Dart* (the package is part of) is available on the
geospatial.navibyte.dev website.

Shortcuts to the geobase package documentation by chapters:

- 📍 Coordinates
- 🧩 Simple geometries
- 🔷 Geospatial features
- 📃 Vector formats
- 📅 Metadata
- 🗺️ Projections
- 📐 Spherical geodesy
- 🔢 Tiling schemes

See also overview topics about *Geospatial tools for Dart*:

## Introduction

General purpose positions, series of positions and bounding boxes:

```
// A position as a view on a coordinate array containing x and y.
Position.view([708221.0, 5707225.0]);
// The sample above shorted.
[708221.0, 5707225.0].xy;
// A bounding box.
Box.view([70800.0, 5707200.0, 70900.0, 5707300.0]);
// A series of positions from an array of position objects.
PositionSeries.from(
[
[70800.0, 5707200.0].xy, // position 0 with (x, y) coordinate values
[70850.0, 5707250.0].xy, // position 1 with (x, y) coordinate values
[70900.0, 5707300.0].xy, // position 2 with (x, y) coordinate values
],
type: Coords.xy,
);
```

*Geographic* and *projected* positions and bounding boxes:

```
// A geographic position without and with an elevation.
Geographic(lon: -0.0014, lat: 51.4778);
Geographic(lon: -0.0014, lat: 51.4778, elev: 45.0);
// A projected position without and with z.
Projected(x: 708221.0, y: 5707225.0);
Projected(x: 708221.0, y: 5707225.0, z: 45.0);
// Geographic and projected bounding boxes.
GeoBox(west: -20, south: 50, east: 20, north: 60);
GeoBox(west: -20, south: 50, minElev: 100, east: 20, north: 60, maxElev: 200);
ProjBox(minX: 10, minY: 10, maxX: 20, maxY: 20);
// Positions and bounding boxes can be also built from an array or parsed.
Geographic.build([-0.0014, 51.4778]);
Geographic.parse('-0.0014,51.4778');
Geographic.parse('-0.0014 51.4778', delimiter: ' ');
Geographic.parseDms(lon: '0° 00′ 05″ W', lat: '51° 28′ 40″ N');
GeoBox.build([-20, 50, 100, 20, 60, 200]);
GeoBox.parse('-20,50,100,20,60,200');
GeoBox.parseDms(west: '20°W', south: '50°N', east: '20°E', north: '60°N');
```

Coordinates for *pixels* and *tiles* in tiling schemes:

```
// Projected coordinates to represent *pixels* or *tiles* in tiling schemes.
Scalable2i(zoom: 9, x: 23, y: 10);
```

Spherical geodesy functions for *great circle* (shown below) and *rhumb line*
paths:

```
final greenwich = Geographic.parseDms(lat: '51°28′40″ N', lon: '0°00′05″ W');
final sydney = Geographic.parseDms(lat: '33.8688° S', lon: '151.2093° E');
// Distance (~ 16988 km)
greenwich.spherical.distanceTo(sydney);
// Initial and final bearing: 61° -> 139°
greenwich.spherical.initialBearingTo(sydney);
greenwich.spherical.finalBearingTo(sydney);
// Destination point (10 km to bearing 61°): 51° 31.3′ N, 0° 07.5′ E
greenwich.spherical.destinationPoint(distance: 10000, bearing: 61.0);
// Midpoint: 28° 34.0′ N, 104° 41.6′ E
greenwich.spherical.midPointTo(sydney);
```

Geometry primitive and multi geometry objects:

```
// A point with a 2D position.
Point.build([30.0, 10.0]);
// A line string (polyline) with three 2D positions.
LineString.build([30, 10, 10, 30, 40, 40]);
// A polygon with an exterior ring (and without any holes).
Polygon.build([
[30, 10, 40, 40, 20, 40, 10, 20, 30, 10]
]);
// A polygon with an exterior ring and an interior ring as a hole.
Polygon.build([
[35, 10, 45, 45, 15, 40, 10, 20, 35, 10],
[20, 30, 35, 35, 30, 20, 20, 30],
]);
// A multi point with four points:
MultiPoint.build([
[10, 40],
[40, 30],
[20, 20],
[30, 10]
]);
// A multi line string with two line strings (polylines):
MultiLineString.build([
[10, 10, 20, 20, 10, 40],
[40, 40, 30, 30, 40, 20, 30, 10]
]);
// A multi polygon with two polygons both with an outer ring (without holes).
MultiPolygon.build([
[
[30, 20, 45, 40, 10, 40, 30, 20],
],
[
[15, 5, 40, 10, 10, 20, 5, 10, 15, 5],
],
]);
// A geometry collection with a point, a line string and a polygon.
GeometryCollection([
Point.build([30.0, 10.0]),
LineString.build([10, 10, 20, 20, 10, 40]),
Polygon.build([
[40, 40, 20, 45, 45, 30, 40, 40],
])
]);
```

Primitive geometries introduced above contain geographic or projected positions:

`Point`

with a single position`LineString`

with a chain of positions (at least two positions)`Polygon`

with an array of linear rings (exactly one exterior and 0 to N interior rings with each ring being a closed chain of positions)

In previous samples position data (chains of positions) is NOT modeled as iterables of position objects, but as a flat structure represented by arrays of coordinate values, for example:

- 2D position arrays:
`[x0, y0, x1, y1, x2, y2, ...]`

- 3D position arrays:
`[x0, y0, z0, x1, y1, z1, x2, y2, z2, ...]`

To distinguish between arrays of different spatial dimensions you can use
`Coords`

enum:

```
LineString.build([30, 10, 10, 30, 40, 40]); // default type == Coords.xy
LineString.build([30, 10, 10, 30, 40, 40], type: Coords.xy);
LineString.build([30, 10, 5.5, 10, 30, 5.5, 40, 40, 5.5], type: Coords.xyz);
```

GeoJSON, WKT and WKB formats are supported as input and output:

```
// Parse a geometry from GeoJSON text.
final geometry = LineString.parse(
'{"type": "LineString", "coordinates": [[30,10],[10,30],[40,40]]}',
format: GeoJSON.geometry,
);
// Encode a geometry as GeoJSON text.
print(geometry.toText(format: GeoJSON.geometry));
// Encode a geometry as WKT text.
print(geometry.toText(format: WKT.geometry));
// Encode a geometry as WKB bytes.
final bytes = geometry.toBytes(format: WKB.geometry);
// Decode a geometry from WKB bytes.
LineString.decode(bytes, format: WKB.geometry);
```

*Features* represent geospatial entities with properies and geometries:

```
Feature(
id: 'ROG',
// a point geometry with a position (lon, lat, elev)
geometry: Point.build([-0.0014, 51.4778, 45.0]),
properties: {
'title': 'Royal Observatory',
},
);
```

The GeoJSON format is supported as text input and output for features:

```
final feature = Feature.parse(
'''
{
"type": "Feature",
"id": "ROG",
"geometry": {
"type": "Point",
"coordinates": [-0.0014, 51.4778, 45.0]
},
"properties": {
"title": "Royal Observatory"
}
}
''',
format: GeoJSON.feature,
);
print(feature.toText(format: GeoJSON.feature));
```

Collections of feature objects are modeled as `FeatureCollection`

objects. See
the chapter about geospatial features for more
information.

Temporal instants and intervals, and geospatial extents:

```
// An instant and three intervals (open-started, open-ended, closed).
Instant.parse('2020-10-31 09:30Z');
Interval.parse('../2020-10-31');
Interval.parse('2020-10-01/..');
Interval.parse('2020-10-01/2020-10-31');
// An extent with spatial (WGS 84 longitude-latitude) and temporal parts.
GeoExtent.single(
crs: CoordRefSys.CRS84,
bbox: GeoBox(west: -20.0, south: 50.0, east: 20.0, north: 60.0),
interval: Interval.parse('../2020-10-31'),
);
```

Coordinate projections, tiling schemes (web mercator, global geodetic) and coordinate array classes are some of the more advanced topics not introduced here. Please see separate chapters about projections, tiling schemes and coordinate arrays to learn about them.

## Usage

The package requires at least Dart SDK 2.17, and it supports all Dart and Flutter platforms.

Add the dependency in your `pubspec.yaml`

:

```
dependencies:
geobase: ^1.2.0
```

Import it:

```
import `package:geobase/geobase.dart`
```

There are also partial packages containing only a certain subset. See the Packages section below.

Other resources:

📚

Web APIs: See also the geodata package that extends capabilities of`geobase`

by providing geospatial API clients to read GeoJSON data sources and OGC API Features web services.🚀

Samples: The Geospatial demos for Dart repository contains more sample code showing also how to use this package!

## Reference

### Documentation

Please see the geospatial.navibyte.dev website for the geobase package documentation.

### Packages

The **geobase** library contains also following partial packages, that can be
used to import only a certain subset instead of the whole **geobase** package:

Package | Description |
---|---|

common |
Common codes, constants, functions, presentation helpers and reference systems related to geospatial applications. |

coordinates |
Position, bounding box and positions series (with coordinate arrays). |

geodesy |
Spherical geodesy functions for great circle and rhumb line paths. |

meta |
Temporal data structures (instant, interval) and spatial extents. |

projections |
Geospatial projections (currently only between WGS84 and Web Mercator). |

projections_proj4d |
Projections provided by the external proj4dart package. |

tiling |
Tiling schemes and tile matrix sets (web mercator, global geodetic). |

vector |
Text and binary formats for vector data (features, geometries, coordinates). |

vector_data |
Data structures for geometries, features and feature collections. |

External packages `geobase`

is depending on:

## Authors

This project is authored by Navibyte.

More information and other links are available at the geospatial repository from GitHub.

## License

This project is licensed under the "BSD-3-Clause"-style license.

Please see the LICENSE.

## Derivative work

This project contains portions of derivative work.

See details about DERIVATIVE work.

## Libraries

- common
- Common codes, constants, functions, presentation helpers and reference systems related to geospatial applications.
- coordinates
- Position, bounding box and positions series (with coordinate arrays).
- geobase
- Geospatial data, spherical geodesy, projections, tiling schemes and vector data.
- geodesy
- Spherical geodesy functions for
*great circle*and*rhumb line*paths. - meta
- Temporal data structures (instant, interval) and spatial extents.
- projections
- Geospatial projections (currently only between WGS84 and Web Mercator).
- projections_proj4d
- Projections provided by the external
`proj4dart`

package. - tiling
- Tiling schemes and tile matrix sets (web mercator, global geodetic).
- vector
- Text and binary formats for vector data (features, geometries, coordinates).
- vector_data
- Data structures for geometries, geometry collections, features and feature collections.