mirror of
https://github.com/Xastir/Xastir
synced 2026-08-13 17:46:16 -04:00
5041cef9f2
README.OSM_maps is an old file documenting Xastir's OpenStreetMap support. It is mostly still valid (though ultimately it should be recast as a wiki page instead of a text README). However, there were some minor outdated points of information: - We have, for quite some time, only had 3 OSM geo files in our repo, because of changes to upstream servers. - Cloudmade got out of the map publishing business ages ago and we removed our geo files that used their (defunct) servers. I've fixed the incorrect count of files and removed all references to Cloudmade from README.OSM_maps. I have also removed references to Cloudmade from the "Help->About" dialog.
207 lines
8.2 KiB
Text
207 lines
8.2 KiB
Text
|
|
Copyright (C) 2000-2026 The Xastir Group
|
|
|
|
|
|
Using OpenStreetMap in Xastir
|
|
------------------------------------------------------------------------
|
|
CONTENTS
|
|
Introduction
|
|
Map Types
|
|
Map Sources and Renderings (Styles)
|
|
Map Cache
|
|
Sharing Tiles
|
|
Map Definition Files
|
|
Copyrights and Licenses
|
|
|
|
|
|
Introduction
|
|
------------
|
|
What, you may ask is 'OpenStreetMap' (OSM)? From the web site,
|
|
www.openstreetmap.org, we read that
|
|
|
|
"OpenStreetMap is a free editable map of the whole world.
|
|
It is made by people like you".
|
|
|
|
The tag line for the map is "The Free Wiki World Map".
|
|
|
|
Xastir will display bitmap versions of the OSM. There are multiple
|
|
renderings of the OSM to choose from and, by default, three
|
|
are available in Xastir.
|
|
|
|
Map Types
|
|
---------
|
|
Xastir can use two different map types based on OSM: static and
|
|
tiled. Static maps are bitmaps that are least as large as the Xastir
|
|
window. Tiled maps are built up from 256x256 pixel images.
|
|
|
|
Static maps are also assembled from tiles, but the assembly occurs
|
|
at the server and the full size image is downloaded to Xastir. There
|
|
is a major disadvantage to static maps: even slight changes in map
|
|
position requires a new map download.
|
|
|
|
Most online maps, including OSM, use map tiles that follow the "Web
|
|
Mercator" projection and tiling scheme. The Web Mercator
|
|
projection was first popularized by Google Maps. It is a modified
|
|
Mercator projection, using a hybrid spheroid/ellipsoid model that
|
|
is faster to compute. Wikipedia has a nice description:
|
|
https://en.wikipedia.org/wiki/Web_Mercator.
|
|
|
|
Map tiles are referred to by their zoom level, and row and column
|
|
number. Major providers (such as OSM, Google, Apple, Mapbox, and
|
|
Bing) and open source projects (such as Open Layers and
|
|
openmaptiles.org) use the same general tile numbering scheme,
|
|
although they vary in the specific sequence of zoom/row/column
|
|
numbers, and the supporting parts of the URL. The URL for a
|
|
particular tile looks something like this:
|
|
https://a.tile.openstreetmap.org/11/329/715.png
|
|
(tile server a, zoom level 11, column 329, row 715).
|
|
You can see more in this Wikiepedia article:
|
|
https://en.wikipedia.org/wiki/Tiled_web_map.
|
|
|
|
Bitmap images, whether static or tiled, are available for only a
|
|
limited number of zoom levels. There are 18 possible zoom levels.
|
|
It takes 2^zoom tiles to represent 360 degrees. Since the tiles are
|
|
256 pixel squares, there are 2^(zoom + 8) pixels in 360 degrees.
|
|
|
|
When the Xastir scale is different from a bitmap image's zoom
|
|
level, the bitmap image is scaled. However, scaled bitmaps tend to
|
|
look ugly. The scaled bitmap can have jagged lines, unequal pixel
|
|
sizes, and/or missing information. At best a scaled bitmap looks
|
|
blurred, but more typically some pixels will be enlarged into visible
|
|
blocks or compressed invisibility.
|
|
|
|
You can use the F4 key to adjust the Xastir scale to approximate the
|
|
OSM zoom level and refresh the display. (The key can be changed by
|
|
modifying a variable in the OSM definition (GEO) files.
|
|
|
|
|
|
Map Sources and Renderings (Styles)
|
|
-----------------------------------
|
|
The OSM data is rendered into tiles using different styles. The
|
|
easiest place to view and compare the styles is at
|
|
http://ojw.dev.openstreetmap.org/StaticMap/?mode=Style&
|
|
|
|
Tiles can be retrieved from a number of servers. The supplied map
|
|
definitions will download tiles from http://tile.openstreetmap.org/
|
|
|
|
Map Cache
|
|
---------
|
|
Static maps are cached with other bitmap map images in the
|
|
~/.xastir/map_cache/ directory.
|
|
|
|
Tiles are cached separately to make it possible to share them
|
|
with other applications. By default tiles are cached in
|
|
~/.xastir/map_cache/OSMtiles/, but that location can be changed on a
|
|
by-style basis. The tiles are organized directories by style, zoom
|
|
level, and longitude:
|
|
|
|
~/.xastir/map_cache/OSMtiles/
|
|
+ <style1>/
|
|
| + <zoom>/
|
|
| <longitude>/
|
|
| + [0 ... (2^zoom - 1)].png
|
|
+ <style2>/
|
|
...
|
|
|
|
Note that 'longitude' is a tile number between 0 and (2^zoom -1).
|
|
|
|
Xastir downloads tiles as needed. If Xastir is compiled with
|
|
libcurl support, then it will check for updates to tiles that have
|
|
been cached for 7 days or more.
|
|
See http://wiki.openstreetmap.org/wiki/Tile_usage_policy
|
|
|
|
If a tile can not be downloaded for any reason or if the downloaded
|
|
file is not usable image, then the downloaded file (if any) will be
|
|
deleted and a red area will be shown in it's place on the display.
|
|
|
|
NOTE: Run Xastir at debug level 512 (-v 512) for more information
|
|
on download issues. At debug level 512, corrupt tile files
|
|
will not be deleted. Examining the contents of the corrupt
|
|
files can be informative.
|
|
|
|
If Xastir is compiled with libcurl support, then debug level
|
|
8192 will enable verbose output from libcurl.
|
|
|
|
WARNING: Corrupt tile files will not be deleted when running at
|
|
debug level 512. If you do not delete them manually before
|
|
restarting Xastir, then the first time Xastir displays the
|
|
tile it will be shown in red and then deleted from the
|
|
cache.
|
|
|
|
|
|
Sharing Tiles
|
|
-------------
|
|
The directory structure used to cache tiles is common to other
|
|
programs, though the style names are typically different. An
|
|
example of a program that can share tiles with Xastir is TangoGPS
|
|
(http://www.tangogps.org).
|
|
|
|
Here are some examples of how you can share tiles with TangoGPS
|
|
(the setup for other programs would be similar):
|
|
|
|
1) Setup a symlink at the style level of the caches
|
|
$ cd ~/.xastir/OSMmaps/
|
|
$ ln ~/Maps/<tangoStyleName>/ <xastirStyleName>
|
|
|
|
2) Change the Xastir map definition file to specify the TangoGPS
|
|
cache by changing the following variables (see the next
|
|
section for more information):
|
|
OSM_TILED_MAP-<tangoStyleName>
|
|
TILE_DIR /home/<user>/Maps
|
|
|
|
3) Share all styles and tiles by creating a symlink at the top
|
|
level of the cache. This also requires changing the Xastir
|
|
map definition files to specify the style names used by
|
|
TangoGPS:
|
|
$ cd ~/.xastir
|
|
$ rm -rf OSMmaps/
|
|
$ ln -s ../Maps OSMmaps
|
|
|
|
|
|
Map Definition Files
|
|
--------------------
|
|
OSM map type, style, server, cache directory, and function keys are
|
|
specified in Xastir GEO files. By default the files are located in
|
|
the /usr/local/share/xastir/maps/Online/ directory. The supplied
|
|
definition files have filenames of this form:
|
|
|
|
OSM_<name>.geo - static maps
|
|
OSM_tiled_<name>.geo - tiled maps
|
|
|
|
Where <name> is replaced with the style name. Note that <name> could
|
|
be any unique string and is not required to be the style.
|
|
|
|
Read the comments in the supplied definition files for more
|
|
information.
|
|
|
|
|
|
Copyrights and Licenses
|
|
-----------------------
|
|
Maps and tiles from the OpenStreetMap project are
|
|
Copyright OpenStreetMap and contributors, CC-BY-SA
|
|
|
|
http://www.openstreetmap.org/
|
|
http://creativecommons.org/licenses/by-sa/2.0/
|
|
|
|
TopOSM tiles are a composite of CC-BY-SA and public domain data,
|
|
including MassGIS data. See
|
|
http://wiki.openstreetmap.org/wiki/TopOSM for more information.
|
|
|
|
Changing the Displayed Attribution
|
|
----------------------------------
|
|
|
|
The licenses from OpenStreetMap require attribution that is met,
|
|
in part, by a label shown at the top left corner of the map. Two
|
|
label images have been provided, one shows icons and the other
|
|
shows black text on a white background.
|
|
|
|
You can change between the two label styles by changing a symlink:
|
|
|
|
$ cd /usr/local/share/xastir/maps/ # your installing may differ!
|
|
$ rm CC_OpenStreetMap.png
|
|
$ ln -s CC_OpenStreetMap_txt.png CC_OpenStreetMap.png
|
|
or
|
|
$ ln -S CC_OpenStreetMap_logo.png CC_OpenStreetMap.png
|
|
|
|
|
|
------------------------------------------------------------------------
|