Image::WorldMap - Create graphical world maps of data


  use Image::WorldMap;
  my $map = Image::WorldMap->new("earth-small.png", "maian/8");
  $map->add(4.91, 52.35, "");
  $map->add(-2.355399, 51.3828, "");
  $map->add(-0.093999, 51.3627, "");


This module helps create graphical world maps of data, such as the Perl Monger World Map ( This module takes in a number of label locations (longitude/latitude) and outputs an image. It can attach text to the labels, and tries to make sure that labels do not overlap.

It is intended to be used to create images of information such as "where are all the Perl Monger groups?", "where in the world are all the CPAN mirrors?" and so on.

This module comes with a low-resolution image of the world. Additional larger images have not been bundled with the module due to their size, but are available at:



The constructor. It takes two mandatory arguments, the filename of the image of the earth used for the background, and whether or not to display labels.

The label option is actually a font size and name. You must have a local truetype font in your directory. The font name format is "font_name/size". For example. If there is a font file called cinema.ttf somewhere in the font path you might use "cinema/20" to load a 20 pixel sized font of cinema.

  # Without labels
  my $map = Image::WorldMap->new("earth-small.png");

  # With labels
  my $map = Image::WorldMap->new("earth-small.png", "maian/8");


This adds a node to the map, with an optional label. Longitude and latitude are given as a decimal, with (0, 0) representing a point on the Greenwich meridian and the equator and (-180, -180) top-left and (180, 180) bottom-right on a projection of the Earth.

  $map->add(-2.355399, 51.3828, "");

You can also add a colour as a red, green, blue triple. For example, to make the dot orange, you could do:

  $map->add(-2.355399, 51.3828, "", [255,127,0]);


This draws the map and writes it out to a file. The file format is chosen from the filename, but is typically PNG.



This module tries hard to make sure that labels do not overlap. This is an NP-hard problem. It currently uses a simulated annealing method with some optimisations. It could be faster still.

The label positioning method used is random: if you run the program again, you will get a different set of label positions, which may or may not be better.

The images produced by this module are quite large, as they contain lots of colour information. You should probably reduce the size somehow (such as using the Gimp to convert it to use indexed colours) before using the image on the web.


Copyright (C) 2001-2, Leon Brocard


This module is free software; you can redistribute it or modify it under the same terms as Perl itself.


Leon Brocard,