gmt-fork/doc/rst/source/explain_symbols2.rst_

**-S**\ [*symbol*][*size*][/*size_y*]
    Plot symbols. If present, *size* is symbol size in the unit set in
    :doc:`gmt.conf` (unless **c**, **i**, or **p** is appended). If the symbol
    code (see below) is not given it will be read from the last column in
    the input data; this cannot be used in conjunction with binary input.
    Optionally, append **c**, **i**, or
    **p** to indicate that the size information in the input data is in
    units of cm, inch, or point, respectively [Default is
    :term:`PROJ_LENGTH_UNIT`]. **Note**: If you give *both* size and symbol via the
    input file you must use :term:`PROJ_LENGTH_UNIT` to indicate the units
    used for the symbol size or append the units to the size in the file.
    Some 2-dimensional symbols optionally take a second size via *size_y*.
    If symbol sizes are expected via the fourth data column then you may convert
    those values to suitable symbol sizes via the **-i** mechanism. The general
    input expectations are::

    *x y z* [ *w* ] [ *size* ] [ *symbol-parameters* ] [ *symbol* ]

    where the optional *w* is required when **-C** is used, the optional
    *size* is required when no symbol size is specified, and the trailing
    text with the symbol code is required when symbol code is not specified
    on the command line.  The *symbol-parameters* may vary in numbers; see
    specifics below.
    
    The uppercase symbols **A**, **C**, **D**, **G**, **H**, **I**, **N**,
    **S**, **T** are normalized to have the same area as a circle with
    diameter *size*, while the size of the corresponding lowercase symbols
    refers to the diameter of a circumscribed circle.

    You can change symbols by adding the required **-S** option to any of
    your multisegment headers.

    Choose between these symbol codes:

    **-S-**
        x-dash (-). *size* is the length of a short horizontal (x-dir) line segment.

    **-S+**
        plus (+). *size* is diameter of circumscribing circle.

    **-Sa**
        st\ **a**\ r. *size* is diameter of circumscribing circle.

    **-Sb**
        Vertical **b**\ ar extending from *base* to y. The *size* is bar width.
        Append **u** if *size* is in x-units [Default is plot-distance units].
        By default, *base* = 0. Append **+b**\ [*base*] to change this
        value. If *base* is not appended then we read it from the last input
        data column.  Use **+B**\ [*base*] if the bar height is measured relative
        to *base* [Relative to origin].

    **-SB**
        Horizontal **b**\ ar extending from *base* to x. The *size* is bar width.
        Append **u** if *size* is in y-units [Default is plot-distance units].
        By default, *base* = 0. Append **+b**\ [*base*] to change this
        value. If *base* is not appended then we read it from the last input
        data column.  Use **+B**\ [*base*] if the bar length is measured relative
        to *base* [Relative to origin].

    **-Sc**
        **c**\ ircle. *size* is diameter of circle.

    **-Sd**
        **d**\ iamond. *size* is diameter of circumscribing circle.

    **-Se**
        **e**\ llipse. Direction (in degrees counter-clockwise from horizontal),
        major\_axis, and minor\_axis must be found in columns 4, 5, and 6.

    **-SE**
        Same as **-Se**, except azimuth (in degrees east of north) should be
        given instead of direction. The azimuth will be mapped into an angle
        based on the chosen map projection (**-Se** leaves the directions
        unchanged.) Furthermore, the axes lengths must be given in geographical instead of
        plot-distance units. An exception occurs for a linear projection in
        which we assume the ellipse axes are given in the same units as **-R**.
	For degenerate ellipses (circles) with just the diameter given, use **-SE-**.
	The diameter is excepted to be given in column 4.  Alternatively, append
	the desired diameter to **-SE-** and this fixed diameter is used instead.
	For allowable geographical units, see `Units`_ [Default is k for km].

    **-Sf**\ [±]\ *gap*\ [/*size*][**+l**\|\ **+r**][**+b+c+f+s+t**][**+i**][**+o**\ *offset*][**+p**\ [*pen*]].
        Draw a **f**\ ront.  Supply distance *gap* between symbols and symbol size. If *gap* is
        negative, it is interpreted to mean the number of symbols along the
        front instead. If *gap* has a leading + then we use the value exactly as given
        [Default will start and end each line with a symbol, hence the *gap* is adjusted to fit].
        If *size* is missing it is set to 30% of the *gap*, except
        when *gap* is negative and *size* is thus required.  Append **+l** or
        **+r** to plot symbols on the left or
        right side of the front [Default is centered]. Append **+**\ *type* to
        specify which symbol to plot: **b**\ ox, **c**\ ircle, **f**\ ault,
        **s**\ lip, or **t**\ riangle. [Default is **f**\ ault]. Slip means
        left-lateral or right-lateral strike-slip arrows (centered is not an
        option). The **+s** modifier optionally accepts the angle used to draw
        the vector [30]. Append **+o**\ *offset* to offset the first symbol from the
        beginning of the front by that amount [0]. The chosen symbol is drawn
        with the same pen as set for the line (i.e., via **-W**). To use an
        alternate pen, append **+p**\ *pen*. To skip the outline, just use
        **+p**.  To make the main front line invisible, add **+i**.  **Note**:
        By placing **-Sf** options in the segment header you can change the front
        types on a segment-by-segment basis.

    **-Sg**
        octa\ **g**\ on. *size* is diameter of circumscribing circle.

    **-Sh**
        **h**\ exagon. *size* is diameter of circumscribing circle.

    **-Si**
        **i**\ nverted triangle. *size* is diameter of circumscribing circle.

    **-Sj**
        Rotated rectangle. Direction (in degrees counter-clockwise from
        horizontal), x-dimension, and y-dimension must be found in columns 4, 5, and 6.

    **-SJ**
        Same as **-Sj**, except azimuth (in degrees east of north) should be
        given instead of direction. The azimuth will be mapped into an angle
        based on the chosen map projection (**-Sj** leaves the directions
        unchanged.) Furthermore, the dimensions must be given in geographical instead of
        plot-distance units.
	For a degenerate rectangle (square) with one dimension given, use **-SJ-**.
	The dimension is excepted to be given in column 4.  Alternatively, append
	the dimension diameter to **-SJ-** and this fixed dimension is used instead.
	An exception occurs for a linear projection in
        which we assume the dimensions are given in the same units as **-R**.
	For allowable geographical units, see `Units`_ [Default is k for km].

    **-Sk**
        **k**\ ustom symbol. Append <name>/*size*, and we will look for a
        definition file called <name>.def in (1) the current
        directory or (2) in ~/.gmt or (3) in
        **$GMT\_SHAREDIR**/custom. The symbol as defined in that file is of size
        1.0 by default; the appended *size* will scale symbol accordingly.
        The symbols are plotted in the *x-y* plane.  Users
        may add their own custom \*.def files; see CUSTOM SYMBOLS below.

    **-Sl**
        **l**\ etter or text string (less than 64 characters). Give size, and
        append /*string* after the size. Note that the size is only approximate;
        no individual scaling is done for different characters. Remember to
        escape special characters like \*. Optionally, you may append %\ *font*
        to select a particular font [Default is :term:`FONT_ANNOT_PRIMARY`] and
        **+j**\ *justify* to change justification [CM].

    **-Sm**
        **m**\ ath angle arc, optionally with one or two arrow heads [Default is
        no arrow heads]. The *size* is the length of the vector head. Arc width
        is set by **-W**, with vector head outlines defaulting to half of arc width.
	The radius of the arc and its start and stop
        directions (in degrees counter-clockwise from horizontal) must be given
        in columns 4-6. See `Vector Attributes`_ for specifying attributes.

    **-SM**
        Same as **-Sm** but switches to straight angle symbol if angles subtend
        90 degrees exactly.

    **-Sn**
        pe\ **n**\ tagon. *size* is diameter of circumscribing circle.

    **-So**
        c\ **o**\ lumn (3-D) extending from *base* to *z*.  The *size* sets base width
        (Use *xsize/ysize* if not the same).  Append **u** if *size* is in the users' x-units
        [Default is plot-distance units].  If no *size* is given we expect both *xsize*
        and *ysize* as two extra data columns.  By default, *base* = 0.  Append
        **+b**\ *base* to change this value.  If *base* is not appended then we read it
        from the last input data column.  Use **+B**\ [*base*] if the column height
        is measured relative to *base* [Relative to origin].
        The facet colors will be modified to
        simulate shading.  Use **-SO** to disable such 3-D illumination.
        Normally a single *z* value is considered.  For multi-band columns, append
        **+z**\ *nbands* (and provide *nbands* *z*-values on input; these must be monotonically
        increasing up the column) or **-Z**\ *nbands* (and expect *nbands* of *dz* increments
        that must be summed to yield actual *z* values).  The multi-band column symbol
        requires **-C** and will use the band number (0, 1, *nbands*\ -1) to assign
        the band color.

    **-Sp**
        **p**\ oint. No size needs to be specified (1 pixel is used).

    **-Sq**
        **q**\ uoted line, i.e., lines with annotations such as contours.
        It is assumed that each individual line has a constant *z* level
        (i.e., each line must lie in the *x-y* plane).  Append
        [**d**\|\ **D**\|\ **f**\|\ **l**\|\ **L**\|\ **n**\|\ **x**\|\ **X**]\ *info*\ [:*labelinfo*].
        Note the colon that separates the algorithm settings from the label information.
        The required argument controls the placement of labels along the quoted
        lines. Choose among five controlling algorithms:

            **d**\ *dist*\ [**c**\|\ **i**\|\ **p**] or **D**\ *dist*\ [**d**\|\ **e**\|\ **f**\|\ **k**\|\ **m**\|\ **M**\|\ **n**\|\ **s**]
                For lower case **d**, give distances between labels on the plot in
                your preferred measurement unit **c** (cm), **i** (inch), or **p**
                (points), while for upper case **D**, specify distances in map units
                and append the unit; choose among **e** (m), **f** (foot), **k**
                (km), **M** (mile), **n** (nautical mile) or **u** (US survey foot),
                and **d** (arc degree), **m** (arc minute), or **s** (arc second).
                [Default is 10\ **c** or 4\ **i**]. As an option, you can append
                /*fraction* which is used to place the very first label for each
                contour when the cumulative along-contour distance equals *fraction
                \* dist* [0.25].

            **f**\ *ffile.d*
                Reads the ASCII file *ffile.d* and places labels at locations in the
                file that matches locations along the quoted lines. Inexact matches
                and points outside the region are skipped.

            **l**\|\ **L**\ *line1*\ [,\ *line2*,...]
                Give *start* and *stop* coordinates for one or more comma-separated
                straight line segments. Labels will be placed where these lines
                intersect the quoted lines. The format of each *line* specification
                is *start/stop*, where *start* and *stop* are either a specified
                point *lon/lat* or a 2-character **XY** key that uses the
                justification format employed in **text** to indicate a point on
                the map, given as [LCR][BMT]. **L** will interpret the point pairs
                as defining great circles [Default is straight line].

            **n**\ *n\_label*
                Specifies the number of equidistant labels for quoted lines line
                [1]. Upper case **N** starts labeling exactly at the start of the
                line [Default centers them along the line]. **N**-1 places one
                justified label at start, while **N**\ +1 places one justified label
                at the end of quoted lines. Optionally, append
                /*min\_dist*\ [**c**\|\ **i**\|\ **p**] to enforce that a
                minimum distance separation between successive labels is enforced.

            **x\|X**\ *xfile.d*
                Reads the multisegment file *xfile.d* and places labels at the
                intersections between the quoted lines and the lines in *xfile.d*.
                **X** will resample the lines first along great-circle arcs.
                In addition, you may optionally append
                **+r**\ *radius*\ [**c**\|\ **i**\|\ **p**] to set a minimum
                label separation in the x-y plane [no limitation].

            The optional *labelinfo* controls the specifics of the label
            formatting and consists of a concatenated string made up of any of
            the following control arguments:

            **+a**\ *angle*
                For annotations at a fixed angle, **+an** for line-normal, or
                **+ap** for line-parallel [Default].

            **+c**\ *dx*\ [/*dy*]
                Sets the clearance between label and optional text box. Append
                **c**\|\ **i**\|\ **p** to specify the unit or % to indicate a
                percentage of the label font size [15%].

            **+d**
                Turns on debug which will draw helper points and lines to illustrate
                the workings of the quoted line setup.

            **+e**
                Delay the plotting of the text. This is used to build a clip path
                based on the text, then lay down other overlays while that clip path
                is in effect, then turning of clipping with clip **-Cs** which
                finally plots the original text.

            **+f**\ *font*
                Sets the desired font [Default :term:`FONT_ANNOT_PRIMARY` with its
                size changed to 9p].

            **+g**\ [*color*]
                Selects opaque text boxes [Default is transparent]; optionally
                specify the color [Default is :term:`PS_PAGE_COLOR`].

            **+i**
                Make the main quoted line invisible [Draw it per **-W**].

            **+j**\ *just*
                Sets label justification [Default is MC]. Ignored when
                **-SqN**\|\ **n**\ +\|-1 is used.

            **+l**\ *label*
                Sets the constant label text.

            **+L**\ *flag*
                Sets the label text according to the specified flag:

                **+Lh**
                Take the label from the current segment header (first scan for
                an embedded **-L**\ *label* option, if not use the first word
                following the segment flag). For multiple-word labels, enclose
                entire label in double quotes.
                **+Ld**
                Take the Cartesian plot distances along the line as the label;
                append **c**\|\ **i**\|\ **p** as the unit [Default is
                :term:`PROJ_LENGTH_UNIT`].
                **+LD**
                Calculate actual map distances; append
                **d\|e\|f\|k\|n\|M\|n\|s** as the unit [Default is
                **d**\ (egrees), unless label placement was based on map
                distances along the lines in which case we use the same unit
                specified for that algorithm]. Requires a map projection to be
                used.
                **+Lf**
                Use text after the 2nd column in the fixed label location file
                as the label. Requires the fixed label location setting.
                **+Lx**
                As **+Lh** but use the headers in the *xfile.d* instead.
                Requires the crossing file option.

            **+n**\ *dx*\ [/*dy*]
                Nudges the placement of labels by the specified amount (append
                **c**\|\ **i**\|\ **p** to specify the units). Increments
                are considered in the coordinate system defined by the
                orientation of the line; use **+N** to force increments in the
                plot x/y coordinates system [no nudging]. Not allowed with **+v**.

            **+o**
                Selects rounded rectangular text box [Default is rectangular].
                Not applicable for curved text (**+v**) and only makes sense for
                opaque text boxes.

            **+p**\ [*pen*]
                Draws the outline of text boxes [Default is no outline];
                optionally specify pen for outline [Default is width = 0.25p,
                color = black, style = solid].

            **+r**\ *min\_rad*
                Will not place labels where the line's radius of curvature is
                less than *min\_rad* [Default is 0].

            **+t**\ [*file*]
                Saves line label x, y, and text to *file* [Line\_labels.txt].
                Use **+T** to save x, y, angle, text instead.

            **+u**\ *unit*
                Appends *unit* to all line labels. If *unit* starts with a
                leading hyphen (-) then there will be no space between label
                value and the unit. [Default is no unit].

            **+v**
                Specifies curved labels following the path [Default is straight labels].

            **+w**
                Specifies how many (*x*,\ *y*) points will be used to estimate
                label angles [Default is 10].

            **+=**\ *prefix*
                Prepends *prefix* to all line labels. If *prefix* starts with a
                leading hyphen (-) then there will be no space between label
                value and the prefix. [Default is no prefix].

        **Note**: By placing **-Sq** options in the segment header you can change
        the quoted text attributes on a segment-by-segment basis.

    **-Sr**
        **r**\ ectangle. No size needs to be specified, but the x- and
        y-dimensions must be found in columns 4 and 5.

    **-SR**
        **R**\ ounded rectangle. No size needs to be specified, but the x-
        and y-dimensions and corner radius must be found in columns 4, 5, and 6.

    **-Ss**
        **s**\ quare. *size* is diameter of circumscribing circle.

    **-St**
        **t**\ riangle. *size* is diameter of circumscribing circle.

    **-Su**
        c\ **u**\ be (3-D).  The *size)* sets length of all sides. Append
        **u** if *size* is in x-units [Default is plot-distance units].
        The facet colors will be modified to simulate shading.
        Use **-SU** to disable such 3-D illumination.

    **-Sv**
        **v**\ ector. Direction (in degrees counter-clockwise from
        horizontal) and length must be found in columns 4 and 5, and *size*,
        if not specified on the command-line, should be  present in column 3,
        pushing the other items to later columns.
        The *size* is the length of the vector head. Vector width is set by **-W**,
	with head outline pen width defaulting to half of stem pen width.
        See `Vector Attributes`_ for specifying attributes. But also be aware
        that using color via a CPT implies a shift of columns 4 and on to accommodate
        the color fill determined by the z-value in new 4rd column (See **-C** option).

    **-SV**
        Same as **-Sv**, except azimuth (in degrees east of north) should be
        given instead of direction. The azimuth will be mapped into an angle
        based on the chosen map projection (**-Sv** leaves the directions
        unchanged.) See `Vector Attributes`_ for specifying attributes.

    **-Sw**
        pie **w**\ edge. Start and stop directions (in degrees
        counter-clockwise from horizontal) for pie slice must be found in
        columns 4 and 5.  Append /*inner* to select a separate inner diameter [0].
        Append **+a**\ [*dr*] to draw the arc line (at inner and outer diameter);
        if *dr* is appended then we draw all arc lines separated radially by *dr*.
 	Append **+r**\ [*da*] to draw radial lines (at start and stop directions)
        if *da* is appended then we draw all radial lines separated angularly by *da*.
        These spider-web lines are drawn using the current pen unless **+p**\ *pen* is added.

    **-SW**
        Same as **-Sw**, except azimuths (in degrees east of north) should
        be given instead of the two directions. The azimuths will be mapped
        into angles based on the chosen map projection (**-Sw** leaves the
        directions unchanged). Specify *size* as a geographical diameter.
        For allowable geographical units, see `Units`_ [Default is k for km]. To instead
        specify a diameter in plot units, you must append the desired unit.
        Append /*inner* to select a separate inner diameter [0].
        Append **+a**\ [*dr*] to draw the arc line (at inner and outer diameter);
        if *dr* is appended then we draw all arc lines separated radially by *dr*.
 	Append **+r**\ [*da*] to draw radial lines (at start and stop directions)
        if *da* is appended then we draw all radial lines separated angularly by *da*.
        These spider-web lines are drawn using the current pen unless **+p**\ *pen* is added.

    **-Sx**
        cross (x). *size* is diameter of circumscribing circle.

    **-Sy**
        y-dash (\|). *size* is the length of a short horizontal (y-dir) line segment.

    **-S=**
        geovector. Azimuth (in degrees east from north) and length (in km)
        must be found in columns 4 and 5. The *size* is the length of the
        vector head. Vector width is set by **-W**. See `Vector Attributes`_
        for specifying attributes. **Note**: Geovector stems are drawn as thin
        filled polygons and hence pen attributes like dashed and dotted are
        not available. For allowable geographical units, see `Units`_.

    **-S~**
        decorated line, i.e., lines with symbols along them. Append
        [**d**\|\ **D**\|\ **f**\|\ **l**\|\ **L**\|\ **n**\|\ **N**\|\ **s**\|\ **S**\|\ **x**\|\ **X**]\ *info*\ [:*symbolinfo*].
        Note the colon that separates the algorithm settings from the symbol information.
        The required argument controls the placement of symbols along the decorated
        lines. Choose among six controlling algorithms:

            **d**\ *dist*\ [**c**\|\ **i**\|\ **p**] or **D**\ *dist*\ [**d**\|\ **e**\|\ **f**\|\ **k**\|\ **m**\|\ **M**\|\ **n**\|\ **s**]
                For lower case **d**, give distances between symbols on the plot in
                your preferred measurement unit **c** (cm), **i** (inch), or **p**
                (points), while for upper case **D**, specify distances in map units
                and append the unit; choose among **e** (m), **f** (foot), **k**
                (km), **M** (mile), **n** (nautical mile) or **u** (US survey foot),
                and **d** (arc degree), **m** (arc minute), or **s** (arc second).
                [Default is 10\ **c** or 4\ **i**]. As an option, you can append
                /*fraction* which is used to place the very first symbol for each
                line when the cumulative along-line distance equals *fraction
                \* dist* [0.25].

            **f**\ *ffile.d*
                Reads the ASCII file *ffile.d* and places symbols at locations in the
                file that matches locations along the decorated lines. Inexact matches
                and points outside the region are skipped.

            **l**\|\ **L**\ *line1*\ [,\ *line2*,...]
                Give the coordinates of the end points for one or more comma-separated straight line segments.
                Symbols will be placed where these lines intersect the decorated lines.
                The format of each *line* specification is *start_lon*/*start_lat*/*stop_lon*/*stop_lat*.
                Both *start_lon*/*start_lat* and *stop_lon*/*stop_lat* can be replaced by a 2-character key
                that uses the justification format employed in **text** to indicate a point on the frame or
                center of the map, given as [LCR][BMT].
                **L** will interpret the point pairs as defining great circles [Default is straight line].

            **n**\|\ **N**\ *n_symbol*
                Specifies the number of equidistant symbols for decorated lines
                [1]. Upper case **N** starts placing symbols exactly at the start of the
                line [Default centers them along the line]. **N**-1 places one symbol
                at start, while **N**\ +1 places one symbol
                at the end of decorated lines. Optionally, append
                /*min_dist*\ [**c**\|\ **i**\|\ **p**] to enforce that a
                minimum distance separation between successive symbols is enforced.

            **s**\|\ **S**\ *n_symbol*
                Same as **n**\|\ **N**\ *n_symbol* but implies that the input data are
		        first to be converted into a series of 2-point line segments before plotting.

            **x**\|\ **X**\ *xfile.d*
                Reads the multisegment file *xfile.d* and places symbols at the
                intersections between the decorated lines and the lines in *xfile.d*.
                **X** will resample the lines first along great-circle arcs.

            The optional *symbolinfo* controls the specifics of the symbol selection and
            formatting and consists of a concatenated string made up of any of
            the following control arguments:

            **+a**\ *angle*
                For symbols at a fixed angle, **+an** for line-normal, or
                **+ap** for line-parallel [Default].

            **+d**
                Turns on debug which will draw helper points and lines to illustrate
                the workings of the decorated line setup.

            **+g**\ [*fill*]
                Sets the symbol fill [no fill].

            **+i**
                Make the main decorated line invisible [Draw it using pen settings provided by **-W**].

            **+n**\ *dx*\ [/*dy*]
                Nudges the placement of symbols by the specified amount (append
                **c**\|\ **i**\|\ **p** to specify the units). Increments
                are considered in the coordinate system defined by the
                orientation of the line; use **+N** to force increments in the
                plot x/y coordinates system [no nudging].

            **+p**\ [*pen*]
                Draws the outline of symbols [Default is no outline];
                optionally specify pen for outline [Default is width = 0.25p,
                color = black, style = solid].

            **+s**\ <symbol><size> or **+sk**\ *customsymbol*/*size*
                Specifies the code and size of the decorative symbol.
                Custom symbols need to be simple, i.e., not require data columns.

            **+w**
                Specifies how many (*x*,\ *y*) points will be used to estimate
                symbol angles [Default is 10].

        If neither **+g** nor **+p** are set we select the default pen outline (:term:`MAP_DEFAULT_PEN`).
        **Note**: By placing **-S~** options in the segment header you can change
        the decorated lines on a segment-by-segment basis.