"format_grid(e,n)"
Formats an (easting, northing) pair into traditional `full national grid reference' with two letters and
two sets of three numbers, like this `SU 387 147'.
$gridref = format_grid(438710.908, 114792.248); # SU 387 147
If you want the individual components call it in a list context.
($sq, $e, $n) = format_grid(438710.908, 114792.248); # ('SU', 387, 147)
Note that rather than being rounded, the easting and northing are truncated to hectometres (as the OS
system demands), so the grid reference refers to the lower left corner of the relevant 100m square. The
system is described below the legend on all OS Landranger maps.
The format grid routine takes an optional third argument to control the form of grid reference returned.
This should be a hash reference with one or more of the keys shown below (with the default values).
format_grid(e, n, {form => 'SS EEE NNN', maps => 0, series => 'ABCHJ'})
Optionsfor"format_grid"
form
Controls the format of the grid reference. With "$e, $n" set as above:
Format produces Format produces
----------------------------------------------------------------
'SS' SU
'SSEN' SU31 'SS E N' SU 3 1
'SSEENN' SU3814 'SS EE NN' SU 38 14
'SSEEENNN' SU387147 'SS EEE NNN' SU 387 147
'SSEEEENNNN' SU38711479 'SS EEEE NNNN' SU 3871 1479
'SSEEEEENNNNN' SU3871014792 'SS EEEEE NNNNN' SU 38710 14792
You can't leave out the SS, you can't have N before E, and there must be the same number of Es and
Ns.
There are two other special formats:
form => 'TRAD' is equivalent to form => 'SS EEE NNN'
form => 'GPS' is equivalent to form => 'SS EEEEE NNNNN'
In a list context, this option means that the individual components are returned appropriately
truncated as shown. So with "SS EEE NNN" you get back "('SU', 387, 147)" and not "('SU', 387.10908,
147.92248)". The format can be given as upper case or lower case or a mixture. If you want just the
local easting and northing without the grid square, get the individual parts in a list context and
format them yourself:
my $gr = sprintf('Grid ref %2$s %3$s on Sheet %4$s', format_grid_landranger($e, $n))
# returns: Grid ref 387 147 on Sheet 196
maps
Controls whether to include a list of map sheets after the grid reference. Set it to 1 (or any true
value) to include the list, and to 0 (or any false value) to leave it out. The default is "maps =>
0".
In a scalar context you get back a string like this:
SU 387 147 on A:196, B:OL22E, C:180
In a list context you get back a list like this:
('SU', 387, 147, A:196, B:OL22E, C:180)
series
This option is only used when "maps" is true. It controls which series of maps to include in the
list of sheets. Currently the series included are:
"A" : OS Landranger 1:50000 maps
"B" : OS Explorer 1:25000 maps (some of these are designated as `Outdoor Leisure' maps)
"C" : OS Seventh Series One-Inch 1:63360 maps
"H" : Harvey British Mountain maps - mainly at 1:40000
"J" : Harvey Super Walker maps - mainly at 1:25000
so if you only want Explorer maps use: "series => 'B'", and if you want only Explorers and
Landrangers use: "series => 'AB'", and so on.
Note that the numbers returned for the Harvey maps have been invented for the purposes of this
module. They do not appear on the maps themselves; instead the maps have titles. You can use the
numbers returned as an index to the data in Geo::Coordinates::OSGB::Maps to find the appropriate
title.
"format_grid_trad(e,n)"
Equivalent to "format_grid(e,n, { form => 'trad' })".
"format_grid_GPS(e,n)"
Equivalent to "format_grid(e,n, { form => 'gps' })".
"format_grid_map(e,n)"
Equivalent to "format_grid(e,n, { maps => 1 })".
"format_grid_landranger(e,n)"
Equivalent to
format_grid(e,n,{ form => 'ss eee nnn', maps => 1, series => 'A' })
except that the leading "A:" will be stripped from any sheet names returned, and you get a slightly
fancier set of phrases in a scalar context depending on how many map numbers are in the list of sheets.
"parse_grid"
The "parse_grid" routine extracts an (easting, northing) pair from a string or a list of arguments
representing a grid reference. The pair returned are in units of metres from the false origin of the
grid, so that you can pass them to "format_grid" or "grid_to_ll".
The arguments should be in one of the following forms
• A single string representing a grid reference
String -> interpreted as
--------------------------------------------------
parse_grid("TA 123 678") -> (512300, 467800)
parse_grid("TA 12345 67890") -> (512345, 467890)
The spaces are optional in all cases. You can also refer to a 100km square as "TA" which will return
"(500000,400000)", a 10km square as "TA16" which will return "(510000, 460000)", or to a kilometre
square as "TA1267" which gives "(512000, 467000)". For completeness you can also use "TA 1234 6789"
to refer to a decametre square "(512340, 467890)" but you might struggle to find a use for that one.
• A list representing a grid reference
List -> interpreted as
-----------------------------------------------------
parse_grid('TA', 0, 0) -> (500000, 400000)
parse_grid('TA', 123, 678) -> (512300, 467800)
parse_grid('TA', 12345, 67890) -> (512345, 467890)
parse_grid('TA', '123 678') -> (512300, 467800)
parse_grid('TA', '12345 67890') -> (512345, 467890)
If you are processing grid references from some external data source beware that if you use a list
with bare numbers you may lose any leading zeros for grid references close to the SW corner of a grid
square. This can lead to some ambiguity. Either make the numbers into strings to preserve the
leading digits or supply a hash of options as a fourth argument with the `figs' option to define how
many figures are supposed to be in each easting and northing. Like this:
List -> interpreted as
-------------------------------------------------------------
parse_grid('TA', 123, 8) -> (512300, 400800)
parse_grid('TA', 123, 8, { figs => 5 }) -> (500123, 400008)
The default setting of figs is 3, which assumes you are using hectometres as in a traditional grid
reference.
• A string or list representing a map sheet and a grid reference on that sheet
Map input -> interpreted as
----------------------------------------------------
parse_grid('A:164/352194') -> (435200, 219400)
parse_grid('B:OL43E/914701') -> (391400, 570100)
parse_grid('B:OL43E 914 701') -> (391400, 570100)
parse_grid('B:OL43E','914701') -> (391400, 570100)
parse_grid('B:OL43E',914,701) -> (391400, 570100)
Again spaces are optional, but you need some non-digit between the map identifier and the grid
reference. There are also some constraints: the map identifier must be one defined in
Geo::Coordinates::OSGB::Maps; and the following grid reference must actually be on the given sheet.
Note also that you need to supply a specific sheet for a map that has more than one. The given
example would fail if the map was given as `B:OL43', since that map has two sheets: `B:OL43E' and
`B:OL43W'.
If you give the identifier as just a number, it's assumed that you wanted a Landranger map;
parse_grid('176/224711') -> (522400, 171100)
parse_grid(164,513,62) -> (451300, 206200)
"parse_grid" will croak of you pass it a sheet identifier that is not defined in
Geo::Coordinates::OSGB::Maps. It will also croak if the supplied easting and northing are not
actually on the sheet.
If you just want the corner of a particular map, just pass the sheet name:
parse_grid('A:82') -> (195000, 530000)
parse_grid(161) -> (309000, 205000)
Again, it's assumed that you want a Landranger map. The grid reference returned is the SW corner of
the particular sheet. This is usually obvious, but less so for some of the oddly shaped 1:25000
sheets, or Harvey's maps. What you actually get is the first point defined in the maps polygon, as
defined in Maps. If in doubt you should work directly with the data in Geo::Coordinates::OSGB::Maps.
"parse_trad_grid(grid_ref)"
This is included only for backward compatibility. It is now just a synonym for "parse_grid".
"parse_GPS_grid(grid_ref)"
This is included only for backward compatibility. It is now just a synonym for "parse_grid".
"parse_landranger_grid(sheet,e,n)"
This is included only for backward compatibility. It is now just a synonym for "parse_grid".
"parse_map_grid(sheet,e,n)"
This is included only for backward compatibility. It is now just a synonym for "parse_grid".
"random_grid([sheet1,sheet2,...])"
Takes an optional list of map sheet identifiers, and returns a random easting and northing for some place
covered by one of the maps. There's no guarantee that the point will not be in the sea, but it will be
within the bounding box of one of the maps.
• If you omit the list of sheets, then one of map sheets defined in Geo::Coordinates::OSGB::Maps will
be picked at random.
• As a convenience whole numbers in the range 1..204 will be interpreted as Landranger sheets, as if
you had written "A:1", "A:2", etc.
• Any sheet identifiers in the list that are not defined in Geo::Coordinates::OSGB::Maps will be
(silently) ignored.
• The easting and northing are returned as meters from the grid origin, so that they are suitable for
input to the "format_grid" routines.
Install Now
PNG Icons
