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

**-S**\ [*symbol*][*size*]
    Plot symbols (including vectors, pie slices, fronts, decorated or quoted lines).
    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 provide *both* size and symbol via the
    input file you must use :term:`PROJ_LENGTH_UNIT` to indicate the unit
    used for the symbol size or append the units to the sizes in the file.
    If symbol sizes are expected via the third data column then you may convert
    those values to suitable symbol sizes via the **-i** mechanism. The general
    input expectations are::

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

    where the optional *z* 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**\ [*size*\ [**c**\|\ **i**\|\ **p**\|\ **u**]][**+b**\ [*base*]]
        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**\ [*size*\ [**c**\|\ **i**\|\ **p**\|\ **u**]][**+b**\ [*base*]]
        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 3, 4, and 5.

    **-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 3.  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**][**+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 [20]. Alternatively, use **+S** which draws arcuate arrow
        heads. 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 3, 4, and 5.

    **-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 3.  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. Users
        may add their own custom \*.def files; see CUSTOM SYMBOLS below.

    **-Sl**
        **l**\ etter or text string (less than 256 characters). Give size, and
        append **+t**\ *string* after the size. **Note**: The size is only approximate;
        no individual scaling is done for different characters. Remember to
        escape special characters like \*. Optionally, you may append **+f**\ *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 3-5. See `Vector Attributes`_ for specifying other 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.

    **-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. Append
        [**d**\|\ **D**\|\ **f**\|\ **l**\|\ **L**\|\ **n**\|\ **N**\|\ **s**\|\ **S**\|\ **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 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 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.txt*
                Reads the ASCII file *ffile.txt* 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 the coordinates of the end points 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_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_label*
                Specifies the number of equidistant labels for quoted lines
                [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.

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

            **x**\|\ **X**\ *xfile.txt*
                Reads the multisegment file *xfile.txt* and places labels at the
                intersections between the quoted lines and the lines in *xfile.txt*.
                **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. Warning: if the text length exceeds the line length then no text will appear.

            **+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.txt* 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].

            **+x**\ [*first*,\ *last*]
                Append the suffices *first* and *last* to the corresponding labels.
		        This modifier is only available when **-SqN2** is in effect.  Used
		        to annotate the start and end of a line (e.g., a cross-section),
		        append two text strings separated by comma
		        [Default just adds a prime to the second label].

            **+=**\ *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 3 and 4.  Alternatively, append **+s**
        and then the diagonal corner coordinates are expected in columns 3 and 4.

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

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

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

    **-Sv**
        **v**\ ector. Direction (in degrees counter-clockwise from
        horizontal) and length must be found in columns 3 and 4, 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 stem width is set by **-W**,
	with head outline pen width defaulting to half of stem pen width.
        See `Vector Attributes`_ for specifying this and other attributes. But also be aware
        that using color via a CPT implies a shift of columns 3 and on to accommodate
        the color fill determined by the z-value in new 3rd 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.) If your *length* is not in plot units but in arbitrary
        user units (e.g., a rate in mm/yr) then you can use the **-i** option
        to scale the corresponding column via the **+s**\ *scale* modifier.
        See `Vector Attributes`_ for specifying symbol attributes.

    **-Sw**
        pie **w**\ edge. Start and stop directions (in degrees
        counter-clockwise from horizontal) for pie slice must be found in
        columns 3 and 4.  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 vertical (y-dir) line segment.

    **-S=**
        geovector. Azimuth (in degrees east from north) and geographical length
        must be found in columns 3 and 4. 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.txt*
                Reads the ASCII file *ffile.txt* 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.txt*
                Reads the multisegment file *xfile.txt* and places symbols at the
                intersections between the decorated lines and the lines in *xfile.txt*.
                **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.