psbasemap

Plot base maps and frames

Synopsis

gmt psbasemap -Jparameters -Rwest/east/south/north[/zmin/zmax][+r][+uunit] [ -B[p|s]parameters ] [ -A[file] ] [ -Dinsetbox ] [ -Fbox ] [ -K ] [ -Lscalebar ] [ -O ] [ -P ] [ -Trose ] [ -Tmag_rose ] [ -U[stamp] ] [ -V[level] ] [ -X[a|c|f|r][xshift] ] [ -Y[a|c|f|r][yshift] ] [ -fflags ] [ -pflags ] [ -ttransp ] [ --PAR=value ]

Description

Creates a basic or fancy basemap with axes, fill, and titles. Several map projections are available, and the user may specify separate tick-mark intervals for boundary annotation, ticking, and (optionally) gridlines. A simple map scale (-L) or directional rose (-T) may also be plotted. At least one of the options -B, -L, or -T must be specified.

Required Arguments

-Jparameters

Specify the projection. (See full description) (See cookbook summary) (See projections table).

-Rxmin/xmax/ymin/ymax[+r][+uunit]

Specify the region of interest. (See full description) (See cookbook information).

For perspective view -p, optionally append /zmin/zmax. (more …)

Optional Arguments

-A[file]

No plotting is performed. Instead, we determine the geographical coordinates of the polygon outline for the (possibly oblique) rectangular map domain. The plot domain must be given via -R and -J, with no other options allowed. The sampling interval is controlled via MAP_LINE_STEP parameter. The coordinates are written to file or to standard output if no file is specified.

-B[p|s]parameters

Set map boundary frame and axes attributes. (See full description) (See cookbook information).

-F[d|l|t][+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]][+s[[dx/dy/][shade]]]

Without further options, draws a rectangular border around any map inset (-D; classic mode only), map scale (-L) or map rose (-T) using MAP_FRAME_PEN. Used in combination with -D, -L or -T. Append d for map inset, l for map scale, or t for map rose to specify which plot embellisment the -F parameters should be applied to [default uses the same panel parameters for all selected map embellishments]. The following modifiers can be appended to -F, with additional explanation and examples provided in the The background panel cookbook section:

  • +cclearance where clearance is either gap, xgap/ygap, or lgap/rgap/bgap/tgap and gap gives a uniform clearance, xgap/ygap gives separate clearances in the x- and y- directions, and lgap/rgap/bgap/tgap gives individual clearances between the map embellishment and the border for each side.

  • +gfill to fill the box with a color specified by fill [default is no fill].

  • +i[[gap/]pen] to draw a secondary, inner border as well. Optionally, specify the gap between the inner and outer border and the pen for the inner border [default is a uniform gap between borders of 2p and the MAP_DEFAULT_PEN].

  • +ppen to specify different pen attributes.

  • +r[radius] to draw rounded rectangular borders instead with a corner radius set by radius (append units) [defaults is 6p].

  • +s[[dx/dy/][shade]] to draw an offset background shaded region. Here, dx/dy indicates the shift relative to the foreground frame [default is 4p/-4p] and shade sets the fill style to use for shading [default is gray50].

-L[g|j|J|n|x]refpoint+wlength[e|f|k|M|n|u][+aalign][+c[[slon/]slat]][+f][+jjustify][+l[label]][+odx[/dy]][+u][+v]

Draw a simple map scale at the location defined by the reference (refpoint) and anchor point (set by +odx[/dy] and/or +jjustify). Give the reference point on the map for the rose using one of four coordinate systems:

  1. Append glon/lat for map coordinates. Requires both -R and -J to be set.

  2. Append jcode or Jcode for setting the refpoint via a 2-char justification code that refers to the (invisible) projected map bounding box. Requires both -R and -J to be set.

  3. Append nxn/yn for normalized bounding box coordinates (0-1). Requires both -R and -J to be set.

  4. Append xx/y for plot coordinates (append cm, inch, or ppoint).

The following modifiers can be appended to -L (+w is required), with additional explanation and examples provided in the Placing map scales cookbook section. For Cartesian projectsion, the modifiers +c and +f are not allowed and no units should be appended in +w.

  • +wlength to set scale length in km, or append unit from e|f|k|M|n|u.

  • +aalign to change the label alignment (choose among l(eft), r(ight), t(op), and b(ottom)) [default is t(op)].

  • +c[[slon/]slat]] to control where on a geographic map the scale applies. Map scale is calculated for latitude slat (optionally supply longitude slon for oblique projections [default is central meridian]). If +c is not given we default to the location of the refpoint. If +c is given with no arguments then we select the scale origin to be the middle of the map.

  • +f to get a “fancy” scale [default is plain].

  • +jjustify to set the justification anchor point, where justify is a 2-character justification code that is a combination of a horizontal (L, C, or R) and a vertical (T, M, or B) code. Note: If j is used to set the reference point then justify defaults to the same as refpoint; if J is used then justify defaults to the mirror opposite of refpoint; if g, n, or x is used to set the reference point then justify defaults to MC.

  • +l[label] to add a scale label. If label is not provided, we use the distance unit provided in +w [default is k(m)]. The label alignment is set by +a [default is t(op)]. Requires +f.

  • +odx[/dy] to offset the anchor point by dx and optionally dy (if different than dx).

  • +u to append the unit set by +w to all distance annotations along the scale (for the plain scale, +u will instead select the unit to be appended to the distance length).

  • +v to get a vertical rather than a horizontal Cartesian scale.

Note: Use FONT_LABEL to change the label font and FONT_ANNOT_PRIMARY to change the annotation font. The height of the map scale is controlled by MAP_SCALE_HEIGHT, and the pen thickness is set by MAP_TICK_PEN_PRIMARY. Optionally, use -F to place a panel behind the scale.

-Td[g|j|J|n|x]refpoint[+f|F[level]][+jjustify][+l[w,e,s,n]][+odx[/dy]][+wwidth]

Draw a map directional rose on the map at the location defined by the reference (refpoint) and anchor point (set by +odx[/dy] and/or +jjustify). Give the reference point on the map for the rose using one of four coordinate systems:

  1. Append glon/lat for map coordinates. Requires both -R and -J to be set.

  2. Append jcode or Jcode for setting the refpoint via a 2-char justification code that refers to the (invisible) projected map bounding box. Requires both -R and -J to be set.

  3. Append nxn/yn for normalized bounding box coordinates (0-1). Requires both -R and -J to be set.

  4. Append xx/y for plot coordinates (append cm, inch, or ppoint).

The following optional modifiers can be appended to -Td, with additional explanation and examples provided in the Placing directional map roses cookbook section. Optionally, use -F to place a panel behind the directional rose.

  • +f[level] to get a “fancy” rose, and optionally specify the level of fanciness. Level 1 draws the two principal E-W, N-S orientations, 2 adds the two intermediate NW-SE and NE-SW orientations, while 3 adds the eight minor orientations WNW-ESE, NNW-SSE, NNE-SSW, and ENE-WSW [default is 1]. Use +F to force the labels to be readable from the south if the projection has extensive rotation of the directions.

  • +jjustify to set the justification anchor point, where justify is a 2-character justification code that is a combination of a horizontal (L, C, or R) and a vertical (T, M, or B) code. Note: If j is used to set the reference point then justify defaults to the same as refpoint; if J is used then justify defaults to the mirror opposite of refpoint; if g, n, or x is used to set the reference point then justify defaults to MC.

  • +l[w,e,s,n] to label the cardinal points W,E,S,N. Optionally, append your own four comma-separated strings to override the default. Skip a specific label by leaving it blank.

  • +odx[/dy] to offset the anchor point by dx and optionally dy (if different than dx).

  • +wwidth to set the width of the rose in plot coordinates (append inch, cm, or points), or append unit % for a size in percentage of map width [10%].

For further information, see the Map Embellishment section on Directional Roses.

-Tm[g|j|J|n|x]refpoint[+ddec[/dlabel]]][+ipen][+jjustify][+l[w,e,s,n]][+ppen][+tints][+odx[/dy]][+wwidth]

Draw a map magnetic rose on the map at the location defined by the reference (refpoint) and anchor point (set by +odx[/dy] and/or +jjustify). Give the reference point on the map for the rose using one of four coordinate systems:

  1. Append glon/lat for map coordinates. Requires both -R and -J to be set.

  2. Append jcode or Jcode for setting the refpoint via a 2-char justification code that refers to the (invisible) projected map bounding box. Requires both -R and -J to be set.

  3. Append nxn/yn for normalized bounding box coordinates (0-1). Requires both -R and -J to be set.

  4. Append xx/y for plot coordinates (append cm, inch, or ppoint).

The following optional modifiers can be appended to -Tm, with additional explanation and examples provided in the Placing magnetic map roses cookbook section. Optionally, use -F to place a panel behind the magnetic rose.

  • +ddec[/dlabel] to assign the magnetic declination and set dlabel, which is a label for the magnetic compass needle (omit dlabel to format a label from dec, or give - to bypass labeling). With +d, both directions to geographic and magnetic north are plotted [default is geographic only].

  • +ipen to draw the outline of the inner circle in the specified pen.

  • +jjustify to set the justification anchor point, where justify is a 2-character justification code that is a combination of a horizontal (L, C, or R) and a vertical (T, M, or B) code. Note: If j is used to set the reference point then justify defaults to the same as refpoint; if J is used then justify defaults to the mirror opposite of refpoint; if g, n, or x is used to set the reference point then justify defaults to MC.

  • +l[w,e,s,n] to label the cardinal points W,E,S,N and append your own four comma-separated strings to override the default. Skip a specific label by leaving it blank. If the north label is * then a north star is plotted instead of the north label.

  • +ppen to draw the outline of the outer circle in the specified pen.

  • +tints to specify the annotation and two tick interval levels for the geographic and magnetic directions by providing three slash-separated intervals. Specify separate intervals by appending three slash-separated geographic intervals followed by three slash-separated magnetic intervals [default is 30/5/1]. Note: If MAP_EMBELLISHMENT_MODE is auto and the compass size is smaller than 2.5 cm then the interval defaults are reset to 90/30/3/9450/15/3.

  • +odx[/dy] to offset the anchor point by dx and optionally dy (if different than dx).

  • +wwidth to set the width of the rose in plot coordinates (append inch, cm, or points). or append unit % for a size in percentage of map width [15%].

For further information, see the Map Embellishment section on Magnetic Roses.

-U[label|+c][+jjust][+odx[/dy]]

Draw GMT time stamp logo on plot. (See full description) (See cookbook information).

-V[level]

Select verbosity level [w]. (See full description) (See cookbook information).

-X[a|c|f|r][xshift]

Shift plot origin. (See full description) (See cookbook information).

-Y[a|c|f|r][yshift]

Shift plot origin. (See full description) (See cookbook information).

-f[i|o]colinfo (more …)

Specify data types of input and/or output columns. This applies only to the coordinates specified in the -R option.

-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more …)

Select perspective view.

-ttransp[/transp2] (more …)

Set transparency level(s) in percent.

-^ or just -

Print a short message about the syntax of the command, then exit (Note: on Windows just use -).

-+ or just +

Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.

-? or no arguments

Print a complete usage (help) message, including the explanation of all options, then exit.

--PAR=value

Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Classic Mode Arguments

These options are used to manipulate the building of layered GMT PostScript plots in classic mode. They are not available when using GMT modern mode.

-K (more …)

Do not finalize the PostScript plot.

-O (more …)

Append to existing PostScript plot.

-P (more …)

Select “Portrait” plot orientation.

-Dxmin/xmax/ymin/ymax[+r][+sfile][+t][+uunit] | -D[g|j|J|n|x]refpoint+wwidth[/height][+jjustify][+odx[/dy]][+sfile][+t]

Draw a simple map inset box on the map. Requires -F. Specify the box in one of three ways: (a) Give west/east/south/north of geographic rectangle bounded by parallels and meridians; append r if the coordinates instead are the lower left and upper right corners of the desired rectangle. (b) Give xmin/xmax/ymin/ymax of bounding rectangle in projected coordinates and optionally append +uunit [Default coordinate unit is meter (e)]. (c) Give the reference point on the map for the inset using one of four coordinate systems: (1) Use -Dg for map (user) coordinates, (2) use -Dj or -DJ for setting refpoint via a 2-char justification code that refers to the (invisible) map domain rectangle, (3) use -Dn for normalized (0-1) coordinates, or (4) use -Dx for plot coordinates (inches, cm, etc.). Append +wwidth[/height] of bounding rectangle or box in plot coordinates (inches, cm, etc.). By default, the anchor point on the scale is assumed to be the bottom left corner (BL), but this can be changed by appending +j followed by a 2-char justification code justify (see pstext). Note: If -Dj is used then justify defaults to the same as refpoint, if -DJ is used then justify defaults to the mirror opposite of refpoint. Add +o to offset the inset fig by dx/dy away from the refpoint point in the direction implied by justify (or the direction implied by -Dj or -DJ). If you need access to the placement of the lower left corner of the map inset and its dimensions in the current map unit, use +sfile to write this information to file. Alternatively, you may append +t to translate the plot origin to the lower left corner of the map inset. Specify inset box attributes via the -F option [outline only].

Examples

The following section illustrates the use of the options by giving some examples for the available map projections. Note how scales may be given in several different ways depending on the projection. Also note the use of upper case letters to specify map width instead of map scale.

Non-geographical Projections

Linear x-y plot

To make a linear x/y frame with all axes, but with only left and bottom axes annotated, using xscale = yscale = 1 cm per unit, ticking every 1 unit and annotating every 2, and using xlabel = “Distance” and ylabel = “No of samples”, use

gmt psbasemap -R0/9/0/5 -Jx1c -Bf1a2 -Bx+lDistance -By+l"No of samples" -BWeSn -P > linear.ps

Log-log plot

To make a log-log frame with only the left and bottom axes, where the x-axis is 25 cm and annotated every 1-2-5 and the y-axis is 15 cm and annotated every power of 10 but has tick-marks every 0.1, run

gmt psbasemap -R1/10000/1e20/1e25 -JX25cl/15cl -Bx2+lWavelength -Bya1pf3+lPower -BWS -P > loglog.ps

Power axes

To design an axis system to be used for a depth-sqrt(age) plot with depth positive down, ticked and annotated every 500m, and ages (in millions of years) annotated at 1 My, 4 My, 9 My etc., use

gmt psbasemap -R0/100/0/5000 -Jx1cp0.5/-0.001c -Bx1p+l"Crustal age" -By500+lDepth -P > power.ps

Polar (theta,r) plot

For a base map for use with polar coordinates, where the radius from 0 to 1000 should correspond to 3 inch and with gridlines and ticks intervals automatically determined, use

gmt psbasemap -R0/360/0/1000 -JP6i -Bafg -P > polar.ps

Cylindrical Map Projections

Cassini

A 10-cm-wide basemap using the Cassini projection may be obtained by

gmt psbasemap -R20/50/20/35 -JC35/28/10c -P -Bafg -B+tCassini > cassini.ps

Mercator [conformal]

A Mercator map with scale 0.025 inch/degree along equator, and showing the length of 5000 km along the equator (centered on 1/1 inch), may be plotted as

gmt psbasemap -R90/180/-50/50 -Jm0.025i -Bafg -B+tMercator -Lx1i/1i+c0+w5000k -P > mercator.ps

Miller

A global Miller cylindrical map with scale 1:200,000,000 may be plotted as

gmt psbasemap -Rg -Jj180/1:200000000 -Bafg -B+tMiller -P > miller.ps

Oblique Mercator [conformal]

To create a page-size global oblique Mercator basemap for a pole at (90,30) with gridlines every 30 degrees, run

gmt psbasemap -R0/360/-70/70 -Joc0/0/90/30/0.064cd -B30g30 -B+t"Oblique Mercator" -P > oblmerc.ps

Transverse Mercator [conformal]

A regular Transverse Mercator basemap for some region may look like

gmt psbasemap -R69:30/71:45/-17/-15:15 -Jt70/1:1000000 -Bafg -B+t"Survey area" -P > transmerc.ps

Equidistant Cylindrical Projection

This projection only needs the central meridian and scale. A 25 cm wide global basemap centered on the 130E meridian is made by

gmt psbasemap -R-50/310/-90/90 -JQ130/25c -Bafg -B+t"Equidistant Cylindrical" -P > cyl_eqdist.ps

Universal Transverse Mercator [conformal]

To use this projection you must know the UTM zone number, which defines the central meridian. A UTM basemap for Indo-China can be plotted as

gmt psbasemap -R95/5/108/20+r -Ju46/1:10000000 -Bafg -B+tUTM -P > utm.ps

Cylindrical Equal-Area

First select which of the cylindrical equal-area projections you want by deciding on the standard parallel. Here we will use 45 degrees which gives the Gall projection. A 9 inch wide global basemap centered on the Pacific is made by

gmt psbasemap -Rg -JY180/45/9i -Bafg -B+tGall -P > gall.ps

Conic Map Projections

Albers [equal-area]

A basemap for middle Europe may be created by

gmt psbasemap -R0/90/25/55 -Jb45/20/32/45/0.25c -Bafg -B+t"Albers Equal-area" -P > albers.ps

Lambert [conformal]

Another basemap for middle Europe may be created by

gmt psbasemap -R0/90/25/55 -Jl45/20/32/45/0.1i -Bafg -B+t"Lambert Conformal Conic" -P > lambertc.ps

Conic Equidistant

Yet another basemap of width 6 inch for middle Europe may be created by

gmt psbasemap -R0/90/25/55 -JD45/20/32/45/6i -Bafg -B+t"Equidistant conic" -P > econic.ps

Polyconic

A basemap for north America may be created by

gmt psbasemap -R-180/-20/0/90 -JPoly/4i -Bafg -B+tPolyconic -P > polyconic.ps

Azimuthal Map Projections

Lambert [equal-area]

A 15-cm-wide global view of the world from the vantage point -80/-30 will give the following basemap:

gmt psbasemap -Rg -JA-80/-30/15c -Bafg -B+t"Lambert Azimuthal" -P > lamberta.ps

Follow the instructions for stereographic projection if you want to impose rectangular boundaries on the azimuthal equal-area map but substitute -Ja for -Js.

Azimuthal Equidistant

A 15-cm-wide global map in which distances from the center (here 125/10) to any point is true can be obtained by:

gmt psbasemap -Rg -JE125/10/15c -Bafg -B+tEquidistant -P > equi.ps

Gnomonic

A view of the world from the vantage point -100/40 out to a horizon of 60 degrees from the center can be made using the Gnomonic projection:

gmt psbasemap -Rg -JF-100/40/60/6i -Bafg -B+tGnomonic -P > gnomonic.ps

Orthographic

A global perspective (from infinite distance) view of the world from the vantage point 125/10 will give the following 6-inch-wide basemap:

gmt psbasemap -Rg -JG125/10/6i -Bafg -B+tOrthographic -P > ortho.ps

General Perspective

The -JG option can be used in a more generalized form, specifying altitude above the surface, width and height of the view point, and twist and tilt. A view from 160 km above -74/41.5 with a tilt of 55 and azimuth of 210 degrees, and limiting the viewpoint to 30 degrees width and height will product a 6-inch-wide basemap:

gmt psbasemap -Rg -JG-74/41.5/6i+z160+a210+t55+v30 -Bafg -B+t"General Perspective" -P > genper.ps

Stereographic [conformal]

To make a polar stereographic projection basemap with radius = 12 cm to -60 degree latitude, with plot title “Salinity measurements”, using 5 degrees annotation/tick interval and 1 degree gridlines, run

gmt psbasemap -R-45/45/-90/-60 -Js0/-90/12c/-60 -B5g1 -B+t"Salinity measurements" > stereo1.ps

To make a 12-cm-wide stereographic basemap for Australia from an arbitrary view point (not the poles), and use a rectangular boundary, we must give the pole for the new projection and use the -R option to indicate the lower left and upper right corners (in lon/lat) that will define our rectangle. We choose a pole at 130/-30 and use 100/-45 and 160/-5 as our corners. The command becomes

gmt psbasemap -R100/-45/160/-5+r -JS130/-30/12c -Bafg -B+t"General Stereographic View" -P > stereo2.ps

Miscellaneous Map Projections

Hammer [equal-area]

The Hammer projection is mostly used for global maps and thus the spherical form is used. To get a world map centered on Greenwich at a scale of 1:200000000, use

gmt psbasemap -Rd -Jh0/1:200000000 -Bafg -B+tHammer -P > hammer.ps

Sinusoidal [equal-area]

To make a sinusoidal world map centered on Greenwich, with a scale along the equator of 0.02 inch/degree, use

gmt psbasemap -Rd -Ji0/0.02i -Bafg -B+tSinusoidal -P > sinus1.ps

To make an interrupted sinusoidal world map with breaks at 160W, 20W, and 60E, with a scale along the equator of 0.02 inch/degree, run the following sequence of commands:

gmt psbasemap -R-160/-20/-90/90 -Ji-90/0.02i -Bx30g30 -By15g15 -BWesn -K -P > sinus_i.ps
gmt psbasemap -R-20/60/-90/90 -Ji20/0.02i -Bx30g30 -By15g15 -Bwesn -O -K -X2.8i >> sinus_i.ps
gmt psbasemap -R60/200/-90/90 -Ji130/0.02i -Bx30g30 -By15g15 -BwEsn -O -X1.6i >> sinus_i.ps

Eckert IV [equal-area]

Pseudo-cylindrical projection typically used for global maps only. Set the central longitude and scale, e.g.,

gmt psbasemap -Rg -Jkf180/0.064c -Bafg -B+t"Eckert IV" -P > eckert4.ps

Eckert VI [equal-area]

Another pseudo-cylindrical projection typically used for global maps only. Set the central longitude and scale, e.g.,

gmt psbasemap -Rg -Jks180/0.064c -Bafg -B+t"Eckert VI" -P > eckert6.ps

Robinson

Projection designed to make global maps “look right”. Set the central longitude and width, e.g.,

gmt psbasemap -Rd -JN0/8i -Bafg -B+tRobinson -P > robinson.ps

Winkel Tripel

Yet another projection typically used for global maps only. You can set the central longitude, e.g.,

gmt psbasemap -R90/450/-90/90 -JR270/25c -Bafg -B+t"Winkel Tripel" -P > winkel.ps

Mollweide [equal-area]

The Mollweide projection is also mostly used for global maps and thus the spherical form is used. To get a 25-cm-wide world map centered on the Dateline:

psbasemap -Rg -JW180/25c -Bafg -B+tMollweide -P > mollweide.ps

Van der Grinten

The Van der Grinten projection is also mostly used for global maps and thus the spherical form is used. To get a 18-cm-wide world map centered on the Dateline:

gmt psbasemap -Rg -JV180/18c -Bafg -B+t"Van der Grinten" -P > grinten.ps

Arbitrary rotation

If you need to plot a map but have it rotated about a vertical axis then use the -p option. For instance, the rotate the basemap below 90 degrees about an axis centered on the map, try

gmt psbasemap -R10/40/10/40 -JM10c -P -Bafg -B+t"I am rotated" -p90+w25/25 -Xc -P > rotated.ps

Custom Labels or Intervals

The -B option sets up a regular annotation interval and the annotations derive from the corresponding x, y, or z coordinates. However, some applications requires special control on which annotations to plot and even replace the annotation with other labels. This is achieved by using cintfile in the -B option, where intfile contains all the information about annotations, ticks, and even gridlines. Each record is of the form coord type [label], where coord is the coordinate for this annotation (or tick or gridline), type is one or more letters from a (annotation), i interval annotation, f tickmark, and g gridline. Note that a and i are mutually exclusive and cannot both appear in the same intfile. Both a and i requires you to supply a label which is used as the plot annotation. If not given then a regular formatted annotation based on the coordinate will occur.

Restrictions

For some projections, a spherical earth is implicitly assumed. A warning will notify the user if -V is set.

Bugs

The -B option is somewhat complicated to explain and comprehend. However, it is fairly simple for most applications (see examples).

See Also

gmt, gmt.conf, gmtcolors