@here/harp.gl

Overview

This is convienience module that provides harp.gl as JS-friendly bundle, with whole harp.gl API exposed in harp namespace.

Usage example with unpkg.com CDN:

<script src="https://unpkg.com/three/build/three.min.js"></script>
<!-- harp.gl bundle requires specific threejs version to be already loaded in runtime -->
<script src="https://unpkg.com/@here/harp.gl/dist/harp.js"></script>
<!-- latest version of harp.gl bundle -->
<script>
    const canvas = document.getElementById("mapCanvas");

    const map = new harp.MapView({
        canvas,
        theme:
            "https://unpkg.com/@here/[email protected]/resources/berlin_tilezen_base.json"
    });
    ...
</script>

This snippets loads all required scripts and creates MapView with theme loaded from unpkg.com CDN.

Architecture

@here/harp.gl provides following bundles:

• harp.js and harp.min.js containing selected symbols from these bundles in harp namespace:
  • Core MapView functionality - @here/harp-mapview
  • GeoUtils - @here/harp-geoutils
  • Map Controls - @here/harp-controls (excluding [CameraAnimation] related functions)
  • OMV/MVT Tile Provider @here/harp-vectortile-datasource
  • Custom Features Provider @here/harp-features-datasource
  • Web Tile Provider @here/harp-webtile-datasource
  • GeoJSON Tile Provider @here/harp-geojson-datasource
• harp-decoders.js
  • Web Worker script that contains code for services.
  • Due to same-origin policy,
  • This script depends on external three.js implementation, which usually is detected automatically (it re-uses same script URL that is used in main JS runtime).

Technical notes

• harp.js bundle depends on Three.JS being already loaded in Javascript Runtime.
• harp.gl uses Web Workers from harp-decoders.js to offload CPU intensive work from main thread (in particular for OmvDataSource and GeoJsonDataProvider. Web Workers.
• For convienience harp.gl detects URL from which is loaded and by default detects location of harp-decoders.js which is distributed together. That may cause problems with same-origin policy that mandates that Web Workers can be loaded only from same origin that main page. To overcome this issue, we attempt to load harp-decoders.js by converting it to Blob. This requires, that CSP policy of your page allows loading workers from blob: URLs.

Troubleshooting

• harp.js: Unable to determine location of three(.min).js

  As noted above, harp.gl tries to find URL of three.js so URL can loaded in web-workers. If for some reason you don't have three.js script in your DOM, you can tell harp.gl where to find like this:

  harp.WorkerLoader.dependencyUrlMapping.three = "https://unpkg.com/three/build/three.min.js";

• Refused to create a worker from 'blob:http://...' because it violates the following Content Security Policy ...

  As noted above, if harp.js and harp-decoders.js is loaded from other domain (like CDN), we try to load script into Blob and then execute worker from blob-url. For this mechanism to work, your CSP policy for worker-src and/or child-src should allow blob: origin. blob: origin is enabled by default, but if for some reason it's not the case, you can re-enable it with following snippet:

  <meta http-equiv="Content-Security-Policy" content="worker-src 'self' blob:" />

  If for some reason, you cannot change CSP policy of your app to allow blob: worker-source, you have to load harp-decoders.js (and possibly harp.js) from same origin as your main page.

More info

• Running example
• Example source code
• harp.gl Getting started guide