SABRE Maps/Creating map tiles

Tiling is probably the most complex part of the process to add a map to SABRE Maps, and requires several steps. Before reading this, please ensure you are familiar with SABRE Maps terminology, such as layers and layer groups, and have read and understood all of the previous pages in the in-depth guide.

Any questions can be directed towards the SABRE Maps Co-ordinator on the SABRE Forums, either by Private Message or within the Developing SABRE Wiki and Maps forum.

There are several main stages in the process, which require completing in order. They are:

1. Combine scanned map and calibration file together to create a Google Earth-compatible KML file
2. Clear space for the new map within the existing layer
3. Generate new map tiles that include the new map

The programs in use for each stage are command-line tools, and so anyone wishing to use them will need to be comfortable with running this type of software.

Generating the initial KML file

The program used to generate the initial KML file needed for the process is called warp-sabre, created by Ritchie333. It is derived off a suite of OpenStreetMap tools called warp-gbos, with some extra bells and whistles to handle a whole load of other projections relevant to SABRE Maps.

It currently supports the following projections:

• OSGB National Grid
• Irish Grid
• WGS84 Lat/Lon
• Cassini (Delamere)
• Bonne (Scotland)
• Bonne (Ireland)

It does not currently support:

• OSGB National Yard Grid (hence the calibration tool converting to OSGB National Grid)
• OSGB36 Lat/Lon
• Irish Transverse Mercator Grid
• Cassini (War Office) Grid (hence the calibration tool converting to OSGB National Grid)
• War Office Irish Grid
• UTM

Before starting on this section, make sure you have both the original stitched map scan, and the matching calibration file as created in earlier steps.

The basic command line needed to generate the KML file for an OSGB National Grid map is as follows, replacing the items in italics with the names in each case:

warp-sabre.exe -i mapfilename.jpg -p calibrationfilename.csv -o KMLname --fit 1

Note that KMLname does not have a file extension. Each KML file has a (mostly!) standardised name in order to make the tiling requirements simpler. Some examples are given below, though if an example isn't given, please confirm with the SABRE Maps Co-ordinator what the KML filename should be.

Map series	KML file example name	Notes
OSGB One Inch 7th Series/ New Popular	78.kml	Combined sheet 138/151 is 138151.kml. Note for those five sheets where NPE sheetlines are different, a different format is used.
OSGB One Inch New Popular	106npe.kml	Only used for sheets 106, 160, 161, 185 and 189 which differ from the equivalent Seventh Series sheets.
OSGB One Inch Fifth Edition	5th-112.kml	Sheet 113 comes in two sizes, the later large sheet version is 5th-113l.kml; whilst the later district version of Sheet 95 is 5th-95d.kml
OSGB Scottish Popular	spe01.kml
OSGB England and Wales Popular	pop01.kml
OSNI One Inch Third Edition	osni_01.kml
OSNI Popular Edition	osni_pop_01.kml
OSI One Inch	i01.kml
OSGB Landranger	001.kml	Reserved for future use
OSI/OSNI Discoverer/Discovery	dis001.kml	Reserved for future use
OSGB Quarter Inch Fifth Series	05.kml
OSGB Quarter Inch Fourth Edition	qi-4-01.kml	Scottish sheets have their sheet number prefixed with "s", for example, qi-4-s04.kml
OSGB Quarter Inch Third Edition	qi-3-01.kml	Scottish sheets have their sheet number prefixed with "s", for example, qi-3-s04.kml
OSGB 1:25k Provisional Edition	TL21.kml	Whilst early maps have a sheet number that uses the original numbered National Grid squares, we standardise on the modern lettered squares - so Sheet 21/58 would be SS58.kml.
OSI Half Inch	i05.kml
OSGB Half Inch Second Series	28.kml

If the map is not an OSGB National Grid map, then the correct item from the below table needs to be added to the end of the warp-sabre command line:

Projection	additional command argument
Irish Grid	--inproj osi
WGS84 Lat / lon	--inproj mercator
Cassini (Delamere)	--inproj cassini
Bonne (Scotland)	--inproj bonnes
Bonne (Ireland)	--inproj bonnei

This will then generate a KML file (and associated JPG with the same name). Opening this KML file within Google Earth will show the quality of the calibration as features on the map such as roads, rivers, railways and so on can be compared to their actual location. Note that a perfect match won't always be possible, but if the KML file map and reality are too far apart, then a poor quality final product will be achieved. In this case, the map should be recalibrated before re-entering this process.

In addition, don't be put off if your KML file appears skew within Google Earth, with part margins showing. This happens because the various Grids are skewed when compared to Lat/Lon, which can be easily seen if a map has Lat/Lon values also printed within the margins. These part-margins will be sorted out during the tiling process later on.

Note that the --inproj mercator parameter is special, as it can take a mixture of points and co-ordinates in any other projection, that are automatically converted to WGS84. For example, the post-war revisions of Scottish Popular Edition maps can be calibrated using a mix of the corners in Cassini (Delamere) and other points using the National Grid.

Bounds file

The bounds file is a simple CSV document that describes where the top left and bottom right corners of each map are. This is used to "tidy up" the edges of the final maps and to ensure that all margin areas are removed. Not creating a relevant bounds file will result in maps not meeting up properly, and random margin sections will be shown.

An example of a bounds file for OSGB National Grid would be:

OS,124.kml,535000:345000,575000:300000
OS,125.kml,575000:347000,615000:302000
OS,126.kml,615000:347000,655000:302000
OS,127.kml,248000:308000,288000:263000
OS,128.kml,288000:300000,328000:255000
OS,129.kml,328000:300000,368000:255000
OS,130.kml,360000:300000,400000:255000

For all other projection types, the same format is used with colons between the northing and eastings values for each corner; though they each have a different prefix code to identify the map type as per the below table.

Projection	Prefix code
OSGB National Grid	OS
Irish Grid	I
WGS84 Lat / Lon	M
Cassini (Delamere)	C
Bonne (Scotland)	B
Bonne (Ireland)	R

The bounds file does not need to only contain information regarding the maps on a specific layer. For example, it is entirely possible to have a single bounds file containing all of the needed data for all OS One Inch Seventh Series, New Popular Edition, Scottish Popular, OSNI Popular and Irish One Inch maps in one file (with careful naming) that can be used for any layer containing a combination of those map types. Any unused lines are simply ignored.

For ease of use, the correct line item for a map for use within the relevant bounds file can be created at the same time as the calibration of that map - the Grid Calibrator has an optional section for this use. And again, the SABRE Maps Co-ordinate Finder can help to find the correct locations, although this information should be also found within the relevant map calibration file.

Clearing space for the new map

Once you are happy with the KML, then unless it is the first map on a new map layer, the cleartiles program is required to be used with the KML and bounds files to "empty" the area of the new map ready to add the new map, or in other words, it actually deletes tiles. If you miss this step, then the maps will not fit together nicely as the later tile generation program only creates tiles where there is no tile already in that location - so any previous "edge" tile, where part of another map is shown but part is blank, will cause a new tile showing both maps to not be generated.

The basic command line required is:

cleartiles.exe --bounds boundsfile --out tilelocation *.kml

Boundsfile is clearly the name of the bounds file to be used, and tilelocation is the foldername containing the map layer tiles. This basic commandline is appropriate for 99.99% of cases where the new KML files are in the same location that the command is run from.

This then readies the map layer to be able to generate the correct tiles to include the new map within it.

Generating the new map tiles

Finally, the gentiles program is required, in combination with all the KML files for every map contained with the layer, as well as the bounds file.

The map tile creation process will take some time, though fortunately it doesn't try to regenerate map tiles that already exist - which is again why the previous step was to clear out those tiles that need to be replaced. The length of time required will depend on a number of factors - how many maps, over how wide and area, and how in-depth the coverage required is.

The basic commandline here is:

gentiles.exe --bounds boundsfile --out tilelocation --minzoom minzoom --maxzoom maxzoom *.kml

Whilst some parameters are fairly obvious, such as boundsfile and tilelocation, the zoom values depend upon the scale of the maps concerned. For a Route Planning Map at 1:625,000 scale, generating tiles above level 12 does not assist with clarity of the map, but instead simply adds to the space taken up by the tiles, as each tile layer takes up roughly the square of the layer before for any area with full coverage. However, generating tiles that are too low a level to display can crash the tools, and hence any layer containing small map areas (such as the Redrawn Plans layer) will need to have the minzoom tweaked to suit.

The below table shows the standard zoom sizes created for each scale. It is not comprehensive, but is best thought of as a guide to standards.

Map scale	Minzoom	Maxzoom
One Inch / 1:50,000	3	14
Half Inch	3	13
Quarter Inch	3	13
Ten Mile / 1:625,000	3	12
Two Inch / 1:25,000	3	15
Redrawn Map Plans	5	16

How can I get copies of the tools?

Windows

A Windows version of the generator tools can be downloaded from this location on the SABRE webspace. This is "ready to run" and requires no additional tools; and is the least complex way to get started.

OS X and Linux

You will need to be familiar with compiling source code to use the programs on OS X and Linux.

The source code can be downloaded from github using: git clone https://github.com/Ritchie333/warp-sabre and has been used successfully on Debian and Arch Linux, and OS X Yosemite and El Capitan.

The program principally depends on these libraries:

• Boost - for odds and ends (mainly used for parsing command line arguments)

• ImageMagick - for loading and saving images

• LibXML - for parsing Google Earth KML files

• Newmat - for the matrix transformations used when rectifying map images

• Xmorph - does the job of physically moving pixels in an image when rectifying it

A configuration file to build all this from scratch on Debian can be found at https://github.com/Ritchie333/warp-sabre/blob/master/.github/workflows/ccpp.yml

Manual Install

To manually install under ubuntu

git clone https://github.com/Ritchie333/warp-sabre

sudo apt-get install libboost-dev libboost-filesystem-dev libboost-thread-dev libboost-program-options-dev libmorph-dev libmagick++-dev libxml2-dev libnewmat10-dev

cd ~/warp-sabre

./bootstrap

./configure

make

sudo make install

For Mac OS/X, you should install MacPorts (https://www.macports.org/) - you will need the boost, xmorph, imagemagick, libxml and newmat packages. There is no package for xmorph, but the latest version can be downloaded from SourceForge and compiled via ./configure ; make ; make install manually. It is recommended to install the fftw package otherwise xmorph will be slow.

Background: SABRE Maps tile format

Once a map is properly calibrated, tile images can be created from it. We use the standard Slippy map naming convention, where all tiles are 256x256 images.

Tiles are organised into different zoom levels, which allow you to see the map in higher or lower resolution as you "zoom" in and out using the user interface. The lowest zoom level is 0, which fits the entire world on a single tile; in practice maps on SABRE start at zoom 3 (all of the British Isles available on a single tile) and generally go down to level 12 for ten mile maps, 13 for quarter inch or half inch maps, and 14 for one inch maps.

Following each zoom level, tiles are organised into X and Y co-ordinates. There are always a power of 2 tiles available (ie: 1 for zoom 0, 2 for zoom 1, 4 for zoom 2, 8 for zoom 3 etc) and increase from 0 upwards from the international date line and 85.0511 degrees north in the Arctic Circle, though in practice only a small subset of values are used.