forked from Xastir/Xastir
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.OSM_maps
214 lines (164 loc) · 8.49 KB
/
README.OSM_maps
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
Copyright (C) 2000-2023 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, nine (9)
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/
in addition, tiles from CloudMade are
Copyright CloudMade, CC-BY-SA
http://www.cloudmade.com/
http://cloudmade.com/about/api-terms-and-conditions
http://cloudmade.com/terms_conditions
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 and CloudMade 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
------------------------------------------------------------------------