Both my main encoding utility and my point and click encoding utility use my
PolylineEncoder class, which makes it easy to encode a polyline
on the fly in javascript. Suppose you've got a path defined by an array of
GLatLngs stored in points. Generating an encoded
polyline is as simple as this:
polylineEncoder = new PolylineEncoder();
polyline = polylineEncoder.dpEncodeToGPolyline(points);
That's it - the variable polyline now holds an encoded
polyline. Of course, you now need to add it as an overlay and you need to
make sure that your script has acces to the
PolylineEncoder.js module. The constructor has optional arguments
numLevels, zoomFactor, and
verySmall, that affect the encoding algorithm. The
dpEncodeToGPolyline function has several optional arguments to
specify the style of the line. There is an analagous method,
dpEncodeToGPolygon, which accepts an array of arrays of
GLatLngs specifying the portions of the boundary of a polygon
and returns an encoded polygon.
You should keep in mind that the encoding process is computationally intensive and takes time. If you have a small number of static maps with complicated path data, then it is definitely best to pre-encode those paths and place them in your web page as I have done with most of the examples here. If you have an extremely complicated path (say tens of thousands of vertices), then on the fly encoding with javascript will simply take too long; perhaps, a compiled server side encoding program could work. If, however, you have dynamically generated data that is moderately complicated (say a few hundred to a few thousand points), then encoding with the script here might be a reasonable approach.
In the example below, the data for the path is read from (the rather large) AOTC.xml (which is actually a GPX file) and then encoded using the PolylineEncoder class. Since the path is encoded on the fly, you'll probably notice that this map loads more slowly than my other maps when you hit the reload button. It's quite zippy once it does load, however. The path in the XML file consists of about 2200 points, but approximately 700 of these are removed in the encoding process. The file is read asyncronously using the API's GXmlHttp namespace. This process is described on Mike Williams outstanding Google Maps tutorial here: http://www.econym.demon.co.uk/googlemaps/basic7.htm, although he generates a regular GPolyline. You can view the javascript for this example here: PolylineEncoderExample.js.
Again, the line which actually performs the encoding contains
polylineEncoder.dpEncodeToGPolyline(points). If
you want a polygon, simply change this to
polylineEncoder.dpEncodeToGPolygon([points]).
Note that the argument has changed from the array points
to the array of arrays [points]. We represent
the boundary of a polygon this way since it might consist of
several parts.
PolylineEncoder(numLevels?, zoomFactor?, verySmall?)
The constructor takes three optional arguments specifying the encoding parameters as described here.
dpEncodeToGPolyline(points, color?, weight?, opacity?)
The argument points should be an array of objects
with lat and lng methods -
GLatLng or PolylineEncoder.latLngs, for
example. The other optional arguments are the usual style
directives.
dpEncodeToGPolygon(pointsArray,
boundaryColor?, boundaryWeight?, boundaryOpacity?,
fillColor?, fillOpacity?, fill?, outline?)
The argument pointsArray should be an array of
arrays of objects with lat and lng methods -
GLatLng or PolylineEncoder.latLngs, for
example. The other optional arguments are the usual style directives.
The previous methods expect points in the form of an object with
lat and lng methods. A GLatLng
as defined by the Google Maps API does quite nicely. If you're
developing a javascript without loading the API, however, you can use
a PolylineEncoder.latLng for this purpose. The
constructor is called via PolylineEncoder.latLng(y,x),
where y is the latitude and x is the
longitude.
Sometimes your points are defined in terms of an
array of arrays, rather than an array of latLngs.
PolylineEncoder.pointsToLatLngs(points)
converts to an array of arrays to an array of latLngs
for use by the dpEncode* functions.
PolylineEncoder.pointsToGLatLngs is analagous to the
previous function, but it returns GLatLngs rather
than PolylineEncoder.latLngs. The first function may
be used independently of Google Maps. Use the second,
if you need to use the result in a Goole Map function.
dpEncodeToJSON(points,
color?, weight?, opacity?)
The argument points should be an array of objects
with lat and lng methods.
Returns a legal argument to GPolyline.fromEncoded.
dpEncode(points)
This is where the real work is done. The argument points
should be an array of objects with lat and
lng methods. The return value is a JSON object with
properties named encodedLevels,
encodedPoints and encodedPointsLiteral.
These are strings which are acceptable input to the
points and levels properties of the
GPolyline.fromEncoded function. The
encodedPoints string should be used for maps generated
dynamically, while the encodedPointsLiteral string should
be copied into a static document.
Both my main encoding utility and
my point and click encoding utility call
the dpEncode method directly, since they need to access
the encodedPointsLiteral string to produce suitable
for copying and pasting.