NAME
    Geo::Dymaxion - Plot latitude/longitude on a Fuller Dymaxion(tm) map

SYNOPSIS
      use Geo::Dymaxion;
  
      # Suppose we have a Fuller projection of the Earth's surface that's
      # 800 pixels wide and 600 pixels high.

      my $map = Geo::Dymaxion->new( 800, 600 );

      # Find the x and y coordinates in pixels of Philadelphia, PA, USA.

      my ($x, $y) = $map->plot( 40, -75 );

      # Do the same for Sebastopol, CA, USA.

      ($x, $y) = $map->plot( 38.3993, -122.8259 );

DESCRIPTION
    "Geo::Dymaxion" allows you to draw points on Dymaxion(tm) maps using
    latitude and longitude data, which turns out to be quite difficult and
    requires some tricky trigonometry. This module strives to hide away all
    the ugly math and allow you to concentrate on drawing your map.

    The Dymaxion(tm), or Fuller, projection was invented by R. Buckminster
    Fuller in 1954, and is "the only flat map of the entire surface of the
    Earth which reveals our planet as one island in one ocean, without any
    visually obvious distortion of the relative shapes and sizes of the land
    areas, and without splitting any continents." See
    http://www.bfi.org/map.htm for more details.

METHODS
    new( [WIDTH [, HEIGHT]] )
        "new" takes two arguments: the length and width of your Dymaxion map
        in pixels. Be sure when supplying this measure that you have
        excluded any margins that may exist around the edges of your map
        image. If no arguments are provided, operations with "Geo::Dymaxion"
        will return values expressed in fractions of a unit-sized map.

    plot( LATITUDE, LONGITUDE )
        "plot" takes a floating-point (lat, long) pair, and returns a list
        consisting of floating-point (x, y) coordinates, scaled to the width
        and height provided to "new()". Latitudes south of the equator and
        longitudes west of the prime meridian should be expressed as
        negative values. These X and Y values can then be plugged into
        "Imager->setpixel()" or any other drawing module you'd care to use.

FUNCTIONS
    Geo::Dymaxion::dymax( LATITUDE, LONGITUDE )
        "dymax()" provides access to the internal routines used by
        "Geo::Dymaxion". Takes a (lat, long) pair, returns an (x, y) pair,
        scaled in unit triangle edges, with (0, 0) at the *lower left*
        corner of the map. For reference, a Fuller projection of the Earth's
        surface is 5.5 by sqrt(7.75) unit triangle edges in size.

EXAMPLE
      # This script takes a Dymaxion map and (lat, long) point and
      # outputs a JPEG of the map with a large red dot over that point.
      #
      # For a more elaborate example of the same, see:
      #    http://iconocla.st/hacks/dymax/
  
      use Imager;
      use Imager::Fill;
      use Geo::Dymaxion;
      use strict;
  
      my ($lat, $long) = @ARGV;
      my $map_file = "dymaxion.gif"; # make sure the margins are trimmed!

      my $map = Imager->new;
      $map->open( file => $map_file );
  
      my $dymax = Geo::Dymaxion->new( $map->getwidth, $map->getheight );
      my ($x, $y) = $dymax->plot( $lat, $long );
  
      my $dot  = Imager::Color->new( 255, 0, 0 );
      my $fill = Imager::Fill->new( solid => $dot );
      $map->circle( fill => $fill, r => 5, x => $x, y => $y );
  
      $map->write( type => "jpeg", fd => fileno(STDOUT) )
          or die $map->errstr;
  
BUGS
    It would be really cool if this module could convert (x, y) points on a
    Fuller projection back into (lat, long).

DESIDERATA
    "Think of it. We are blessed with technology that would be indescribable
    to our forefathers. We have the wherewithal, the know-it-all to feed
    everybody, clothe everybody, and give every human on Earth a chance. We
    know now what we could never have known before-that we now have the
    option for all humanity to "make it" successfully on this planet in this
    lifetime. Whether it is to be Utopia or Oblivion will b a touch-and-go
    relay race right up to the final moment." - R. Buckminster Fuller

    "When I am working on a problem, I never think about beauty. I only
    think about how to solve the problem. But when I have finished, if the
    solution is not beautiful, I know it is wrong." - R. Buckminster Fuller

SEE ALSO
    The word "Dymaxion" and the Fuller projection design are trademarks of
    the Buckminster Fuller Institute (<http://www.bfi.org>). The BFI can be
    reached at <info@bfi.org>.

    This module would not exist without the prior work of Robert W. Gray in
    determining the calculations necessary to plot latitude and longitude on
    a Fuller map. Gray's notes and original code are available at
    <http://www.rwgrayprojects.com/rbfnotes/maps/graymap1.html>, which is
    well worth the read if you're into such things.

    Also, see also Imager, Inline.

AUTHOR
    Robert W. Gray <rwgray@rwgrayprojects.com> wrote the C code on which
    this module is based.

    Schuyler D. Erle <schuyler@nocat.net> wrote the Perl API, with a little
    help from Inline.pm.

COPYRIGHT AND LICENSE
    The C code that performs the actual conversions is copyright Robert W.
    Gray <rwgray@rwgrayprojects.com>. His code is distributed under the
    following terms taken from
    <http://www.rwgrayprojects.com/rbfnotes/maps/graymap6.html>:

    "Usage Note: My work is copyrighted. You may use my work but you may not
    include my work, or parts of it, in any for-profit project without my
    consent."

    This bears reiteration, in case it wasn't clear the first time:
    According to Gray's license, you must obtain his consent prior to using
    his code for commercial or for-profit purposes. Please contact him, not
    me. (But please contact me if you use this module anyway, I'm curious to
    know what people might want it for.)

    The rest of the module is copyright 2003 by Schuyler D. Erle, and is
    free software, distributed under the same terms as Perl itself.