Edge Documentation

{{DISPLAYTITLE:Offline Tilesets}}
[[Category:AppBoard 2.5]]
The [[appboard/2.5/builder/widgets/tile_map|Tile Map Widget]] can be configured to use multiple base layer tilesets and multiple overlay tilesets, including tilesets served up by the AppBoard server removing the need for external Internet access.

Viewer clients connected to AppBoard will fetch the tilesets from the AppBoard server, to which they must already have network access.

It's important to understand that the size of the offline tileset grows exponentially for each additional zoom level. Levels 0 through 7 of the default OpenStreetMap (OSM) tiles is roughly 100MB, but online you can zoom through to level 20. Attempting to have an offline tileset with this deep level of zoom would be ... big.


== Importing Offline Tilesets ==

Edge can provide some packaged OSM tiles for offline use; please contact support for assistance. It is also possible to build your own offline tilesets using a variety of sources and tools (see the Building section below).

# Shutdown AppBoard
# In a terminal change into <tt>[INSTALL_HOME]/server/bin</tt>
# Run the following command: <tt>portal FilesImport -jar <OfflineTilePackage></tt>
# Restart AppBoard, the new tileset should be available when configuring Tile Map widgets.

{{Note|Due to the size of tilesets these are '''not''' backed up by default. That means both the tiles and the tile registry file are excluded from backup archives. It is recommended to have a restore/migration procedure that includes installing any custom offline tilesets as an additional step in the process.}}

== Building Offline Tileset Packs ==

Tileset packages are simply a zip file containing a set of XYZ tiles and a tile registry file for AppBoard to understand how to use the tiles.

The general process to build a tileset:

# create a working directory, and change into that directory
# create a subdirectory for the tile images, this '''must''' be in the following hierarchy: <tt>webapps/enportal/custom/tiles/''your_tileset''</tt> and replace ''your_tileset'' with an appropriate name.
# place the set of XYZ directories and images files into the directory above. So for example you may end up with something like <tt>webapps/enportal/custom/tiles/''your_tileset''/''z''/''x''/''y.png''</tt> where ''z'', ''x'', and ''y'' would be numbers representing the zoom level and coordinates.
# create the subdirectory for the tile registry file and place it there. This '''must''' be in the following hierarchy: <tt>webapps/enportal/WEB-INF/xmlroot/appboard/config/tileregistry/''your_tileset.csv''</tt> where ''your_tileset.csv'' is the registry file and the rest of the path is the subdirectory. Refer to the [[appboard/2.5/builder/widgets/tile_map/registering_tilesets#Registry_Format|Registering Tilesets]] page for the format of this file.
# use zip to compress the working directory and call it <tt>''your_tileset''.zip</tt>.

As an example, here is the output from a listing of files and directories from a valid offline tileset package containing zoom levels 0 through 7 of OpenStreetMap tiles. Since there are too many files to list only a handful are shown:

<pre>
./webapps
./webapps/enportal
./webapps/enportal/WEB-INF
./webapps/enportal/WEB-INF/xmlroot
./webapps/enportal/WEB-INF/xmlroot/appboard
./webapps/enportal/WEB-INF/xmlroot/appboard/config
./webapps/enportal/WEB-INF/xmlroot/appboard/config/tileregistry
./webapps/enportal/WEB-INF/xmlroot/appboard/config/tileregistry/mytileset.csv
./webapps/enportal/custom
./webapps/enportal/custom/tiles
./webapps/enportal/custom/tiles/mytileset
./webapps/enportal/custom/tiles/mytileset/7
./webapps/enportal/custom/tiles/mytileset/7/119
./webapps/enportal/custom/tiles/mytileset/7/119/52.png
./webapps/enportal/custom/tiles/mytileset/7/119/4.png
./webapps/enportal/custom/tiles/mytileset/7/119/63.png
./webapps/enportal/custom/tiles/mytileset/7/119/85.png
./webapps/enportal/custom/tiles/mytileset/7/119/82.png
... (continued ) ...
</pre>


And the example contents from <tt>mytileset.csv</tt>.

<pre>
"id","name","source","minZoom","maxZoom","initialZoom","initialLatitude","initialLongitude","copyright","isOverlay","initialAlpha"
"mytileset","mytileset name","../custom/tiles/mytileset/${z}/${x}/${y}.png",0,7,1,0.0,0.0,"Map data <a href=\'http://www.openstreetmap.org\'>CC-BY-SA OpenStreetMap.org</a>",false,1
</pre>


=== How to Create an XYZ Tileset ===

Creating XYZ tilesets is beyond the scope of the AppBoard product but there are plenty of existing tilesets that can be used and tools to create and modify tilesets. Some companies even specialize in creating tilesets.

Some useful references:

* [http://www.openstreetmap.org OpenStreetMap]: the starting point for OpenStreetMap data and the default online tileset the Tile Map widget is configured to use.
* [[appboard/2.5/builder/widgets/tile_map/tileset_from_images|Creating Custom Tiles from Images]]: additional information on building tilesets from images.

{{Warning|There may be copyright requirements and other legal restrictions when using tilesets from other parties. Edge is not responsible to ensure these requirements and restrictions are enforced. The Tile Map widget is simply a tool to visualize XYZ tilesets and it is the responsibility of the user/producer of the tilesets to ensure compliance.}}