Markers

Returns an array with [width, dx_left, dx_right, dy_down,
dy_up] given in figure coordinates.  The first is the width in
figure x coordinates, the remainder is the bounding box
relative to the reference point for showing the string.

Show markers at given coordinates

INPUTS

  x       -- x location(s) for marker reference point(s)
  y       -- y location(s) for marker reference point(s)

OPTIONAL INPUTS

  marker  -- tuple of marker definition or a string; defaults
             to Circle
  color   -- default for fill_color and stroke_color
  scale   -- float of factor for rescaling marker size
  legend  -- dict or str for adding marker to legend
  fill_color
          -- tuple of color to be used for filled markers
  stroke_color
          -- tuple of color to be used for stroked markers
  stroke_width
          -- float to be used for stroked markers
  rendering_mode
          -- see below
  font    -- int for one of the predefined font numbers
  angle   -- float of degrees to rotate marker
  horizontal_scale
          -- float for scaling along baseline
  vertical_scale
          -- float for scaling vertical to baseline
  italic_angle
         -- float for slanting text relative to baseline
  ascent_angle
          -- float of factor for slanting baseline
  alignment
          -- see alignment
  justification
          -- see justification

This routine takes care of text that is being used as a
graphical element and consequently is going straight to PDF
rather than to TeX for normal typesetting (see `show_text()`).

The most common use of markers is probably to mark points on
plots (hence the name).  The ZapfDingbats font provides a
useful collection for this purpose, and several glyphs from it
are provided as predefined markers (see the `marker_constants`
module).  A marker of this sort is represented either by an
array of (font_number, character_code) for filled markers, or
by an array holding (font_number, character_code, line_width)
for stroked markers.  Often the same character can be used
both for a filled marker and for an open one.  For example,
the predefined markers include Box and Circle (filled) as well
as the same glyphs as BoxOpen and CircleOpen (stroked).

For the primary purpose of marking points on plots, we could
stop with just single characters taken from ZapfDingbats.
However, for not much more effort, we can broaden this to
allow strings of characters and fonts other than the dingbats.
But the usefulness of this is limited given that typesetting
is properly done using TeX, and the problems of dealing with
fonts in general are notoriously awful.  So the compromise is
to allow markers using any of the 14 standard Adobe PDF fonts
which are guaranteed to be supported by all PDF viewers and to
toss in for good measure some Computer Modern fonts which are
likely to be around since they come with TeX.  These fonts are
predefined in the figure_constants module.  Any character (or
string of characters) from any of these fonts can be used as a
marker.

Because markers are sent to PDF rather than TeX, they are
limited typographically but powerful graphically.  In addition
to specifying color, scale, and rotatation, as you can for TeX
text, you can also stretch the characters either along the
baseline (`horizontal_scale`) or perpendicular to it
(`vertical_scale`).  You can slant the individual characters
(`italic_angle`) or shift the baseline along the text
(`ascent_angle`).  Finally, you can specify the
`rendering_mode` for the marker to be any combination of fill,
stroke, and clip.  (So for next Valentine's Day you can take a
Heart marker, scale it up, and use it to clip a JPEG image of
yourself to send to your sweetheart.)

Defaults for many of the entries come from the
`self.marker_defaults` dict.

Example

TODO: add a code snippet

This dictionary holds defaults for `show_marker()`.