GRASS logo


m.printws - Opens a workspace file and creates a map sheet according to its visible contents.


map, print, layout, workspace


m.printws --help
m.printws [-d] input=name [dpi=integer] output=name [page=string] [format=string] [maintitle=string] [font=string] [titlecolor=name] [maintitlesize=integer] [subtitle=string] [subtitlesize=integer] [psunderleft=string] [psunderright=string] [psundercentral=string] [pssize=integer] [region=name] [layunits=string] [pagemargin=string] [mapupperleft=string] [mapsize=string] [screendpi=integer] [--overwrite] [--help] [--verbose] [--quiet] [--ui]


Debug - Leave temp files as is for alternative usage or checkup
Allow output files to overwrite existing files
Print usage summary
Verbose module output
Quiet module output
Force launching GUI dialog


input=name [required]
Name of workspace file to process
DPI for the generated page
Default: 150
output=name [required]
Name of output file without extension
Output map page size
Options: A4landscape, A4portrait, LETTERlandscape, LETTERportrait, A3landscape, A3portrait, Flexi
Default: A4landscape
Output file format
Options: pdf, png, tiff, bmp, ppm, jpg
Default: pdf
Main title of map sheet
Font for title above and postscript under the map
Title text color
Default: black
Main title font size in layout units
Subtitle text above the map sheet in the middle
Subtitle font size in layout units
Postscript text under the map sheet on the left
Postscript text under the map sheet on the right
Postscript text under the map sheet, centered
Postscript text font size in layout units
Name of region to use - uses workspace displayed area if empty
Unit used for layout specification
Options: cm, mm, inch
Default: mm
Margins in layout units left,right,top,bottom
Map frame upper left coordinates - negative means centering
Default: -1,-1
Map frame size in layout units as width,height
Default: 1000
The DPI of your monitor
Default: 100

Table of contents


m.printws adds a quick 'print workspace' function to GRASS GIS. Its purpose is to read a saved workspace file and render its content into a bitmap or PDF file similar to what the user configured in the workspace file for screen display, originally. As an opposite to other methods, the user is not required to create a separate map definition.

The module creates bitmap files so it is not suitable to produce professional cartographic quality. However, the following usage scenarios are recommended:


The module is set up to run with a full set of default values. To get quick result it is enough to specify the workspace file as input and the name of the output file without its exentsion since it is added autmatically depending on the selected output format. It creates a PDF format A4 landscape page at 150 dpi as default. Margins are 25mm, map area is 1000mm. Map frame is centered between the margins.

When selecting font, font names visible to GRASS GIS are not self evident. To ease font selection an "*" can be used to ask the script to look for a matching font. For example: titlefont="Open*" should find OpenSans or similar variations.

While running, the module modifies the map area edges ratio according to the region edges ratio. It also reduces the map area to fit between margins. It means that even faulty settings are corrected automatically. This is why initial settings of 1000mm map size and -1,-1 placement results an optimally filled and fitted page.

When reducing the target dpi resolution the content gerenation is very fast. It is recommended to run tests around 100dpi or lower and once we are satisfied with the layout it is time to set the final target dpi.

The module tries to render everything what are checked on the layer list and also adds overlays like barscale, legend and north arrow*

*=As of August, 2016 overlay modules positioning is slightly different on a map display compared to the created maps in files. With manual aligment and saving the workspace again the required positions could be set manually.

Some drawbacks of the module which should be taken into consideration:

The module changes region meanwhile it runs but restores the original when finished.

Vector legend (d.legend.vect) information

The d.legend.vect module integrates well with the GRASS GIS Layer Manager. When the user exits the GUI, its settings and status became invalid. It means that d.legend.vect may face problems when restarting GRASS GIS and trying to use the saved workspace file with m.printws with its old settings. To prevent such issues do the following steps:
  1. Compose your vector legend using the GUI as it is provided by d.legend.vect.
  2. When you are staisfied with the result or preparing for printing with m.printws, set an output CSV file in the d.legend.vect dialog. This could be done on the In/Out tab.
  3. Click the OK button.
  4. In the background, your composed legend contents will be listed to the corresponding CSV file.
  5. Reopen the d.legend.vect dialog.
  6. On the In/Out tab cut the text from the "Output csv file:" field and paste it to the "Input legend file:"
  7. Clik OK and check if you legend is still the same as you want it to be.
  8. Save the workspace as usual.
Thusly prepared vector legends will be printed correctly by m.printws. If you would like to modify your legend, delete the "Input legend file:" field on the In/Out tab and also repeat the process above before printing.

Multiple display support

When your workspace contains more than one display definitions m.printws would create multiple maps printing all displays on a separate page in a separate file. File naming is automatic and works like demonstrated blow if having to displays named 'Downtown' and 'OVERVIEW OF CITY': When regenerating the map the files are overwritten. Selecting a full name as output (outname_DISPLAY_2_Downtown.pdf) the module will recognize its own additinons _DISPLAY_2_.... and .pdf and won't duplicate them in the newly generated filenames.

Windows specific settings for ImageMagick

ImageMagick (IM) is essential for merging createt map layers and convert to the desired format. On Windows, IM should be installed by the user and be sure to add IM program directory to the PATH. It is done by the IM installation program on windows. However, for GRASS GIS, the OSGeo4W environment should be changed. Find the o4w_env.bat file in the OSGeo4W installation path. This is usually under C:\OSGeo4W\bin. Look at this part:
REM start with clean path
set Path=%OSGEO4W_ROOT%\bin;%WINDIR%\system32;%WINDIR%;%WINDIR%\WBem
and put back Windows path or if there is a collision in your system, add only IM path at the beginning (add %Path%; before the first occurence of %WINDIR%).
REM start with clean path
set Path=%OSGEO4W_ROOT%\bin;%Path%;%WINDIR%\system32;%WINDIR%;%WINDIR%\WBem
Save the .bat file. Restart GRASS GIS after this change. To check whether IM is accessible, in the GRASS GIS Layer Manager window click on the Command console tab and enter:
magick convert
If everything went fine, you will see the IM convert command help.

Tips and tricks

Title macros

There is a macro possibility for titles. Please take care of possible command line variable expansion rules of your own operating system or shell. For example on Linux or generally in Bash $ sign is used for shell variables. So, when calling m.printws from command line take care to use single quotes around such parameter values like this to prevent substitution:
... maintitle='$DISPLAY' ...

Fill your map display

By filling the map display of GRASS GIS positioning of map gadgets like legends, scale and north arrow could be more consequent. A fully drawn map window is also a space saver on paper hardcopies.
Filled map display Partly filled map display
Figure: Demonstration of filled or partly filled map displays

On the figures above the difference is clearly visible. Before running m.printws it is recommended to fill the map display fully with map content. It could be easily done with the Pan tool.
Pan function   Partly filled map display
Figure: Using Pan function display could be filled again

Using the tool and making a minor movement or a simple click the map will fill the display again. After this alignment with the Pan tool the workspace must be saved again so m.printws could print up to the newly set extents.

Making illustrations with the Flexi page option

When creating figures for scientific articles or book illustration purposes maps usually don't have elements like titles and others outside the map frame. In research papers map content is described in subtitles as Figure nn.: and so on. In this case page options like A4, or A4 landscape would always have white stripes on the top/bottom or left/right even when margin is set to be zero. This is because the ratio of the edges of the map never exactly follows the ratio of the A4 or other page edges. Supporting the creation of publication ready images (especially when the target format is tif, png or jpg) the Flexi option is introduced as a virtual page size. Using the Flexi page:

Background: The Flexi mechanism actually sets up the same layout as it is specified with margins and titles on a 300x300mm page and then cuts off everything outside the map frame together with cancelling the rendering of title elements.

An ideal resolution could easily be set using the dpi option of m.printws.


# create am A4 landscape 150dpi PDF copy of a workspace
m.printws input=/home/kuszi/grassdata/Duna/maps/VP/nice_vectors_workspace.gxw \
output=/home/kuszi/grassdata/Duna/maps/VP/sample_generated_printws maintitle=MAIN \
subtitle=sub psunderleft=left psunderright=right psundercentral=center \
region=cartosim_2@PERMANENT pagemargin=10
Screen view of workspace
Figure: Screen view of workspace

m.printws run example
Figure: m.printws run example created from the same workspace


d.legend.vect, g.gui, is an alternative option, d.label, ImageMagick

GRASS environment variables for rendering (GRASS_RENDER_FRAME)


Robert Kuszinger, Giscom Kkt Hungary

Based on d.* commands and their functions in GRASS 7 by many authors.
Depends on ImageMagick multi-platform image manipulation tools.


Available at: m.printws source code (history)

Main index | Miscellaneous index | Topics index | Keywords index | Graphical index | Full index

© 2003-2017 GRASS Development Team, GRASS GIS 7.2.3svn Reference Manual