plucky (3) Geo::Gpx::Point.3pm.gz

NAME

       Geo::Gpx::Point - Class to store and edit GPX Waypoints

SYNOPSIS

         use Geo::Gpx::Point;

DESCRIPTION

       Geo::Gpx::Point provides a data structure for GPX points and provides accessor methods to read and edit
       point data.

   Constructor Method
       new( lat => $lat, lon => $lon [, ele => $ele, desc => $desc, … ] )
           Create and return a new point as per the fields provided, which can be any of "lat lon ele time
           magvar geoidheight name cmt desc src link sym type fix sat hdop vdop pdop ageofdgpsdata dgpsid". Most
           expect numberial values except: "name", "cmt", "desc", "src", "sym", "type", "fix" that can contain
           strings.

           "lat" and "lon" are required, all others keys are optional.

             %fields = ( lat => 47.0871, lon => 70.9318, ele => 808.000, name => 'MSA', desc => 'A nice view of the River at the top');
             $pt = Geo::Gpx::Point->new( %fields );

           The "link" field is expected to be structured as:

             link => { href => 'http://hexten.net/', text => 'Hexten', type => 'Blah' },

       flex_coordinates( $lat, $lon, %fields )
           Takes latitude and longitude decimal values or strings and returns a "Geo::Gpx::Point" object. The
           latitude should always appear before the longitude and both can be in formatted form (i.e Degrees,
           Minutes, Seconds or "dms") and the constructor will attempt to convert them to decimals. Any other
           %fields are optional.

             $pt = Geo::Gpx::Point->flex_coordinates( '47.0871', '-70.9318', desc => 'Mont Ste-Anne' );

           If a string reference is passed as the first argument (instead of $lat and $lon), the constructor
           will attempt to parse it as coordinates (decimal-form only). For instance you can simply call
           "flex_coordinates( '47.0871 -70.9318' )" with or without a comma along with optional fields.

             $str_ref = \'47.0871 -70.9318';
             $pt = Geo::Gpx::Point->flex_coordinates($str_ref, desc => 'Mont Ste-Anne' );

       clone()
           Returns a deep copy of the "Geo::Gpx::Point".

             $clone = $ggp->clone;

   AUTOLOAD Methods
       field( $value )
           Methods with respect to fields of the object can be autoloaded.

           Possible fields consist of those listed and accepted by new(), specifically: lat, lon, ele, time,
           magvar, geoidheight, name, cmt, desc, src, link, sym, type, fix, sat, hdop, vdop, pdop,
           ageofdgpsdata, and dgpsid.

           Some fields may contain a value of 0. It is safer to check if a field is defined with "if (defined
           $point->ele)" rather than "if ($point->ele)".

           Caution should be used if setting a $value as no checks are performed to ensure the value is
           appropriate or in the proper format.

   Object Methods
       distance_to( $pt or lat => $lat, lon => $lon, [ %options ] )
           Returns the distance in meters from the "Geo::Gpx::Point" $pt or from the coordinates provided by
           $lat and $lon. The distance is calculated as the straight-line distance, ignoring any topography. $pt
           must be the first argument if specified.

           %options may be any of the following key/value pairs (all optional):

               "dec => $decimals": how many digits to return after the decimal point. Defaults to 6 but this
           will change to 1 or 2 in the future.
               "km  => boole":     scale the return value to kilometers rather than meters (default is false).
               "rad => $radius":   the earth's radius in kilometers (see below).

           $radius should rarely be specified unless the user knows what they are doing. The default is the
           global average of 6371 kilometers and any value outside the 6357 to 6378 range will be ignored. This
           implies that a given value would affect the returned distance by at most 0.16 percent versus the
           global average.

       to_geocalc()
           Returns a point as a Geo::Calc object. (Requires that the Geo::Calc module be installed.)

       to_tcx()
           Returns a point as a basic Geo::TCX::Trackpoint object, i.e. a point with only Position information.
           (Requires that the Geo::TCX module be installed.)

       time_datetime ()
           Return a DateTime object corresponding to the time of the point. The "time_zone" of the object will
           be 'UTC'. Specify "time_zone => $tz" to set a different one.

       summ()
           For debugging purposes mostly. Summarizes the fields of point by printing to screen. Returns nothing.

       as_string()
           Returns a string with the coordinates e.g. "lat="47.0871" lon="-70.9318"".

   Overloaded Methods
       as_string() is called when using a "Geo::Gpx::Point" instance as a string.

EXAMPLES

       Coming soon.

AUTHOR

       Patrick Joly "<patjol@cpan.org>".

VERSION

       1.11

SEE ALSO

       perl(1).