Objects on the map
Geographical objects in the real world are matched to program objects known as geo objects. Geo objects include placemarks, circles, polylines, rectangles, polygons, and their collections.
Each geo object is described in a geometry, which is defined by a geometric type and coordinates.
The base class implementing a geo object is GeoObject.
The map instance stores geo objects in its own storage, implemented as a collection, which is referenced from the geoObjects field. Adding a geo object to the map, modifying it and removing it are all done by accessing this collection.
var myMap = new ymaps.Map("map", {
center: [55.76, 37.64],
zoom: 10
}),
myGeoObject = new ymaps.GeoObject({
geometry: {
type: "Point", // geometry type - point
coordinates: [55.8, 37.8] // координаты точки
}
});
myMap.geoObjects.add(myGeoObject); // Placing a geo object on the map.
For each geometry type, an auxiliary class is defined that provides abbreviated syntax for creating a geo object.
// Auxiliary class that can be used
// instead of GeoObject with the «Point» geometry type (see the previous example)
var myPlacemark = new ymaps.Placemark([55.8, 37.6]);
myMap.geoObjects.add(myPlacemark);
Geo object geometry
The following table provides a list of geometries, their IDs that are used in the GeoObject class, and the corresponding auxiliary classes.
Geometry type / ID / Auxiliary class |
Example |
Point / Point / Placemark |
Creating a placemark using the
Creating a placemark using the auxiliary class
|
Polyline / LineString / Polyline |
Creating a polyline using the
Creating a polyline using the
|
Rectangle / Rectangle / Rectangle |
Creating a rectangle using the
Creating a rectangle using the
|
Polygon / Polygon / Polygon |
Creating a polygon using the
Creating a polygon using the
|
Circle / Circle / Circle |
Creating a circle using the
Creating a circle using the
|
The geometry type is assigned to a geo object when it is created, and cannot be changed later. However, the geometry's coordinates can be changed either programmatically, or using the visual editor.
var myPlacemark = new ymaps.Placemark([55.754952, 37.615319], {}, {
draggable: true, // The placemark is draggable.
preset: 'islands#whiteStretchyIcon'
});
myPlacemark.events.add('dragend', function(e) {
// Getting a reference to an object that was dragged.
var thisPlacemark = e.get('target');
// Determining the placemark coordinates
var coords = thisPlacemark.geometry.getCoordinates();
// and outputting them when the placemark is clicked
thisPlacemark.properties.set('balloonContent', coords);
});
If a geo object was initialized without specifying a geometry, it will not be displayed on the map. It will also be impossible to assign a geometry type to such a geo object.
Visual editing
A geo object's geographical properties can be modified by the user in visible mode. The API provides two ways to do this: moving a geo object in its entirety, and the visual editor.
The ability to drag a geo object is controlled by the draggable
option, which can take the values true
and false
.
The visual editor is available for geo objects with the point, polyline, or polygon geometry type. The reference to the editor is in the editor field of the instance of the corresponding class.
|
|
Setting the placemark style
You can select the style for placemark icons from a set of preset styles. The style sets the color of the placemark icon, as well as its type (such as an icon without content, or an icon that stretches to fit the content).
Each style from the set is assigned a unique key. To set a desired style, specify the corresponding key as the value of the preset
option:
|
|
Note
The default style is 'islands#blueIcon'
.
Setting a custom placemark image
You can use your own image for a placemark icon. To do this, set the following options:
iconLayout
— The 'default#image' or 'default#imageWithContent' value, for placemarks without text and with text on top of the picture, respectively.iconImageHref
— URL of the icon's image file.iconImageSize
— Icon size, in pixels.iconImageOffset
— Number of pixels to offset the icon from its anchor point (set if the icon is not anchored at the upper-left corner of the image).iconContentOffset
— For placemarks with text, the offset of the text relative to the placemark's anchor point.
|
|
Using CSS sprites
When adding a large number of placemarks to the map with different custom icons, it makes sense to use CSS sprites technology. The idea behind the technology is that all the images are combined in a single graphics file, the sprite. Using CSS, the appropriate image is extracted from the sprite and set as the icon for a specific placemark.
An example of a sprite containing three images is shown below:
In order to set the desired image as the placemark icon, this placemark must have the following options set:
iconLayout
— Icon layout. This option must have the 'default#image' value set.iconImageCliptRect
— Position of the desired image in the sprite. It is defined by the pixel coordinates of the upper-left and lower-right corners of the rectangle the image is placed in.iconImageHref
— URL of the sprite.iconImageSize
— Icon size, in pixels.iconImageOffset
— Number of pixels to offset the icon from its anchor point (set if the icon is not anchored at the upper-left corner of the image).
|
|
Using sprite technology reduces the number of HTTP requests to the server, since only a single image is loaded in place of a large number of images.
For more information about setting styles for placemark icons, see the example.
Placemarks with glyphs
The API lets you add placemarks to the map that contain glyphs (Glyphicons).
Alert
To use Glyphicons, you need to enable the Bootstrap CSS styles:
<link rel="stylesheet" type="text/css" href="https://yastatic.net/bootstrap/3.3.4/css/bootstrap.min.css">
To create a placemark with a glyph, set the following options in the placemark designer:
preset
— The type of placemark. Specified with the 'glyph' prefix. For example, 'islands#glyphCircleIcon' (a circle placemark) or 'islands#glyphIcon' (a placemark with a tail). You can also use this option to set the placemark color. For example, 'islands#redGlyphIcon'.iconGlyph
— The name of the glyph. For a list of available glyphs and their names, see the Glyphicons page. Note that the name is set without the 'glyph' prefix. For example, 'asterisk' or 'plus'.iconGlyphColor
(optional) — The color of the glyph. There are three ways to set the color: using a keyword, in Hex format, or RGB. If this option is omitted, a black glyph is used by default.iconColor
(optional) — The color of the placemark. There are three ways to set the color: using a keyword, in Hex format, or RGB. A blue placemark is used by default.
An example of using glyphs is shown below.
|
|
Geo object collections
Geo objects can be combined in collections, which lets you define properties for all of their members at once and perform group operations with them.
A geo object can only belong to one collection. If you add a geo object to a collection when it already belongs to a different collection, it will be deleted from the first collection.
|
|
You can implement your own class of collections that can be placed on the map; to do this, implement the IMapObjectCollection interface.
Clusters
Point geo objects can be located so close to each other that at some zoom level their placemarks will start to overlap each other. In this case, the user must «aim» carefully in order to get the mouse cursor on a visible part of the desired placemark. There is even a special term used to describe this effect: pixel hunting.
|
|
If multiple placemarks are located at the same point and the size of their icons is the same, it is actually impossible to point at a placemark that is covered up by another one.
The standard way to solve this problem is by combining neighboring objects in a group (cluster) and using a special cluster icon for the group. The cluster icon often shows the number of items that are in it.
The Clusterer class is used for clustering objects in the Yandex Maps API.
|
|
When the zoom is increased, the cluster visually separates into individual placemarks and/or other clusters.
When the cluster icon is clicked, either the zoom increases or a balloon opens that displays the list of geo objects in the cluster. This behavior is controlled using the clusterDisableClickZoom
option (true/false).
var myGeoObjects = [];
for (var i = 0; i < coords.length; i++) {
myGeoObjects[i] = new ymaps.GeoObject({
geometry: {
type: "Point",
coordinates: coords[i]
},
properties: {
clusterCaption: 'Geo object # '+(i+1),
balloonContentBody: 'Balloon text # '+(i+1)
}
});
}
var myClusterer = new ymaps.Clusterer(
{clusterDisableClickZoom: true}
);
myClusterer.add(myGeoObjects);
myMap.geoObjects.add(myClusterer);
Note
If the cluster is displayed at the maximum zoom level, the cluster will not separate into separate placemarks when its marker is clicked. The balloon opens in this case, regardless of the value of the clusterDisableClickZoom
parameter.
In this way, information can be displayed for geo objects that are positioned close together, even if their placemarks overlap at the maximum zoom level.
Using the clusterer significantly increases performance when displaying a large number of geo objects in the browser.
Rendering and handling a geo object is an expensive operation in terms of resource consumption, and the more objects are clusterized, the more resources are saved. Performance decreases significantly even when displaying a few hundred objects without clustering.