
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 TYPWiz[1] and
TYPViewer[2] are supported.
--
[1] http://www.pinns.co.uk/osm/ostyp.html
[2] https://sites.google.com/site/sherco40/

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 here[3].

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 elsewhere[4]. 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:
--
[3] https://wiki.openstreetmap.org/wiki/Mkgmap/help/typ_compile#Appendix
[4] http://en.wikipedia.org/wiki/X_PixMap

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.
  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 Type tag is required. It identifies the point type that this image set will
  be used for.
* The String 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.
