Geospatial features

A geospatial feature is an entity with an identifier, a geometry and properties. Features are used to represent real-world objects like roads, buildings, cities, electric lines, etc.

Below is an illustration of features in a simple vector map. Wells are features with point geometries, rivers with line strings (or polyline) geometries, and finally lakes are features with polygon geometries.

Features normally contain also an identifier and other attributes (or properties) along with a geometry.

Sets of features are contained by feature collections.

🗺️ Feature data model

As specified also by the GeoJSON format a Feature object contains a geometry object and additional members (like “id” and “properties”). A FeatureCollection object contains an array of Feature objects. Both may also contain “bbox” or bounding box. Any other members on Feature and FeatureCollection objects are foreign members, allowed property values or geometry objects, but not specified by the GeoJSON model (and so potentially not known by many GeoJSON parsers).

This package models features and feature collections according to these definitions:

🔷 Feature

A single Feature object:

  // A geospatial feature with id, a point geometry and properties.
  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',
      'place': 'Greenwich',
      'city': 'London',
      'isMuseum': true,
      'measure': 5.79,
    },
  );

Naturally, the geometry member could also contain any other geometry types described earlier, not just points.

An optional id, when given, should be either a string or an integer. The properties member defines feature properties as a map with the JSON Object compatible model (or Map<String, dynamic> as such data is typed in Dart).

🪣 FeatureCollection

A FeatureCollection object with Feature objects:

  // A geospatial feature collection (with two features):
  FeatureCollection([
    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',
        'place': 'Greenwich',
        'city': 'London',
        'isMuseum': true,
        'measure': 5.79,
      },
    ),
    Feature(
      id: 'TB',
      // a point geometry with a position (lon, lat)
      geometry: Point.build([-0.075406, 51.5055]),
      properties: {
        'title': 'Tower Bridge',
        'city': 'London',
        'built': 1886,
      },
    ),
  ]);

ℹ️ Additional information

Features and feature collections also are Bounded, that is they have similar options to calculate, store, specify explicitly and access minimum bounding boxes as described in the previous chapter for geometry objects.

And just like geometry objects, features and feature collections can be constructed using various alternative ways, for example using build, and parse factories with similar use cases to examples already shown for line strings.

There is also a special static factory method fromData that takes as an input a JSON Object as decoded by json.decode() from external standardized data formats.

// a feature with an id and a point geometry (2D coordinates)
Feature.fromData(
  format: GeoJSON.feature,

  // `Map<String, dynamic>` compatible with objects created by `json.decode()`
  // (in this case the object tree follows GeoJSON data structure)
  {
    'type': 'Feature',
    'id': '1',
    'geometry': {
      'type': 'Point',
      'coordinates': [10.0, 20.0]
    }
  },
);