Asking Questions

Q: What is the best place to ask a question on Maperitive?

The best place is Maperitive's Google Group. There are a lot of good people there that are happy to help and answer your questions.

Reporting Bugs

Q: What is the best place to report bugs?

If the bug occurred inside the application, the best way would be to use the Report Bug button, which will open an e-mail message containing the technical information about the bug.

If you notice a strange behavior in Maperitive, you can use the Send Feedback menu or report a bug at Maperitive's User Feedback site.

Suggesting Features

Q: I have a feature X I want to have in Maperitive.

If you have a idea for a feature, there are several ways you can go about it:

Contacting The Author

You can contact me directly via Maperitive's support e-mail (you can access it through the Send Feedback menu in Maperitive) or through my blog.

"I'm a total newbie" questions

My rules are not detected

Q: I started Maperitive and loaded the rules (or changed the existing ones), but I cannot see any difference on the map.

When you start Maperitive, it shows the OSM Web map (the Mapnik layer). The Web map is basically the same thing you see in your browser when you visit OSM's main map site and it consists of static bitmap tiles downloaded from an OSM server. Since these tiles are already pre-generated, you cannot change their styling.

Maperitive rendering rules work on vector data, like OSM and GPX files. So you first need to load a vector file into Maperitive to see the actual rules in action. You can use File | Open Map Sources menu command to open one or more map sources.

After loading, make sure you turn off the Web map layer (you can see the layers list in the bottom right tool window).

General Usage

Setting up internet access through a proxy

See Internet Proxy for more info.


"Anonymous arguments are not allowed here" error

Q: when I enter a command, for example:

set-setting map.decoration.copyright value=false

I keep getting the "anonymous arguments are not allowed here" error message. What's wrong?

Short answer: you need to specify the name of the command argument, in your case you did not specify the name of the first argument. So the correct command would be:

set-setting name=map.decoration.copyright value=false

Long answer: Maperitive commands fall into two basic categories:

  1. Commands with a single argument.
  2. Commands with multiple arguments.

set-setting command has multiple arguments, so Maperitive expects you to name the argument you specify (since some arguments could be optional).

Commands with single argument, on the other hand, are specified without the argument name.

I intend to improve this system in the near future since it causes headaches to a lot of users.

Rendering Rules

How do I write comments?

By putting // at the beginning of the line, like

 // this is a comment

How do I define a relation rule?

By defining a feature which targets relations, for example:

		cycling route : relation[type=route AND route=bicycle]
	target : cycling route

This example is for stuff you want to draw as lines. If you have a relation which is used for areas (I cannot remember any example of this), you would define the feature under the "areas" subsection.

How do I choose which text to display?

By setting the text property to the name of a tag, like:

	text : int_name

By default the text property uses the name tag.

NOTE: In the near future this will be enhanced with tag fallback functionality and with more complex text construction.

Does Maperitive support right-to-left (RTL) scripts?

It does (to a certain extent). See text-direction.

Can I set the word wrapping for texts?

Currently no, but it will be possible soon.

Can I use SVG icons in rendering rules?

Unfortunately .NET lacks any good SVG library for rendering, so the only other option would be to write one from scratch. This means a lot of work, so SVG icons will not be available any time soon.

An alternative option is to convert SVG icons to PNGs and save them in Maperitive Cache/Images directory. Soon I'll add support for loading icons from local disk, too.

Inkscape offers a command-line interface for such a conversion:http://old.nabble.com/convert-pdf-to-svg-from-command-line-td17797689.html

Rendering In General

How do I increase the maximum zoom level?

You can set the maximum zoom level for the map by setting the value to the map.max-zoom setting, example:

 set-setting name=map.max-zoom value=21

sets the maximum zoom level to 21. You may need to restart Maperitive in order for this setting to take the full effect.

NOTE: I do not recommend increasing the maximum zoom level to large values since this can affect the application performance (or it could even cause the application to crash).

How do I render a map without any text labels?

See Painting Stages (under the Techniques section) for an easy way to achieve this.

My OSM map is flooded by the sea

See Rendering Coastlines And Sea for more information about why this happens.

Hypsometric layer together with an OSM layer

Q: Is it possible to have both the Hypsometric layer plus the Web Map layer on at the same time. Currently if I turn on the Web Map layer the Hypsometric is not visible. I have to turn off the Web Map layer to see the Hypsometric one.

Maperitive does not provide an option for this for a simple reason: it would look ugly. The only way to show both layers would be to somehow blend them (since the OSM web map does not provide a transparency for the background). This would mean all OSM stuff would be blended, including text labels, roads etc. and it would be hard to distinguish these features.

Tile generator creates messed up tiles

This probably happens because you turned off the Map decoration layer. This layer draws the background color and without it Maperitive just reuses the existing drawing surface without clearing it first.

Web Maps

Some Web tiles are missing in exports

Q: Sometimes when I export a bitmap which includes a Web map source, some tiles are missing

Maperitive sets a limit of how many Web tiles it holds in the memory at one time. So if you try to export a large bitmap, it then exceeds this limit and cannot show all the tiles needed.

You can increase this limit by setting the value to the webmap.max-loaded-tiles setting, example:

 set-setting name=webmap.max-loaded-tiles value=1000

will allow holding up to 1000 Web tiles in memory.

Exporting To SVG

For all SVG-related questions, please visit the export-svg Command page.

Where is the source code?

Q: I would like to see the source code of Maperitive.

You can't. Maperitive is not an open source application.

Q: But you are using open-source third party libraries!?

All of the third party libraries are properly attributed (see the licenses subdirectory). None of the third party libraries uses GPL (nor any other kind of viral copyleft license that would require the source code to be distributed).

If you think there are some licensing issues with third party licenses, feel free to contact me. I am a strong believer in respecting other people's hard work and I take utmost care of adhering to license terms of third party libraries and tools.

Q: Why is Maperitive not open source?

While I do believe in open source and I've released a number of open source projects, I've decided against it in the case of Maperitive. There are several reasons for this:

Is it really free?

Q: You say Maperitive is free. Is it really free and will it remain free?

Yes, it's free in the sense that you don't have to pay anything for it. My long-term goal is to make Maperitive a first-class product with two or more editions. The basic edition of Maperitive will always be free and it will contain all the functionality needed by amateur cartographers and OSM mappers. For users that require more advanced things for professional work I plan to offer a "pro" edition, which you will have to pay for. But the price should still be negligible compared to prices of similar products.

Q: Why do you need money?

Unfortunately, the development is not free. Good development tools cost money and without such tools there can be no good software. Quality knowledge costs, too - so I continually buy books on cartography, geometry, algorithms, graphics. And beer is not free, either.

I really like developing software like Maperitive and that in itself is a reward for me. An even greater reward is seeing people use it to make beautiful things. However, not being able to make money out of it means I have to do other less interesting stuff to make a living. This is a shame because I have a lot of ideas on how Maperitive can be improved, but my free time is limited. That's why I have to strike a balance between offering good products and making some money out of it. We will see how that goes.

Non-commercial Use

Q: I have an open source project and I want to use Maperitive to do X/Y/Z. Is it possible?

It depends on lot of things: your project's license, your project goals, your willingness to do a lot of homework yourself etc. Please contact me directly and describe your project and what your plans are.

Q: We are a non-profit/humanitarian organization and we need your help in mapping

Feel free to contact me.

Commercial use

Here is are some typical cases of what you are permitted to do with Maperitive:

And here are some scenarios which Maperitive's license prohibits:

If in doubt about your usage case, please contact me.

Commercial Licensing And Support

Q: I want to include Maperitive as a library and use its X/Y/Z feature for commercial purposes. Is it possible?

The general answer is: yes, it is possible. A lot of it depends on your exact usage case, so it is best to contact me directly and we will discuss it further.

Q: Can I expect the library documentation in that case?

I see no point in releasing a library without the documentation. The extensiveness of the documentation depends on your particular usage case.

Q: I'm using Maperitive for commercial purposes and I need help / feature X.

If you are using Maperitive according to the license described above, feel free to contact me and we will discuss your needs and problems. If you need help for commercial purposes and you're in a hurry, please indicate this in your e-mail.

Custom Work And Consulting

Q: Do you do custom cartography work (like maps, styles, etc)?

Yes, I do. Please contact me for more informatiom.


Contributing Code

Q: I want to contribute some work/code to Maperitive. Is this possible?

Although I'm very grateful to anyone wishing to contribute its own time and effort to Maperitive, I have to respectfully decline (at least at this stage of the development). See the above section about licensing and open source for reasons why.

Contributing Documentation

Q: Maperitive's documentation is poor, a lot of it missing. I want to contribute by writing documentation.

Maperitive's documentation is written in wiki text (not Web wiki) which is part of the source code. It gets compiled and generated during the building phase of the project (and then FTP-ed as HTML files to the Web server). Wiki text is used just for simplicity - beats writing HTML. So the documentation is not in a form that can be freely edited by multiple people, it's just a an electronic book (of sorts) written in a simple format.

This one of the reasons why contributing directly to the Maperitive Documentation would be impractical. Also, the functionality changes so often that in this phase of the project I don't see it very practical to write a full and extensive documentation. I guess the quality (and quantity) of the docs will grow as the project grows.

You are, however, welcome to contribute, for example, by writing docs & tutorials on the OSM Wiki pages.