From Navit's Wiki
Revision as of 13:57, 11 April 2010 by Mvglasow (talk | contribs) (command)
Jump to: navigation, search

The On Screen Display (OSD) provides status information and controls blended directly onto the map. These can be implemented using the <osd ... /> tag inside navit.xml. Example layouts can be found at OSD_Layouts.


An osd item can be enabled/disabled using the following:

   <osd enabled="yes" />
   <osd enabled="no"  />


An osd item can have configuration flags using the following:

   <osd osd_configuration="1" />

The osd will only be visible if the value of osd_configuration from the navit tag bitwise ANDed with the value of osd_configuration of the osd is not zero. So you can have up to 32 dynamically changeable osd layouts. Don't overuse this feature, since a non-visible osd will still consume memory and cpu cycles.


An osd item can contain a command like in the following:

   <osd command="osd_configuration=2" />

Use it to associate a function call or attribute setting that will be associated when the item is clicked.

Available commands are:

  • announcer_toggle() FIXME: to be completed
  • gui.fullscreen Use gui.fullscreen=!gui.fullscreen to toggle between window and fullscreen mode.
  • gui.menu() Bring up the menu.
  • gui.get_data() FIXME: to be completed
  • osd_configuration Set the osd_configuration flags for navit. With the command osd_configuration=2 all osds where the condition (osd_configuration & 2) != 0 is true will get visible, all others non-visible.
  • say() Use to produce speech output. FIXME: how?
  • set_center_cursor() FIXME: to be completed
  • speech.active Use speech.active!=speech.active to enable or disable spoken directions.
  • zoom_in() Zoom into the map (dividing the current zoom level by 2).
  • zoom_out() Zoom out of the map (multiplying the current zoom level by 2).
  • zoom_to_route() Zoom the entire route into view


The position of an element is specified in x and y pixels from the top-left hand corner of the screen. Negative values will position the element with respect to the bottom-right hand corner of the screen.

For example:

   <osd enabled="yes" x="0"   y="0"   />
   <osd enabled="yes" x="10"  y="10"  />
   <osd enabled="yes" x="-10" y="-10" />
   <osd enabled="yes" x="10"  y="-10" />
  • The first osd item is placed in the top left hand corner of the screen.
  • The second osd item is placed 10 pixels right from the left-hand-side of the screen and 10 pixels down from the top of the screen (i.e. top left of the screen).
  • The third osd item is placed 10 pixels left from the right-hand-side of the screen and 10 pixels up from the bottom of the screen (i.e. bottom right of the screen).
  • The fourth osd item is placed 10 pixels right from the left-hand-side of the screen and 10 pixels up from the bottom of the screen (i.e. bottom left of the screen).


The sizes of each item can be explicitly set in pixels using the 'w[idth]' and 'h[eight]' attributes.

For example:

   <osd enabled="yes" x="0" y="0" w="100" h="50" />

This will create an item of width 100 and height 50 pixels from the top-left corner of the item. The top-left corner of the item is also the point which is used when positioning the item using the 'x' and 'y' attributes.

Example navit.xml contents, based on osd items mentioned so far:

   <osd type="text" osd_configuration="1" w="100" h="50" x="-100" y="0" label="${vehicle.position_speed[named]}" font_size="350" command="osd_configuration=2"/>
   <osd type="text" osd_configuration="2" w="400" h="100" x="-400" y="0" label="${vehicle.position_speed[named]}" font_size="1200" command="osd_configuration=1"/>

The first osd is the small one, if you click on it, the second one (large) will get visible. If you click on the large one, you will get the small one back.


Certain osd items may be aligned. For example, text may be aligned centrally within an item. Alignment is specified using:

   <osd enabled="yes" x="0" y="0" w="100" h="50" align="ALIGN_NUMBER"/>

Where the alignment number can be any of the following:

  • "1": Align to the top
  • "2": Align to the bottom
  • "0" or "3": Align to the center (vertical)
  • "4": Align to the left
  • "8": Align to the right
  • "0" or "12": Align to the center (horizontal)

To get a combination of alignment you have to sum vertical and horizontal alignment, so align="5" would give top left alignment.

Background Color

The osd item's background color can be changed using the 'background_color' attribute. For example:

   <osd enabled="yes" x="0" y="0" w="100" h="50" align="0" background_color="#000000c8" />

The color is specified in standard 6-figure hexadecimal, with the last two figures specifying amount of transparency/opacity (FF = fully transparent, 99 = fully opaque). The above color is a translucent black.

As can be seen, the previous attributes can be combined to create a filled box of particular dimensions and in a particular position. However, a box is useless without content, which is where the 'type' attribute comes in.


An osd type is implemented using:

   <osd enabled="yes" x="10" y="10" type="OSD_TYPE" />

Current OSD types (from navit/osd/core/osd_core.c):

For example:

   <osd enabled="yes" x="10" y="10" type="compass" />
   <osd enabled="yes" x="10" y="10" type="gps_status" />
   <osd enabled="yes" x="10" y="10" type="text" />
   <osd enabled="yes" x="10" y="10" type="scale" />

You can determine the supported xml options for each OSD type by reading navit/osd/core/osd_core.c, searching for "attr_xxx" inside the osd_xxx_new() functions. Most types have at least an "x" and "y" option that determine the location of their OSD.


The button type creates a placeholder in which a specified image is clickable; this is usually accompanied by a command.

Example navit.xml contents:

   <osd enabled="yes" type="button" x="48"  y="48"  command="gui.fullscreen=!gui.fullscreen" src="toggle_fullscreen.xpm" />
   <osd enabled="yes" type="button" x="-96" y="48"  command="gui.menu()"                     src="menu.xpm" />
   <osd enabled="yes" type="button" x="-96" y="-96" command="zoom_in()"                      src="zoom_in.xpm" />
   <osd enabled="yes" type="button" x="48"  y="-96" command="zoom_out()"                     src="zoom_out.xpm" />

The button type is useful when using gui_internal, as it could provide zoom in/out functionality. gui_internal does not draw any controls onto the map view, so unless you have a scroll wheel the zoom in/out functionality will be missing.


This creates a compass containing a white arrow, pointing north (whenever a GPS signal is available). In routing mode, the compass shows a second green arrow, indicating the direction to the destination, and the direct distance to the destination. Example:

   <osd enabled="yes" type="compass" font_size="150" x="-68" y="-58" w="36" h="45"/>


This shows a bar indicating the GPS signal strength. Example:

   <osd enabled="yes" type="gps_status" x="-32" y="-58"/>


This osd item displays an image of the next turn which the vehicle will have to undertake. Nothing is displayed if routing is not on (i.e when just using navit for GPS instead of sat-nav).

An example use is:

   <osd enabled="yes" type="navigation_next_turn" x="0" y="-75" />


The 'scale' type overlays a simple ruler and scale on the current map. This updates as you zoom in or out. For example:

   <osd enabled="yes" x="0" y="-84" w="240" h="26" font_size="150" type="scale"/>


The text type is useful for displaying static text, current GPS data, routing information or status information on the map view (viewable in the status bar in GTK mode). This is implemented in the following manner:

   <osd enabled="yes" type="text" label="${GPS_OR_ROUTE_DATA}" x="-200" y="0" />

The label attribute can hold any combination of static text and variables.

When using the text type, it is useful to set the width and height of each item, in addition to aligning the text using the 'align' attribute.

Variables are specified as ${variable}. Variables which can be used in labels include:

Variable Value
navigation Routing information, available only when routing
navigation.item Information related to the entire route
navigation.item.destination_length[named] Remaining distance to destination. Use navigation.item.destination_length[value] to get the bare value (without units) or navigation.item.destination_length[unit] to get just the unit. Useful for displaying the value and the unit in two rows, or in different font sizes.
navigation.item.destination_time[arrival] Estimated time of arrival
navigation.item.destination_time[remaining] Estimated remaining time
navigation.item.street_name Name of the road which the vehicle is currently on
navigation.item.street_name_systematic Name of the road which the vehicle is currently on
navigation.item[1] Information related to the next navigation item (from the next maneuver to the one following it)
navigation.item[1].length[named] Distance to next maneuver. Use navigation.item[1].length[value] and navigation.item[1].length[unit] in the same manner as for navigation.item.destination_length.
navigation.item[1].street_name Name of the road following the next maneuver
navigation.item[1].street_name_systematic Name of the road following the next maneuver
tracking Information on current track, available whenever valid GPS information and corresponding map data is available. The difference to navigation is that tracking data is also available when not routing. Ensure that tracking="1" is set in the <navit> tag to use these variables.
tracking.item Information related to the road the vehicle is currently traveling along
tracking.item.route_speed Speed limit on the road which the vehicle is currently on
tracking.item.street_name Name of the road which the vehicle is currently on
tracking.item.street_name_systematic Name of the road which the vehicle is currently on
vehicle GPS information, available whenever valid GPS information is available
vehicle.position_coord_geo Current position (NMEA-style coordinates, formatted as hhmm.mmmm)
vehicle.position_direction Current orientation (direction of travel) in degrees
vehicle.position_height Current altitude in m
vehicle.position_qual Number of satellites which your GPS receiver can see. However, your receiver may not be using all of them for positioning due to low signal etc...
vehicle.position_sats_used Number of satellites used
vehicle.position_speed Current speed in km/h


   <!-- ALWAYS AVAILABLE (if GPS connected) -->
   <!-- Current Speed (integer in km/h) -->
   <osd enabled="yes" type="text" label="${vehicle.position_speed}" x="-200" y="0" />
   <!-- Current Coordinate Position -->
   <osd enabled="yes" type="text" label="${vehicle.position_coord_geo}" x="-200" y="0" />
   <!-- Current Altitude (in metres)-->
   <osd enabled="yes" type="text" label="${vehicle.position_height}m" x="-60" y="-80" />
   <!-- Current Direction of Travel (integer from<!-- 0-360) -->
   <osd enabled="yes" type="text" label="${vehicle.position_direction}" x="-60" y="-80" />
   <!-- Number of Satellites Used / Number of Satellites Available -->
   <osd enabled="yes" type="text" label="${vehicle.position_sats_used}/${vehicle.position_qual}" x="-50"
  y="40" />
   <!-- ONLY AVAILABLE WHEN ROUTING (i.e in Sat-Nav mode) -->
   <!-- Currently on ROADNAME -->
   <osd enabled="yes" type="text" label="Currently on ${navigation.item.street_name_systematic}" x="0" y="0" />
   <!-- Distance to next turn (in metres) -->
   <osd enabled="yes" type="text" label="${navigation.item[1].length[named]}" x="0" y="-105" />
   <!-- Next turn is onto ROADNAME -->
   <osd enabled="yes" type="text" label="Turn onto ${navigation.item[1].street_name_systematic}" x="0" y="-105" />
   <!-- Estimated time of arrival (HH:mm) -->
   <osd enabled="yes" type="text" label="ETA ${navigation.item.destination_time[arrival]}" x="-150" y="-30" />
   <!-- Entire route distance remaining (in km) -->
   <osd enabled="yes" type="text" label="DR ${navigation.item.destination_length[named]}" x="-85" y="-60" />
   <!-- Time remaining until destination is reached (HH:mm) -->
   <osd enabled="yes" type="text" label="TR ${navigation.item.destination_time[remaining]}" x="-85" y="-90" />

Font Size

The size of font used in an osd item can be set using the 'font_size' attribute, for example:

   <osd enabled="yes" type="text" label="${vehicle.position_coord_geo}" x="0" y="0" w="360" font_size="300" />

This creates an osd item displaying the current position coordinates with a font size of 300. Default font size is currently 200.


An example implementation is shown below.


  • Top left is type="compass"
  • Bottom left is type="navigation_next_turn"
  • Top right is type="text" with label="${navigation.item.destination_time[arrival]}" and label="${navigation.item.destination_length[named]}"

More osd layouts can be found at OSD_Layouts.

Icon source setting for OSD

The N8x0 platform (and possibly others) is not very supportive of .svg image files. Navit on the other hand relies heavily on svg. The result is often missing images from your display. In the examples above you may need to replace the .svg with .png. The solution for Next Turn is to use the following config addition:

<osd enabled="yes" type="navigation_next_turn" x="325" y="-135" w="150" h="100" align="15"
   background_color="#a60c0f00" icon_src="$NAVIT_SHAREDIR/xpm/%s_wh_48_48.png" />

Note the icon_src parameter specifies the template for the image file names. This should work for all OSD items.

If you don't have the .png files already, you can create them this way:

$ for f in *wh.svg; do convert -background none -resize 48x48 $f `basename $f .svg`_48_48.png; done

Please note that the OSD layer is still under development, and content on this page may be out-of-date.