Geospatial data structures (coordinates, geometries, features, metadata),ellipsoidal and spherical geodesy, projections and tiling schemes. Vector dataformat support forGeoJSON,WKTandWKB.

Features#

Key features:

• 🌐 geographic (longitude-latitude) and projected positions and bounding boxes
• 🧩 simple geometries (point, line string, polygon, multi point, multi line string, multi polygon, geometry collection)
• 📏 cartesian 2D calculations (centroid, polylabel, point-in-polygon, distance).
• 🔷 features (with id, properties and geometry) and feature collections
• 📐 ellipsoidal (vincenty) and spherical (great circle,rhumb line) geodesy tools, with ellipsoidal datum,UTM,MGRS and ECEF (earth-centric earth-fixed) support
• 📅 temporal data structures (instant, interval) and spatial extents
• 📃 vector data formats supported (GeoJSON,Newline-delimited GeoJSON,WKT,WKB)
• 🗺️ coordinate projections (built-in WGS84 based projections on geographic, geocentric, UTM and Web Mercator coordinates + externalproj4dart support)
• 🔢 tiling schemes and tile matrix sets (web mercator, global geodetic)
• ⚖️ unit conversions (angle, angular velocity, area, distance, speed and time)

Latest changes#

✨ New (2025-03-11): The stable version 1.5.0 withglobal grids, better WGS84projection support andunit conversions.

✨ New (2024-11-10): The stable version 1.4.0 withellipsoidal geodesy functions letting you calculate distances, bearings, destination positions and intermediate points along the Earth surface accurately.

✨ New (2024-07-26): The stable version 1.3.0 with centroid, polylabel, point-in-polygon and other cartesian 2D calculations enhanced -read more!

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

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

Documentation#

Comprehensive guidance on how to use this package and aboutGeospatial tools for Dart (the package is part of) is available on thegeospatial.navibyte.dev website.

Shortcuts to thegeobasepackage documentation by chapters:

• 📍 Coordinates
• 🧩 Simple geometries
• 📏 Geometry calculations
• 🔷 Geospatial features
• 📃 Vector formats
• 🔵 Ellipsoidal geodesy
• 📐 Spherical geodesy
• 📅 Metadata
• 🌐 Global grids
• 🗺️ Projections
• 🔢 Tiling schemes
• ⚖️ Unit conversions

See also overview topics aboutGeospatial tools for Dart:

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

Introduction#

Unit conversions for length, area, speed, angle, angular velocity and timeunits.

  // For example conversions between length units.  const meters = 1500.0;  meters.convertLength(to: LengthUnit.foot); // ~ 4921.26 feet  meters.convertLength(to: LengthUnit.kilometer); // 1.5 km  meters.convertLength(to: LengthUnit.nauticalMile); // 0.8099 nmi  254.convertLength(from: LengthUnit.millimeter, to: LengthUnit.inch); // 10.0

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 andprojected 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 forpixels andtiles in tiling schemes:

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

Ellipsoidal andspherical geodesy functions to calculate distances etc.:

  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');  // How to calculate distances using ellipsoidal Vincenty, spherical  // great-circle and spherical rhumb line methods is shown first.  // The distance along a geodesic on the ellipsoid surface (16983.3 km).  greenwich.vincenty().distanceTo(sydney);  // By default the WGS84 reference ellipsoid is used but this can be changed.  greenwich.vincenty(ellipsoid: Ellipsoid.GRS80).distanceTo(sydney);  // The distance along a spherical great-circle path (16987.9 km).  greenwich.spherical.distanceTo(sydney);  // The distance along a spherical rhumb line path (17669.8 km).  greenwich.rhumb.distanceTo(sydney);  // Also bearings, destination points and mid points (or intermediate points)  // are provided for all methods, but below shown only for great-circle paths.  // Destination point (10 km to bearing 61°): 51° 31.3′ N, 0° 07.5′ E  greenwich.spherical.initialBearingTo(sydney);  greenwich.spherical.finalBearingTo(sydney);  // Destination point: 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);  // Vincenty ellipsoidal geodesy functions provide also `inverse` and `direct`  // methods to calculate shortest arcs along a geodesic on the ellipsoid. The  // returned arc object contains origin and destination points, initial and  // final bearings, and distance between points.  greenwich.vincenty().inverse(sydney);  greenwich.vincenty().direct(distance: 10000, bearing: 61.0);

Universal Transverse Mercator (UTM) coordinates and Military Grid ReferenceSystem (MGRS) references based on the WGS84 ellipsoid are supported:

  // sample geographic position  final eiffel = Geographic(lat: 48.8582, lon: 2.2945);  // UTM coordinates for the position  final eiffelUtm = eiffel.toUtm();  print(eiffelUtm.toText()); // "31 N 448252 5411933"  // It's also possible to convert between UTM coordinates and MGRS references  print(eiffelUtm.toMgrs().toText()); // "31U DQ 48251 11932"  // UTM coordinates can be converted back to geographic coordinates;  print(eiffelUtm.toGeographic().latLonDms()); // "48.8582°N, 2.2945°E"  // MGRS references can be constructed from components too (4Q FJ 12345 67890)  final honoluluMgrs = Mgrs(4, 'Q', 'F', 'J', 12345, 67890);  // MGRS references can be printed in different precisions  print(honoluluMgrs.toText(digits: 8)); // "4Q FJ 1234 6789" (10 m precision)  print(honoluluMgrs.toText(digits: 4)); // "4Q FJ 12 67" (1 km precision)  print(honoluluMgrs.gridSquare.toText()); // "4Q FJ" (100 km precision)

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 asiterables of position objects, but as a flat structure represented by arrays ofcoordinate 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 useCoords 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 asFeatureCollection objects. Seethe documentation chapter aboutgeospatial featuresfor 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'),  );

Projections can be applied on any geometry and feature objects along withpositions.

  // The source point geometry with a position in WGS 84 coordinates.  final positionWgs84 = Geographic(lon: 2.2945, lat: 48.8582);  final point = Point(positionWgs84);  // Project to UTM projected coordinates (in zone 31 N).  final zone31N = UtmZone(31, 'N');  final wgs84toUtm31N = WGS84.utmZone(zone31N).forward;  final pointUtm31N = point.project(wgs84toUtm31N);  // Project back to WGS 84 coordinates.  final utm31NtoWgs84 = WGS84.utmZone(zone31N).inverse;  final pointWgs84 = pointUtm31N.project(utm31NtoWgs84);

Other coordinate projections, tiling schemes (web mercator, global geodetic) andcoordinate array classes are some of the more advanced topics not introducedhere. Please see chapters aboutprojections,tiling schemes andcoordinate arrayson thedocumentation website to learn aboutthem.

Usage#

The package requires at leastDart SDK 2.17, and itsupports allDart andFlutterplatforms.

Add the dependency in yourpubspec.yaml:

dependencies:  geobase: ^1.5.0

Import it:

import `package:geobase/geobase.dart`

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

Other resources:

📚Web APIs: See also thegeodatapackage that extends capabilities ofgeobase by providing geospatial APIclients to readGeoJSON data sources andOGC API Features web services.

🚀Samples:TheGeospatial demos for Dartrepository contains more sample code showing also how to use this package!

Reference#

Documentation#

Please see thegeospatial.navibyte.devwebsite for thegeobasepackage documentation.

Packages#

Thegeobase library contains also following partial packages, that can beused to import only a certain subset instead of the wholegeobase package:

External packagesgeobase is depending on:

• meta for annotations
• proj4dart for coordinate projections

Authors#

This project is authored byNavibyte.

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

License#

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

Please see theLICENSE.

Derivative work#

This project contains portions of derivative work.

See details aboutDERIVATIVEwork.

Source repositories used when porting functionality to Dart and this project:

• geodesy by Chris Veness 2002-2024
• polylabel by Mapbox 2016-2024
• tinyqueue by Vladimir Agafonkin 2017-2024