OSD

From Navit's Wiki
Revision as of 21:36, 12 July 2010 by Mvglasow (talk | contribs) (Commands)
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.

Enable/Disable

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

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

osd_configuration

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.

command

An osd item can contain a command as in those examples:

   <osd command="osd_configuration=2" />
   <osd command="zoom_in()" />

The command will be called when the item is clicked.

Commands can contain expressions or one of the commands listed under Commands.

Expressions may use the following operators:

  • ~ ! Bit-wise and logical NOT
  • * / % Multiplication, division, modulo
  • + - Addition, subtraction
  • == != <= >= < > Comparison (equal, not equal, less than or equal, greater than or equal, less than, greater than)
  • & | ^ Bit-wise AND, OR, XOR
  • && || Logical AND, OR
  • ? : Conditional (a?b:c will return b if a is true, else it will return c)
  • = Assignment
  • , Comma operator

Available attributes for use in expressions are:

  • gui.fullscreen Use gui.fullscreen=!gui.fullscreen to toggle between window and fullscreen mode.
  • osd Not yet implemented. Use e.g. osd[type=="xxx"].active=0 to disable or enable certain OSD items.
  • 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.
  • speech.active Use speech.active!=speech.active to enable or disable spoken directions.

Position

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).

Size

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.

Alignment

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.

Types

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.

button

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.

compass

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"/>

gps_status

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

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

navigation_next_turn

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" />

scale

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"/>

text

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.

Attributes are specified as ${section.attribute}. Attributes which can be used in labels include:

Attribute Value
navigation Section containing 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 (e.g. Via Gallarate)
navigation.item.street_name_systematic Number/reference of the road which the vehicle is currently on, if available (e.g. SS33)
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 (cf. navigation.item.street_name)
navigation.item[1].street_name_systematic Name of the road following the next maneuver (cf. navigation.item.street_name_systematic)
navit
navit.messages
tracking Section containing 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 attributes.
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 (cf. navigation.item.street_name)
tracking.item.street_name_systematic Number/reference of the road which the vehicle is currently on (cf. navigation.item.street_name_systematic)
vehicle Section containing GPS information, available whenever valid GPS information is available
vehicle.position_coord_geo Current position. Use vehicle.position_coord_geo[format] to control the output format of the coordinates (works reliably from r3490 onwards). Valid format values are:
  • pos_deg: Latitute and longitude in decimal degrees
  • pos_degmin: Latitude and longitude in degrees, minutes and fractions of minutes (similar to NMEA style)
  • pos_degminsec: Latitude and longitude in degrees, minutes and seconds
  • lat_deg, lat_degmin, lat_degminsec: Only the latitude in one of the formats described above
  • lng_deg, lng_degmin, lng_degminsec: Only the longitude in one of the formats described above

If omitted, pos_degminsec will be assumed.

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
vehicle.position_time_iso8601 Current GPS time (roughly the same as UTC, with a few seconds of difference)

Examples:

   <!-- 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.

Example

An example implementation is shown below.

Navit-internal-osd-fon.png

  • 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 Nokia 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:

$ cd $NAVIT_SHAREDIR/xpm
$ 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.

Commands

The following commands (from navit/navit.c) can be used in the command attribute of OSD items:

Command Meaning
announcer_toggle() FIXME: description to be completed
fmt_coordinates() FIXME: description to be completed
say() Use to produce speech output. FIXME: how?
set_center_cursor() FIXME: description to be completed
set_destination() FIXME: description to be completed
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

GUI menu commands can be used within from GUI menu items or from OSD items. In the latter case, prefix them with gui. The following are available (from navit/gui/internal/gui_internal.c):

Command Meaning
abort_navigation() Cancels navigation: The route is cleared and Navit switches to tracking mode.
about() Displays the About screen.
back() FIXME: description to be completed.
back_to_map() Leaves the menu and returns to map view.
bookmarks() Shows bookmarks.
get_data() FIXME: description to be completed
locale() Shows locale information.
log FIXME: description to be completed
menu() Brings up the menu (used as gui.menu() in OSD items in order to have a dedicated menu button).
position(position, text, flags) Presents possible operations on a position (set as current location, set as destination etc.). position is a coordinate-type attribute (e.g. position_coord_geo).
quit() Closes Navit.
route_description() Shows a turn-by-turn description of the active route when in navigation mode.
route_height_profile() Shows a height profile of the active route when in navigation mode.
setting_layout() Presents a selection of available screen layouts.
setting_maps() Presents a dialog to switch between available mapsets.
setting_rules() Presents a dialog for setting various internal options.
setting_vehicle() Presents a dialog for selecting the active vehicle.
town() Presents a dialog for selecting an address, starting with a town.
write(attribute) Writes an attribute. Used by the GUI menu in conjunction with <script> to display the content of an attribute in a menu item.