@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>
<script src="https://unpkg.com/@here/harp.gl/dist/harp.js"></script>
<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:
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