forked from Xastir/Xastir
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.OSM_maps
216 lines (164 loc) · 8.41 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
215
216
$Id: $
Copyright (C) 2012 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.
Tiles have become the standard for bitmap map images. Their small
size allows for short download times and easy reuse. Tiles are the
basis of the 'slippy map' implementations on web sites,
applications, and portable devices. Note that Xastir is not a
'slippy map' application and map motions and refresh times are not
as smooth or quick as you can find in other applications (Xastir's
strengths lie in other areas).
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 does not equate to one of the 18 OSM zoom
levels, 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 retreived from a number of servers. The supplied map
definitions will download tiles from:
http://tile.openstreetmap.org/
http://tah.openstreetmap.org/Tiles/tile/
http://tiles.openpistemap.org/tiles/contours/
http://andy.sandbox.cloudmade.com/tiles/cycle/
The CloudMade tiles are also available, but a user account and a key
are required. Register at http://www.cloudmade.com/ and then create
new OSM map definition files (GEO) by copying an existing file and
changing the URL variable. The CloudMade tile URLs have this form:
http://tile.cloudmade.com/<key>/<style#>/256/
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
------------------------------------------------------------------------