Map Objects

Types of Map Objects

The Maps API comes with an object model, which provides a convenient means to organize objects on the map. The API distinguishes between three different types of objects: markers, spatials and groups.

Markers are objects that visually indicate locations on the map, therefore each marker is defined by the geographical point (latitude and longitude) to which it is anchored, and it includes an icon. Panning the map changes the position of the marker on the screen, but the size of the marker icon remains constant when you change the map zoom level (if you zoom in or out).

The API offers two types of markers to cater to different scenarios:

• normal marker (H.map.Marker)
• DOM marker (H.map.DomMarker)

For further details, see Marker Objects.

Spatials (spatial objects, also referred to as geo shapes in this guide) are circles, rectangles, polylines and polygons and can be used to mark areas on the map. A spatial object is defined by a set of geographical points. The points are translated and scaled as the map is panned and zoomed so that the position of the shape on the display faithfully reflects its geographic location. A spatial object includes styling information, which determines how to trace its outlines and how to fill it (if it is a closed shape).

The Maps API offers the following classes that represent spatial objects:

• Polylines (H.map.Polyline)
• Polygons (H.map.Polygon)
• Circles (H.map.Circle)
• Rectangles (H.map.Rect)

For more information, see Geo Shapes.

Overlay is an object that covers a rectangular area on the map with the bitmap image and is defined by a set of geographical points. The image can be procedurally generated or a static bitmap fetched from the server.

For more information, see Overlays.

Groups are logical containers that can hold a collection of child objects (markers or spatials, but also sub-groups). Groups make it easy to add, remove, show or hide whole sets of map objects in an atomic operation, without the need to manipulate each object individually. In addition, a group allows you to calculate a bounding box enclosing all the objects it contains and to listen for events dispatched by the group's child objects.

Adding and Removing Objects

Each map object type corresponds to a class in the API. A newly created instance of such a class does not automatically appear on the map, but, like a node in the HTML document object model (DOM), must be added to the root. This means that to make an object appear on the map, it must be added to the map's root group through a call to the map object's method addObject(). Conversely, to remove an object from the map, a call to the map object's method removeObject() is required.

Groups have their own addObject() and removeObject() methods and behave like container elements in the HTML document object model. It is possible to add an empty group to the map and add individual objects later.

The code below demonstrates how to create an empty group, add it to the map, then create a marker and make it a member of the group.

// Create a group that can hold map objects:
group = new H.map.Group();

// Add the group to the map object (created earlier):
map.addObject(group);

// Create a marker:
marker = new H.map.Marker(map.getCenter());

// Add the marker to the group (which causes 
// it to be displayed on the map)
group.addObject(marker);

Rendering Order

The rendering engine in the HERE Maps API for JavaScript evaluates map objects and then renders spatial objects, markers and DOM markers in separate passes. This means that spatials, markers and DOM markers cannot be intermixed. Spatial objects are rendered in the main scene geo space and are painted like any other map layers. After rendering all map layers, the Maps API renders all Markers (normal markers) and finally all DomMarkers.

See also:

• Marker Objects
• Overlays
• Geo Shapes