Subversion Repositories mkgmap

== The mkgmap TYP file compiler ==

This document describes the format that is understood by the mkgmap TYP compiler.
It contains everything you need to write a TYP file description that can be compiled, showing exactly how
you can get the different colour effects that are available.

The file can be in written in almost any character-set that allows basic ascii characters and can have Strings for any language that can be encoded in that character-set.
The mkgmap .txt TYP processor looks at the start of the file for a unicode BOM or a header line of the form:
 ; -*- coding: charset -*-

to determine the encoding, and then will convert those Strings that can be represented in the target .IMG code-page and ignore the ones that can't.

It is safest to edit multi-lingual TYP files (eg. resources/mapnik.txt) with a good text editor;
if nessessary, using a graphical editor to manipulate the icons, then cutting the result back into the TYP .txt file.

For your own TYP file it might be convenient to use one of the graphical editors that are available.
However, beware that some of these editors don't preserve the full contents of the file
and might change the character representations of the Strings to those in a different character
set/encoding.
Also they make assumptions about the chars used to represent colours in icons and might change them.

These produce file formats that differ from each other and have variations to the specification that is presented here.  These variations will be supported as they are discovered as long as they do not conflict with each other, but are not listed here for clarity. In particular the files produced by [http://www.pinns.co.uk/osm/ostyp.html TYPWiz] and [https://sites.google.com/site/sherco40/ TYPViewer] are supported.

== The [_id] section ==

;FID=#
: The family id.
;ProductCode=#
: The product code within a family, usually just left as one.
;CodePage=#
: The code page to use for writing the labels.

Example:
 [_id]
 FID=1299
 ProductCode=1
 CodePage=1252
 [end]

== The [_drawOrder] section ==
This is a list of polygon types and level numbers. Polygons with a higher
level number are drawn on top of those with a lower one.

There is only one tag that is valid in this section.

;Type=object_type,level
:The object_type is the polygon type such as 0x07 or an extended type such as 0x10208
:The level is a number starting at 1.

Example:
 [_drawOrder]
 Type=0x032,1
 Type=0x10101,2
 Type=0x002,3
 Type=0x003,3
 Type=0x007,3
 Type=0x009,3
 Type=0x00c,3
 Type=0x00e,3
 Type=0x010,3
 Type=0x012,3
 Type=0x015,3
 Type=0x01b,3
 ...
 [end]

If a polygon type is not listed in this section, then it will not be displayed at all. If it is then it will be styled according to a definition in a [_polygon] section later in this file, or in the default Garmin style if these is no such definition.

== Element sections ==
The main part of the file consists of descriptions of how elements are to be displayed so that you can change the colours and style of the displayed elements.

Each style definition starts with the name of the section in square brackets and ends with the line "[end]". For example:
 [_polygon]
 Type=0x02
 String1=0x04,Residential
 String2=0x01,Résidentiel
 String3=0x03,Bebouwde kom
 ExtendedLabels=Y
 FontStyle=NoLabel
 Xpm="0 0 2 0"
 "! c #DCDCDC"
 "  c none"
 [end]

 [_line]
 Type=0x22
 ; options to style the line
 [end]

 [_point]
 Type=0x52
 ; options to style the POI
 [end]

You have one of these for each polygon, line of POI you want to change from the built in Garmin style.

== Common options for element sections ==

These options will work in all the element sections [_point], [_line] and [_polygon].

;Type=object_type
:The object type number - the kind of element that it is. If the number is greater than 0xff then it will be treated as a type and subtype combination. Eg 0x2305 is type 0x23 with subtype 0x5.

;String=#,xxx
;String=xxx
:Defines a label that will be attached to the element.
The (optional) first part is a language number, the next is the actual string.
You can use String1, String2 for compatibility, but just String will do for the mkgmap compiler.
  String=Parking Lot
  String=0x04,Parking
  String=0x03,Parkeerplaats
:If the language number isn't specified it defaults to 0x00 which is the generic language.
This string is used if there isn't a definition for the currently selected language;
If there isn't a default the device shows the first string in the list.
The language numbers are defined [https://wiki.openstreetmap.org/wiki/Mkgmap/help/typ_compile#Appendix here].

;FontStyle=xxx
: xxx can be one of NoLabel, SmallFont, NormalFont, LargeFont.

;DayCustomColor=#colour
: The colour used for the font when the GPS unit is displaying day colours.

;NightCustomColor=#colour
: The colour used when the GPS unit is displaying night colours.

== XPM format ==
The XPM format is a fairly widely used format for small image icons, so you
can read about it [http://en.wikipedia.org/wiki/X_PixMap elsewhere].
You would normally use some tool to create the image and copy it in,
but it is possible to create them by hand.
This is a brief summary of what it all means based on the following example:
 Xpm="10 5 3 1"
 "r  c #ff0000"
 "g  c #00ff00"
 "b  c #0000ff"
 "rrrrrrrrrr"
 "rrrrrrrrrr"
 "rbbbbbgggr"
 "rbbbrggggr"
 "rbbrrrrrrr"
 "rrrrrrrrrr"

Working from the top, the first line consists of four numbers that mean
in order: the pixmap has a width of 10 and a height of 5; there are 3
different colours and each colour is represented by 1 character.

There then follows the three lines giving the colours to use. The first character(s) are a short name for the colour, in this case there is one character (r, g, b) because the last field in the first line was 1. Next is the letter 'c' which can be ignored, and the follows the normal RGB representation of the colour. In this case I have chosen red to be represented by the letter r, g for green and b for blue, but you can use any characters or colours you choose.  A space is allowed, and it is traditional to use a space for the background colour.

Then there is the pixmap itself, it is 10 columns wide and 5 lines to match the width and height values in the first line.  If the number of characters representing each pixel was 2 say, then there would be 10 groups of 2 characters across. Each letter represents one pixel of the final image, in this example, the top of the icon would be a red line and in the middle there would be some blue and green.

== Polygon elements ==
A [_polygon] section can have any of the common tags.

It must also contain an Xpm tag. This uses a modified form of the XPM format, see the XPM section for details about the format that are common between all the element types. The following notes only refer to how it is used within the polygon section.

* A single solid colour, that is the same in day and night displays
 Xpm="0 0 1 0"
 "a   c #778899"

* One solid colour that is used in the day display mode and another that is used in the night display mode.
 Xpm="0 0 2 0"
 "a   c #778899"
 "b   c #223322"

* A pixmap that has the same solid colours in day and night modes. The pixmap must be 32x32 and have two colours.
 Xpm="32 32 2 1"
 "a   c #778899"
 "b   c #223322"
 "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
 "aaaaaaaaaaaaabbbbbbbaaaaaaaaaaaa"
 "aaaaaaaaaaabbbbbbbbbbbaaaaaaaaaa"
 ; ... 32 rows in total

* The pixmap can have a transparent background, in which case the second colour will be given as 'none'
 Xpm="32 32 2 1"
 "a   c #778899"
 "b   c none"
 "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
 "aaaaaaaaaaaaabbbbbbbaaaaaaaaaaaa"
 "aaaaaaaaaaabbbbbbbbbbbaaaaaaaaaa"
 ; ... 32 rows in total

* If you want to have different colours for the day and night modes, then use 4 colours. As before the second and fourth colours can be 'none' to indicate that the background is transparent for the day and/or night colour respectively. In the example the night colour has a transparent background and the day version does not. When you draw the pixmap you only use the day colours, the device will automatically switch to the alternate colours when in night mode. It is traditional to use '3' and '4' for the night colour tags in the XPM, but with mkgmap you can use whatever you like.
 Xpm="32 32 4 1"
 "a   c #778899"
 "b   c #221133"
 "3   c #112233"
 "4   c none"
 "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
 "aaaaaaaaaaaaabbbbbbbaaaaaaaaaaaa"
 "aaaaaaaaaaabbbbbbbbbbbaaaaaaaaaa"
 ; ... 32 rows in total

== Line elements ==
A line section can contain any of the common tags. It can also have the following additional tags

;LineWidth=#
:The line width in pixels. This is the width, excluding borders if there are any. This is only used if there is not a pixmap.
;BorderWidth=#
:The border width. The line will be drawn (on devices that support this) with a border at each edge of the line. It is only used if there is no pixmap. If there should not be a border then it can be omitted or set to zero.
;UseOrientation=(Y|N)
:If Y then the pixmap is rotated so that is always following the direction of the road.
 LineWidth=2
 BorderWidth=2
 UseOrientation=Y

As with polygons there is an Xpm tag too and it can specify that solid colours should be used or that there is a bitmap.

If there is a bitmap then it is always has a width of 32, its height will be the width of the line (yes that sound confusing the first time you read it, it just means that the line is written horizontally in the pixmap). The colours work in exactly the same way as they do for polygons, so see the examples there for the different possibilities with day/night and transparent colours. An example with a pixmap, which shows a line that will have a thickness of 3. 
 Xpm="32 3 4 1"
 "a  c #550088"
 ".  c #889988"
 "3  c #889988"
 "4  c #889955"
 "aaaaaaaaaaaaaaaaaaaaaaaaa....aaa"
 "aaaaaa................aaaaaaaaaa"
 "aaaaaaaaaaaaaaaaaaaaaaaaa....aaa"

When there is no pixmap then the LineWidth and BorderWidth options come into play. The following combinations are recognised by mkgmap.

* Solid line, no border. Same colour day and night.
 LineWidth=2
 Xpm="0 0 1 0"
 "a  c #989898"

* Solid line, no border. Different colour for day and night.
 LineWidth=2
 Xpm="0 0 2 0"
 "a  c #989898"
 "b  c #228844"

* Solid line, border width 1, same colour day/night.  The second colour is the border colour, the first the main line colour.
 LineWidth=2
 BorderWidth=1
 Xpm="0 0 2 0"
 "a  c #989898"
 "b  c #345544"

* Solid line, border of 1, different day/night colours
 LineWidth=2
 BorderWidth=1
 Xpm="0 0 4 0"
 "a  c #989898"
 "b  c #345544"
 "3  c #119811"
 "4  c #3499ee"

== Points (POI) ==
A point can have any of the common tags and in addition can have the following two tags to specify the icon to be used in day and/or night modes.

;DayXpm
:The XPM to be used as the only or when the display is showing day-time colours.
;NightXpm
:This is optional and if given is an alternative XPM to use when showing night-time colours. It must have the same width and height as the DayXpm, but everything else about it can be different.

Only the DayXpm will be explained, the NightXpm is exactly the same, except that it is constrained to have the same width and height as the DayXpm.

Unlike lines and polygons which are simple two colour bitmaps, points can have many colours and partial transparency.
There are several colour modes, mkgmap will automatically determine which you need without having to specify it separately. Each POI can have different colours, transparency schemes and sizes.
* Up to 255 solid pixel colours
* Up to 254 solid pixel colours with an additional transparent pixel.
* Up to 255 pixel colours which can each have a different transparency value.  
* Up to 16 million different colours, no transparency
* Up to 16 million different colours, one transparent pixel.

Here are example of the input and the effect that is achieved.
* A 10x5 icon with 5 solid colours
 DayXpm="10 5 5 1"
 "a  c #112211"
 ".  c #1e2291"
 "/  c #1ef291"
 "@  c #1eff91"
 "?  c #11ff11"
 "aaaaaaaaaa"
 "a...aa//??"
 "aaaaa@@//a"
 "aaa.....aa"
 "aaaaaaaaaa"

* A 10x5 icon with 4 solid colours and a transparent pixel
 DayXpm="10 5 5 1"
 ".  c #1e2291"
 "/  c #1ef291"
 "@  c #1eff91"
 "?  c #11ff11"
 "a  c none"
 "aaaaaaaaaa"
 "a...aa//??"
 "aaaaa@@//a"
 "aaa.....aa"
 "aaaaaaaaaa"

* Icon 10x5 with variable transparency on each colour. This is represented in the normal way by adding an extra alpha value to the end of the RGB colour value. The value 00 is completely transparent and FF is completely opaque. Since the TYP format only has 15 different levels of transparency, you should restrict to using the values [11, 22, 33, ... EE, FF]. However you can use any value and it will be rounded to the nearest supported value.
 DayXpm="10 5 5 1"
 ".  c #1e2291"
 "/  c #1ef291"
 "@  c #1eff91dd"
 "?  c #11ff1188"
 "a  c #00000000"
 "aaaaaaaaaa"
 "a...aa//??"
 "aaaaa@@//a"
 "aaa.....aa"
 "aaaaaaaaaa"
the first two colours are completely solid (if the alpha value is omitted it defaults to FF as usual), the third is slightly transparent, down to the last which is completely transparent.
<p>
An alternate notation is supported where the transparency value is appended to the line in the form "alpha=13", this is a transparency value that goes from 0 to 15, with 15 being completely transparent. As such it works the opposite way to the alpha value of the normal RGBa values in the previous example. The required conversions are made by mkgmap which ever one you use.

* Image with up to 16 million different colours.
By setting the number of colours in the XPM to zero you can specify a
different kind of image, where the colour for each pixel is specified
separately.

Example
 IconXpm="10 10 0 0"
 "#990088"
 "#990088"
 "#990067"
 " ... and so on for 100 different values ..."
 
If you prefer you can place several pixel values on the same line, as
long as there are the correct number altogether.
 IconXpm="10 10 0 0"
 "#990088 #990088 #990067"
 " ... and so on for 100 different values ..."

The spaces can be omitted for the most compact representation.
It is also possible to have a transparent pixel with this format, but there is currently not a way to represent this.

== Icons ==
An [_icons] section holds a set of images at different resolutions. The images are intended to be of the same logo or icon at a range of different sizes to suit different resolution devices.

Only a few tags are valid in this section.

* The <code>Type</code> tag is required. It identifies the point type that this image set will be used for.
* The <code>String</code> tag is also allowed, but it does not take a language code at the beginning. Therefore there can only be one of them.

The other tag that can be present is IconXpm.
There can be several of these tags, each one is a different
resolution/size. Each one can have a different size, colour mode, and
number of colours.
The appropriate version is selected according the capabilities of the
device it is being displayed on.

The format of the IconXpm tags has the same possibilities as in the _point sections.