Third Party Extensions

Google Maps API Tutorial

Animated Markers

From API v2.59, the API supports animated GIFs as markers in all browsersThe techniques described on the rest of this page are no longer necessary

You may have noticed that the API accepts GIF images as markers, but that animated GIF icons don’t work in IE. This is because the API loads the marker image with the “DXImageTransform.Microsoft.AlphaImageLoader” filter under IE, so that transparent PNG files are displayed correctly, and that filter doesn’t handle animated GIFs.

This example  shows three strategies for animating a marker.

The main v1 methods are no longer possible, so the only possibility is to use a third party extension.

The example shows three implementations of clickable animated markers using third party extensions. From left to right:

  1. Pure TLabel
    The contents of the TLabel are an animated GIF.
    addDomListener() is used on the TLabel div to catch mouse clicks and open an info window.
  2. TLabel plus GMarker
    The contents of the TLabel are an animated GIF.
    An invisible GMarker is plotted at the same location. The GMarker mouse target goes above the TLabel to catch the clicks and the GMarker shadow goes underneath.
  3. ELabel plus GMarker
    The contents of the ELabel are an animated GIF.
    An invisible GMarker is plotted at the same location. The GMarker mouse target goes above the ELabel to catch the clicks and the GMarker shadow goes underneath.ELabels overlap intelligently when the “overlap” property is set.

Custom Maps

Google Maps API Tutorial

Using Google Maps API for Flat Maps and Diagrams

You might think that we can use the techniques in the previous examples to get the Google Map API to manage views of things that are not spherical maps, such as flat maps, diagrams and circuit boards. That would be fine as long as we don’t want to draw markers or polylines on it.

Once we start drawing lines, we encounter the fact that all the maps we’ve looked at so far use the Mercator projection, which distorts the mapping geometry in order to represent a spherical Earth on a flat map.

The line on the “Mercator” map type in this example is a “straight” line that gets distorted into a curve due to the Mercator projection. You can imagine that such a distortion wouldn’t be much use for dealing with things like circuit diagrams.

The “Euclidean” map type in the same example Note I don’t move or redraw the markers or the polyline. When the map type changes, the API redraws all the overlays using the new projection.

Copyright strings

The GTileLayer.getCopyright() method must return an Object that has the following properties

prefix String to be placed at the front of the copyright text, like “Map Data:” or “Satellite Imagery:”
copyrightTexts Array of strings: Copyright texts that apply to various parts of the area.

The constructor and methods of the object class are not exposed, so it’s not possible to construct the return value properly, but it is possible to return an anonymous object literal.

E.g., in the example, I’ve used

     tilelayers[0].getCopyright = function(a,b) {
        return {prefix:"Fractal: ©", copyrightTexts:["Mike Williams"]};

Potential Pitfalls

  1. The GScaleControl() and point.distanceFrom() features assume spherical geometry, so they’re not going to be useful for non-Mercator maps.
  2. The API calculates the polyline geometry at zoom level 17. This means that any GProjection used in a map that has polylines must be created with at least 18 zoom levels, even if the map itself has far fewer zoom levels.

More advanced stuff

Google Maps API Tutorial

Setting the z-index of markers

It is possible to set the z-index of markers.

You might want to do this if your map tends to be rather cluttered with overlapping markers, and you want to highlight a particular marker, but normally find it to be partially obscured behind less significant ones.

To use the facility, you need to create a little function which will return an integer to be used as the z-index. Markers with higher z-index values are drawn on top of those with lower z-index values.

You can calculate the value from scratch, or you might modify the usual value, which can be obtained fromGOverlay.getZIndex(marker.getPoint().lat()).

The Function is passed two Parameters. The first Parameter is a reference to the marker and the second one always seems to be undefined at present.

Attach your function to the marker by using the GMarkerOption {zIndexProcess:myFunction}

You can’t change the order of the markers afterwards. The Function only gets evaluated when the marker is addOverlay()ed.

I don’t think you can pass a Parameter directly to the zIndexProcess Function, but what you can so is to add a Property to the marker before you addOverlay() it. The function can read that Property and use it in the calculation. For example, if you want important markers to be placed on top, then you can add a marker.importance property to each marker, and return higher z-index values for markers with higher importance.

More advanced stuff

Google Maps API Tutorial

Making your own custom markers

To make custom markers, you’ll need a graphics program that supports partially transparent PNG images.

I’ve used Paint Shop Pro 8. In that program there’s just one special thing to watch out for: don’t use “save”, use the PNG optimiser and specify “Alpha Channel Transparency”.

To create a custom shadow, take a copy of your marker, change all the opaque points to black, reduce the opacity to about 50%, skew the image by about 45 degrees and add some blur.

I’ve also used POV-Ray to create custom 3d markers. Use the switches “+ua +fn” to create a partially transparent png file.

To create a shadow image in POV-Ray, I applied the keyword “noimage” to my marker object, and allowed the shadow to fall on a tilted plane

   plane {y,0 pigment {rgb 2} rotate -x*45}

In this case it’s not possible to make the plane transparent directly from POV-Ray, the white plane needs to be removed with a suitable image editor.


To create a transparentImage for your custom marker, simply load the marker image into an image editor, change the opacity to 1% and export the result as a 24-bit partially transparent PNG. The transparentImage allows the marker to correctly respond to clicks and mouseover events in IE when the marker is under a shadow. You can omit the transparentImage, in which case clicks and mouseovers will not work correctly for icons that are in shadow.


To get shadowed markers to correctly respond to clicks in other browsers, you need to create an imageMap. That’s a lot trickier, and I’m not going to cover that in this tutorial.

GIcon.printImage and GIcon.mozPrintImage

Most browsers can’t print partially transparent PNG images. Google has provided the option to provide printable GIF images instead. If you want your markers to be printable you can create the required GIF images by converting your PNG images to GIF format. For the GIcon.printImage Google a GIF with transparency that matches that of the PNG image. For GIcon.mozPrintImage Google use a non-transparent GIF with the background set to a pale grey.

In my experiments, Firefox seems to print the transparent GIFs just as well as the non-transparent ones, it just ignores the transparency when printing.

If you omit the GIcon.printImage and GIcon.mozPrintImage settings, then IE6 will print the main PNG images of the markers (ignoring the transparency) but Firefox will omit the markers from the print.


If you want shadows to be printed you need to provide a GIF image for this parameter. GIF images don’t support partial transparency, but it is possible to dither the image, like this dithshadow.gif image used by Google

Third Party Markers

If you don’t want to draw your own markers, you can find some markers that other people have made.

There’s a list of available marker sets here:

Here’s an example that uses the finger icon.

    var Icon = new GIcon();
      Icon.image = "mymarker.png";
      Icon.iconSize = new GSize(20, 34);
      Icon.shadow = "myshadow.png";
      Icon.shadowSize = new GSize(36, 34);
      Icon.iconAnchor = new GPoint(5, 34);
      Icon.infoWindowAnchor = new GPoint(5, 2);
      Icon.transparent = "mytran.png";
      Icon.printImage = "mymarkerie.gif";
      Icon.mozPrintImage = "mymarkerff.gif";
      Icon.printShadow = "myshadow.gif";

This enlarged image shows the anchor points used for this marker.

  • Icon.image is simply the name of the main image for the marker.
  • Icon.iconSize is the pixel size of the Icon.image
  • Icon.shadow (optional) is the name of the shadow image.
  • Icon.shadowSize is the pixel size of the Icon.shadow
  • Icon.iconAnchor (indicated by the red pixel) is the pixel which will be placed on the specified geographical location. You can think of it as the point that the image points at.
  • Icon.infoWindowAnchor (indicated by the green pixel) is the pixel that the tip of the info Window stem will touch.
  • Icon.transparent (optional) is the name of a transparent image used for capturing clicks and mouseovers in MSIE.
  • Icon.printImage (optional) is the name of a GIF file to be used for printing.
  • Icon.mozPrintImage (optional) is the name of a GIF file to be used for printing from the Mozilla/Firefox browser.
  • Icon.printShadow (optional) is the name of a GIF file to be used for printing the shadow.
  • Icon.imageMap (optional) is an array of integers representing the x/y coordinates of the image map used fopr capturing image clicks in non-IE browsers.

Note that the Size parameters are specified as GSize objects and the Anchor parameters are specified as GPoint objects.

In both cases, the values count from the top left corner which is considered to be the point (1,1). This may well be different from what you see in an image editing program, where the top left pixel is usually considered to be (0,0).

Positioning the infoWindowAnchor is an art rather than a science. You can see when it looks wrong but there doesn’t seem to be any formula that will produce the result that looks right.

Required parameters

They’re not actually mandatory. There are certain strange circumstances in which you might want to omit almost any parameter, but you should think carefully before omitting any of these parameters:

  • iconSize : without it your marker will have zero size and be invisible
  • iconAnchor : without it your marker won’t appear in the correct place
  • infoWindowAnchor : without it marker.openInfoWindow() will fail
  • transparent : without it your marker won’t be clickable in MSIE if there’s an info window shadow nearby
  • imageMap : without it your marker won’t be clickable in Firefox if there’s an info window shadow nearby

Graham’s Custom Marker Maker

If you don’t want to go through all the bother of doing that yourself, then simply create the main image file and pass it to Graham’s Custom Marker Maker You get back a zip file that contains files for all the other parts of the GIcon and some sample code with all the parameter settings.