.TH PSSCALE 1gmt "Feb 27 2014" "GMT 4.5.13 (SVN)" "Generic Mapping Tools"
.SH NAME
psscale \- Plot gray scale or color scale on maps
.SH SYNOPSIS
\fBpsscale\fP \fB\-D\fP\fIxpos\fP/\fIypos\fP/\fIlength\fP/\fIwidth\fP[\fBh\fP] [ \fB\-A\fP[\fBa\fP|\fBl\fP|\fBc\fP] ] [ \fB\-B\fP[\fBp\fP|\fBs\fP]\fIparameters\fP ] 
[ \fB\-C\fP\fIcpt_file\fP ] [ \fB\-E\fP[\fBb\fP|\fBf\fP][\fIlength\fP] ] [ \fB\-I\fP[\fImax_intens\fP|\fIlow_i\fP/\fIhigh_i\fP] ] 
[ \fB\-K\fP ] [ \fB\-L\fP[\fBi\fP][\fIgap\fP] ] [ \fB\-M\fP ] 
[ \fB\-N\fP\fIdpi\fP ] [ \fB\-O\fP ] [ \fB\-P\fP ] [ \fB\-Q\fP ] 
[ \fB\-U\fP[\fIjust\fP/\fIdx\fP/\fIdy\fP/][\fBc\fP|\fIlabel\fP] ] [ \fB\-V\fP ] [ \fB\-X\fP[\fBa\fP|\fBc\fP|\fBr\fP][\fIx-shift\fP[\fBu\fP]] ] 
[ \fB\-Y\fP[\fBa\fP|\fBc\fP|\fBr\fP][\fIy-shift\fP[\fBu\fP]] ] [ \fB\-Z\fP\fIzfile\fP ] [ \fB\-c\fP\fIcopies\fP ]
.SH DESCRIPTION
\fBpsscale\fP plots gray scales or color scales on maps.  Both horizontal and vertical scales
are supported.  For cpt_files with gradational colors (i.e., the lower and upper
boundary of an interval have different r/g/b values) \fBpsscale\fP will interpolate to give
a continuous scale.  Variations in intensity due to shading/illumination may be
displayed by setting the option \fB\-I\fP.  Colors may be spaced according to a linear
scale, all be equal size, or by providing a file with individual tile widths.
.TP
\fB\-D\fP
Defines the position of the center/top (for horizontal scale) or center/left (for
vertical scale) and the dimensions of the scale.
Give a negative length to reverse the scalebar.
Append \fIh\fP to get a horizontal scale [Default is vertical].
.SH OPTIONS
No space between the option flag and the associated arguments.
.TP
\fB\-A\fP
Place annotations and labels above (instead of below) horizontal scalebars and to the left
(instead of the right) of vertical scalebars.
Append \fBa\fP or \fBl\fP to move only the annotations or the label to the other side.
Append \fBc\fP if you want to print a vertical label as a column of characters (does not work with special characters).
.TP
\fB\-B\fP
Set annotation, tick, and gridline interval for the colorbar.  The
x-axis label will plot beneath a horizontal bar (or vertically
to the right of a vertical bar), except when using \fB\-A\fP.
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).
If \fB\-B\fP is omitted, or no annotation intervals are provided, the default is to annotate
every color level based on the numerical entries in the cpt file
(which may be overridden by ULB flags in the cpt file).
To specify custom text annotations for intervals, you must append ;\fIannotation\fP to each z-slice in the cpt file.
.TP
\fB\-C\fP
\fIcpt_file\fP is the color palette file to be used.
By default all color changes are annotated.  To use a subset, add an extra column to the
cpt-file with a L, U, or B to annotate Lower, Upper, or Both color segment boundaries (but see \fB\-B\fP).
If not given, \fBpsscale\fP will read stdin.  Like \fBgrdview\fP, \fBpsscale\fP can understand
pattern specifications in the cpt file.
.TP
\fB\-E\fP
Add sidebar triangles for \fBb\fPack- and/or \fBf\fPoreground colors.  Add \fBf\fP or \fBb\fP for
only one sidebar triangle [Default gives both].  Optionally, append
triangle height [Default is half the barwidth].
.TP
\fB\-I\fP
Add illumination effects.  Optionally, set the range of intensities from
- to + \fImax_intens\fP.  If not specified, 1 is used.  Alternatively,
append \fIlow/high\fP intensities to specify an asymmetric range [Default is no illumination].
.TP
\fB\-K\fP
More \fIPostScript\fP code will be appended later [Default terminates the plot system].
.TP
\fB\-L\fP
Gives equal-sized color rectangles.  Default scales rectangles according to the
z-range in the cpt-file  (Also see \fB\-Z\fP).  If set, any equal interval annotation
set with \fB\-B\fP will be ignored.  If \fIgap\fP is appended and the cpt table is
discrete we will center each annotation on each rectangle, using the lower boundary
z-value for the annotation.  If \fBi\fP is prepended we annotate the interval range instead.
If \fB\-I\fP is used then each rectangle will have its constant color modified by the specified intensity.
.TP
\fB\-M\fP
Force a monochrome graybar using the (television) YIQ transformation.
.TP
\fB\-N\fP
Effective dots-per-inch for the rectangular image making up the color scale [300].
.TP
\fB\-O\fP
Selects Overlay plot mode [Default initializes a new plot system].
.TP
\fB\-P\fP
Selects Portrait plotting mode [Default is Landscape, see \fBgmtdefaults\fP to change this].
.TP
\fB\-Q\fP
Select logarithmic scale and power of ten annotations.  All z-values in the cpt file
will be converted to p = log10(z) and only integer p values will be annotated using
the 10^p format [Default is linear scale].
.TP
\fB\-S\fP
Do not separate different colour intervals with black lines.
.TP
\fB\-U\fP
Draw Unix System time stamp on plot.
By adding \fIjust/dx/dy/\fP, the user may specify the justification of the stamp and
where the stamp should fall on the page relative to lower left corner of the plot.
For example, BL/0/0 will align the lower left corner of the time stamp with the lower left corner of the plot.
Optionally, append a \fIlabel\fP, or \fBc\fP (which will plot the command string.).
The \fBGMT\fP parameters \fBUNIX_TIME\fP, \fBUNIX_TIME_POS\fP, and \fBUNIX_TIME_FORMAT\fP can affect the appearance;
see the \fBgmtdefaults\fP man page for details.
The time string will be in the locale set by the environment variable \fBTZ\fP (generally local time).
.TP
\fB\-V\fP
Selects verbose mode, which will send progress reports to stderr [Default runs "silently"].
.TP
\fB\-X\fP \fB\-Y\fP
Shift plot origin relative to the current origin by (\fIx-shift,y-shift\fP) and
optionally append the length unit (\fBc\fP, \fBi\fP, \fBm\fP, \fBp\fP).
You can prepend \fBa\fP to shift the origin back to the original position after plotting,
or prepend  \fBr\fP [Default] to reset the current origin to the new location.
If \fB\-O\fP is used then the default (\fIx-shift,y-shift\fP) is (0,0), otherwise it is
(r1i, r1i) or (r2.5c, r2.5c).
Alternatively, give \fBc\fP to align the center coordinate (x or y) of the plot with the center of the page
based on current page size.
.TP
\fB\-Z\fP
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 \fB\-L\fP).
.TP
\fB\-c\fP
Specifies the number of plot copies. [Default is 1].
.SH EXAMPLES
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 illumination, and show back- and foreground colors, and annotating every 5 units, use
.br
.sp
\fBpsscale\fP \fB\-D\fP 6.5\fBi\fP/2\fBi\fP/7.5\fBc\fP/1.25\fBc\fP \fB\-O\fP \fB\-C\fP colors.cpt \fB\-I\fP \fB\-E\fP \fB\-B\fP 5:BATHYMETRY:/:m: >> map.ps
.SH NOTES
When the cpt file 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.
.SH "SEE ALSO"
.IR GMT (1),
.IR makecpt (1),
.IR grd2cpt (1)