Provided by: gmt-common_5.2.1+dfsg-3build1_all bug

NAME

       psimage - Place images or EPS files on maps

SYNOPSIS

       psimage  imagefile  [  refpoint  ]  [  box  ]  [  [b|f|t]color  ]  [   ]  [ parameters ] [
       z|Zparameters ]  [   ]  [   ]  [   ]  [   ]  [  west/east/south/north[/zmin/zmax][r]  ]  [
       [just/dx/dy/][c|label]  ] [ [level] ] [ x_offset ] [ y_offset ] [ -ccopies ] [ -p<flags> ]
       [ -t<transp> ]

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

DESCRIPTION

       psimage reads an Encapsulated PostScript file or a raster image file and  plots  it  on  a
       map.  The  image  can  be scaled arbitrarily, and 1-bit raster images can be (1) inverted,
       i.e., black pixels (on) becomes white (off) and vice versa, or (2) colorized, by assigning
       different foreground and background colors, and (3) made transparent where one of back- or
       foreground is painted only. As an option, the user may choose to  convert  colored  raster
       images  to  grayscale using TV's YIQ-transformation. For raster files, the user can select
       which color to be made transparent. The user may also choose to replicate the image which,
       when preceded by appropriate clip paths, may allow larger custom-designed fill patterns to
       be implemented (the -Gp mechanism offered in most  GMT  programs  is  limited  to  rasters
       smaller than 146 by 146).

REQUIRED ARGUMENTS

       imagefile
              This  must  be an Encapsulated PostScript (EPS) file or a raster image. An EPS file
              must contain an appropriate BoundingBox. A raster file can have a depth  of  1,  8,
              24,  or  32 bits and is read via GDAL.  Note: If GDAL was not configured during GMT
              installation then only Sun raster files are  supported  natively.   You  must  then
              convert other formats to Sun raster files before use.

OPTIONAL ARGUMENTS

       -D[g|j|J|n|x]refpoint+edpi+w[-]width[/height][+jjustify][+nnx[/ny] ][+odx[/dy]]
              Sets reference point on the map for the image 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.).   All  but  -Dx  requires both -R and -J to be specified.  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 color scale by dx/dy away from the  refpoint  point
              in  the  direction  implied  by  justify  (or the direction implied by -Dj or -DJ).
              Specify image size in one of two ways: Use +edpi to set the dpi  of  the  image  in
              dots  per  inch,  or  use  +w[-]width[/height] to set the width (and height) of the
              image in plot coordinates (inches, cm, etc.). If height is not given, the  original
              aspect  ratio  of the image is maintained. If width is negative we use the absolute
              value and interpolate image to the device resolution  using  the  PostScript  image
              operator.  Optionally,  use  +nnx[/ny] to replicate the image nx times horizontally
              and ny times vertically. If ny is omitted, it will be identical to nx  [Default  is
              1/1].

       -F[+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]][+s[[dx/dy/][shade]]]
              Without  further  options,  draws  a  rectangular  border  around  the  image using
              MAP_FRAME_PEN; specify a different pen with +ppen.  Add +gfill to  fill  the  image
              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  values  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 relative to the foreground  frame  [4p/-4p]
              and shade sets the fill style to use for shading [gray50].

       -Jparameters (more ...)
              Select map projection. (Used only with -p)

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

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

       -M     Convert   color   image   to   monochrome   grayshades   using   the   (television)
              YIQ-transformation.

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

       -P (more ...)
              Select "Portrait" plot orientation.

       -R[unit]xmin/xmax/ymin/ymax[r] (more ...)
              Specify the region of interest. (Used only with -p)

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

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

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

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

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

       -ccopies (more ...)
              Specify number of plot copies [Default is 1].

       These options are for 1-bit images only. They have no effect when plotting other images or
       PostScript files.

       -G[b|f|t]color

              -Gb    Sets  background  color  (replace  white  pixel)  of 1-bit images. Use - for
                     transparency (and set -Gf to the desired color).

              -Gf    Sets foreground color (replace black pixel)  of  1-bit  images.  Use  -  for
                     transparency (and set -Gb to the desired color).

              -I     Invert 1-bit image before plotting. This is what is done when you use -GP in
                     other GMT programs.

       These options are for 8-, 24-, and 32-bit raster images only. They  have  no  effect  when
       plotting 1-bit images or PostScript files.

       -Gt    Assigns  the  color that is to be made transparent. Sun Raster files do not support
              transparency, so indicate here which color to be made transparent.

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

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

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

       -+ or just +
              Print  an  extensive  usage  (help)  message,  including  the  explanation  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  options,  then
              exits.

       --version
              Print GMT version and exit.

       --show-datadir
              Print full path to GMT share directory and exit.

       gmt,  pslegend,  To  plot  the image logo.jpg, scaling it be 1 inch wide (height is scaled
       accordingly), and outline with a thin, blue pen, use

              gmt psimage logo.jpg -Dx0/0+w1i -F+pthin,blue > image.ps

       To include an Encapsulated PostScript file tiger.eps with its upper right corner 2 inch to
       the  right and 1 inch up from the current location, and have its width scaled to 3 inches,
       while keeping the aspect ratio, use

              gmt psimage tiger.eps -Dx2i/1i+jTR+w3i > image.ps

       To replicate the 1-bit raster image template 1_bit.ras, colorize it (brown background  and
       red foreground), and setting each of 5 by 5 tiles to be 1 cm wide, use

              gmt psimage 1_bit.ras -Gbbrown -Gfred -Dx0/0+w1c+n5 > image.ps

SEE ALSO

       gmt, gmtcolors, gmtlogo pslegend, psscale psxy, convert(1)

COPYRIGHT

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