Geography::NationalGrid::IE(3pm)			User Contributed Perl Documentation			  Geography::NationalGrid::IE(3pm)

NAME

       Geography::NationalGrid::IE - Module to convert Irish National Grid references to/from Latitude and Longitude

SYNOPSIS

       You should _create_ the object using the Geography::NationalGrid factory class, but you still need to know the object interface, given
       below.

	       my $point1 = new Geography::NationalGrid::IE(
		       GridReference => 'M 345132',
	       );
	       my $point2 = new Geography::NationalGrid::IE(
		       Latitude => 53.8,
		       Longitude => -7.5
	       );
	       print "Point 1 is " . $point->latitude . " degrees north
";

DESCRIPTION

       Once created, the object allows you to retrieve information about the point that the object represents.	For example you can create an
       object using a grid reference and the retrieve the latitude and longitude.

OPTIONS

       These are the options accepted in the constructor. You MUST provide either a GridReference or Latitude and Longitude, or Easting and
       Northing (the origin for these is the usual location of V 000000).

       Projection
	   Default is 'IRNATGRID', the Irish National Grid.  Other projections recognized are 'NATGRID', 'UTM29', 'UTM30', and 'UTM31', which
	   stand for the National Grid (British), and the UTM29 to 31 zones. This argument is a string.

	   NOTE: if you use a projection other than the default then the results for the gridReference() method will be wrong, so the method will
	   return undef.  However, you can use the northing() and easting() results instead to find the location in the desired projection.

       GridReference
	   A grid reference string composed of the following: a 1-letter 100km square identifier; an even number of digits, from 2 to 10,
	   depending on required accuracy. A standard 6-figure reference such as 'M 345132' gives 100m accuracy. Case and whitespace is ignored
	   here.

       Latitude
	   The latitude of the point. Actually should be the latitude using the spheroid related to the grid projection but for most purposes the
	   difference is not too great. Specify the amount in any of these ways: as a decimal number of degrees, a reference to an array of three
	   values (i.e. [ $degrees, $minutes, $seconds ]), or as a string of the form '52d 13m 12s'. North is positive degrees, south is negative
	   degrees.

       Longitude
	   As for latitude, except that east is positive degrees, west is negative degrees.

       Easting
	   The number of metres east of the grid origin, using grid east.

       Northing
	   The number of metres north of the grid origin, using grid north.

       Userdata
	   The value of this option is a hash-reference, which you can fill with whatever you want - typical usage might be to specify "Userdata
	   =" { Name => 'Dublin Observatory' }> but add whatever you want. Access using the data() method.

METHODS

       Most of these methods take no arguments. Some are inherited from Geography::NationalGrid

       latitude
	   Returns the latitude of the point in a floating point number of degrees, north being positive.

       longitude
	   As latitude, but east is positive degrees.

       gridReference( [ RESOLUTION ] )
	   Returns the grid reference of the point in standard format. The default resolution is 100m, or if you used a grid reference in the
	   constructor then the default resolution is the resolution of that reference.  You can explicitly set the resolution to 1, 10, 100,
	   1000, or 10000 metres.

       easting
	   How many metres east of the origin the point is. The precision of this value depends on how it was derived, but is truncated to an
	   integer number of metres. For example if the object was created from a 6 figure grid reference the easting only has precision to 100m.

       northing
	   How many metres north of the origin the point is. The precision of this value depends on how it was derived, but is truncated to an
	   integer number of metres.

       deg2string( DEGREES )
	   Given a floating point number of degrees, returns a string of the form '51d 38m 34.34s'. Intended for formatting, like:
	   $self->deg2string( $self->latitude );

       data( PARAMETER_NAME )
	   Returns the item from the Userdata hash whose key is the PARAMETER_NAME.

ACCURACY AND PRECISION

       The routines used in this code may not give you completely accurate results for various mathematical and theoretical reasons.  In tests the
       results appeared to be correct, but it may be that under certain conditions the output could be highly inaccurate. It is likely that output
       accuracy decreases further from the datum, and behaviour is probably divergent outside the intended area of the grid.

       This module has been coded in good faith but it may still get things wrong.  Hence, it is recommended that this module is used for
       preliminary calculations only, and that it is NOT used under any circumstance where its lack of accuracy could cause any harm, loss or
       other problems of any kind. Beware!

REFERENCES

       Equations for converting co-ordinate systems appear in the guide at http://www.gps.gov.uk/guidecontents.asp - entitled "A guide to
       coordinate systems in Great Britain: A primer on coordinate system concepts, including full information on GPS and Ordnance Survey
       coordinate systems."

       Irish National Grid letter-pairs checked at http://www.evoxfacilities.co.uk/evoxig.htm

       Constants also checked at http://www.ddl.org/figtree/pub/proceedings/korea/full-papers/session8/cory-morgan-bray-greenway.htm

       ISO 3166 Country codes checked against http://www.din.de/gremien/nas/nabd/iso3166ma/codlstp1/en_listp1.html

       Conversions compared with software from ftp://ftp.kv.geo.uu.se/pub/ and online services

AUTHOR AND COPYRIGHT

       Copyright (c) 2002 P Kent. All rights reserved.	This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

       $Revision: 1.2 $

perl v5.10.0							    2007-10-23					  Geography::NationalGrid::IE(3pm)