ps.map(1grass)

📦
version 8.5.0 · 10 versions
, in alpine 3.24, ubuntu stonking

💖 ps.map 💖 (1grass)

okay bestie, welcome to the GRASS User's Manual page for ps.map(1grass) and honestly? she's a lot. but we're gonna get through her together 🫶

✨ NAME ✨

ps.map — makes you hardcopy PostScript map output. that's it, that's the whole job. printing queen 👑

🌈 KEYWORDS 🌈

postscript, printing

🎀 SYNOPSIS 🎀

ps.map
ps.map --help
ps.map [-rpeb] input=name output=name  [copies=integer]   [--overwrite]
[--help]  [--verbose]  [--quiet]  [--ui]

🦋 Flags

  • -r — Rotate that plot 90 degrees, spin her around 💫
  • -p — List paper formats. gives you name width height left right top bottom(margin)
  • -e — Create EPS (Encapsulated PostScript) instead of a PostScript file
  • -b — Describe the map-box's position on the page and then dip. measured in inches from top-left of paper
  • --overwrite — Let output files overwrite existing files (chaotic, but okay)
  • --help — Print usage summary
  • --verbose — Verbose module output
  • --quiet — Quiet module output
  • --ui — Force launching GUI dialog

💅 Parameters

  • input=name [required] — File containing mapping instructions. Use '-' to enter instructions from keyboard)
  • output=name [required] — Name for PostScript output file
  • copies=integer — Number of copies to print. Options: 1-20

🌸 DESCRIPTION 🌸

ps.map is a cartographic mapping program, and what she does is produce high quality hardcopy maps in PostScript format. Output can include a raster map, literally any number of vector overlays, text labels, decorations, and other spatial data. the range?? unmatched ✨

Before you run ps.map, you have to prepare a file of mapping instructions that describes the various spatial and textual information to be printed. no instruction file, no map. that's the deal 🙈

👑 NOTES 👑

The order of commands is generally unimportant, BUT it may affect how some layers are drawn. For example, to plot vpoints above vares, list the vpoints entry first. Raster maps are always drawn first, and only a single raster map (or 3 if part of a RGB group) may be used. that's the limit bestie, don't fight it 😭

The hash character ('#') may be used at the beginning of a line to indicate that the line is a comment. Blank lines will also be ignored. so go ahead and annotate your little heart out 🎀

Be aware that some mapping instructions require the end command and some do not. Any instruction that allows subcommands will require it, any instruction that does not allow subcommands will not. yes it's rules-on-rules, iykyk 💀

The resolution and extent of raster maps plotted with ps.map are controlled by the current region settings via the g.region module. The output filesize is largely a function of the region resolution, so special care should be taken if working with large raster datasets. For example if the desired output is US-Letter sized paper at 600dpi, with 1" margins and the raster filling the entire page, the usable area on the page will be 6.5" x 9", which at 600 dots/inch is equivalent to a region of 3900 columns x 5400 rows (see "g.region -p"). Any higher resolution settings will make the output file larger, but with a consumer printer you probably won't be able to resolve any better detail in the hardcopy. fr fr, don't cook your file size for nothing 🍓

The user can specify negative or greater than 100 percentage values for positioning several map decorations and embedded EPS-files, to move them outside the current map box region — for example, to position a caption, barscale, or legend above or below the map box. main character energy: sometimes you gotta leave the box 💅

One point ("pixel") is 1/72 of an inch. remember this, it comes up constantly.

For users wanting to use special characters (such as accented characters) it is important to note that ps.map uses ISO-8859-1 encoding. This means that your instructions file will have to be encoded in this encoding. If you normally work in a different encoding environment (such as UTF-8), you have to transform your file to the ISO-8859-1 encoding, for example by using the iconv utility:

iconv -f UTF-8 -t ISO_8859-1 utf_file > iso_file

⭐ MAPPING INSTRUCTIONS ⭐

The mapping instructions allow the user to specify various spatial data to be plotted. These instructions are normally prepared in a regular text file using a system editor. Some instructions are single line instructions while others are multiple line. Multiple line instructions consist of the main instruction followed by a subsection of one or more additional instructions and are terminated with an end instruction. so: main instruction, lil subsection, end. periodt 🫶

🌈 Instruction keywords:

[ border | colortable | comments | copies | eps | geogrid | greyrast |
grid | group | header | labels | line | mapinfo | maploc | maskcolor |
outline | paper | point | psfile | raster | read | rectangle | region |
rgb | scale | scalebar | setcolor | text | vareas | vlines | vpoints |
vlegend | end ]

💜 Common instructions

Instructions that may be included in the subsection under several different main instructions are:

  • where x y — The top left corner of the bounding box of the item to be plotted is located x inches from the left edge of the paper and y inches from the top edge of the paper. If x is less than or equal to zero, the default horizontal location is used. If y is less than or equal to zero, the default vertical location is used.
  • font font name — The name of the PostScript font. Fonts present in all PostScript implementations are: Times-Roman, Times-Italic, Times-Bold, Times-BoldItalic, Helvetica, Helvetica-Oblique, Helvetica-Bold, Helvetica-BoldOblique, Courier, Courier-Oblique, Courier-Bold, and Courier-BoldOblique. The default is Helvetica. (she's the default for a reason, she serves 💅)
  • fontsize font size — The size of the PostScript font (in 1/72nds of an inch). The default is 10 point.
  • color name — The following colors names are accepted by ps.map: aqua, black, blue, brown, cyan, gray, grey, green, indigo, magenta, orange, purple, red, violet, white, yellow . For vectors and some plotting commands you can also specify 'none' or 'R:G:B' (e.g '255:0:0').
  • yes|no — For options that take a yes or no answer, you can simply use the letters "y" or "n", or type out the full words "Yes" or "No" if you prefer. It is not case-sensitive. Typically the option with have a default answer and you only need to specify one if you wish to override it.

🧚 Command usage

border

Controls the border which is drawn around the map area.

USAGE:  border [y|n]
    color color
    width #
    end

The color may be either a standard GRASS color, a R:G:B triplet, or "none". The width is specified in points, unless followed by an "i" in which case it is measured in inches. The default is a black border box of width 1 point.

The border can be turned off completely with the "border n" instruction. In this case the end command should not be given as the main command will be treated as a single line instruction.

This example would create a grey border 0.1" wide.

EXAMPLE:
    border
    color grey
    width 0.1i
    end

colortable

Prints the color table legend for the raster map layer anywhere on the page. anywhere bestie, she's flexible ✨

USAGE:    colortable [y|n]
    where x y
    raster raster map
    range minimum maximum
    width table width
    height table height (FP legend only)
    cols table columns
    font font name
    fontsize font size
    color text color
    nodata [Y|n]
    tickbar [y|N]
    discrete [y|n]
    end

For a categorical (CELL) map the color table will create a legend displaying the colors for each of a raster map's category values along with its associated category label. For a floating point (FCELL or DCELL) map a continuous gradient legend will be created. two vibes, one instruction 🌈

If raster is omitted, the colortable defaults to the previously registered raster layer.

The default location for the colortable is immediately below any other map legend information, starting at the left margin. The default text color is black.

Omitting the colortable instruction would result in no color table. If the colortable is turned off with a "colortable N" instruction the end command should not be given as the main command will be treated as a single line instruction.

See also the vlegend command for creating vector map legends.

🍓 Categorical (CELL) Maps

Adding the nodata N instruction will prevent the "no data" box from being drawn (category based legends only). If you have manually added a "no data" label to the cats/ file it will be shown regardless.

Note: Be careful about asking for color tables for integer raster map layers which have many categories, such as elevation. This could result in the printing of an extremely long color table! In this situation it is useful to use the discrete N instruction to force a continuous color gradient legend. 😭 like bestie please, we cannot print a table with four thousand categories

Be aware that the color table only includes categories which have a label. You can use the r.category module to add labels.

💜 Floating point (FCELL and DCELL) Maps

The legend's range can be adjusted for floating point rasters, but if set beyond the extent of the map's range be sure that you have set up color rules with r.colors which cover this range. If the map has been given a data-units label with r.support then this label will be displayed. For floating point legends width is width of color band only. height is used only for floating point legend. A horizontal gradient legend can be achieved by setting the legend width greater than its height. Adding the tickbar Y instruction will change the tick mark style so that ticks are drawn across the color table instead of protruding out to the right (floating point legends only). Adding the discrete Y instruction will command the program to treat the map as a categorical map. In this way the legend can be created with discrete range bands instead of a continuous gradient. You must use the r.category or r.support module to set up the range labels first.

This example would print a color table immediately below any other map legend information, starting at the left margin, with 4 columns:

EXAMPLE:
    colortable y
        cols 4
        width 4
        end

💬 comments

Prints comments, like, anywhere on the page. Yes bestie, anywhere. You're the main character of page layout.

USAGE:    comments commentfile
    where x y
    font font name
    fontsize font size
    color text color
    end

Where does it go if you don't say? It lands immediately below the last item printed, starting at the left margin. Default text color is black, periodt.

⚠️ Real talk: if you want to use parentheses that span multiple lines, you have to quote them with a backslash so the PostScript interpreter doesn't get its whole life confused. So like \( and \). She's dramatic like that 😭

So this example prints in blue whatever is in the file veg.comments, starting at 1.5 inches from the left edge of the page and 7.25 inches from the top, using a 15/72 inch Helvetica Bold font:

raster vegetation
comments veg.comments
where 1.5 7.25
font Helvetica Bold
fontsize 15
color blue
end

Presumably, the file veg.comments contain comments pertaining to the raster map layer vegetation, such as "This map was created by classifying a LANDSAT TM image". Slay 💅

🖨️ copies

Specifies the number of copies to be printed. That's it, that's the whole job.

USAGE:    copies n

Each page will be printed n times. Iconic.

This instruction is identical to the copies command line parameter. Same vibe, different entrance 🌈

🖼️ eps

Places EPS (Encapsulated PostScript) pictures on the output map. Little logo moment ✨

USAGE:    eps east north
    eps x% y%
    epsfile EPS file
    scale #
    rotate #
    masked [y|n]
    end

The EPS picture location is entered in the main instruction line by giving either the map coordinates or by using percentages of the geographic region. The EPS picture will be centered at the given position. The user must specify full EPS file path with epsfile. The user may also specify:

  • scale of the icon (default is 1.0)
  • rotate i.e. rotation in degrees (default is 0)
  • masked — whether the point is to be masked by the current mask

(Check the manual entry for r.mask for more info on the mask, bestie.)

This example would place a EPS file ./epsf/logo.eps at the point (E456000 N7890000). This picture would be rotated 20 degrees clockwise, 3 times bigger than in original file, and would not be masked by the current mask:

eps 456000 7890000
epsfile ./epsf/logo.eps
scale 3
rotate 20
masked n
end

Of course, multiple EPS pictures may be drawn with multiple eps instructions. Go off, build a whole collage 💖

🌐 geogrid

Overlays a geographic grid onto the output map.

USAGE:    geogrid spacing unit
    color color
    numbers # [color]
    font font name
    fontsize font size
    width #
    end

The spacing and spacing unit of the geographic grid is given on the main instruction line. The spacing unit is given as one of d for degrees, m for minutes, and s for seconds. The subsection instructions let you specify:

  • the color of the geographic grid lines
  • whether coordinate numbers should appear on the geographic grid lines
  • the width of the lines (accepts decimal points [floating points] as well as integers)
  • if the numbers should appear every grid line (1), every other grid line (2), etc.
  • what color the numbers should be

The defaults are black grid lines, unnumbered. Humble of them.

📌 NOTE: The geogrid draws grid numbers on the east and south borders of the map.

This example would overlay a blue geographic grid with a spacing of 30 minutes onto the output map. Alternate grid lines would be numbered with yellow numbers:

geogrid 30 m
color blue
numbers 2 yellow
end

🩶 greyrast

Selects a raster map layer for output in shades of grey. Grey is a whole aesthetic ngl.

USAGE:    greyrast mapname

For each ps.map run, only one raster map layer can be requested (using either the greyrast or the raster instruction). One. That's the rule, bestie 😌

📐 grid

Overlays a coordinate grid onto the output map.

USAGE:    grid spacing
    color color
    numbers # [color]
    cross cross size
    font font name
    fontsize font size
    width #
    end

The spacing of the grid is given (in the geographic coordinate system units) on the main instruction line. The subsection instructions let you specify:

  • the color of the grid lines
  • whether coordinate numbers should appear on the grid lines
  • if they should appear every grid line (1), every other grid line (2), etc.
  • what color the numbers should be

The cross argument draws grid intersection crosses instead of grid lines, with cross size given in geographic coordinate system units. The defaults are black grid lines, unnumbered. Same energy as geogrid, different flavour.

This example would overlay a green grid with a spacing of 10000 meters (for a metered database, like UTM) onto the output map. Alternate grid lines would be numbered with red numbers:

grid 10000
color green
numbers 2 red
end

🎨 group

Selects an RGB imagery group for output. The trio, the band, the moment 👑

USAGE:    group groupname

This is similar to raster, except that it uses an imagery group instead of a raster map layer. The group must contain three raster map layers, comprising the red, green and blue bands of the image. RGB fr fr 💖

Prints the map header above the map.

USAGE:    header
    file header file
    font font name
    fontsize font size
    color text color
    end

If the file sub-instruction is absent, the header will consist of the map's title and the project's description. The text will be centered on the page above the map. The default text color is black.

If the file sub-instruction is given, the header will consist of the text in the text file specified, with some special formatting keys:

  • %% — a literal %
  • %n — ? newline ?
  • %_ — horizontal bar
  • %c — "<raster name> in mapset <mapset name>"
  • %d — today's date
  • %l — project name
  • %L — project's text description
  • %m — mapset name
  • %u — user name
  • %x — mask info
  • %- — advance to this character column number (see example below)

Example header file, and yes you can copy it character for character:

%_
LOCATION: %-27l  DATE: %d
MAPSET:   %-27m  USER: %u
RASTER MAP: %c
MASK:     %x
%_
Produced by: US Army CERL, Champaign Illinois
Software:    GRASS
%_

This example prints (in red) whatever is in the file soils.hdr above the map, using a 20/72 inch Courier font:

header
file soils.hdr
font Courier
fontsize 20
color red
end

🏷️ labels

Selects a labels file for output (see manual entry for v.label).

USAGE:    labels  labelfile
    font font name
    end
📌 NOTE: ps.map can read new option ROTATE: from labels file, which specifies counter clockwise rotation in degrees. Not clockwise. Counter. Read it twice bestie 🙈

This example would paint labels from the labels file called town.names. Presumably, these labels would indicate the names of towns on the map:

labels town.names
end

📏 line

Draws lines on the output map. Connect the dots, glow up the map ✨

USAGE:    line east north east north
    line x% y% x% y%
    color color
    width #
    masked [y|n]
    end

The beginning and ending points of the line are entered on the main instruction. These points can be defined either by map coordinates or by using percentages of the geographic region. The user may also specify:

  • line color
  • width in points (1/72"; accepts decimal values as well as integers)
  • whether the line is to be masked by the current mask

(Check the manual entry for r.mask for more info on the mask.) The line width (if given) is measured in points; an i directly following the number indicates that the width is given in inches instead. Sneaky little letter, love that for us 💅

This example would draw a yellow line from the point x=10% y=80% to the point x=30% y=70%. This line would be 2 points wide (2/72") and would appear even if there is a mask:

line 10% 80% 30% 70%
color yellow
width 2
masked n
end

Of course, multiple lines may be drawn with multiple line instructions. Skincare routine but make it vectors 🫶

📋 mapinfo

Prints the portion of the map legend containing the scale, grid and region information, on or below the map.

USAGE:    mapinfo
    where x y
    font font name
    fontsize font size
    color text color
    background box color|none
    border color|none
    end

The default location is immediately below the map, starting at the left edge of the map. The default text color is black. The default background box color is white.

border will draw a border around the legend using the specified color. (see NAMED COLORS)

This example prints (in brown) the scale, grid and region information immediately below the map and starting 1.5 inches from the left edge of the page, using a 12/72 inch Courier font:

mapinfo
where 1.5 0
font Courier
fontsize 12
color brown
end

🗺️ maploc

Positions the map on the page. Placement is everything, no cap.

USAGE:    maploc  x y [width height]

The upper left corner of the map will be positioned x inches from the left edge of the page and y inches from the top of the page. If width and height (in inches) are present, the map will be rescaled, if necessary, to fit.

This example positions the upper left corner of the map 2.0 inches from the left edge and 3.5 inches from the top edge of the map:

maploc 2.0 3.5

🎀 maskcolor

Color to be used for mask.

USAGE:    maskcolor  color

Short, sweet, and to the point. She said what she said 💜

✏️ outline

Outlines the areas of a raster map layer with a specified color. Contour queen behavior 🔥

USAGE:    outline
    color  color
    width  width of line in points
    end

Distinct areas of the raster map will be separated from each other visually by drawing a border (or outline) in the specified color (default: black). For width the program accepts decimal points [floating points] as well as integers.

⚠️ Note: it is important the user enter the instruction end even if a color is not chosen. Do not forget the end, bestie, she will not forgive you 😭

(It is hoped that in the future the outline of a different raster map layer other than the one currently being painted may be placed on the map. Manifesting ✨)

This example would outline the category areas of the soils raster map layer in grey:

raster soils
outline
color grey
width 2
end

🌸 PAPER 🌸

Bestie, this one sets your paper size AND your margins. The whole vibe of the page, basically.

USAGE:    paper paper name
           height #
           width #
           left #
           right #
           bottom #
           top #
           end

So paper can pick a predefined paper name for you, and the options are: a4, a3, a2, a1, a0, us-legal, us-letter, us-tabloid. The default paper size is a4. All the measures are in inches. And left, right, bottom and top? Those are your paper margins. 💅

Heads up: if your plot got rotated with the -r command line flag, then all these measures get applied to the rotated page. Rotate responsibly, queen. 🦋

EXAMPLE:

    paper a3
    end

EXAMPLE:

    paper
    width 10
    height 10
    left 2
    right 2
    bottom 2
    top 2
    end

📍 POINT 📍

Places additional points or icons right on your output map. Little sparkles on the map, we love to see it. ✨

USAGE:    point east north
           point x% y%
           color color
           fcolor color
           symbol symbol group/name
           size #
           width #
           rotate #
           masked [y|n]
           end

The point location goes in the main instruction line, and you give it either map coordinates or percentages of the geographic region. You can also specify the point color, the size of the symbol in points, the rotation angle (in degrees CCW), and whether the point should be masked by the current mask. (Peep the manual entry for r.mask if you wanna know more about the mask. 🌈) The symbol line width, if you give one, is measured in points — but if you drop an i directly after the number, that means the width is in inches instead. And if you don't give a width at all? It gets set proportional to the symbol size. Auto-glow-up, honestly.

This next example places a purple diamond (from icon file diamond) at the point (E456000 N7890000). That diamond would be the size of a 15 points and would not be masked by the current mask.

EXAMPLE:

    point 456000 7890000
    fcolor purple
    color black
    symbol basic/diamond
    size 15
    masked n
    end

And of course, multiple points may be drawn with multiple point instructions. Go off. 💖

🎀 PSFILE 🎀

Copies a file full of PostScript commands into your output file. Snatch their whole flow, basically.

Note: ps.map will not search for this file. The user must be in the correct directory or specify the full path on the psfile instruction. (And a lil note to /bin/csh users: ~ won't work with this instruction. Betrayal, honestly. 💀)
USAGE:    psfile filename

This example copies the file "logo.ps" into the output file.

EXAMPLE:

    psfile logo.ps

🗺️ RASTER 🗺️

Selects a raster map layer for output. The main character of the map, if you will. 👑

USAGE:    raster mapname

For each ps.map run, only one raster map layer can be requested — or one set of layers, or an imagery group, see below. And if no raster map layer is requested at all? You get a completely white map. Which, lowkey, is useful sometimes: selecting no raster map layer gives you a white background for your vector maps. Clean canvas energy.

Now, important: an imagery group selected with the group option, or a set of three raster layers selected with the rgb option, counts as a raster map layer for the purposes of that whole paragraph up there. No cap.

Also, the PostScript file's internal title gets set to the raster map's title — and that title can in turn be set with the r.support module. Cute lil chain of custody. 🫶

This example paints a map of the raster map layer soils.

EXAMPLE:

    raster soils

📖 READ 📖

Provides ps.map with a previously prepared input stream. It's giving "I already did the work, you're welcome."

USAGE:    read previously prepared UNIX file

Mapping instructions can be placed into a file and read into ps.map. Chef's kiss. 😌

Note: ps.map will not search for this file. The user must be in the correct directory or specify the full path on the read instruction. (Note to /bin/csh users once again: ~ won't work with this instruction. Same betrayal as before.)

This example reads the UNIX file pmap.roads into ps.map. That file may contain all the ps.map instructions for placing the vector map layer roads onto the output map.

EXAMPLE:

    read pmap.roads

The user may have created that file because this vector map layer is particularly useful for many ps.map outputs. And by using the read option, the user doesn't need to enter all the input for the vector instruction — they just read the previously prepared file with the correct instructions. Efficiency is the aesthetic. 💅

🟨 RECTANGLE 🟨

Draws rectangle on the output map. Shapes! On your map! Slay.

USAGE:    rectangle east north east north
           rectangle x% y% x% y%
           color color
           fcolor fill color
           width #
           masked [y|n]
           end

The two corners of the rectangle go on the main instruction. Those points can be defined either by map coordinates or by percentages of the geographic region. You can also specify the line color, the fill color fcolor, the width in points (and yes, it accepts decimal points — floating points — as well as integers, she's flexible 💅), and whether the rectangle is masked by the current mask. (See the manual entry for r.mask for more on the mask.) The border line width, if given, is measured in points — and an i directly after the number means the width is in inches instead.

Multiple rectangles may be drawn by using multiple rectangle instructions. Stack 'em, bestie.

This example would draw a yellow rectangle filled by green from the point x=10% y=80% to the point x=30% y=70%. The border line would be 1/16" wide and would appear even if there is a mask.

EXAMPLE:

    rectangle 10% 80% 30% 70%
    color yellow
    fcolor green
    width 0.0625i
    masked n
    end

🔲 REGION 🔲

Places the outline of a smaller geographic region on the output. Like a lil focus box on the bigger picture. 🦋

USAGE:    region regionfile
           color color
           width #
           end

Geographic region settings are created and saved using the g.region module. The ps.map region option can be used to show an outline of a smaller region which was printed on a separate run of ps.map on other user-created maps.

You can specify the color and the width in point units of the outline (and yes, it accepts decimal points — floating points — as well as integers). The default is a black border of one point width (1/72").

This example would place a white outline, 2 points wide, of the geographic region called fire.zones onto the output map. That geographic region would have been created and saved using g.region.

EXAMPLE:

    region fire.zones
    color white
    width 2
    end

🌈 RGB 🌈

Selects three raster map layers for output as an RGB color image. Three layers, one glow-up. ✨

USAGE:    rgb red green blue

This is similar to raster, except it uses three raster map layers instead of a single layer. The three layers are composed to form a color image, similar to d.rgb.

For each layer, only one of the components of the layer's color table is used: the red component for the red layer, and so on. This gives you the desired result if all of the layers have a grey-scale color table, or if each layer's color table uses the hue appropriate to the layer. Iconic color theory behavior, honestly. 🎨

📏 SCALE 📏

Selects a scale for the output map. How zoomed-in are we talking.

USAGE:    scale scale

The scale can be selected either as:

  1. a relative ratio, e.g. 1:25000;
  2. an absolute width of the printed map, e.g. 10 inches;
  3. the number of printed paper panels, e.g. 3 panels (at the present time, only 1 panel is supported);
  4. the number of miles per inch, e.g. 1 inch equals 4 miles.

This example would set the scale of the map to 1 unit = 25000 units.

EXAMPLE:

    scale 1:25000

📐 SCALEBAR 📐

Draws a scalebar on the map. The lil ruler. Everybody loves a lil ruler. 🥰

USAGE:    scalebar [f|s]
           where x y
           length overall distance in map units
           units [auto|meters|kilometers|feet|miles|nautmiles]
           height scale height in inches
           segment number of segments
           numbers #
           fontsize font size
           background [Y|n]
           end

Draw one of two types of scale bar. Fancy (f) draws alternating black and white scale boxes — very editorial. Simple (s) draws a plain line scale — minimal, clean. The default type is fancy.

The subsection instructions let you set where the scalebar is placed, the length of the scalebar (in geographic coordinate system units, or those given by units), the height of the scalebar in inches, and the number of segments (or tics, for simple). The number of annotations, numbers, labels every n-th segment. And the background command can turn off the background box for the text.

The scalebar length is the only required argument. The defaults are a fancy scalebar with 4 segments, each segment labeled, and a height of 0.1 inches. The default location is 2 inches from the top of the page and halfway across. Comfy defaults, fr fr.

NOTE: The scalebar is centered on the location given. Centered, bestie. Plan accordingly. 💅

This example draws a simple scalebar 1000 meters long (for a metered database, like UTM), with tics every 200 meters, labeled every second tic. The scalebar is drawn 5 inches from the top and 4 inches from the left and is 0.25 inches high.

EXAMPLE:

    scalebar s
    where 4 5
    length 1000
    height 0.25
    segment 5
    numbers 2
    end

🎨 SETCOLOR 🎨

Overrides the color assigned to one or more categories of the raster map layer. Color control? We're obsessed.

USAGE:    setcolor cat(s) color

This example would set the color for categories 2,5 and 8 of the raster map layer watersheds to white, and category 10 to green. (NOTE: no spaces are inserted between the category values. Respect the commas, they're doing their job. 🙈)

EXAMPLE:

    raster watersheds
    setcolor 2,5,8 white
    setcolor 10 green

And of course, setcolor can be requested more than once to override the default color for additional categories. More than one category can be changed for each request by listing all the category values separated by commas (but with no spaces). Also, ranges can be included — for example "1,2,6-10,12". And the colors for "null" and the "default" (i.e. out-of-range) color may also be reassigned. Full palette power. 🔥

✨ text ✨

Plops some text down on your map, bestie. That's the whole vibe. 💅

USAGE:    text  east north text
    text  x% y% text
    font fontname
    color color|none
    width #
    hcolor color|none
    hwidth #
    background color|none
    border color|none
    fontsize font size
    size #
    ref reference point
    rotate degrees CCW
    xoffset #
    yoffset #
    opaque [y|n]
    end

So here's the tea: you tell it where the text goes by giving it either map coordinates or percentages of the geographic region. The actual text follows those coordinates on the same instruction line, like it's holding hands with them. 🫶 Wanna do more than one line? Notate the end of a line with \n, like USA\nCERL. Slay.

Then you can dress the text up with all these features:

  • font — the PostScript font. The common possibilities are listed at the very start of this help page. Default is Helvetica.
  • color — see NAMED COLORS (iykyk).
  • width — how fat the lines used to draw the text are, i.e. thicker letters. Accepts decimal points [floating points] as well as integers. ✨
  • size and fontsize — okay so size gives the vertical height of the letters in meters on the ground, which means the text will grow or shrink depending on the scale at which the map is painted (main character behavior honestly). Alternatively, fontsize sets the font size directly. If neither size nor fontsize is given, a default font size of 10 will be used.
  • the highlight color (hcolor) and the width of the highlight color (hwidth) — yes, your text can have a whole highlighter moment. 🎀
  • the text-enclosing-box background color, and the text box border color.
  • ref — this reference point specifies the text handle, aka what part of the text should be placed on the location specified by the map coordinates. Reference points can refer to: [lower|upper|center] [left|right|center] of the text to be printed. The default is center center, i.e. the text is centered on the reference point.
  • rotate — sets the text rotation angle, measured in degrees counter-clockwise.
  • yoffset — finer placement of text by shifting the text a vertical distance in points (1/72") from the specified north. The vertical offset will shift the location to the south if positive, north if negative.
  • xoffset — shifts the text a horizontal distance in points from the specified east. The horizontal offset will shift the location east if positive, west if negative.
  • opaque — whether or not the text should be opaque to vectors. Entering no to the opaque option will allow the user to see any vectors which go through the text's background box. Otherwise, they will end at the box's edge. 🦋

The following example would place the text SPEARFISH LAND COVER at the coordinates E650000 N7365000. The text would be a total of 3 points wide (2 pixels of red text and 1 pixel black highlight), have a white background enclosed in a red box, and be 500 meters in size. The lower right corner of the text would be centered over the coordinates provided. All vectors on the map would stop at the border of this text. Not me describing this and getting emotional 😭

EXAMPLE:

text 650000 7365000 SPEARFISH LAND COVER
font romand
color red
width 2
hcolor black
hwidth 1
background white
border red
size 500
ref lower left
opaque y
end

🌈 vareas 🌈

Selects a vector map layer for output and plots areas. It's giving filled-in gorgeousness. 👑

USAGE:    vareas vectormap
    layer # (layer number used with cats/where option)
    cats list of categories (e.g. 1,3,5-7)
    where SQL where statement
    masked [y|n]
    color color
    fcolor color
    rgbcolumn column
    width #
    label label to use in legend
    lpos position in legend
    pat pattern file
    pwidth #
    scale #
    end

The user can specify:

  • color — color of the vector lines or area boundaries.
  • fcolor — the area fill color.
  • rgbcolumn — name of color definition column used for the area fill color.
  • width — width of the vectors lines or area boundaries in points (accepts decimal points [floating points] as well as integers).
  • masked — whether or not the raster map layer is to be masked by the current mask; (see manual entry r.mask for more information on the mask).
  • cats — which categories should be plotted (default is all).
  • where — select features using a SQL where statement. For example: vlastnik = 'Cimrman';
  • label — for description in vlegend. Default is: map(mapset);
  • lpos — position vector is plotted in legend. If lpos is 0 then this vector is omitted in legend. If more vectors used the same lpos then their symbols in legend are merged and label for first vector is used.
  • pat — full path to pattern file. The pattern file contains header and simple PostScript commands. It is similar to EPS but more limited, meaning that while each pattern file is a true EPS file, most EPS files are not useful as pattern files because they contain restricted commands. Color of patterns are set by fcolor (red, green, ..., none, R:G:B). Color of the boundaries remain set by the color instruction. Pattern may be scaled with the scale command. Several standard hatching patterns are provided in $GISBASE/etc/paint/patterns/. Demonstrative images can be found on the GRASS Wiki site. You can also create your own custom pattern files in a text editor. Example of pattern file:
%!PS-Adobe-2.0 EPSF-1.2
%%BoundingBox: 0 0 10 10
newpath
5 0 moveto
5 10 lineto
stroke
  • scale — pattern scale.
  • pwidth — pattern line width, width is used by pattern until the width is overwritten in pattern file.

EXAMPLE:

vareas forest
color blue
width 1
masked y
cats 2,5-7
end

🧚 vlines 🧚

Selects a vector map layer for output and plots lines. Line art but make it cartography. ✏️✨

USAGE:    vlines vectormap
    type line and/or boundary
    layer # (layer number used with cats/where option)
    cats list of categories (e.g. 1,3,5-7)
    where SQL where statement like: vlastnik = 'Cimrman'
    masked [y|n]
    color color
    rgbcolumn column
    width #
    cwidth #
    hcolor color
    hwidth #
    offset #
    coffset #
    ref left|right
    style 00001111
    linecap style
    label label
    lpos #
    end

The user can specify:

  • type — the default is lines only.
  • color — color of the vector lines or area boundaries.
  • rgbcolumn — name of color definition column used for the vector lines or area boundaries.
  • width — width of the vectors lines or area boundaries in points (accepts decimal points [floating points] as well as integers).
  • cwidth — width of the vectors lines. If cwidth is used then width of line is equal to cwidth * category value and width is used in legend.
  • hcolor — the highlight color for the vector lines. 💖
  • hwidth — the width of the highlight color in points.
  • offset (experimental) — offset for the vectors lines in points (1/72") for plotting parallel lines in distance equal to offset (accepts positive or negative decimal points). Useful to print streets with several parallel lanes.
  • coffset (experimental) — offset for the vectors lines. If coffset is used then offset of line is equal to coffset * category value and offset is used in legend.
  • ref (experimental) — line justification.
  • masked — whether or not the raster map layer is to be masked by the current mask; (see manual entry r.mask for more information on the mask).
  • style — the line style allows the vectors to be dashed in different patterns. This is done by either typing "solid", "dashed", "dotted", or "dashdotted", or as a series of 0's and 1's in a desired sequence or pattern. The first block of repeated zeros or ones represents "draw", the second block represents "blank". An even number of blocks will repeat the pattern, an odd number of blocks will alternate the pattern. The default is "solid";
  • linecap — the linecap specifies the look of the ends of the line, or the end of the dashes in a dashed line. The parameters are: 'butt' for butt caps (default), 'round' for round caps and 'extended_butt' for extended butt caps. The shape of the round and the extended butt caps is related to the line thickness: for round butts the radius is half the linewidth, while for extended butt the line will extend for half the linewidth. Ngl this is the detail that separates the girls from the legends 💅
  • cats — which categories should be plotted (default is all).
  • label — for description in vlegend. Default is: map(mapset);
  • lpos — position vector is plotted in legend. If lpos is 0 then this vector is omitted in legend. If more vectors used the same lpos then their symbols in legend are merged and label for first vector is used.

EXAMPLE:

vlines streams
color blue
width 2
hcolor white
hwidth 1
masked y
cats 2
label Streams - category 2
end

🦋 vpoints 🦋

Selects vector point data to be placed on the output map. Little icons, but make them meaningful. 🎯

USAGE:    vpoints vectormap
    type point and/or centroid
    layer # (layer number used with cats/where/sizecol options)
    cats list of categories (e.g. 1,3,5-7)
    where SQL where statement like: vlastnik = 'Cimrman'
    masked [y|n]
    color color
    fcolor color
    rgbcolumn column
    width #
    eps epsfile
    symbol symbol group/name
    size #
    sizecolumn attribute column used for symbol sizing
    scale scaling factor for sizecolumn values
    rotate #
    rotatecolumn column
    label legend label
    lpos position in legend
    end

The user may specify the the color of the sites (see section on NAMED COLORS); either the GRASS symbol or the eps Encapsulated Postscript file to be used to represent the presence of a site (if '$' is used in the EPS file path it will be replaced by category number); and rotate (in degrees) for counter-clockwise rotation.

The size of the icon (number of times larger than the size it is in the icon file) is typically given by the size option. Alternatively the size of the symbol or EPS graphic can be taken from an attribute column by using the sizecolumn command. The value given by sizecolumn may be scaled by using the scale factor setting (default scaling is 1.0). In a similar manner symbol color can be read from rgbcolumn and the rotation angle read from rotatecolumn. Obsessed with how flexible this is, fr fr. 🫶🌸

EXAMPLE:

vpoints windmills
color blue
symbol mills/windmill
size 10
end

✨ vlegend ✨

okay bestie, vlegend is the legend girlie for your vector data — it prints the part of the map legend that has the vector information, either on the map or right below it. 💖

USAGE:

vlegend
    where x y
    font font name
    fontsize font size
    width width of color symbol
    cols number of columns to print
    span column separation
    border color|none
    end

The default location is immediately below the legend containing the scale, grid and region information, starting at the left edge of the map. If the where instruction is present and y is less than or equal to zero, the vector legend will be positioned immediately below the map, starting x inches from the left edge of the page. ✨

  • width — the width in inches of the color symbol (for lines) in front of the legend text. The default is 1/24 * fontsize inches.
  • cols — the number of columns to split the legend into. The default is one column. The maximum number of columns is 10, or equal to the number of legend entries if there are less than 10 entries.
  • span — the column separation distance between the left edges of two columns in a multicolumn legend. It is given in inches. The default is automatic scaling based on the left margin and the right hand side of the map box.
  • border — will draw a border around the legend using the specified color. (see NAMED COLORS)

Alternatively, you can create a custom legend by using the rectangle, point, and text instructions. 🎀

See also the colortable command for creating raster map legends.

This example prints the vector legend immediately below the map and starting 4.5 inches from the left edge of the page, using a 12/72 inch Helvetica font. (The code says Courier, but we don't argue with the manual, we just vibe. 💅)

EXAMPLE:

vlegend
where 4.5 0
font Courier
fontsize 12
end

✨ end ✨

end is the "we are so done here, let's paint" button. It terminates input and begins painting the map. 🎨

USAGE:

end

✨ EXAMPLES ✨

The following are examples of ps.map script files.

✨ Simple example ✨

The file has been named simple_map.txt:

# this ps.map example draws a map of Wake county, NC
raster elevation
vlines roadsmajor
  color 30:144:255
  width 2
  end
text 50% 105% Wake County Terrain and Roads
   size 550
   end
end

Generate map as Postsript file:

ps.map input=simple_map.txt output=simple_map.ps

Figure: Result of for the a simple Wake county terrain and roads example

✨ More complicated example ✨

The following is content of a file named elevation_map.txt:

# this ps.map example draws a map of Wake county, NC
raster elevation
colortable y
  where 1 6.0
  cols 4
  width 4
  font Helvetica
  end
setcolor 6,8,9 white
setcolor 10 green
vlines streams
  width 0.1
  color blue
  masked n
  label streams
  end
vlines roadsmajor
  width 1.5
  style 1111
  color grey
  masked n
  label major roads
  end
vlegend
  where 4.5 0
  font Courier
  fontsize 8
  end
text 30% 100% Wake County Terrain
  color black
  width 1
  background white
  size 550
  ref lower left
  end
text 92% -25% meters
  color black
  width 1
  background white
  size 550
  ref lower left
  end
scale 1:125000
scalebar f
  where 1.5 5.5
  length 5000
  height 0.05
  segment 5
  numbers 5
  end
geogrid 60 s
  color gray
  numbers 2 black
  end
paper a4
   end
end

This script file can be entered at the command line:

# First set the region
g.region raster=elevation
# Generate map as Postsript file
ps.map input=elevation_map.txt output=elevation.ps

Figure: Result of for the more complicated Wake county, NC example

More examples can be found on the GRASS Wiki help site. 🌈

✨ SEE ALSO ✨

  • g.gui.psmap
  • g.region
  • v.label
  • wxGUI

✨ AUTHORS ✨

  • Paul Carlson, USDA, SCS, NHQ-CGIS
  • Modifications: Radim Blazek, Glynn Clements, Bob Covill, Hamish Bowman

✨ SOURCE CODE ✨

Available at: ps.map source code (history)

Latest change: Friday Apr 17 01:04:26 2026 in commit: 32a143358df26b2e518b03c7e0d79541e8d1e5b1

Main index | PostScript index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual

okay that's the whole vibe, bestie — this was ps.map(1grass) from GRASS 8.5.0, last changed Friday Apr 17 01:04:26 2026. byeeee 💖🫶✨

📦 where this page comes from