geobase 1.2.0

Geospatial data, spherical geodesy, projections, tiling schemes, and vector formats (GeoJSON, WKT, WKB).

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:

• ⛳️ Getting started
• 📖 Introduction
• 💼 Code project
• 📚 API documentation

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:

• equatable for equality and hash utils
• meta for annotations
• proj4dart for coordinate projections

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.