Using MarkerImage in Maps Javascript API v3

When creating custom markers, you need to supply two images, the icon and the shadow. While you can supply a simple URL for each property, using MarkerImage allows you more flexibility and improves performance.

1. Creating a simple image:

The simplest marker is one made of individual icon and shadow images, with the anchor point (The point used to position the marker) located in the middle of the bottom edge of the image, like the standard marker using by the API.
In this situation, you only need to speficy the image URL such as:

var icon = new google.maps.MarkerImage("http://domain/path/image.png");

2. Specifying an anchor point

Depending of the shape of the marker, you may not want the middle of the bottom edge to be used as the anchor point. For example, in this sample, the anchor point of the beach flag is at the bottom left corner.
In those situation, you need to specify the anchor point of the image as the fourth parameter. This is a value of type Point, relative to the top left corner of the image with positive X going right and positive Y going down.
For example, if the image "beach_flag.png" is 20*32 pixels, we would use:

var icon = new google.maps.MarkerImage("http://domain/path/beach_flag.png", null, null, new google.maps.Point(0, 32));


3. Resizing the image

If you need to display the image larger or smaller than its original size, supply the scaledImage parameter:

var icon = new google.maps.MarkerImage("http://domain/path/image.png", null, null, null, new google.maps.Size(64, 64));

Note that if you use both size and anchor, the anchor value needs to be specified after scaling.
Combining the two previous examples, we would have:

var icon = new google.maps.MarkerImage("http://domain/path/beach_flag.png", null, null, new google.maps.Point(0, 64), new google.maps.Size(40, 64));

Note the change to the anchor from 0, 32 to 0, 64.

4. Using a sprite image

One simple way to imrove the performance of your website is to use sprite images. It means using a single image that contains many of the images you need of the site then using a section of it as required. The browser only makes a single call to download the image where before it would have made many.
To create a MarkerImage from a sprite image, you need to specify the origin and size of the section of the image you want to use to create the icon.

var icon = new google.maps.MarkerImage("http://domain/path/sprite.png", new google.maps.Size(12, 20), new google.maps.Point(100, 34));

You can, if you need, also provide the anchor point. The valoue of the anchor is relative to the section of the image, not the whole image.
For example, to use the center of the sprite image above as the anchor point, we would have:

var icon = new google.maps.MarkerImage("http://domain/path/sprite.png", new google.maps.Size(12, 20), new google.maps.Point(100, 34), new google.maps.Point(6, 10));

5. Using a scaled sprite image

To combine spriting and scaling, you need to supply a scaled section size as well as the scaled image size.
For example, if we want to display the section in the previous example of size 12*20 pixels, but display it 24*40 pixels, from an image originally 200*300 in size we would have:

var icon = new google.maps.MarkerImage("http://domain/path/sprite.png", new google.maps.Size(24, 40), new google.maps.Point(200, 68), new google.maps.Point(12, 20), new google.maps.Size(400, 600));

To display a scaled image or a scaled prite image, just supply the size, origin, anchor and scaledSize parameters with the scale factor applied.

6. Improving performance

They are two ways to improve the performance of MarkerImage:

- When you know the size of the image, specify it. If the size is not supplied, we make a call to download the image and read its size. While most browsers will cache the image and not download it again, this is not true in all cases and it may trigger the download of the image earlier than required, delaying the display of the map.
- When displaying multiple markers with the same shadow or icon, reuse the MarkerImage for all the markers:

var icon = new google.maps.MarkerImage(...);
for (...) {
var marker = new google.maps.Marker({
icon: icon,
...
};
}