Use Cases

Vector Use Cases

These use cases describe common scenarios for loading, rendering, and editing vector data.

Load data once from static file

User has a static file (e.g. GeoJSON) hosted on the same origin as their application. User expects data to be loaded and rendered in the map projection.

Alternative 1

// assume features.json is a FeatureCollection in EPSG:4326
var vector = new ol.layer.Vector({
  source: new ol.source.Vector({
    protocol: new ol.protocol.HTTP({
      url: './data/features.json'
    }),
    parser: new ol.parser.GeoJSON()
  })
});

var map = new ol.Map({
  target: 'map',
  layers: [vector],
  view: new ol.View2D({
    projection: 'EPSG:1234',
    center: ol.projection.transform(
        new ol.Coordinate(139.7, 35.7), 'EPSG:4326', 'EPSG:1234'),
    zoom: 9
  })
});

This alternative can be implemented if the layer knows the map projection. The vector layer is responsible for calling source.protocol.read({success: callback}) where the callback calls source.parser.parseFeatures(data, {projection: projection}) (data is supplied to the callback and projection comes from the map's view). The layer maintains a cache of features in the map view's projection, and these are on demand to layer's the renderer.

Generate features in app and add to a layer

User writes an application that generates features at run time. These features are added to the layer for display and interaction (e.g. popup on selection).

Alternative 1

// a vector layer with no source means user will be manually adding features
var vector = new ol.layer.Vector();

var map = new ol.Map({
  target: 'map',
  layers: [vector]
  view: new ol.View2D({
    projection: 'EPSG:1234',
    center: ol.projection.transform(
        new ol.Coordinate(-111, 45), 'EPSG:4326', 'EPSG:1234'),
    zoom: 3
  })
});

var parser = new ol.parser.GeoJSON();

vector.addFeatures(parser, {
  type: 'FeatureCollection',
  features: [{
    type: 'Feature',
    geometry: {
      type: 'Point',
      coordinates: [-111, 45]
    },
    properties: {
      foo: 'bar'
    }
  }]
});

In this alternative, the vector layer has no source set - meaning the user will be manually generating features. This alternative can be implemented if the layer knows about the map projection. In the addFeatures method, the layer calls parser.readFeatures(data, {projection: projection}) where data is the first argument to addFeatures and projection is the map view's projection.

Load data based on map extent

User has a service that provides vector features for requests with an arbitrary BBOX (e.g. a WFS). Data source contains hundreds of millions of features with worldwide coverage (e.g. OSM) and the user only wants to display a small subset, updating rendered features as the user navigates around the map.

Alternative 1

var vector = new ol.layer.WFS({
  featureNS: 'http://opengeo.org/#osm'
  featureType: 'roads'
});

var map = new ol.Map({
  target: 'map',
  layers: [vector]
  view: new ol.View2D({
    projection: 'EPSG:1234',
    center: ol.projection.transform(
        new ol.Coordinate(-111, 45), 'EPSG:4326', 'EPSG:1234'),
    zoom: 3
  })
});

This alternative can be implemented if the layer knows about the map. The WFS layer creates a WFS protocol, a GML parser, a BBOX strategy by default. The layer creates a vector source with the protocol and the parser (these are the two things associated with the data source). The bbox strategy listens for changes in map extent. When the previous data bounds become invalid, the bbox strategy notifies the layer that new data is needed, and the layer calls source.protocol.read({success: callback}). The provided callback would call source.parser.readFeatures(data, {projection: projection}) with the provided data and the map view's projection. The resulting features would replace the existing features (or new ones would be added and features outside the data bounds would be removed).

Edit existing features and synchronize them with a server

The user loads a vector layer with a very large number of features. He then modifies a few of them, and saves the modified features back to the server. The feature currently being edited should be on top, and the system should maintain good performance even if the underlying layer contains a very large number of features. Only the modified features should be sent back to the server. Example case: editing OSM building outlines.

Pure vector layers

Some data are represented most compactly as vector features. It should be possible to include them as first-class layers. Example: overlaying roads on satellite imagery.

Markers and labels maintain orientation even when the map is rotated

Map rotation is useful, for example so that "up" corresponds to the direction in which the user is moving. However, labels and markers should not rotate with the map, and should instead always be aligned horizontally.

Sub-feature styling

The user wishes to style a feature, e.g. a line string, according to some value that varies across the feature. It should be possible to "sub-style" a feature, e.g. to vary the color of a GPS tracklog by the speed of movement at that point.