Firefly overlay for Google Maps

1. Overview

Firefly module is meant for drawing and animating brightly colored and partly transparent dots with blurred edges and varying sizes atop of a Google Maps. The result looks like a firefly, hence the naming of the module.

Download

2. Module description

2.1. Requirements

Firefly utilizes Google Maps API V3 for drawing the objects. In order to use Firefly, key for Google Maps API V3 is required. The key is free and only requires Google account.

Information on how the Google Maps API works: Google Maps API tutorial.
To create the Google Maps API V3 key: https://code.google.com/apis/console

2.2. Structure

Module includes two classes, MovementOverlay and firefly_object. The second class, i.e. firefly_object, is a container for single firefly-object and its variables. Class MovementOverlay is the main class, which keeps track of the firefly- objects' size and movement. Firefly-objects and the animation are controlled through this class.

Listing of MovementOverlay's methods:

• MovementOverlay(map) is a constructor for the class. Takes the google.maps.Map-object as a parameter.
• add_object(properties) is for adding firefly-objects to overlay. Takes list of properties for object to be created, which will be discussed in more detail later.
• toggle_animation(state), update(timestamp) and move_objects(timing) are methods for controlling the flow of animation. Toggle_animation() will activate, or deactivate, the animation, which will call the update()-function to activate the move_objects() on regular intervals. Function move_objects() will calculate the next state and size for each firefly-object and update the overlay.
• check_animation() will check whether the animation has already ended and will return a Boolean value.
• reset_animation() will reset the whole animation. This changes the location and size for each firefly-object as it was in the beginning of the animation.
• hide() will hide every firefly-object.
• toggle() functions like the hide(), but can also turn objects back to visible, if earlier made hidden.

• firefly_object(startCoord, endCoord, startSize, endSize, colour) is a constructor for the single firefly-object. Takes coordinates for ending and starting point in google.maps.LatLng() format and start and end sizes in pixels. Colour variable determines the color of the object, which can be given as a string. Constructor will also calculate necessary variables for moving the object across the map.
• calculate_distance(coord1, coord2) will calculate the distance between two given coordinates and returns it in meters.
• set_size(size) sets the objects size. Size is given in pixels.
• set_frames(frames) sets time-to-live variable for firefly-object. Will affect the distance moved.

2.3. Limitations

When animating large number of objects at the same time, the whole animation can become considerably slower.

Also different browsers will behave differently when animating firefly-objects. At least Chrome and Opera have some problems with animating lots of objects at once smoothly. Firefox and Safari do not have the same kind of problems and will make the animation look considerably smoother. This could be caused by the Google Maps itself, since the dots are just circles found on Google Maps API, which have their center and size changed constantly.

3. Usage example

Below is a simple example Javascript code for creating Google Maps map-object and firefly overlay. One single object is created to the overlay, after which its animated, stopped and then the overlay is being reset.

In the picture below is an example of how multiple firefly-objects with varying sizes and colours will look with the Google Maps.