manpagez: man pages & more
man psscale(1)
Home | html | info | man
psscale(1)                            GMT                           psscale(1)




NAME

       psscale - Plot a gray or color scale-bar on maps


SYNOPSIS

       psscale   -Drefpoint  [   -B[p|s]parameters  ]  [  -Ccpt ] [  -Fbox ] [
       -Gzlo/zhi ]  [   -I[max_intens|low_i/high_i]  ]  [   -Jparameters  ]  [
       -Jz|Zparameters  ] [  -K ] [  -L[i][gap] ] [  -M ] [  -N[p|dpi ]] [  -O
       ] [  -P ] [  -Q ] [  -Rregion ] [  -S ] [  -U[stamp] ] [  -V[level] ] [
       -Wscale  ]  [   -Xx_offset ] [  -Yy_offset ] [  -Zzfile ] [ -pflags ] [
       -ttransp ]

       Note: No space is allowed between the option flag  and  the  associated
       arguments.


DESCRIPTION

       psscale  plots gray scales or color scales on maps. Both horizontal and
       vertical scales are supported. For CPTs with gradational colors  (i.e.,
       the lower and upper boundary of an interval have different colors) pss-
       cale will interpolate to give a continuous scale.  Variations in inten-
       sity due to shading/illumination may be displayed by setting the option
       -I. Colors may be spaced according to a  linear  scale,  all  be  equal
       size, or by providing a file with individual tile widths. The font used
       for the annotations along the scale and optional units is specified  by
       FONT_ANNOT_PRIMARY.   If  a  label  is  requested,  it  is plotted with
       FONT_LABEL.


REQUIRED ARGUMENTS

       -D[g|j|J|n|x]refpoint[+wlength[/width]][+e[b|f][length]][+h|v][+jjus-
       tify][+m[a|c|l|u]][+n[txt]][+odx[/dy]]
              Defines the reference point on the map for the color scale using
              one of four coordinate systems: (1) Use -Dg for map (user) coor-
              dinates, (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.).  All but -Dx
              requires both -R and -J to be specified.  For -Dj  or  -DJ  with
              codes TC, BC, ML, MR (i.e., centered on one of the map sides) we
              pre-calculate all further settings.  Specifically, the length is
              set  to  80%  of the map side, horizontal or vertical depends on
              the side, the offset is MAP_LABEL_OFFSET for Dj  with  an  extra
              offset MAP_FRAME_WIDTH for DJ, and annotations are placed on the
              side of the scale facing away from the map frame.  However,  you
              can  override  any of these with these modifiers: Append +w fol-
              lowed by the length and width of the color bar.  If width is not
              specified then it is set to 4% of the given length.  Give a neg-
              ative length to reverse the scale bar. Append +h to get a  hori-
              zontal scale [Default is vertical (+v)].  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.
              Finally, add +o to offset the color scale by dx/dy away from the
              refpoint point in the  direction  implied  by  justify  (or  the
              direction  implied  by  -Dj  or -DJ).  Add sidebar triangles for
              back- and/or foreground colors with +e. Append f (foreground) or
              b  (background)  for  only  one  sidebar triangle [Default gives
              both]. Optionally, append triangle height [Default is  half  the
              barwidth].   Move text to opposite side with +m[a|c|l|u].  Hori-
              zontal scale bars: Move annotations and labels above  the  scale
              bar  [Default is below]; the unit remains on the left.  Vertical
              scale bars: Move annotations and labels to the left of the scale
              bar  [Default  is to the right]; the unit remains below.  Append
              one or more of a, l or u to control which  of  the  annotations,
              label,  and unit that will be moved to the opposite side. Append
              c if you want to print a vertical label as a column  of  charac-
              ters (does not work with special characters).  Append +n to plot
              a rectangle with the NaN color at the start of the  bar,  append
              text to change label from NaN.


OPTIONAL ARGUMENTS

       -B[p|s]parameters
              Set  annotation,  tick,  and gridline interval for the colorbar.
              The x-axis label will plot beneath a horizontal bar  (or  verti-
              cally  to the right of a vertical bar), except when using -A. As
              an option, use the y-axis label to plot the  data  unit  to  the
              right of a horizontal bar (and above a vertical bar). When using
              -Ba or -Baf annotation and/or minor tick  intervals  are  chosen
              automatically.  If -B is omitted, or no annotation intervals are
              provided, the default is to annotate every color level based  on
              the numerical entries in the CPT (which may be overridden by ULB
              flags in the CPT). To specify custom text annotations for inter-
              vals, you must append ;annotation to each z-slice in the CPT.

       -Ccpt  cpt  is  the  CPT  to  be used. By default all color changes are
              annotated. To use a subset, add an extra column to the CPT  with
              a  L,  U,  or  B to annotate Lower, Upper, or Both color segment
              boundaries (but see -B). If not given, psscale will read  stdin.
              Like  grdview,  psscale can understand pattern specifications in
              the CPT. For CPTs where the z range is in meters, it may be use-
              ful  to  change to another unit when plotting.  To do so, append
              +Uunit to the file name.  Likewise, if the CPT uses another unit
              than  meter  and  you wish to plot the CPT versus meters, append
              +uunit.  If a GMT master dynamic CPT is given instead  then  its
              z-range  will be set to its default range (if it has one) before
              plotting.

       -F[+cclear-
       ances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]][+s[[dx/dy/][shade]]]
              Without further options, draws a rectangular border  around  the
              scale  using  MAP_FRAME_PEN; specify a different pen with +ppen.
              Add +gfill to fill the scale box [no fill].  Append  +cclearance
              where clearance is either gap, xgap/ygap, or lgap/rgap/bgap/tgap
              where these items are uniform, separate in x-  and  y-direction,
              or individual side spacings between scale and border.  Append +i
              to draw a secondary, inner border as well. We use a uniform  gap
              between borders of 2p and the MAP_DEFAULTS_PEN unless other val-
              ues are specified. Append +r to draw rounded rectangular borders
              instead,  with  a 6p corner radius. You can override this radius
              by appending another value. Finally, append +s to draw an offset
              background  shaded region. Here, dx/dy indicates the shift rela-
              tive to the foreground frame [4p/-4p] and shade  sets  the  fill
              style to use for shading [gray50].

       -Gzlo/zhi
              Truncate  the incoming CPT so that the lowest and highest z-lev-
              els are to zlo and zhi.  If one of these equal NaN then we leave
              that  end  of  the CPT alone.  The truncation takes place before
              the plotting.

       -I[max_intens|low_i/high_i]
              Add illumination effects. Optionally, set the range of  intensi-
              ties  from  -  to  +  max_intens.  If  not specified, 1 is used.
              Alternatively, append low/high intensities to specify  an  asym-
              metric range [Default is no illumination].

       -Jparameters (more a|)
              Select map projection.

       -Jz|Zparameters (more a|)
              Set z-axis scaling; same syntax as -Jx.

       -K (more a|)
              Do not finalize the PostScript plot.

       -L[i][gap]
              Gives  equal-sized  color  rectangles. Default scales rectangles
              according to the z-range in the CPT (Also see -Z). If  set,  any
              equal interval annotation set with -B will be ignored. If gap is
              appended and the CPT is discrete we will center each  annotation
              on  each  rectangle,  using  the  lower boundary z-value for the
              annotation. If i is prepended we  annotate  the  interval  range
              instead.  If  -I  is used then each rectangle will have its con-
              stant color modified by the specified intensity.

       -M     Force a monochrome graybar using the (television) YIQ  transfor-
              mation.

       -N[p|dpi]
              Controls  how  the  color scale is represented by the PostScript
              language.  To preferentially draw color  rectangles  (e.g.,  for
              discrete  colors),  append  p.  Otherwise we will preferentially
              draw images (e.g., for continuous  colors).   Optionally  append
              effective dots-per-inch for rasterization of color scales [600].

       -O (more a|)
              Append to existing PostScript plot.

       -P (more a|)
              Select aPortraita plot orientation.

       -Q     Select logarithmic scale  and  power  of  ten  annotations.  All
              z-values  in  the CPT will be converted to p = log10(z) and only
              integer p  values  will  be  annotated  using  the  10^p  format
              [Default is linear scale].

       -Rwest/east/south/north[/zmin/zmax][+r][+uunit]
              west, east, south, and north specify the region of interest, and
              you   may   specify   them   in   decimal    degrees    or    in
              [A+-]dd:mm[:ss.xxx][W|E|S|N]  format Append +r if lower left and
              upper right map coordinates are given instead  of  w/e/s/n.  The
              two  shorthands  -Rg  and -Rd stand for global domain (0/360 and
              -180/+180 in longitude respectively, with -90/+90 in  latitude).
              Alternatively  for grid creation, give Rcodelon/lat/nx/ny, where
              code is a 2-character combination of L, C, R (for left,  center,
              or  right)  and T, M, B for top, middle, or bottom. e.g., BL for
              lower left.  This indicates which point on a rectangular  region
              the lon/lat coordinate refers to, and the grid dimensions nx and
              ny with grid spacings via -I is used to create the corresponding
              region.   Alternatively,  specify  the  name of an existing grid
              file and the -R settings (and grid spacing, if  applicable)  are
              copied from the grid. Appending +uunit expects projected (Carte-
              sian) coordinates compatible with chosen  -J  and  we  inversely
              project  to determine actual rectangular geographic region.  For
              perspective view (-p), optionally append /zmin/zmax.  In case of
              perspective view (-p), a z-range (zmin, zmax) can be appended to
              indicate the third dimension. This needs to be  done  only  when
              using  the -Jz option, not when using only the -p option. In the
              latter case a perspective view of the plane is plotted, with  no
              third dimension.

       For perspective view p, optionally append /zmin/zmax. (more a|)

       -S     Do not separate different color intervals with black grid lines.

       -U[[just]/dx/dy/][c|label] (more a|)
              Draw GMT time stamp logo on plot.

       -V[level] (more a|)
              Select verbosity level [c].

       -Wscale
              Multiply all z-values in the CPT  by  the  provided  scale.   By
              default the CPT is used as is.

       -X[a|c|f|r][x-shift[u]]

       -Y[a|c|f|r][y-shift[u]] (more a|)
              Shift plot origin.

       -Zzfile
              File  with  colorbar-width per color entry. By default, width of
              entry is scaled to color range, i.e., z = 0-100 gives twice  the
              width as z = 100-150 (Also see -L).

       -p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more a|)
              Select  perspective  view.  (Required -R and -J for proper func-
              tioning).

       -t[transp] (more a|)
              Set PDF transparency level in percent.

       -^ or just -
              Print a short message about the  syntax  of  the  command,  then
              exits (NOTE: on Windows just use -).

       -+ or just +
              Print  an extensive usage (help) message, including the explana-
              tion of any module-specific  option  (but  not  the  GMT  common
              options), then exits.

       -? or no arguments
              Print a complete usage (help) message, including the explanation
              of all options, then exits.


EXAMPLES

       To plot a a horizontal color scale (12 cm long; 0.5  cm  wide)  at  the
       reference  point  (8,1)  (paper  coordinates) with justification at top
       center and automatic annotation interval, do

              gmt makecpt -T-200/1000/100 -Crainbow > t.cpt
              gmt psscale -Ct.cpt -Dx8c/1c+w12c/0.5c+jTC+h -Bxaf+l"topography" -By+lkm > map.ps

       To append a vertical color scale (7.5 cm long; 1.25  cm  wide)  to  the
       right  of  a  plot that is 6 inch wide and 4 inch high, using illumina-
       tion, and show back- and foreground  colors,  and  annotating  every  5
       units,  we  provide  the reference point and select the left-mid anchor
       point via

              gmt psscale -Dx6.5i+jLM/2i+w7.5c/1.25c+e -O -Ccolors.cpt -I -Bx5+lBATHYMETRY -By+lm >> map.ps

       To overlay a horizontal color scale (4 inches long and  default  width)
       above  a Mercator map produced by a previous call, ensuring a 2 cm off-
       set from the map frame, use

              gmt psscale -DjCT+w4i+o0/2c+h -O -Ccolors.cpt -Baf -R -J >> map.ps


NOTES

       When the CPT is discrete and no illumination is  specified,  the  color
       bar  will  be painted using polygons. For all other cases we must paint
       with an image. Some color printers may give slightly  different  colors
       for the two methods given identical RGB values.


SEE ALSO

       gmt(1), makecpt(1), gmtlogo(1), grd2cpt(1), psimage(1), pslegend(1)


COPYRIGHT

       2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe



5.4.2                            Jun 24, 2017                       psscale(1)

gmt5 5.4.2 - Generated Thu Jun 29 15:46:23 CDT 2017
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.