# NAME Geo::OSM::Imager - simplifies plotting onto OpenStreetMap tiles # SYNOPSIS my $g=Geo::OSM::Imager->new(ua => 'MyApplication'); my $image=$g->init(\@points); ... my ($x,$y)=$g->latlon2xy($lat,$lon); $image->circle(x=>$x,y=>$y,r=>50,color=>$blue); ... $image->circle($g->latlon2hash($lat,$lon),r=>50,color=>$blue); ... $image->write(file => 'test.png'); # DESCRIPTION This module sets up an Imager object made of OpenStreetMap tiles, for drawing of geographic data. Beware of over-using OpenStreetMap tile servers, and see the usage policy at https://operations.osmfoundation.org/policies/tiles/ . Be hesitant about drawing straight lines over long distances, as map projections will cause distortion. Over more than a few hundred metres, the author prefers to break the line into a series of points and plot individual line segments. # USAGE - new() Creates a new Geo::OSM::Imager object. Takes an optional hash of parameters: maxx - maximum X size of the image, in pixels. maxy - maximum Y size of the image, in pixels. The image will generally be between 50% and 100% of this size. margin - fractional margin around bounding points marginlat - fractional latitude margin around bounding point marginlon - fractional longitude margin around bounding points The fraction of the latitude/longitude span to leave as space around the matter to be plotted. With a margin of zero, points will be plotted right at the edges of the image. A margin of 1/7 works well, and is the default. marginlat and marginlon allow you to define this separately for latitude and longitude. tileage - minimum age to expire tiles The number of seconds after which a tile may be considered "old" and re-downloaded. Tileserver usage policy forbids an expiry of less than one week (604800s), which is the default. tiledir - directory for the tile cache The directory in which to store tiles; it must exist. tilesize - size of tiles The pixel size of each tile. Leave at its default of 256 unless you know what you're doing. tileurl - base URL for downloading tiles The base URL for downloading files. If you are using a local tileserver, or a public tileserver other than OpenStreetMap, set it here. ua - user-agent Tileserver usage policy requires a "Valid HTTP User-Agent identifying application". - init() Checks bounds and sets up the image. Pass an arrayref of points, each of which can be either an arrayref \[lat,lon\] or a hashref including lat and lon keys (or "latitude", "long", "longitude"). These need not be the same points you're going to plot, though that's obviously the easiest approach. Returns the Imager object. - image() Returns the Imager object. - zoom() Returns the zoom level of the initialised object. See [Zoom levels](http://wiki.openstreetmap.org/wiki/Zoom_levels) and [Slippy Map Tilenames](http://wiki.openstreetmap.org/wiki/Slippy_map_tilenames) for more. - latlon2xy($lat,$lon) Given a (latitude, longitude) coordinate pair, returns the (x, y) coordinate pair needed to plot onto the Imager object. - latlon2hash($lat,$lon) Given a (latitude, longitude) coordinate pair, returns a list of the form ('x', $x, 'y', $y) for use with many Imager plotting functions. - segment($lat1,$lon1,$lat2,$lon2,$step) Given two (latitude, longitude) coordinate pairs and a step value, returns an arrayref of (latitude, longitude) coordinate pairs interpolating the route on a great circle. This is generally worth doing when distances exceed around 100 miles or high precision is wanted. A positive step value is the length of each segment in metres. A negative step value is the number of divisions into which the overall line should be split. # OTHER CONSIDERATIONS Note that you need not draw directly onto the supplied object: you can create a new transparent image using the width and height of the one provided by the module, draw onto that, and copy the results with a rubthrough or compose command. See [Imager::Transformations](https://metacpan.org/pod/Imager::Transformations) for more. # BUGS Won't work to span +/- 180 degrees longitude. # LICENSE Copyright (C) 2017 Roger Bell\_West. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. # AUTHOR Roger Bell\_West # SEE ALSO [Imager](https://metacpan.org/pod/Imager)