Segment Header Parsing
----------------------

Segment header records may contain one of more of the following options:

**-G**\ *fill*
    Use the new *fill* and turn filling on
**-G-**
    Turn filling off
**-G**
    Revert to default fill (none if not set on command line)
**-L**\ *label*
    Set a label for this segment (e.g., perhaps for quoted lines)
**-W**\ *pen*
    Use the new *pen* and turn outline on
**-W**
    Revert to default pen :term:`MAP_DEFAULT_PEN`
    (if not set on command line)
**-W-**
    Turn outline off
**-Z**\ *zval*
    Obtain fill via cpt lookup using z-value *zval* (what the color is used
    for is controlled further by |-L| or **-W**)
**-Z**\ *NaN*
    Get the NaN color from the CPT
**-t**\ *transparency*
    Obtain transparency and apply it to fill and pen colors.

Custom Symbols
--------------

We allow users to define and plot their own custom symbols. This
is done by encoding the symbol using our custom symbol macro code
described in Appendix N. Put all the macro codes for your new symbol in
a file whose extension must be .def; you may then address the symbol
without giving the extension (e.g., the symbol file tsunami.def is used
by specifying **-Sk**\ *tsunami/size*. The definition file can contain
any number of plot code records, as well as blank lines and comment
lines (starting with #). The module will look for the definition files
in (1) the current directory, (2) the ~/.gmt directory,
and (3) the **$GMT_SHAREDIR**/custom directory, in that
order. Freeform polygons (made up of straight line segments and arcs of
circles) can be designed - these polygons can be painted and filled with
a pattern. Other standard geometric symbols can also be used. See Appendix
:ref:`App-custom_symbols` for macro definitions.

Bezier spline
-------------

The **+s** modifier to pen settings (**-W**) is limited to plotting lines and
polygons.  Lines with embellishments (fronts, decorated, or quoted lines) are
excluded.

Auto-Legend
-----------

The **-l** option for symbols expects the symbol color, size, and type to be given
on the command line.  If you have variable symbol sizes then you must append **+s**\ *size* to set
a suitable size for the legend entry.  For other symbol cases the **-l** option will
be ignored.  Legend entries also work for lines and polygons, but not more complicated
features such as decorated and quoted lines, fronts, etc.

Data Column Order
-----------------

The |-S| option determines how many size columns are required to generate
the selected symbol, but if *size* is not given then we expect to read *size*
from file.  In addition, your use of options |-H|, |-I| and **-t** will
require extra columns.  The order of the data record is fixed regardless of
option order, even if not all items may be activated. We expect data columns
to come in the following order::

    x y z [w] [size-columns] [scale] [intens] [transp [transp2]] [trailing-text]

where items given in brackets are optional and under the control of the stated
options: |-C| selects the optional *w* column for color-lookup, |-S| without
a size selects the optional *size-columns* (may be more than one depending on
the selected symbol), |-H| selects the optional *scale* column, |-I| selects
the optional *intens* column, and **-t** selects the optional *transp* column(s).
Trailing text is always optional.  **Notes**: (1) If symbol *code* is not given
by |-S| then it is expected to start the trailing text. (2) You can use **-i** to
rearrange your data record to match the expected format.

Bugs
----

No hidden line removal is employed for polygons and lines. Symbols,
however, are first sorted according to their distance from the viewpoint
so that nearby symbols will overprint more distant ones should they
project to the same *x, y* position.

The module cannot handle filling of polygons that contain the south or
north pole. For such a polygon, make a copy and split it into two and
make each explicitly contain the polar point. The two polygons will
combine to give the desired effect when filled; to draw outline use the
original polygon.
