Map Tile API Developer's Guide

Extruded Buildings

In order to make buildings on the map interactive (highlight upon selection and other features) a user wants to obtain metadata information about an image, showing a map tile that includes an extruded building.

Figure 1. Tile with Part of Extruded Building

Metainfo Tile Request

&metadata=metaonly obtains the metadata on a tile with a part of an extruded building.

https://2.base.maps.cit.api.here.com/maptile/2.1/maptile/newest/normal.day/19/281707/171901/256/png8
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&metadata=metaonly
&mgen=2

Processing Metainfo Tile Response

The response to the request delivers the following Metainfo Tile as a JSON object:

{
  "metadata": {
    "street labels":[],
    "labels":[],
    "city center labels":[],
    "buildings":[ 
      {
        "id": "1609441356716643099",
        "vertices": [ 37, 161.69, 18, 199.50, 0, 189.18, 0, 142.78 ],
        "polygons": [ [ 0, 1, 2, 3]],
        "outlines": [ [ 0, 1, 2 ], [ 3, 0 ]]
       }
     ],
    "transit stops":[  ],
    "POIs":[  ]
  }
}

In the response, the building has eight (8) vertices that are ordered counterclockwise for the inner polygon and clockwise for the outer polygon. In this example, there is only an outer polygon, so it is filled inside, all inner polygons are filled outside.

The metadata also contains two arrays, polygons and outlines, each containing arrays of indices that reference the given array of vertices. In this case, there is one polygon that has the vertex indices (0, 1, 2, 3), which represents the contour of our building fragment and two outlines that have also the vertex indices, in this case, (0, 1, 2) and (3, 0).

Polygon with HTML5 Canvas

Using this information, you can draw a polygon reflecting the building's shape, for example with HTML5 canvas:

<canvas id="building_canvas" width="256" height="256" style="border:1px solid #d3d3d3;" />
<script>
var building_canvas = document.getElementById('building-canvas');
building_canvas.getContext('2d').clearRect(0, 0, building_canvas.width, building_canvas.height);

var bcnt = map.custom.tile_meta.metadata.buildings.length;
var bld;
console.log('There are ' + bcnt.toString() + ' buildings on the tile')

var building_canvas = document.getElementById('building-canvas').getContext('2d');
building_canvas.fillStyle = '#FFE8E8';

building_canvas.strokeStyle="green";
building_canvas.lineWidth=1;

var vertices, mpolygons, moutlines;

for (var i=0; i<bcnt; i++) {
  bld = map.custom.tile_meta.metadata.buildings[i];
  vertices = bld.vertices;
  mpolygons = bld.polygons;
  moutlines = bld.outlines;

  // move to first point
  building_canvas.beginPath();

  for (var idx = 0; idx < mpolygons.length; idx++) {
    for ( var vidx = 0; vidx < mpolygons[idx].length; vidx++ ) {
      var index = 2*mpolygons[idx][vidx];
      point = vertices.slice(index, index+2);
      if ( vidx == 0 ) {
        building_canvas.moveTo(point[0], point[1]);
      }
      building_canvas.lineTo(point[0], point[1]);
    }
      }

      building_canvas.fill();

      building_canvas.beginPath();

      for (var idx = 0; idx < moutlines.length; idx++) {
    for ( var vidx = 0; vidx < moutlines[idx].length; vidx++ ) {
      var index = 2*moutlines[idx][vidx];
      point = vertices.slice(index, index+2);
      if ( vidx == 0 ) {
        building_canvas.moveTo(point[0], point[1]);
      }
      building_canvas.lineTo(point[0], point[1]);
    }
      }

      building_canvas.stroke();
      building_canvas.closePath();
}

</script>
Figure 2. Building Shape Reflected Using Metadata

The request above only considers the part of the building visible on this tile. The entire building consists of the building from the response above and another building next to it (column/row: 281706/171901). Requesting the metadata of this building as shown above (Metainfo Tile Request), the resulting responses provide the same building id 1609441356716643099.

Accordingly, you can combine polygons from both tiles and reflect the whole building's shape, merging polygons.

Figure 3. Building Shape Reflected Using Metadata
Figure 4. Original Building Image (Two Tiles)
Figure 5. Highlighted Building Image