@here/harp.gl NPM

@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/harp-map-theme@0.2.2/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.