@sentinel-hub/sentinelhub-js v0.4.7

Warning

The interface of the library is not final yet - expect breaking changes!

Installation

$ npm install @sentinel-hub/sentinelhub-js

Usage

The core data structure is Layer, which corresponds to a layer as returned by OGC WMS GetCapabilities request. If the URL matches one of the Sentinel Hub service URLs, additional capabilities are unlocked.

Basic (WMS-capable) Layer can be initialized like this:

  import { WmsLayer } from 'sentinelhub-js';

  const layer = new WmsLayer('https://services.sentinel-hub.com/ogc/wms/<your-instance-id>', '<layer-id>', 'Title', 'Description');

Such layer would only allow WMS requests. However, Layer is also a superclass for multiple dataset-specific subclasses (like S1GRDIWAWSLayer) which can be instantiated with their own specific parameters and thus unlock additional powers.

When it comes to Sentinel Hub layers, there are four ways to determine their content:

• by layerId: ID of the layer, as used by OGC WMS and SentinelHub Configurator
• by evalscript: custom (javascript) code that will be executed by the service per each pixel and will calculate the (usually RGB/RGBA) values
• by evalscriptUrl: the URL from which the evalscript can be downloaded from
• by dataProduct: the structure which contains an ID of a pre-existing product

  import { S1GRDIWAWSLayer } from 'sentinelhub-js';

  layerS1 = new S1GRDIWAWSLayer(instanceId, '<layer-id>', null, null, null, 'Title', 'Description');
  layerS1 = new S1GRDIWAWSLayer(instanceId, null, myEvalscript);
  layerS1 = new S1GRDIWAWSLayer(instanceId, null, null, myEvalscriptUrl);
  layerS1 = new S1GRDIWAWSLayer(instanceId, null, null, null, '<data-product-id>');
  layerS1 = new S1GRDIWAWSLayer(instanceId, '<layer-id>', null, null, null, 'Title', 'Description', orthorectified=true);

It is also possible to get the list of the layers that service endpoint supports:

  import { LayersFactory } from 'sentinelhub-js';

  const layers = LayersFactory.getLayers('https://services.sentinel-hub.com/ogc/wms/<your-instance-id>');
    // [ layer1, layer2, ... ] - a list of Layer objects

  const layersIds = layers.map(l => l.layerId);
    // [ '<layer-id-1>', '<layer-id-2>',... ]

Depending on baseUrl, method getLayers() tries to determine if a specific Layer subclass would be better suited and instantiates it with all applicable parameters.

Alternatively, the list can be filtered to include only some of the layers:

  // this will return only a list of layers whose IDs start with "ABC_":
  const layers = LayersFactory.getLayers(
    'https://services.sentinel-hub.com/ogc/wms/<your-instance-id>',
    (layerId, datasetId) => layerId.startsWith("ABC_"),
  );

It is also possible to get min and max date as defined on the dataset:

  const minDate = layer.getDatasetMinDate();
  const maxDate = layer.getDatasetMaxDate();

Some information about the layer is only accessible to authenticated users. In case of Playground and EO Browser, ReCaptcha auth token is sufficient to fetch layer information (such as evalscript / dataProduct). To avoid updating every layer when auth token changes, we have a global function for updating it:

  import { isAuthTokenSet, setAuthToken } from 'sentinelhub-js';

  const before = isAuthTokenSet(); // false
  setAuthToken(newAuthToken);
  const after = isAuthTokenSet(); // true

Fetching images

Maps which correspond to these layers can be fetched via different protocols like WMS and Processing. Not all of the protocols can be used in all cases; for example, Processing can only render layers for which it has access to the evalscript and for which evalscript version 3 is used.

  import { BBox, CRS_EPSG4326, MimeTypes, ApiType } from 'sentinelhub-js';

  const bbox = new BBox(CRS_EPSG4326, 18, 20, 20, 22);
  const getMapParams = {
    bbox: bbox,
    from: new Date(Date.UTC(2018, 11 - 1, 22, 0, 0, 0)),
    to: new Date(Date.UTC(2018, 12 - 1, 22, 23, 59, 59)),
    width: 512,
    height: 512,
    format: MimeTypes.JPEG,
  };

  const imageBlob = await layer.getMap(getMapParams, ApiType.WMS);
  const imageBlob2 = await layer.getMap(getMapParams, ApiType.PROCESSING);

Note that in theory both images should be exactly the same. If there are any (minor) differences, they are a consequence of how service processes requests, not because of different interpretation of getMapParams on the side of this library.

In some cases we can retrieve just the image URL instead of a blob:

  const imageUrl = await layer.getMapUrl(getMapParams, ApiType.WMS);
  const imageUrl2 = await layer.getMapUrl(getMapParams, ApiType.PROCESSING); // exception thrown - Processing API does not support HTTP GET method

Searching for data

Searching for the data is a domain either of a layer or its dataset (if available). This library supports different services, some of which (ProbaV and GIBS for example) specify availability dates per layer and not dataset.

We can always use layer to search for data availability:

  const searchParams: DatasetSpecificSearchParams = {
    cloudCoveragePercent: 50,
  }
  const dates = layer.findDatesUTC(bbox, fromDate, toDate, searchParams);
  const flyovers = layer.findFlyovers(bbox, fromDate, toDate, searchParams);
  const tiles = layer.findTiles(bbox, fromDate, toDate, searchParams);

Backwards compatibility

To make it easier to use this library with legacy code, there are two functions that are implemented on top of the library:

  const imageBlob1 = await legacyGetMapFromParams(rootUrl, wmsParams);
  const imageBlob2 = await legacyGetMapFromParams(rootUrl, wmsParams, ApiType.PROCESSING); // ApiType.WMS is default

If we already have a WMS GetMap URL, we can use it directly:

  const imageBlob3 = await legacyGetMapFromUrl(fullUrlWithWmsQueryString);
  const imageBlob4 = await legacyGetMapFromUrl(fullUrlWithWmsQueryString, ApiType.PROCESSING);

Example

$ npm run build
$ cd example/node
$ node index.js