Kosmos/v1.x

From OpenStreetMap Wiki
Jump to navigation Jump to search
Caution
 Kosmos is no longer actively maintained, since it has been replaced by a new tool called Maperitive. The new tool is much more flexible and powerful, so the author recommends switching to it.
Example of a Kosmos map using relief contours

What Is Kosmos?

Kosmos is a new lightweight OSM map rendering platform developed by Igor Brejc (User:Breki). It was primarily designed to be used by OSM users on their own computers to:

  • Render OSM maps interactively
  • Print OSM maps
  • Set up a local tile map server
  • Use their own Map rendering rules or share rules stored in OSM Wiki pages.

These are the main differences between Kosmos and Mapnik and Osmarender. Kosmos was designed to be as simple to set up as possible, without losing much of rendering capabilities.

There are some examples of output images in Category:Kosmos and people are sharing their rendering rules in Category:Kosmos rules

What Kosmos Is NOT

It is not a replacement for Mapnik or Osmarender. Kosmos currently does not use a database to store OSM data. Instead it opens OSM files and loads them directly into memory. That means that there is a limit of how large a map area Kosmos can work with.

Kosmos rendering rules are much simpler than those of Mapnik and Osmarender. On one hand, this enables easy creation and maintenance, but on the other hand it is not as flexible as XSLT transformations to SVG used by Osmarender, for example.

Kosmos uses Microsoft.NET GDI+ library for drawing maps, which directly provides only a subset of graphics capabilities compared to those of SVG. That means that certain graphics features are currently not available to use in Kosmos map rendering. Hopefully this will improve with time.

Download And Installation

Kosmos GUI showing the sample map

The primary platform for Kosmos is Windows. You need to have Microsoft .NET 2.0 (available here) installed on your computer in order to run Kosmos.

Kosmos can run on Linux and Mac OS systems if you have the latest version of Mono installed. There are some problems, however, since Mono does not support all of the features of .NET Framework. Also, the quality of rendering using Mono is not so good compared to the Windows platform. Hopefully this will be improved in the future.

The following procedure describes how to set up Kosmos to show a sample OSM map:

  1. Download the latest Kosmos version from http://igorbrejc.net/kosmoshome
  2. Extract the ZIP archive somewhere
  3. Run Kosmos GUI application (Kosmos.Gui.exe)
  4. Select File | Open Project... menu and browse to Samples/SampleProject.xml file
  5. A sample map of Dutch island of Texel should be displayed in Kosmos (see image)

How To Use

Kosmos uses OSM XML files as the source for map data. These files can be obtained by various means, most typically by using JOSM to download map data from the OSM server and then saving the data into an OSM XML file.

Kosmos can be used both for interactive mapping and as a HTTP tile map server. In both cases you need to have a Kosmos project file defined which tells Kosmos which OSM files to use, which rendering rules to apply and some other things.

First steps to create your own map:

1. Open the desired area in JOSM.
2. Save the area as MyMap.osm (or with a filename of your choice) to the Kosmos/Samples folder.
3. Open the file "SampleProject.xml" with a text editor and enter the name of your area-file in the following line: (now there is MyMap.osm). 

...
    <OsmFiles>
        <!-- here you enter a list of OSM files which you want to render-->
        <File>MyMap.osm</File>
    </OsmFiles>
...


4. Save the file.
5. Open Kosmos.Gui.exe
6. Go to menu "File" and "Open file" in the upper left corner. Open the file "SampleProject.xml".
7. Your area should now appear. If an error message appears, perhaps you should try to save a smaller area in JOSM.

Interactive Mapping

Interactive mapping is done using the Kosmos.Gui. When you run it, you can open a Kosmos project file and the application will load OSM data and rendering rules and it will show the map.

Main features:

  • Generating shaded relief rasters for the area currently shown on the map.
  • Printing the currently displayed map onto paper
  • Geographical grid.
  • Showing of unused ways and nodes.
  • Exporting the current map view to a bitmap

NOTE: If you add the path to the project file in the command line, Kosmos will load it automatically when it starts.

Keyboard Shortcuts

TODO

Generating Relief

Kosmos.Gui application is able to automatically download SRTM3 digital elevation model (DEM) from the NASA FTP site. It can then use this DEM to generate 3 different types of rasters for the area currently shown on the map:

  1. Standard (GRASS GID-like) shaded relief
  2. Shaded relief using my own algorithm: it is less color intensive, especially for plains, but lacks the high contrast of the standard method. Try it and see if you like it.
  3. Slope shading

The first time you generate the relief for a certain area it may take some time for Kosmos.Gui to download the DEM tiles. Once they are downloaded, Kosmos.Gui stores them into a local cache (Srtm subdirectory) and they do not need to be downloaded again.

NOTE: SRTM3 data has voids, so the relief might not look very nice for some areas. Void-filling algorithm (or support for already void-filled data) is planned for a future release of Kosmos.

Printing Maps

You can print the currently displayed map using the File | Print Map... menu item which opens Print Map dialog. Meaning of fields / buttons:

  • Map zoom factor: effectively a map scale to use when printing. Corresponds to the zoom factor of the main map view.
  • Overlap: how much of the map will be duplicated between neighbouring pages (in 1/100 of an inch). This is useful if you want to create a poster map by gluing pages together. Setting overlap value to anything larger than 0 eliminates any white stripes when cutting edges of papers. On the other hand this increases the number of pages needed to print the map using the same scale.
  • Pages columns / rows / Total pages: how many pages are needed to print the map using the current print settings.
  • Page Setup: here you set up page orientation, margins and related stuff.
  • Print...: opens up a system printing dialog where you can select the printer and start the actual printing.
  • Close: closes the map printing dialog
  • Preview / Refresh: displays / refreshes the map printing preview. The preview is only available if the total number of pages is not greater than 50.
  • Preview zoom: zoom to use in the preview.

By default the whole map area will be printed. If you want to print just a portion of the area, select the View|Show Print Area menu option and click on the blue rectangle to select it. You can reposition the rectangle by moving its corners. Also, you print the currently displayed part of the map by selecting the Print Area|Use Current View menu option.

Exporting To PDF

Instead of printing directly onto paper, you can export the map into a PDF file. This is not implemented directly by Kosmos. Instead, install some PDF printer driver (I tried this free one) and print to that driver. The driver should then save the PDF file on the disk.

Tile Map Server

Kosmos is able to run as a tile map service similar to OpenStreetMap slippymap. This can be achieved using the Kosmos Console command line program.

Generating Map Tiles

You first need to generate map tiles. This is done using the tilegen command: 

Kosmos.Console.exe tilegen Samples\SampleProject.xml

This command will generate tiles for the sample project, from the zoom level 0 to the zoom level 17. The tiles will be stored in the Tiles subdirectory.

Serving The Map

After you've created tiles, you can start the HTTP server using the tileserv command: 

Kosmos.Console.exe tileserv Samples\SampleProject.xml

Now you can go to your browser and go to URL http://localhost/Kosmos and you should see a slippymap with the sample map.

NOTE: You can of course generate tiles even while running the HTTP server, just open a separate command line console. Some browsers may need refreshing of page to detect new versions of tiles.

Serving Your Own Maps

The procedure described works with the sample map which comes together with Kosmos. If you want to serve your own maps, see instructions on editing Kosmos project files.

Kosmos Project File

Kosmos project file is an XML configuration file used by Kosmos. The supported node are as follows:

Node Description Required?
OsmFiles/File Physical path to an OSM XML file (can be more than one). You can include zipped OSM files (bz2 and gzip) yes
RulesSource/WikiPage Either a physical path or an OSM Wiki URL to the rendering rules which will be used for rendering the map. Only a single rules source is currently supported yes
TileMapService/TileStorageRootDir Tells Kosmos where to put tiles onto disk when generating them and where to find them when running the tile map service no, default is Tiles subdirectory
TileMapService/TileServerUrl URL which the Kosmos tile map service will run under no, default is http://localhost/Kosmos/
TileMapService/MinTilesZoomLevel At what zoom level Kosmos should start generating tiles no, default is zoom level 0
TileMapService/MaxTilesZoomLevel At what zoom level Kosmos should end generating tiles no, default is zoom level 17

Sample

Here is an example of the project file: 

<KosmosProject>
    <OsmFiles>
        <!-- here you enter a list of OSM files which you want to render-->
        <File>Samples\SampleMap.osm</File>
        <!--<File>path to the OSM file</File>-->
    </OsmFiles>
    <RulesSource>
        <!-- here you enter either a path or an URL to the rendering rules -->
        <!-- NOTE: only one rendering rules source is supported (for now) -->
        <WikiPage>Samples\RenderingRules.txt</WikiPage>
        <!--<WikiPage>https://wiki.openstreetmap.org/index.php?title=KosmosStandardRules</WikiPage>-->
    </RulesSource>

    <TileMapService>
        <!-- you need TileMapService settings only if you want to generate tiles 
        and/or run the tile map service -->
        
        <TileStorageRootDir>Tiles</TileStorageRootDir> <!-- tells Kosmos where to put tiles onto disk -->
        <TileServerUrl>http://localhost/Kosmos</TileServerUrl> <!-- the URL of the tile server -->
        <MinTilesZoomLevel>0</MinTilesZoomLevel> <!-- minimum zoom level when generating tiles (default: 0) -->
        <MaxTilesZoomLevel>17</MaxTilesZoomLevel> <!-- maximum zoom level when generating tiles (default: 17) -->
    </TileMapService>
</KosmosProject>

Rendering Rules

One of the most interesting features of Kosmos is the ability of users to define how maps should be rendered by writing definitions in OpenStreetMap Wiki pages. One example of such a page is KosmosStandardRules page, which is intended to contain rules for rendering standard maps.

Editing Kosmos rendering rules is described on the Kosmos Rendering Help page.

Reporting Bugs

Kosmos is currently in beta phase and is being continually improved. If you discover any bug, please report it under the Talk:Kosmos or Kosmos knowledge base page. Thanks!

Release History

Version 1.12 (23.02.2008)

Version 1.10 (10.02.2008)

Version 1.9 (27.01.2008)

  • Printing maps
  • OSM objects inspection tool
  • Kosmos now understands OSM relations
  • Blog post

Version 1.8 (19.01.2008)

  • Support for more than one template per rendering rule
  • New TextLineOffset parameter for Text template
  • Symbol template can now be used for ways or areas too
  • Blog post

Version 1.7 (17.01.2008)

Version 1.6 (15.01.2008)

  • Now you can see ways and/or nodes which haven’t been covered by the rendering rules.
  • Limited support for color-filling sea - works only for islands
  • Blog post

Version 1.5 (13.01.2008)

Version 1.4 (12.01.2008)

  • Mostly a bugfix release
  • You can now have multiple rasters displayed in Kosmos.GUI
  • Reduced raster projection errors for large areas
  • BUGFIX: the Kosmos.Gui crashed if the relief area was too big.
  • BUGFIX: solved "Collection was modified; enumeration operation may not execute" problem with thread synchronization

Version 1.3 (10.01.2008)

  • Added relief shading tools in Kosmos.Gui
  • Kosmos.Gui can now optionally show geographical grid.
  • Implemented map moving using cursor keys.
  • Added JOSM-style keyboard shortcut '1' for zoom-all.
  • Implemented drawing symbols along polylines (not yet fully functional)
  • BUGFIX: improved handling of wikipage URLs in Kosmos projects.

Version 1.2 (05.01.2008)

  • Fixed "upside down" street names rendering
  • Improved error handling for HTTP tile map server
  • Added setting of default credentials for HTTP proxy - I don't know if this fixes the problem with proxy authorization
  • Mouse wheel zoom now centers on the area pointed by the mouse arrow.
  • Small speedings up of text rendering

Version 1.1 (04.01.2008)

  • Implemented rendering area texts
  • Implemented local file system caching of downloaded icons

Version 1.0 (03.01.2008)

  • First (beta) version
  • Fixed 'file not found' problems when running on Windows XP

Links

Retrieved from "https://wiki.openstreetmap.org/w/index.php?title=Kosmos/v1.x&oldid=2084005"