To begin with harp.gl
, we provide a few starting points:
- Import harp.gl with simple bundle
- Create simple app using Yeoman
- Integrate
harp.gl
into your existing Webpack based project - Look at examples
Add three.js
and harp.gl
to your html and create a canvas with an id map
:
<html>
<head>
<style>
body, html { border: 0; margin: 0; padding: 0; }
#map { height: 100vh; width: 100vw; }
</style>
<script src="https://unpkg.com/three/build/three.min.js"></script>
<script src="https://unpkg.com/@here/harp.gl/dist/harp.js"></script>
</head>
<body>
<canvas id="map"></canvas>
<script src="index.js"></script>
</body>
</html>
Initialize the map:
const map = new harp.MapView({
canvas: document.getElementById("map"),
theme: "https://unpkg.com/@here/harp-map-theme@latest/resources/berlin_tilezen_night_reduced.json",
});
const controls = new harp.MapControls(map);
window.onresize = () => map.resize(window.innerWidth, window.innerHeight);
map.setCameraGeolocationAndZoom(
new harp.GeoCoordinates(37.773972, -122.431297), //San Francisco
13
);
const omvDataSource = new harp.OmvDataSource({
baseUrl: "https://xyz.api.here.com/tiles/herebase.02",
apiFormat: harp.APIFormat.XYZOMV,
styleSetName: "tilezen",
authenticationCode: "YOUR-XYZ-TOKEN",
});
map.addDataSource(omvDataSource);
You need to obtain authentication code to replace 'YOUR-XYZ-TOKEN'.
For more information on the simple bundle, please visit the @here/harp.gl module directory.
For an in depth tutorial on getting started with harp.gl, please visit the HERE Developer portal.
You can create simple harp.gl
app using Yeomans generator @here/generator-harp.gl
:
mkdir 3dmap-example
cd 3dmap-example
npx -p yo -p @here/generator-harp.gl yo @here/harp.gl
harp.gl
is distributed as CommonJS
modules conatined in npm
packages. Modules in CommonJS
format require us to use some javascript code bundler - this example will faciliate webpack
.
Install them into your project:
npm install --save @here/harp-mapview @here/harp-omv-datasource @here/harp-map-theme three@0.104
You have installed 3 key components needed to render basic map:
@here/harp-mapview
- map renderer itself@here/harp-omv-datasource
- tile provider based on OMV/MVT vector tile format@here/harp-map-theme
- default theme and font resources required to render map in OMV/tilezen schemethree
- Three.js - a mandatory dependency ofharp.gl
Our example will decode OMV/MVT tiles in Web Workers, so we can achieve high performance because creating geometry from vector tiles is CPU intensive. For this, we need to create separate bundle with code that will run in Web Workers dedicated to decoding.
You need to add this config to your Webpack config:
const appConfig = {
// your app config
};
const harpGlDecodersConfig = {
target: "webworker",
entry: {
decoder: "./harp-gl-decoders.js"
},
output: {
filename: "harp-gl-decoders.bundle.js"
},
mode: process.env.NODE_ENV || "development"
};
return [appConfig, harpGlDecodersConfig];
The ./harp-gl-decoders.js
needs to initialize decoding service:
import { OmvTileDecoderService } from "@here/harp-omv-datasource/index-worker";
OmvTileDecoderService.start();
harp.gl
renders map on HTML
canvas
element. Add it to your HTML document:
<!-- index.html -->
<canvas id="mapCanvas"></canvas>
<style>
#mapCanvas {
width: 500px;
height: 300px;
padding: 0;
border: 0;
}
</style>
Then, you have to create MapView
that is will render map on mapCanvas
:
// index.js
import { MapView } from "@here/harp-mapview";
const mapCanvas = document.getElementById("mapCanvas");
const mapView = new MapView({
canvas: mapCanvas,
theme: "node_modules/@here/harp-map-theme/resources/berlin_tilezen_base.json",
// note, this URL may vary depending on configuration of webpack
// for this example, it is assumed that app is server from project root
decoderUrl: "harp-gl-decoders.bundle.js"
// note, this URL may vary depending on configuration of webpack
// for this example, it is assumed that webpack emits bundles to project root
});
Next, you have to initialize default view settings like camera height over ground and location of map center:
// index.js
import { GeoCoordinates } from "@here/harp-geoutils";
// ...
mapView.camera.position.set(0, 0, 800);
mapView.geoCenter = new GeoCoordinates(40.70398928, -74.01319808, 0);
mapView.resize(mapCanvas.clientWidth, mapCanvas.clientHeight);
Last step is adding some
OmvDataSource
to our MapView
instance:
import { APIFormat, AuthenticationTypeMapboxV4, OmvDataSource } from "@here/harp-omv-datasource";
const dataSource = new OmvDataSource({
baseUrl: "https://xyz.api.here.com/tiles/herebase.02",
apiFormat: APIFormat.XYZOMV,
styleSetName: "tilezen",
maxZoomLevel: 17,
authenticationCode: "your access token for xyz service",
authenticationMethod: AuthenticationTypeMapboxV4
});
mapView.addDataSource(dataSource);
Note, that this example uses vector tiles downloaded from HERE XYZ service and access to these
files is protected by access token. You should replace your access token for xyz service
with real
one, see HERE Credentials section below.
What we've achieved so far is basic, static non-interactive. If you want to enable control of map
like panning, rotating use
MapControls
Note, this requires additional module: npm install --save @here/harp-map-controls
.
import { MapControls } from "@here/harp-map-controls";
MapControls.create(mapView);
To begin with, we suggest taking a look at our most basic example, the equivalent of a hello_world
in
the examples package
In order to use some of the HERE Services, such as XYZ or Map Tile API, you would need to register and generate credentials.
First, you need to become a HERE Developer.
Afterwards, depending on which service do you want, you might need different credentials.
For Map Tile API, which is needed for the webtile examples, you need to generate a pair of app_id
and app_code
, that you can do directly from your Developer Dashboard, see a step-by-step guide
here.
For XYZ Vector Tiles, you need an access_token
that you can generate yourself from the
Token Manager.
These credentials need to be passed to the Service in order to retrieve tiles, please see the examples to check how it is done.