GRASS logo

Note: A new GRASS GIS stable version has been released: GRASS GIS 7. Go directly to the new manual page here


d.out.gpsdrive - Export display monitor to a GpsDrive compatible backdrop image


display, export, GPS


d.out.gpsdrive help
d.out.gpsdrive [-j] output=string [--verbose] [--quiet]


Make JPEG instead of PNG image
Verbose module output
Quiet module output


name for new map image (lives in ~/.gpsdrive/maps/)


d.out.gpsdrive exports the current GRASS display monitor to a GpsDrive compatible backdrop image and updates the GpsDrive image list with the appropriate geo-referencing information.

Use at your own risk. Do not use as a primary means of navigation. This software comes with absolutely no warranty.


Maps are saved in the user's ~/.gpsdrive/maps/ directory. Geo-referencing information is added to the user's ~/.gpsdrive/maps/map_koord.txt file.

JPEG output requires the pngtopnm and pnmtojpeg programs from the NetPBM tools.

GpsDrive assumes northings are not rotated compared to true-geographic north. If you are using a projection with significant curvature away from the central meridian, or a map datum with a significant rotational component, then you will likely end up with a distorted or inexact background map! Keeping the area small will lessen the error, but not eliminate it, if necessary you could reproject the map into a custom projection (such as tmerc) centered directly on the center of your map. You can check the local convergence angle (difference between grid north and true north) with "g.region -n".

To avoid distortion, anything more global than 1:150k to 1:500k should come from a lat/lon location. Anything more local than that will look better coming from a projected system such as UTM.

The extent of a map given a target scale can be calculated with x_ext=scale*(1280/2817.95). e.g. 1:50,000 translates to approx a 22.7km x 18.2km image window in the GIS.

For your convenience (calculations are rough, but nominal):

1:50,000 uses a region 22.7km x 18.2km.
1:75,000 uses a region 34.1km x 27.3km.
1:100,000 uses a region  45.4km x 36.3km.
1:175,000 uses a region  79.5km x 63.6km.

Maps exported from lat-lon locations will be given a "top_" prefix. Maps exported from locations of other projections will be given a "map_" prefix. This is done so GpsDrive knows how to scale the image correctly.

GpsDrive requires backdrop images to be 1280x1024 pixels in size. While this script takes care of that automatically, to avoid annoying bands on the sides of your image you may want to set up your display monitor at half-scale (same aspect ratio) and use d.zoom to select the full frame. For example:

export GRASS_WIDTH=640
export GRASS_HEIGHT=512
d.mon x0

Map scaling is set from the region settings so should work correctly even when the display's aspect ratio does not match that of the output image.

Batch export

It may be desirable to create a series of image tiles covering a large area. An easy way to do this is to run d.out.gpsdrive in a shell loop. Here is an example Bash script contributed by Manuel Morales:


# map scale is determined by "panels" by dividing the N-S
# region extent into that number of maps. Note that the
# generated maps overlap by 1/2 along the N-S axis and by
# approximately 1/2 along the E-W axis.

eval `g.region -eg`
eval `g.region -g`

unit_ns=$(echo "scale=8; $ns_extent / $panels" | bc)
unit_ew=$(echo "scale=8; $unit_ns * 4/3" | bc)

panels_ew=$(echo "((2*$ew_extent / $unit_ew +.5 ) -1) / 1" | bc)

for i in `seq 1 $panels_ew`;
  east=$(echo "scale=8; $west+$unit_ew" | bc)
  for j in `seq 1 $iter`;
    g.region n=$(echo "scale=8; $north-($j-1) * $unit_ns/2" | bc)      \
        s=$(echo "scale=8; $north-($j-1) * $unit_ns/2-$unit_ns" | bc ) \
        w=$west e=$east ewres=$ewres nsres=$nsres
        d.out.gpsdrive -j tile_${i}_${j}
  shift_west=$(echo "scale=8; ($ew_extent-$unit_ew)/($panels_ew-1)" | bc)
  west=$(echo "scale=8; $west+$shift_west" | bc)

Note that to get a smoother transition between backdrop maps this script creates overlapping tiles. For best results at least 1/3rd overlap should be maintained.

SEE ALSO, d.grid, d.out.file, d.out.png,, g.region,

The GRASS PNG driver
The GpsDrive project
The gpsd personal GPS server project


Hamish Bowman
Department of Marine Science
University of Otago
New Zealand

Last changed: $Date: 2011-11-08 03:29:50 -0800 (Tue, 08 Nov 2011) $

Main index - display index - Full index

© 2003-2016 GRASS Development Team