Skip to content

GettingStartedGuide.md

Latest commit

 

History

History
242 lines (183 loc) · 7.93 KB

GettingStartedGuide.md

File metadata and controls

242 lines (183 loc) · 7.93 KB

Getting Started Guide

To begin with harp.gl, we provide a few starting points:

Import harp.gl with simple bundle

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.

Create Typescript app using Yeoman

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

Integrate harp.gl into your existing Webpack based project

Introduction

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.

Installation

Install them into your project:

npm install --save @here/harp-mapview @here/harp-omv-datasource @here/harp-map-theme

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 scheme

Since Three.js is a peer dependency of harp.gl it has to be installed as well. To get the version that you should install you can use npm view.

THREE=`npm view @here/harp-mapview peerDependencies.three`
npm install --save three@$THREE

Decoder bundle

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();

Create DOM container

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>

MapView

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);

Attach data source

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.

Enable user interaction with map

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);

Examine examples

To begin with, we suggest taking a look at our most basic example, the equivalent of a hello_world in the examples package

HERE Credentials

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. You can see a step-by-step guide here.

These credentials need to be passed to the Service in order to retrieve tiles, please see the examples to check how it is done.