NAME
    Geo::Google::PolylineEncoder - encode lat/lons to Google Maps Polylines

SYNOPSIS
      use Geo::Google::PolylineEncoder;

      my $points = [
                    # can also take points as [lat, lon]
                    { lat => 38.5, lon => -120.2 },
                    { lat => 40.7, lon => -120.95 },
                    { lat => 43.252, lon => -126.453 },
                   ];
      my $encoder = Geo::Google::PolylineEncoder->new;
      my $eline   = $encoder->encode( $points );
      print $eline->{num_levels};  # 18
      print $eline->{zoom_factor}; # 2
      print $eline->{points};      # _p~iF~ps|U_ulLnnqC_mqNvxq`@
      print $eline->{levels};      # POP

      # in Javascript, assuming eline was encoded as JSON:
      # ... load GMap2 ...
      var opts = {
        points: eline.points,
        levels: eline.levels,
        numLevels: eline.num_levels,
        zoomFactor: eline.zoom_factor,
      };
      var line = GPolyline.fromEncoded( opts );

DESCRIPTION
    This module encodes a list of lat/lon points representing a polyline
    into a format for use with Google Maps. This format is described here:

    <http://code.google.com/apis/maps/documentation/polylinealgorithm.html>

    The module is a port of Mark McClure's "PolylineEncoder.js" with some
    tweaks. The original can be found here:

    <http://facstaff.unca.edu/mcmcclur/GoogleMaps/EncodePolyline/>

CONSTRUCTOR & ACCESSORS
    new( [%args] )
        Create a new encoder. Arguments are optional and correspond to the
        accessor with the same name: "num_levels", "zoom_factor",
        "visible_threshold", "force_endpoints", etc...

        Note: there's nothing stopping you from setting these properties
        each time you "encode" a polyline.

    num_levels
        How many different levels of magnification the polyline has.
        Default: 18.

    zoom_factor
        The change in magnification between those levels (see "num_levels").
        Default: 2.

    visible_threshold
        Indicates the length of a barely visible object at the highest zoom
        level. Default: 0.00001. err.. units.

    force_endpoints
        Indicates whether or not the endpoints should be visible at all zoom
        levels. force_endpoints is. Probably should stay true regardless.
        Default: 1=true.

    escape_encoded_points
        Indicates whether or not the encoded points should have escape
        characters escaped, eg:

          $points =~ s/\\/\\\\/g;

        This is useful if you'll be evalling the resulting strings, or
        copying them into a static document.

        Warning: don't turn this on if you'll be passing the encoded points
        straight on to your application, or you'll get unexpected results
        (ie: lines that start out right, but end up horribly wrong). It may
        even crash your browser.

        Default: 0=false.

    lons_first
        Specifies the order in which coordinates passed as arrayrefs to
        "encode" should be interpreted:

          # false: lat, lon
          $encoder->encode([
             [ 38.5, -120.2 ],
             [ 40.7, -120.95 ],
          ]);

          # true: lon, lat
          $encoder->encode([
             [ -120.2, 38.5 ],
             [ -120.95, 40.7 ],
          ]);

        Default: 0 = lat,lon

        (Yes, the default feels wrong to the mathematician in me, but that's
        how Google Maps do it, so for sake of consistency...)

METHODS
    encode( \@points );
        Encode the points into a string for use with Google Maps
        "GPolyline.fromEncoded" using a variant of the Douglas-Peucker
        algorithm to set levels, and the Polyline encoding algorithm defined
        by Google.

        Expects a reference to a @points array:

          [
           { lat => 38.5, lon => -120.2 },
           { lat => 40.7, lon => -120.95 },
           { lat => 43.252, lon => -126.453 },
          ];

        The individual points can also be given as arrayrefs:

          [
           [ 38.5, -120.2 ],
           [ 40.7, -120.95 ],
           [ 43.252, -126.453 ],
          ];

        *Note:* I tried to avoid this initially, because there's no standard
        for which should come first: *lat*s or *lon*s. But I agree, it's
        more convenient in some cases so I've given you enough rope to hang
        yourself... Of course you can easily unhang yourself: the order for
        arrayrefs defaults to "lat, lon", but you can change that by setting
        "lons_first".

        Returns a hashref containing:

          {
           points => 'encoded points string',
           levels => 'encoded levels string',
           num_levels => int($num_levels),
           zoom_factor => int($zoom_factor),
          };

        You can then use the JSON modules (or XML, or whatever) to pass the
        encoded values to your Javascript application for use there.

    decode_points( $encoded_polyline );
        Given an encoded polyline, returns the points:

          [
           { lat => 38.5, lon => -120.2 },
           { lat => 40.7, lon => -120.95 },
           { lat => 43.252, lon => -126.453 },
          ];

        Note that these will likely be slightly different from the original
        points due to rounding errors during both "encode" & decoding.

    decode_levels( $encoded_levels );
        Given encoded levels, returns the levels:

          [ 17, 16, 17 ]

WHY DO MY LINES LOOK FUNNY?
    Do your lines all go through the north pole? Maybe you have your *lon*s
    & *lat*s mixed up... If so and you're using point arrays, you can set
    "lons_first".

    Do your points not show up at particular zoom levels? That's not a bug,
    it's a feature! Try playing with "visible_threshold".

    Do your encoded lines cause your browser to crash? Sounds like a bug -
    file it!

BUGS
    <https://rt.cpan.org/Dist/Display.html?Queue=Geo-Google-PolylineEncoder>

TODO
    More optimization: encoding big files is *slow*. Maybe XS implementation
    if there's enough demand for it?

AUTHOR
    Steve Purkis <spurkis@cpan.org>

    Ported from Mark McClure's "PolylineEncoder.js" which can be found here:
    <http://facstaff.unca.edu/mcmcclur/GoogleMaps/EncodePolyline/PolylineEnc
    oderClass.html>

    Some encoding ideas borrowed from Geo::Google.

    Bringing distance calcs in-line was Joel Rosenberg's idea:
    <http://facstaff.unca.edu/mcmcclur/GoogleMaps/EncodePolyline/gmap_polyli
    ne_encoder.rb.txt>

COPYRIGHT
    Copyright (c) 2008-2010 Steve Purkis. Released under the same terms as
    Perl itself.

SEE ALSO
    <http://code.google.com/apis/maps/documentation/polylinealgorithm.html>,
    <http://facstaff.unca.edu/mcmcclur/GoogleMaps/EncodePolyline/PolylineEnc
    oderClass.html> (JavaScript implementation),
    <http://www.usnaviguide.com/google-encode.htm> (similar implementation
    in perl), Geo::Google, JSON::Any

