Geodart #

A geospatial library for Dart. Designed primarily around vector features, this library provides a simple interface for working with geographic data.

It's based heavily on the geojson specification, but has been extended to add functionality directly to the feature types.

Conversions #

You can convert between different units with the conversions library.

Types of conversions:

• Distance: conversions between meters, kilometers, and miles.
• Area: conversions between square meters, square kilometers, and square miles.
• Angle: conversions between degrees, radians, and gradians.

Here's an example:

import 'package:geodart/conversions.dart';

// Ten miles to kilometers
convertDistance(10, DistanceUnit.miles, DistanceUnit.kilometers); // returns 16.09344

// Ten degrees to radians
convertAngle(10, AngleUnit.degrees, AngleUnit.radians); // returns 0.17453292519943295

// Ten acres to square miles
convertArea(10, AreaUnit.acres, AreaUnit.squareMiles); // returns 0.004046856

Geometries #

To use this library, you'll need to get familiar with the feature types. All other actions taken depend on using the proper feature types. These feature types are very similar to the ones used in the geojson specification.

I'll admit, the feature coordinates are a bit of a mess. I'm working on a better way to handle this.

The following features are included in this library:

• FeatureCollection
• LineString
• MultiLineString
• MultiPoint
• MultiPolygon
• Point
• Polygon

The package also provides a Feature class, which is a abstract class that can be extended to create new feature types.

Positions are stored using Coordinate objects, which has a variety of convenience methods for working with coordinates.

Feature Collection #

A FeatureCollection is a collection of Feature objects.

It functions very similarly to a List of Feature objects, but might extended to include additional properties in the future.

Constructors

• FeatureCollection.fromJson(Map<String, dynamic> json) - Creates a FeatureCollection from a JSON object. Automatically converts features from GeoJSON to their respective types.

Methods

• toJson() - Returns a JSON object representing the FeatureCollection. Automatically converts features to GeoJSON.

Properties

• features - A List of Feature objects.

Point #

A Point is a single position. It is represented by a Coordinate object.

Constructors

• Point.fromJson(Map<String, dynamic> json) - Creates a Point from a Map of GeoJSON data.
• Point.fromLngLat(num lng, num lat) - Creates a Point from a num longitude and latitude.
• Point.fromWKT(String wkt) - Creates a Point from a Well-Known Text string.

Methods

• explode() - Returns a List of itself.
• toJson() - Returns a Map of GeoJSON data.
• toWKT() - Returns a Well-Known Text string representing the Point.

Properties

• coordinates - The Coordinate of the Point.
• type - The type of the Point. Always "Point".
• properties - A Map of properties.

Multi Point #

A MultiPoint is a collection of Coordinate objects, represented by individual and non-connected points.

Constructors

• MultiPoint.fromJson(Map<String, dynamic> json) - Creates a MultiPoint from a Map of GeoJSON data.
• MultiPoint.fromWKT(String wkt) - Creates a MultiPoint from a Well-Known Text string.

Methods

• explode() - Returns a List of Point objects.
• toJson() - Returns a Map of GeoJSON data.
• toWKT() - Returns a Well-Known Text string representing the MultiPoint.
• union(MultiPoint other) - Merges the MultiPoint with another MultiPoint.
• flatten() - Returns a List of Point objects.

Properties

• coordinates - A List of Coordinate objects.
• type - The type of the MultiPoint. Always "MultiPoint".
• properties - A Map of properties.

Line String #

A LineString is a collection of Coordinate objects that form a line.

Constructors

• LineString.fromJson(Map<String, dynamic> json) - Creates a LineString from a Map of GeoJSON data.
• LineString.fromWkt(String wkt) - Creates a LineString from a Well-Known Text string.

Methods

• along(distance) - Returns a Point at the specified distance along the line.
• explode() - Returns a List of Point objects that make up the LineString.
• midpoint() - Returns a Point at the midpoint of the LineString.
• toJson() - Returns a GeoJSON Map of the LineString.
• toPolygon() - Returns a Polygon that is the same as the LineString. LineString must be closed, or an exception will be thrown.
• toWKT() - Returns a String of the LineString in WKT format.

Properties

• coordinates - A List of Coordinate objects that make up the LineString.
• type - The type of the LineString. Always "LineString".
• isClosedRing - A boolean indicating whether the LineString is a closed ring.
• length - The length (in meters) of the LineString.
• properties - A Map of properties.

Multi Line String #

A MultiLineString is a collection of Coordinate objects that form multiple separate LineStrings with one set of shared properties.

Constructor

• MultiLineString.fromJson(Map<String, dynamic> json) - Creates a MultiLineString from a Map of GeoJSON data.
• MultiLineString.fromWkt(String wkt) - Creates a MultiLineString from a Well-Known Text string.

Methods

• explode() - Returns a List of LineString objects.
• toJson() - Returns a Map of GeoJSON data.
• toWKT() - Returns a Well-Known Text string representing the MultiLineString.
• union(MultiLineString other) - Merges the MultiLineString with another MultiLineString.
• flatten() - Returns a List of LineString objects.

Properties

• coordinates - A nested List of Coordinate objects.
• type - The type of the MultiLineString. Always "MultiLineString".
• properties - A Map of properties.

Polygon #

A Polygon is a collection of [LinearRing](#Linear Ring) objects that form a closed ring. The first LinearRing in the list is the outer ring, and any subsequent LinearRings are holes. Holes should be contained within the outer ring - if they are not, some algorithms may not work correctly. A Polygon should also not intersect itself - again, some algorithms may not work correctly if this is not the case.

Constructors

• Polygon.fromJson(Map<String, dynamic> json) - Creates a Polygon from a Map of GeoJSON data.
• Polygon.fromWkt(String wkt) - Creates a Polygon from a Well-Known Text string.

Methods

• explode() - Returns a List of Point objects.
• toJson() - Returns a Map of GeoJSON data.
• toWKT() - Returns a Well-Known Text string representing the Polygon.
• toLineString() - Returns a LineString that is the same geometry as the Polygon.

Properties

• coordinates - A List of [LinearRing](#Linear Ring) objects.
• type - The type of the Polygon. Always "Polygon".
• area - The are (in square meters) of the Polygon.
• properties - A Map of properties.

Multi Polygon #

A MultiPolygon is a collection of Polygon geometries forming one MultiPolygon with shared properties.

Constructors

• MultiPolygon.fromJson(Map<String, dynamic> json) - Creates a MultiPolygon from a Map of GeoJSON data.
• MultiPolygon.fromWkt(String wkt) - Creates a MultiPolygon from a Well-Known Text string.

Methods

• explode() - Returns a List of Point objects.
• toJson() - Returns a Map of GeoJSON data.
• toWKT() - Returns a Well-Known Text string representing the MultiPolygon.
• union(MultiPolygon other) - Merges the MultiPolygon with another MultiPolygon.
• flatten() - Returns a List of Polygon objects.
• toMultiLineString() - Returns a MultiLineString that is the same geometry as the MultiPolygon.

Properties

• coordinates - A List of Polygon objects.
• type - The type of the MultiPolygon. Always "MultiPolygon".
• properties - A Map of properties.
• area - The are (in square meters) of the MultiPolygon.

Coordinate #

A Coordinate is a point in a two-dimensional Cartesian coordinate system.

Constructors

• Coordinate.fromJson(Map<String, dynamic> json) - Creates a Coordinate from a Map of GeoJSON data.
• Coordinate.fromWkt(String wkt) - Creates a Coordinate from a Well-Known Text string.

Methods

• toJson() - Returns a Map of GeoJSON data.
• toWKT() - Returns a Well-Known Text string representing the Coordinate.
• distanceTo(Coordinate other) - Returns the distance (in meters) between the Coordinate and another Coordinate.
• bearingTo(Coordinate other) - Returns the bearing (in degrees) between the Coordinate and another Coordinate.
• destination(num distance, num bearing) - Returns a Coordinate that is the same geometry as the Coordinate but moved a given distance and bearing.
• interpolate(Coordinate other, num fraction) - Returns a Coordinate that is the same geometry as the Coordinate but moved a given fraction of the distance and bearing to another Coordinate.

Properties

• latitude - The latitude of the Coordinate.
• longitude - The longitude of the Coordinate.
• type - The type of the Coordinate. Always "Coordinate".

Usage #

Measure the distance between two points.

import 'package:geodart/measurements.dart';
import 'package:geodart/geometries.dart';

double distanceBetween = distance(
    Point.fromLngLat(1.0, 1.0),
    Point.fromLngLat(2.0, 2.0),
);

Under the hood, this uses the coordinate distanceTo() function, and could be very easily replaced with a different algorithm. I prefer the distanceTo() function because it is more explicit and easier to read.

import 'package:geodart/geometries.dart';

double distanceBetween = Coordinate(1.0, 1.0).distanceTo(Coordinate(2.0, 2.0));

Measure the area of a polygon.

import 'package:geodart/geometries.dart';

Polygon polygon = Polygon.fromJson(
    {
      'type': 'Polygon',
      'coordinates': [
        [
          [1.0, 1.0],
          [2.0, 1.0],
          [2.0, 2.0],
          [1.0, 1.0],
        ],
      ],
    }
);
print(polygon.area);

Measure the length of a LineString.

LineString length is calculated on the fly.

import 'package:geodart/geometries.dart';

LineString lineString = LineString.fromJson(
    {
      'type': 'LineString',
      'coordinates': [
        [1.0, 1.0],
        [2.0, 2.0],
      ],
    }
);
print(lineString.length);

Additional information #

License #

This library is free software under the terms of the MIT license. See the LICENSE file for more details.

Contributing #

If you have any questions or comments, please open an issue on the Github repository.

If you want to make a pull request, please open a pull request on the Github repository. Please make sure to include a test suite. I make no promises that I will accept pull requests, but I will try my best to keep the code up to date.