Skip to content

geospatial-services-framework/gsf-js-client-sdk

Repository files navigation

hero

GSF JavaScript Client SDK

Build Status npm Version

About the SDK

The GSF JavaScript Client SDK provides a client-side JavaScript library for interacting with GSF. The SDK may be used in the browser as well as Node.js. For detailed information visit our full developer documentation page.

  1. This repository contains pre-built distributable files located in the /dist/ directory.
  • /dist/GSF-node.js - The Node.js bundle.
  • /dist/GSF-node.js.map - The Node.js bundle source map.
  • /dist/GSF.js - The non-minified web bundle.
  • /dist/GSF.js.map - The non-minified web bundle source map file.
  • /dist/GSF.min.js - The minified web bundle.
  • /dist/GSF.min.js.map - The minified web bundle source map file.

Installation

The SDK can be installed using npm.

$ npm install gsf-js-client-sdk --save

Importing the SDK

Using ECMAScript 2015

  • Import everything with GSF namespace:

    import * as GSF from 'gsf-js-client-sdk';

  • Import specific classes:

    import { Job, Task } from 'gsf-js-client-sdk';

Using Node.js

  • Require the SDK:

    const GSF = require('gsf-js-client-sdk/dist/GSF-node');

Including the SDK with a Script Tag

  1. Include the GSF JavaScript Client SDK file in your project. The example below assumes the SDK file is located next to your html file.

    <script src="GSF.min.js"></script>

  2. Access the SDK using the global GSF object.

    <script>console.log(GSF);</script>

Basic Example

  1. Below is a simple example of running a job and retrieving the results. You will need to update the server address and port below to reflect the server that you are using.
const myAddress = 'MyServer';
const myPort = 9191;

// GSF Client
const client = GSF.client({
    address: myAddress,
    port: myPort
  });

// Create a service object.
const service = client.service('ENVI');

// Create a task object.
const task = service.task('SpectralIndex');

const NDVIParameters = {
  inputParameters: {
    INPUT_RASTER: {
      FACTORY: 'URLRaster',
      URL: 'http://' + myAddress + ':' + myPort + '/ese/data/qb_boulder_msi'
    },
    INDEX: 'Normalized Difference Vegetation Index'
  }
};

// Submit a job.
task.submitAndWait(NDVIParameters).then((results) => {
    // Do something with results.
    AddToMap(results.OUTPUT_RASTER.best);
  }).catch((err) => {
    // Display error.
  });

TypeScript Example

Below is an example of submitting a job using typescript.

import * as GSF from 'gsf-js-client-sdk';

// Get a task.
const clientOpts: GSF.ClientOptions = {
    address: 'MyServer',
    port: '9191'
  };
const client: GSF.Client = GSF.client(clientOpts);
const ENVIService: GSF.Service = client.service('ENVI');
const myTask: GSF.Task = ENVIService.task('SpectralIndex');

const taskParameters: GSF.SubmitOptions = {
    inputParameters: {
        INPUT_RASTER: {
            FACTORY: 'URLRaster',
            URL: 'http://MyServer:9191/ese/data/qb_boulder_msi'
        },
        INDEX: 'Normalized Difference Vegetation Index'
    }
};

// Submit a job.
task.submitAndWait(taskParameters)
    .then((results: GSF.JobResults) => {
        // Do something with results.
        // This function is an example and is not provided by the SDK.
        AddToMap(results.OUTPUT_RASTER.best);
    }).catch((jobErrorMessage) => {
        // Display error.
    });

This is just a sample of what can be done with the SDK. See our full developer documentation to learn more.

Requirements

Server Sent Events

The GSF JavaScript Client SDK relies on server-sent events for communication with the server. Developers who wish to build apps that run on browsers lacking EventSource support will want to use a polyfill. This is not necessary when using the SDK in Node.js.

To view a list of the browsers that support EventSource go here: https://caniuse.com/#search=eventsource

There are several polyfills available that provide implementations of the EventSource API. One such polyfill that is available from the npm and Bower package managers is called 'eventsource-polyfill'. For information on installation and usage, see https://github.com/amvtek/EventSource.

Developer Documentation

Visit our full developer documentation page for more information.