❤
npm
Sign UpSign In

aframe-map

2.1.1 • Public • Published

aframe-map

A 3D street map entity & component for A-Frame.

The <a-map> entity displays a plane textured with a rendered OpenStreetMap map.

Installation

Browser

Use directly from the unpkg CDN:

<head>
  <script src="https://aframe.io/releases/0.3.0/aframe.min.js"></script> 
  <script src="https://unpkg.com/aframe-map"></script> 
  <script>
    registerAframeMap(window.AFRAME);
  </script> 
</head>
 
<body>
  <a-scene>
    <a-map position="0 0 -5"></a-map>
    <a-camera></a-camera>
  </a-scene>
</body>

npm

Install via npm:

npm install aframe-map

Then register and use.

import aframe from 'aframe';
import registerMap from 'aframe-map';
registerMap(aframe);

map component

Note: The <a-map> entity automatically includes the map component.

Schema

attribute type default description
pxToWorldRatio number 100 The number of pixels per world unit to render the map on the plane. ie; when set to 100, will display 100 pixels per 1 meter in world space. (see a note on fidelity)
style string '' A JSON.stringify'd MapBox style. If none is provided, a default style will be loaded. (see creating a style)
... All other options are passed directly to Mapbox GL
A note on fidelity

This higher pxToWorldRatio, the more map area will be displayed per world unit. That canvas has to be translated into a plane in world space. This is combined with the width and height in world space (from geometry.width and geometry.height on the entity) to set up the plane for rendering in 3D.

The map is rendered as a texture on a 3D plane. For best performance, texture sizes should be kept to powers of 2. Keeping this in mind, you should work to ensure width * pxToWorldRatio and height * pxToWorldRatio are powers of 2.

Creating a style

MapBox styles are a JSON specification for how to render different layers of the map.

Creating new styles can be done by hand, or with an editor such as Maputnik. Take special note of the tile server to be used; Mapbox charges for access to theirs, however there is a free CDN powered by osm2vectortiles.org/ (this is the server used by the default style).

Note: The osm2vectortiles free CDN defaults to insecure http URLs which will be rejected by browsers on security grounds when the main site is served over secure https.

You can also easily host your own tile server!

Events

event name data description
map-loaded (none) Fired on the first render of the map component
map-moveend (none) Fired when zoom, center, bearing, or pitch are changed after the initial render

Readme

Keywords

Package Sidebar

Install

npm i aframe-map

Repository

github.com/jesstelford/aframe-map

Homepage

github.com/jesstelford/aframe-map#readme

Weekly Downloads

23

Version

2.1.1

License

MIT

Last publish

Collaborators

  • jesstelford
Try on RunKit
Report malware