.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Geography::NationalGrid::IE 3pm"
.TH Geography::NationalGrid::IE 3pm "2007-10-23" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Geography::NationalGrid::IE \- Module to convert Irish National Grid references to/from Latitude and Longitude
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
You should _create_ the object using the Geography::NationalGrid factory class, but you still need to
know the object interface, given below.
.PP
.Vb 8
\&        my $point1 = new Geography::NationalGrid::IE(
\&                GridReference => \*(AqM 345132\*(Aq,
\&        );
\&        my $point2 = new Geography::NationalGrid::IE(
\&                Latitude => 53.8,
\&                Longitude => \-7.5
\&        );
\&        print "Point 1 is " . $point\->latitude . " degrees north\en";
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.SH "OPTIONS"
.IX Header "OPTIONS"
These are the options accepted in the constructor. You \s-1MUST\s0 provide either a GridReference or Latitude and Longitude,
or Easting and Northing (the origin for these is the usual location of V 000000).
.IP "Projection" 4
.IX Item "Projection"
Default is '\s-1IRNATGRID\s0', the Irish National Grid.
Other projections recognized are '\s-1NATGRID\s0', '\s-1UTM29\s0', '\s-1UTM30\s0', and '\s-1UTM31\s0', which stand for the National Grid (British),
and the \s-1UTM29\s0 to 31 zones. This argument is a string.
.Sp
\&\s-1NOTE:\s0 if you use a projection other than the default then the results for the \fIgridReference()\fR method will be wrong,
so the method will return undef.
However, you can use the \fInorthing()\fR and \fIeasting()\fR results instead to find the location in the desired projection.
.IP "GridReference" 4
.IX Item "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.
.IP "Latitude" 4
.IX Item "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. [ \f(CW$degrees\fR, \f(CW$minutes\fR, \f(CW$seconds\fR ]), or as a string of the form '52d 13m 12s'. North is positive
degrees, south is negative degrees.
.IP "Longitude" 4
.IX Item "Longitude"
As for latitude, except that east is positive degrees, west is negative degrees.
.IP "Easting" 4
.IX Item "Easting"
The number of metres east of the grid origin, using grid east.
.IP "Northing" 4
.IX Item "Northing"
The number of metres north of the grid origin, using grid north.
.IP "Userdata" 4
.IX Item "Userdata"
The value of this option is a hash-reference, which you can fill with whatever you want \- typical usage might be to specify
\&\f(CW\*(C`Userdata =\*(C'\fR { Name => 'Dublin Observatory' }> but add whatever you want. Access using the \fIdata()\fR method.
.SH "METHODS"
.IX Header "METHODS"
Most of these methods take no arguments. Some are inherited from Geography::NationalGrid
.IP "latitude" 4
.IX Item "latitude"
Returns the latitude of the point in a floating point number of degrees, north being positive.
.IP "longitude" 4
.IX Item "longitude"
As latitude, but east is positive degrees.
.IP "gridReference( [ \s-1RESOLUTION\s0 ] )" 4
.IX Item "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.
.IP "easting" 4
.IX Item "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.
.IP "northing" 4
.IX Item "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.
.IP "deg2string( \s-1DEGREES\s0 )" 4
.IX Item "deg2string( DEGREES )"
Given a floating point number of degrees, returns a string of the form '51d 38m 34.34s'. Intended for formatting, like:
\&\f(CW$self\fR\->deg2string( \f(CW$self\fR\->latitude );
.IP "data( \s-1PARAMETER_NAME\s0 )" 4
.IX Item "data( PARAMETER_NAME )"
Returns the item from the Userdata hash whose key is the \s-1PARAMETER_NAME\s0.
.SH "ACCURACY AND PRECISION"
.IX Header "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.
.PP
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 \s-1NOT\s0 used under any
circumstance where its lack of accuracy could cause any harm, loss or other problems of any kind. Beware!
.SH "REFERENCES"
.IX Header "REFERENCES"
Equations for converting co-ordinate systems appear in the guide at http://www.gps.gov.uk/guidecontents.asp \- entitled
\&\*(L"A guide to coordinate systems in Great Britain: A primer on coordinate system concepts, including full information on \s-1GPS\s0 and Ordnance Survey coordinate systems.\*(R"
.PP
Irish National Grid letter-pairs checked at http://www.evoxfacilities.co.uk/evoxig.htm
.PP
Constants also checked at http://www.ddl.org/figtree/pub/proceedings/korea/full\-papers/session8/cory\-morgan\-bray\-greenway.htm
.PP
\&\s-1ISO\s0 3166 Country codes checked against http://www.din.de/gremien/nas/nabd/iso3166ma/codlstp1/en_listp1.html
.PP
Conversions compared with software from ftp://ftp.kv.geo.uu.se/pub/ and online services
.SH "AUTHOR AND COPYRIGHT"
.IX Header "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.
.PP
\&\f(CW$Revision:\fR 1.2 $