gleplot 6.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- gleplot/__init__.py +772 -0
- gleplot/_warn.py +45 -0
- gleplot/axes.py +10714 -0
- gleplot/cairo_support.py +232 -0
- gleplot/colors.py +721 -0
- gleplot/compiler.py +863 -0
- gleplot/config.py +491 -0
- gleplot/dataio.py +1403 -0
- gleplot/figure.py +5789 -0
- gleplot/guides.py +172 -0
- gleplot/markers.py +424 -0
- gleplot/mathtext.py +679 -0
- gleplot/palettes.py +243 -0
- gleplot/parser/__init__.py +83 -0
- gleplot/parser/expr.py +196 -0
- gleplot/parser/lexer.py +289 -0
- gleplot/parser/metadata.py +374 -0
- gleplot/parser/recognizer.py +12654 -0
- gleplot/parser/report.py +74 -0
- gleplot/parser/syntax.py +756 -0
- gleplot/parser/tables.py +484 -0
- gleplot/parser/units.py +196 -0
- gleplot/py.typed +0 -0
- gleplot/series.py +1609 -0
- gleplot/sources.py +623 -0
- gleplot/writer.py +7215 -0
- gleplot-6.0.0.dist-info/METADATA +138 -0
- gleplot-6.0.0.dist-info/RECORD +31 -0
- gleplot-6.0.0.dist-info/WHEEL +5 -0
- gleplot-6.0.0.dist-info/licenses/LICENSE +25 -0
- gleplot-6.0.0.dist-info/top_level.txt +1 -0
gleplot/guides.py
ADDED
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
"""How guides (axhline/axvline/axhspan/axvspan) are written, and read back.
|
|
2
|
+
|
|
3
|
+
A ``RefLine``/``Span`` declares its extent along the axis it crosses as an
|
|
4
|
+
*axes fraction*. gleplot writes it in one of two plain-GLE forms.
|
|
5
|
+
|
|
6
|
+
**The dataset form** -- the common case. The fraction is measured against the
|
|
7
|
+
axis range gleplot resolved and the guide is written as a literal two-point
|
|
8
|
+
dataset (``Axes.materialize_reflines`` / ``materialize_spans``): a
|
|
9
|
+
``dN line`` for a line, ``fill dA,dB`` for a band. Drawn inside the graph,
|
|
10
|
+
bands with the fills and lines below the data, clipped to the frame.
|
|
11
|
+
|
|
12
|
+
**The after-graph form** -- only when gleplot has no range for the spanned
|
|
13
|
+
axis: the axes carries no data and no limit for it (G14), or the range it
|
|
14
|
+
resolved to collapsed and was handed back to the engine (G15,
|
|
15
|
+
``Figure._defer_degenerate_range``). A literal dataset would then join GLE's
|
|
16
|
+
autoscale and move the frame it was measured against, so the guide is drawn
|
|
17
|
+
after ``end graph``, where ``xgmin``/``xgmax``/``ygmin``/``ygmax`` hold the
|
|
18
|
+
range GLE chose (``Axes.guide_needs_engine_range``). A line is a call of
|
|
19
|
+
``graph_hline``/``graph_vline`` from GLE's include library (``graphutil.gle``)
|
|
20
|
+
under its own ``set color ... lwidth ... lstyle``; a band is a ``box`` between
|
|
21
|
+
``xg()``/``yg()`` page coordinates. Each is wrapped in ``gsave``/``grestore``
|
|
22
|
+
so its style does not leak into the next graph.
|
|
23
|
+
|
|
24
|
+
GLE constraints that rule out drawing these inside the graph block (verified
|
|
25
|
+
on GLE 4.3.10):
|
|
26
|
+
|
|
27
|
+
* A graph ``draw`` command's arguments are evaluated when GLE parses the line
|
|
28
|
+
(``GLEGraphDrawCommand::createGraphDrawCommand``), before the axis range
|
|
29
|
+
exists, so ``draw graph_hline 2`` -- whose defaults are ``xgmin``/``xgmax``
|
|
30
|
+
-- draws nothing.
|
|
31
|
+
* A ``draw`` call carries no colour, line style or width of its own, and a
|
|
32
|
+
``set`` before ``begin graph`` restyles the axes too, so a guide drawn there
|
|
33
|
+
cannot have its own style.
|
|
34
|
+
|
|
35
|
+
The cost, confined to these engine-range guides: they draw above the data and
|
|
36
|
+
the axes (a band covers the ticks inside the frame), and a line is not clipped
|
|
37
|
+
to the frame. ``docs/guides/MATPLOTLIB_MIGRATION.md`` records it.
|
|
38
|
+
|
|
39
|
+
A labelled after-graph guide gets its legend entry from a data-free ``dN``
|
|
40
|
+
line inside the graph (``dN line ... key`` for a line, ``dN keyfill ... key``
|
|
41
|
+
for a band), which draws no ink and takes no part in autoscale.
|
|
42
|
+
|
|
43
|
+
Both forms are preceded by a ``! gleplot:guide`` provenance marker, so a
|
|
44
|
+
re-read file recovers a ``RefLine``/``Span`` rather than the plain commands it
|
|
45
|
+
was written as. See the block comment on :data:`GUIDE_MARKER_PREFIX` for the
|
|
46
|
+
grammar.
|
|
47
|
+
"""
|
|
48
|
+
|
|
49
|
+
from __future__ import annotations
|
|
50
|
+
|
|
51
|
+
from typing import Dict, Tuple
|
|
52
|
+
|
|
53
|
+
__all__ = [
|
|
54
|
+
"GRAPHUTIL_INCLUDE",
|
|
55
|
+
"GUIDE_MARKER_PREFIX",
|
|
56
|
+
"GUIDE_MARKER_KINDS",
|
|
57
|
+
"GUIDE_MARKER_ORIENTS",
|
|
58
|
+
"GUIDE_MARKER_FIELDS",
|
|
59
|
+
"GUIDE_MARKER_LABEL",
|
|
60
|
+
"fraction_expr",
|
|
61
|
+
]
|
|
62
|
+
|
|
63
|
+
#: The gleinc file whose ``graph_hline``/``graph_vline`` draw after-graph lines.
|
|
64
|
+
GRAPHUTIL_INCLUDE = "graphutil.gle"
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
# -- the provenance marker (G18-lite) ---------------------------------------
|
|
68
|
+
#
|
|
69
|
+
# The dataset form is a literal two-point dataset
|
|
70
|
+
# plus a ``dN line`` / ``fill dA,dB`` command (``Axes.materialize_reflines`` /
|
|
71
|
+
# ``materialize_spans``). Nothing in those bytes says "this is a guide", so
|
|
72
|
+
# until G18-lite every ``.gle`` re-import silently demoted a RefLine/Span to
|
|
73
|
+
# the LineSeries/FillSeries it had materialized into.
|
|
74
|
+
#
|
|
75
|
+
# A **comment** closes that with zero rendering impact by construction (GLE
|
|
76
|
+
# never reads past ``!``), so the emission stays additive to the byte:
|
|
77
|
+
# sidecars, dataset indices and every visible command are what they always
|
|
78
|
+
# were.
|
|
79
|
+
#
|
|
80
|
+
# Grammar -- one line, immediately above the guide's own ``data`` statement
|
|
81
|
+
# (dataset form) or the ``gsave`` that opens its drawing (after-graph form)::
|
|
82
|
+
#
|
|
83
|
+
# ! gleplot:guide refline v value 1.5 extent 0,1
|
|
84
|
+
# ! gleplot:guide span v range 0.5,1 extent 0.2,0.6 label "band"
|
|
85
|
+
#
|
|
86
|
+
# Keyword-tagged and GLE-lexable: the recognizer runs the same tokenizer and
|
|
87
|
+
# the same ``_collect_value`` / ``_string_value`` helpers it uses on real
|
|
88
|
+
# statements, so an escaped quote needs no bespoke handling here.
|
|
89
|
+
#
|
|
90
|
+
# **The pair separator is a comma, and that is load-bearing.** GLE's lexer
|
|
91
|
+
# reads a sign as an operator, so two space-separated numbers whose second is
|
|
92
|
+
# negative are one expression to ``_collect_value``: ``range -4 -3`` collects
|
|
93
|
+
# as -7, not as (-4, -3). A comma is not a value operator, so it ends the
|
|
94
|
+
# expression -- and it is GLE's own separator for a pair (``d1=c1,c2``,
|
|
95
|
+
# ``fill dA,dB``), so the marker reads like the script around it. No space
|
|
96
|
+
# inside the pair, for the same reason gleplot writes none in a ``bar``
|
|
97
|
+
# comma-list.
|
|
98
|
+
#
|
|
99
|
+
# **The marker carries the model residue and nothing else.** Everything a
|
|
100
|
+
# visible command already states unambiguously is read back from that command,
|
|
101
|
+
# so there is exactly one source of truth per field:
|
|
102
|
+
#
|
|
103
|
+
# * colour / linestyle / linewidth -> the ``dN line ...`` / ``fill ...``
|
|
104
|
+
# command;
|
|
105
|
+
# * a refline's label -> its ``key "..."`` clause;
|
|
106
|
+
# * the sidecar and its header row -> the ``data`` statement and the
|
|
107
|
+
# ``.dat`` file itself.
|
|
108
|
+
#
|
|
109
|
+
# What is left is unrecoverable from the script at any price, and is exactly
|
|
110
|
+
# what the marker exists to carry:
|
|
111
|
+
#
|
|
112
|
+
# * **kind and orientation** -- derivable only from the *shape* of the
|
|
113
|
+
# dataset, which recognition is forbidden to key off (a hand-written
|
|
114
|
+
# two-point line must stay a plain line);
|
|
115
|
+
# * **the coordinate(s)** -- ``value``, or a band's ``range a b``: they live
|
|
116
|
+
# in the ``.dat`` sidecar, not in the script;
|
|
117
|
+
# * **the fractional extent** -- ``extent lo hi`` is an axes fraction, and
|
|
118
|
+
# the emitted rows are that fraction already resolved against the axis
|
|
119
|
+
# range; inverting it would need that range to be recoverable, which for
|
|
120
|
+
# an autoscaled axis it is not;
|
|
121
|
+
# * **a span's label** -- GLE's ``fill dA,dB`` has no ``key`` option, so the
|
|
122
|
+
# dataset form has never had anywhere to put it (the after-graph form has the
|
|
123
|
+
# same gap; see ``GLEWriter.add_span``). Omitted from the marker when
|
|
124
|
+
# empty, so an unlabelled band costs no extra bytes.
|
|
125
|
+
#
|
|
126
|
+
# A span's ``alpha`` is deliberately NOT carried: it is folded into the
|
|
127
|
+
# emitted colour by ``colors.apply_alpha`` and comes back folded (alpha 1.0
|
|
128
|
+
# over an ``rgba255(...)`` colour text), exactly as a hand-written fill does
|
|
129
|
+
# and exactly as the after-graph form does. Carrying it would mean carrying the
|
|
130
|
+
# unfolded colour with it -- two sources of truth for one visible token.
|
|
131
|
+
#
|
|
132
|
+
# On the after-graph form the drawing repeats the coordinates, and the
|
|
133
|
+
# colour, width and style come from its ``set`` line or ``box ... fill``. The
|
|
134
|
+
# recognizer accepts the drawing only when it is exactly what the writer would
|
|
135
|
+
# write from the marker and those values, so the two cannot disagree.
|
|
136
|
+
|
|
137
|
+
#: Prefix of the dataset-form provenance-marker comment. Distinct from the
|
|
138
|
+
#: metadata block's ``! gleplot: key = value`` lines (no space after the
|
|
139
|
+
#: colon, and a keyword rather than a key) and emitted nowhere else.
|
|
140
|
+
GUIDE_MARKER_PREFIX = "! gleplot:guide"
|
|
141
|
+
|
|
142
|
+
#: The model kinds a marker can name.
|
|
143
|
+
GUIDE_MARKER_KINDS: Tuple[str, ...] = ("refline", "span")
|
|
144
|
+
|
|
145
|
+
#: The orientations a marker can name.
|
|
146
|
+
GUIDE_MARKER_ORIENTS: Tuple[str, ...] = ("v", "h")
|
|
147
|
+
|
|
148
|
+
#: ``kind -> ((keyword, arity), ...)`` for the required numeric fields, in
|
|
149
|
+
#: emission order. The recognizer accepts them in any order but requires all
|
|
150
|
+
#: of them: a marker missing one describes nothing it could rebuild.
|
|
151
|
+
GUIDE_MARKER_FIELDS: Dict[str, Tuple[Tuple[str, int], ...]] = {
|
|
152
|
+
"refline": (("value", 1), ("extent", 2)),
|
|
153
|
+
"span": (("range", 2), ("extent", 2)),
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
#: The optional trailing string field: a band's legend label, and on the
|
|
157
|
+
#: after-graph form any guide's (its legend entry is a separate line).
|
|
158
|
+
GUIDE_MARKER_LABEL = "label"
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def fraction_expr(axis: str, fraction: str) -> str:
|
|
162
|
+
"""The data coordinate at ``fraction`` of GLE's own ``axis`` range.
|
|
163
|
+
|
|
164
|
+
``axis`` is ``"x"`` or ``"y"`` and ``fraction`` the number as written.
|
|
165
|
+
``0`` and ``1`` are the range ends themselves. No spaces: a call argument
|
|
166
|
+
ends at whitespace.
|
|
167
|
+
"""
|
|
168
|
+
if fraction == "0":
|
|
169
|
+
return f"{axis}gmin"
|
|
170
|
+
if fraction == "1":
|
|
171
|
+
return f"{axis}gmax"
|
|
172
|
+
return f"{axis}gmin+({axis}gmax-{axis}gmin)*{fraction}"
|
gleplot/markers.py
ADDED
|
@@ -0,0 +1,424 @@
|
|
|
1
|
+
"""Marker utilities for gleplot.
|
|
2
|
+
|
|
3
|
+
``MATPLOTLIB_TO_GLE_MARKERS`` covers every code in matplotlib's standard
|
|
4
|
+
*string* marker set (``matplotlib.markers.MarkerStyle.markers``). Two
|
|
5
|
+
conventions run through it:
|
|
6
|
+
|
|
7
|
+
* an **uppercase** code takes the filled GLE glyph and its **lowercase**
|
|
8
|
+
partner the outline one, so a case-significant matplotlib pair stays
|
|
9
|
+
visually distinct in GLE -- ``'D'``/``'d'`` -> ``FDIAMOND``/``DIAMOND``,
|
|
10
|
+
``'*'``/``'p'`` -> ``FSTARR``/``STARR``;
|
|
11
|
+
* where GLE has no corresponding glyph, several matplotlib codes collapse
|
|
12
|
+
onto the closest one -- ``'<'``/``'>'`` -> ``TRIANGLE``, ``'x'``/``'X'``
|
|
13
|
+
-> ``PCROSS``, ``'|'``/``'_'`` -> ``PLUS``.
|
|
14
|
+
|
|
15
|
+
Deliberately **not** mapped, having no GLE glyph that would not misrepresent
|
|
16
|
+
them: matplotlib's integer tick markers (``0``-``3``, tickleft/tickright/
|
|
17
|
+
tickup/tickdown -- single line segments drawn beside a point, not symbols
|
|
18
|
+
centred on it) and its caret markers (``4``-``11``). They fall through to the
|
|
19
|
+
``default`` of :func:`get_gle_marker`.
|
|
20
|
+
|
|
21
|
+
Order matters: ``gleplot.parser.tables._build_gle_marker_to_matplotlib``
|
|
22
|
+
inverts this dict and keeps the *first* matplotlib code seen for each GLE
|
|
23
|
+
name as the canonical one for reading GLE back. Append new codes; do not
|
|
24
|
+
insert them among the established entries.
|
|
25
|
+
|
|
26
|
+
Three families of GLE marker name matter here:
|
|
27
|
+
|
|
28
|
+
- **filled** (``FCIRCLE``, ``FSQUARE``, ...) -- solid ink, the historical
|
|
29
|
+
gleplot default for every matplotlib marker code that has a filled form;
|
|
30
|
+
- **outline** (``CIRCLE``, ``SQUARE``, ...) -- stroked only, *transparent*
|
|
31
|
+
inside, so a line or error bar underneath shows through. This is what
|
|
32
|
+
matplotlib's ``fillstyle='none'`` / ``markerfacecolor='none'`` means;
|
|
33
|
+
- **white-filled** (``WCIRCLE``, ``WSQUARE``, ...) -- stroked outline with an
|
|
34
|
+
opaque white interior that masks whatever is underneath. This is what
|
|
35
|
+
matplotlib's ``markerfacecolor='white'`` means.
|
|
36
|
+
|
|
37
|
+
All three were verified against the GLE 4.3.10 binary at
|
|
38
|
+
``/usr/local/bin/gle`` by rendering every name over a coloured rule: the
|
|
39
|
+
``CIRCLE`` family lets the rule through, the ``W`` family hides it.
|
|
40
|
+
|
|
41
|
+
Filled-vs-open is a load-bearing semantic convention in publication figures
|
|
42
|
+
(e.g. zero-field vs longitudinal-field data on one panel), so the mapping is
|
|
43
|
+
exposed explicitly rather than being reachable only by naming a raw GLE
|
|
44
|
+
marker.
|
|
45
|
+
"""
|
|
46
|
+
|
|
47
|
+
from typing import Dict, Optional
|
|
48
|
+
|
|
49
|
+
from ._warn import warn_external
|
|
50
|
+
|
|
51
|
+
# Matplotlib to GLE marker mapping (the *filled* / default family).
|
|
52
|
+
#
|
|
53
|
+
# NOTE: a few entries here are already outline shapes because GLE has no
|
|
54
|
+
# filled counterpart for them: '<'/'>' (matplotlib's left/right triangles --
|
|
55
|
+
# GLE has no sideways triangle at all, so the up-triangle outline stands in),
|
|
56
|
+
# 'p' (pentagon -> STARR) and 'h' (hexagon -> DIAMOND). Those choices predate
|
|
57
|
+
# outline-marker support and are kept verbatim so existing scripts keep
|
|
58
|
+
# rendering identically; ``fill='none'`` still resolves them to their outline
|
|
59
|
+
# family member (which, for those three, is the same name).
|
|
60
|
+
MATPLOTLIB_TO_GLE_MARKERS = {
|
|
61
|
+
"o": "FCIRCLE", # Circle
|
|
62
|
+
"s": "FSQUARE", # Square
|
|
63
|
+
"^": "FTRIANGLE", # Triangle up
|
|
64
|
+
"v": "FTRIANGLED", # Triangle down
|
|
65
|
+
"<": "TRIANGLE", # Triangle left (outline)
|
|
66
|
+
">": "TRIANGLE", # Triangle right (outline)
|
|
67
|
+
"D": "FDIAMOND", # Diamond
|
|
68
|
+
"*": "FSTARR", # Star
|
|
69
|
+
"p": "STARR", # Pentagon
|
|
70
|
+
"H": "HEART", # Heart
|
|
71
|
+
"h": "DIAMOND", # Hexagon
|
|
72
|
+
"+": "PLUS", # Plus sign
|
|
73
|
+
"P": "PLUS", # Plus alternate
|
|
74
|
+
"x": "PCROSS", # X cross
|
|
75
|
+
"X": "PCROSS", # X cross alternate
|
|
76
|
+
".": "DOT", # Point
|
|
77
|
+
",": "DOT", # Pixel
|
|
78
|
+
"|": "PLUS", # Vertical line
|
|
79
|
+
"_": "PLUS", # Horizontal line
|
|
80
|
+
# Appended (see module docstring: order fixes the canonical inverse).
|
|
81
|
+
"d": "DIAMOND", # Thin diamond -- outline partner of 'D'
|
|
82
|
+
"8": "FCIRCLE", # Octagon -- filled, indistinguishable from a circle
|
|
83
|
+
"1": "TRIANGLED", # tri_down -- spokes of a down triangle
|
|
84
|
+
"2": "TRIANGLE", # tri_up -- spokes of an up triangle
|
|
85
|
+
"3": "TRIANGLE", # tri_left -- as '<', GLE has no directed triangle
|
|
86
|
+
"4": "TRIANGLE", # tri_right -- as '>'
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
#: Accepted values for the ``fill`` argument of :func:`get_gle_marker`.
|
|
90
|
+
MARKER_FILLS = ("full", "none", "white")
|
|
91
|
+
|
|
92
|
+
#: Shape families that have all three fill variants in GLE. Keyed by an
|
|
93
|
+
#: internal family name; the values are the GLE marker names per fill mode.
|
|
94
|
+
#: Any GLE marker NOT listed here (PLUS, PCROSS, DOT, CROSS, STAR, HEART, ...)
|
|
95
|
+
#: has no fill concept and is returned unchanged by :func:`apply_marker_fill`.
|
|
96
|
+
MARKER_FILL_VARIANTS: Dict[str, Dict[str, str]] = {
|
|
97
|
+
"circle": {"full": "FCIRCLE", "none": "CIRCLE", "white": "WCIRCLE"},
|
|
98
|
+
"square": {"full": "FSQUARE", "none": "SQUARE", "white": "WSQUARE"},
|
|
99
|
+
"triangle": {"full": "FTRIANGLE", "none": "TRIANGLE", "white": "WTRIANGLE"},
|
|
100
|
+
"triangled": {"full": "FTRIANGLED", "none": "TRIANGLED", "white": "WTRIANGLED"},
|
|
101
|
+
"diamond": {"full": "FDIAMOND", "none": "DIAMOND", "white": "WDIAMOND"},
|
|
102
|
+
"star": {"full": "FSTARR", "none": "STARR", "white": "WSTARR"},
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
#: GLE marker name -> its shape family in :data:`MARKER_FILL_VARIANTS`.
|
|
106
|
+
_GLE_NAME_TO_FAMILY: Dict[str, str] = {
|
|
107
|
+
name: family
|
|
108
|
+
for family, variants in MARKER_FILL_VARIANTS.items()
|
|
109
|
+
for name in variants.values()
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
#: Colour spellings that mean "white face" (matplotlib ``markerfacecolor``).
|
|
113
|
+
_WHITE_SPELLINGS = frozenset({"w", "white", "#fff", "#ffffff", "1.0", "1"})
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def apply_marker_fill(gle_marker: Optional[str], fill: str = "full") -> Optional[str]:
|
|
117
|
+
"""Map a GLE marker name onto the requested fill variant.
|
|
118
|
+
|
|
119
|
+
Parameters
|
|
120
|
+
----------
|
|
121
|
+
gle_marker : str or None
|
|
122
|
+
A GLE marker name (any case). ``None`` passes through.
|
|
123
|
+
fill : {'full', 'none', 'white'}
|
|
124
|
+
Desired fill: solid, transparent outline, or opaque white outline.
|
|
125
|
+
|
|
126
|
+
Returns
|
|
127
|
+
-------
|
|
128
|
+
str or None
|
|
129
|
+
The family member for ``fill``, or ``gle_marker`` unchanged when the
|
|
130
|
+
shape has no fill variants (PLUS, PCROSS, DOT, ...). The returned
|
|
131
|
+
name preserves the uppercase spelling gleplot emits.
|
|
132
|
+
|
|
133
|
+
Raises
|
|
134
|
+
------
|
|
135
|
+
ValueError
|
|
136
|
+
If ``fill`` is not one of :data:`MARKER_FILLS`.
|
|
137
|
+
"""
|
|
138
|
+
if fill not in MARKER_FILLS:
|
|
139
|
+
raise ValueError(f"fill must be one of {MARKER_FILLS!r}, got {fill!r}")
|
|
140
|
+
if not gle_marker:
|
|
141
|
+
return gle_marker
|
|
142
|
+
name = str(gle_marker).upper()
|
|
143
|
+
family = _GLE_NAME_TO_FAMILY.get(name)
|
|
144
|
+
if family is None:
|
|
145
|
+
return gle_marker
|
|
146
|
+
return MARKER_FILL_VARIANTS[family][fill]
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
#: Matplotlib code -> transparent-outline GLE marker (``fillstyle='none'``).
|
|
150
|
+
MATPLOTLIB_TO_GLE_OUTLINE_MARKERS = {
|
|
151
|
+
code: apply_marker_fill(name, "none")
|
|
152
|
+
for code, name in MATPLOTLIB_TO_GLE_MARKERS.items()
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
#: Matplotlib code -> white-filled GLE marker (``markerfacecolor='white'``).
|
|
156
|
+
MATPLOTLIB_TO_GLE_WHITE_MARKERS = {
|
|
157
|
+
code: apply_marker_fill(name, "white")
|
|
158
|
+
for code, name in MATPLOTLIB_TO_GLE_MARKERS.items()
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
# GLE marker types (documentation for the names gleplot itself emits; the
|
|
162
|
+
# authoritative full list GLE accepts is ``MARKERS`` below,
|
|
163
|
+
# transcribed from GLE's stdmark[] table).
|
|
164
|
+
GLE_MARKER_TYPES = {
|
|
165
|
+
# Filled markers
|
|
166
|
+
"FCIRCLE": "Filled circle",
|
|
167
|
+
"FSQUARE": "Filled square",
|
|
168
|
+
"FTRIANGLE": "Filled triangle",
|
|
169
|
+
"FTRIANGLED": "Filled triangle down",
|
|
170
|
+
"FDIAMOND": "Filled diamond",
|
|
171
|
+
"FSTARR": "Filled star",
|
|
172
|
+
# Outline markers (transparent interior)
|
|
173
|
+
"CIRCLE": "Circle outline",
|
|
174
|
+
"SQUARE": "Square outline",
|
|
175
|
+
"TRIANGLE": "Triangle outline",
|
|
176
|
+
"TRIANGLED": "Triangle outline down",
|
|
177
|
+
"DIAMOND": "Diamond outline",
|
|
178
|
+
"STARR": "Star outline",
|
|
179
|
+
# White-filled markers (opaque interior, masks content underneath)
|
|
180
|
+
"WCIRCLE": "Circle, white fill",
|
|
181
|
+
"WSQUARE": "Square, white fill",
|
|
182
|
+
"WTRIANGLE": "Triangle, white fill",
|
|
183
|
+
"WTRIANGLED": "Triangle down, white fill",
|
|
184
|
+
"WDIAMOND": "Diamond, white fill",
|
|
185
|
+
"WSTARR": "Star, white fill",
|
|
186
|
+
# Symbol markers
|
|
187
|
+
"DOT": "Small dot",
|
|
188
|
+
"PLUS": "Plus sign",
|
|
189
|
+
"PCROSS": "X cross",
|
|
190
|
+
"CROSS": "Cross",
|
|
191
|
+
"CLUB": "Club symbol",
|
|
192
|
+
"HEART": "Heart symbol",
|
|
193
|
+
"SPADE": "Spade symbol",
|
|
194
|
+
"STAR": "Star symbol",
|
|
195
|
+
"DAG": "Dagger symbol",
|
|
196
|
+
"DDAG": "Double dagger",
|
|
197
|
+
"SNAKE": "Snake symbol",
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
|
|
201
|
+
def get_gle_marker(
|
|
202
|
+
matplotlib_marker: str,
|
|
203
|
+
default: str = "FCIRCLE",
|
|
204
|
+
fill: str = "full",
|
|
205
|
+
) -> Optional[str]:
|
|
206
|
+
"""
|
|
207
|
+
Convert matplotlib marker to GLE marker name.
|
|
208
|
+
|
|
209
|
+
Parameters
|
|
210
|
+
----------
|
|
211
|
+
matplotlib_marker : str
|
|
212
|
+
Matplotlib marker symbol (``'o'``, ``'s'``, ...) or a literal GLE
|
|
213
|
+
marker name (``'wcircle'``, ``'FDIAMOND'``, ...), which is passed
|
|
214
|
+
through after validation against GLE's own marker table.
|
|
215
|
+
default : str
|
|
216
|
+
GLE marker used when the symbol is not recognized. Unrecognized
|
|
217
|
+
symbols also emit a :class:`UserWarning` -- gleplot used to fall back
|
|
218
|
+
silently, which turned a typo into a wrong-shaped marker with no
|
|
219
|
+
indication anything had happened.
|
|
220
|
+
fill : {'full', 'none', 'white'}
|
|
221
|
+
Fill style. ``'full'`` returns the historical mapping verbatim;
|
|
222
|
+
``'none'`` returns the transparent-outline family member and
|
|
223
|
+
``'white'`` the opaque white-filled one (shapes with no fill variant,
|
|
224
|
+
e.g. ``PLUS``, are unaffected).
|
|
225
|
+
|
|
226
|
+
Returns
|
|
227
|
+
-------
|
|
228
|
+
str or None
|
|
229
|
+
GLE marker name, or ``None`` when no marker was requested.
|
|
230
|
+
|
|
231
|
+
Raises
|
|
232
|
+
------
|
|
233
|
+
ValueError
|
|
234
|
+
If ``fill`` is not one of :data:`MARKER_FILLS`.
|
|
235
|
+
|
|
236
|
+
Warns
|
|
237
|
+
-----
|
|
238
|
+
UserWarning
|
|
239
|
+
If the marker symbol is neither a known matplotlib code nor a valid
|
|
240
|
+
GLE marker name.
|
|
241
|
+
"""
|
|
242
|
+
if fill not in MARKER_FILLS:
|
|
243
|
+
raise ValueError(f"fill must be one of {MARKER_FILLS!r}, got {fill!r}")
|
|
244
|
+
|
|
245
|
+
# matplotlib's *numeric* markers (0-3 tickleft/right/up/down, 4-11 the
|
|
246
|
+
# carets) are a separate namespace from its string codes -- the int 1 is
|
|
247
|
+
# tickright, the str '1' is tri_down -- and none of them has a GLE glyph
|
|
248
|
+
# (see the module docstring). Take the default rather than stringifying
|
|
249
|
+
# the number into the string table and drawing the wrong symbol.
|
|
250
|
+
if isinstance(matplotlib_marker, (int, float)) and not isinstance(
|
|
251
|
+
matplotlib_marker, bool
|
|
252
|
+
):
|
|
253
|
+
return default
|
|
254
|
+
|
|
255
|
+
if not matplotlib_marker or matplotlib_marker == "None":
|
|
256
|
+
return None
|
|
257
|
+
|
|
258
|
+
marker = str(matplotlib_marker).strip()
|
|
259
|
+
|
|
260
|
+
# Matplotlib marker codes are case-significant: 'D' (diamond) vs 'd'
|
|
261
|
+
# (thin diamond), 'P' (filled plus) vs 'p' (pentagon), 'H' (hexagon2) vs
|
|
262
|
+
# 'h' (hexagon1), 'X' vs 'x'. Try the exact code first so these map
|
|
263
|
+
# correctly, then fall back to a case-insensitive lookup for robustness
|
|
264
|
+
# against stray capitalization of unambiguous codes.
|
|
265
|
+
if marker in MATPLOTLIB_TO_GLE_MARKERS:
|
|
266
|
+
base = MATPLOTLIB_TO_GLE_MARKERS[marker]
|
|
267
|
+
elif marker.lower() in MATPLOTLIB_TO_GLE_MARKERS:
|
|
268
|
+
base = MATPLOTLIB_TO_GLE_MARKERS[marker.lower()]
|
|
269
|
+
elif marker.upper() in MARKERS:
|
|
270
|
+
# A literal GLE marker name (e.g. 'wcircle', 'oplus'). Accept it and
|
|
271
|
+
# normalize the spelling to the uppercase form gleplot emits.
|
|
272
|
+
base = marker.upper()
|
|
273
|
+
else:
|
|
274
|
+
warn_external(
|
|
275
|
+
f"Unrecognized marker {matplotlib_marker!r}: it is neither a "
|
|
276
|
+
f"matplotlib marker code nor a GLE marker name. Falling back to "
|
|
277
|
+
f"{default!r}.",
|
|
278
|
+
)
|
|
279
|
+
base = default
|
|
280
|
+
|
|
281
|
+
# 'full' returns the table value verbatim so long-standing mappings that
|
|
282
|
+
# already point at an outline shape ('<'/'>' -> TRIANGLE, 'p' -> STARR,
|
|
283
|
+
# 'h' -> DIAMOND) keep rendering exactly as before.
|
|
284
|
+
if fill == "full":
|
|
285
|
+
return base
|
|
286
|
+
return apply_marker_fill(base, fill)
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
def resolve_marker_fill(
|
|
290
|
+
fillstyle: Optional[str] = None,
|
|
291
|
+
markerfacecolor: Optional[str] = None,
|
|
292
|
+
) -> str:
|
|
293
|
+
"""Reduce matplotlib's two fill controls to one of :data:`MARKER_FILLS`.
|
|
294
|
+
|
|
295
|
+
matplotlib lets a caller open a marker two ways -- ``fillstyle='none'``
|
|
296
|
+
or ``markerfacecolor='none'`` -- and both are common in the wild, so both
|
|
297
|
+
are accepted here and collapse onto the same GLE outline shape.
|
|
298
|
+
``fillstyle`` wins when both are given (matching matplotlib, where
|
|
299
|
+
``fillstyle`` is a property of the marker style itself).
|
|
300
|
+
|
|
301
|
+
Parameters
|
|
302
|
+
----------
|
|
303
|
+
fillstyle : {'full', 'none', None}, optional
|
|
304
|
+
matplotlib ``fillstyle``. The partial styles (``'top'``,
|
|
305
|
+
``'bottom'``, ``'left'``, ``'right'``) have no GLE equivalent and warn.
|
|
306
|
+
markerfacecolor : str, optional
|
|
307
|
+
matplotlib ``markerfacecolor`` / ``mfc``. ``'none'`` opens the
|
|
308
|
+
marker; a white spelling (``'w'``, ``'white'``, ``'#ffffff'``) selects
|
|
309
|
+
the opaque white-filled family. Any *other* colour warns and is
|
|
310
|
+
ignored: a GLE marker is drawn in a single colour, so an edge colour
|
|
311
|
+
differing from the face colour cannot be represented.
|
|
312
|
+
|
|
313
|
+
Returns
|
|
314
|
+
-------
|
|
315
|
+
str
|
|
316
|
+
``'full'``, ``'none'`` or ``'white'``.
|
|
317
|
+
"""
|
|
318
|
+
if fillstyle is not None:
|
|
319
|
+
style = str(fillstyle).strip().lower()
|
|
320
|
+
if style == "none":
|
|
321
|
+
return "none"
|
|
322
|
+
if style == "full":
|
|
323
|
+
return "full"
|
|
324
|
+
warn_external(
|
|
325
|
+
f"fillstyle={fillstyle!r} has no GLE equivalent (GLE markers are "
|
|
326
|
+
"either solid, outline, or white-filled); using a solid marker.",
|
|
327
|
+
)
|
|
328
|
+
return "full"
|
|
329
|
+
|
|
330
|
+
if markerfacecolor is None:
|
|
331
|
+
return "full"
|
|
332
|
+
|
|
333
|
+
face = str(markerfacecolor).strip().lower()
|
|
334
|
+
if face == "none":
|
|
335
|
+
return "none"
|
|
336
|
+
if face in _WHITE_SPELLINGS:
|
|
337
|
+
return "white"
|
|
338
|
+
warn_external(
|
|
339
|
+
f"markerfacecolor={markerfacecolor!r} is ignored: GLE draws a marker "
|
|
340
|
+
"in a single colour, so a face colour differing from the series "
|
|
341
|
+
"colour cannot be represented. Use markerfacecolor='none' for an "
|
|
342
|
+
"open marker or 'white' for a white-filled one.",
|
|
343
|
+
)
|
|
344
|
+
return "full"
|
|
345
|
+
|
|
346
|
+
|
|
347
|
+
def is_valid_gle_marker(marker: str) -> bool:
|
|
348
|
+
"""Check if marker is a valid GLE marker name.
|
|
349
|
+
|
|
350
|
+
Validates against GLE's own ``stdmark[]`` table (case-insensitive), not
|
|
351
|
+
just the subset gleplot documents in :data:`GLE_MARKER_TYPES`.
|
|
352
|
+
"""
|
|
353
|
+
if not marker:
|
|
354
|
+
return False
|
|
355
|
+
return str(marker).upper() in MARKERS
|
|
356
|
+
|
|
357
|
+
|
|
358
|
+
def get_marker_size_scale(marker: str) -> float:
|
|
359
|
+
"""Get size scaling factor for marker (GLE msize vs matplotlib markersize)."""
|
|
360
|
+
# GLE marker sizes typically need scaling down from matplotlib
|
|
361
|
+
# Default scale is 0.1-0.15 for good visibility
|
|
362
|
+
return 0.15
|
|
363
|
+
|
|
364
|
+
|
|
365
|
+
# ---------------------------------------------------------------------------
|
|
366
|
+
# Markers
|
|
367
|
+
# ---------------------------------------------------------------------------
|
|
368
|
+
#
|
|
369
|
+
# Transcribed from GLE 4.3.10 ``src/gle/pass.cpp`` lines ~2371-2418 (the
|
|
370
|
+
# ``stdmark[]`` array -- the current marker table; NOT the legacy
|
|
371
|
+
# ``stdmark_v35[]`` array that precedes it). This is the full set of marker
|
|
372
|
+
# names GLE's ``marker`` keyword accepts.
|
|
373
|
+
MARKERS = frozenset(
|
|
374
|
+
{
|
|
375
|
+
"ASTERISK",
|
|
376
|
+
"ASTERIX",
|
|
377
|
+
"CIRCLE",
|
|
378
|
+
"CLUB",
|
|
379
|
+
"CROSS",
|
|
380
|
+
"DAG",
|
|
381
|
+
"DDAG",
|
|
382
|
+
"DIAMOND",
|
|
383
|
+
"DIAMONDZ",
|
|
384
|
+
"DOT",
|
|
385
|
+
"FCIRCLE",
|
|
386
|
+
"FDIAMOND",
|
|
387
|
+
"FLOWER",
|
|
388
|
+
"FSQUARE",
|
|
389
|
+
"FSTARR",
|
|
390
|
+
"FTRIANGLE",
|
|
391
|
+
"FTRIANGLED",
|
|
392
|
+
"HANDPEN",
|
|
393
|
+
"HEART",
|
|
394
|
+
"LETTER",
|
|
395
|
+
"MINUS",
|
|
396
|
+
"ODOT",
|
|
397
|
+
"OMINUS",
|
|
398
|
+
"OPLUS",
|
|
399
|
+
"OTIMES",
|
|
400
|
+
"PCROSS",
|
|
401
|
+
"PHONE",
|
|
402
|
+
"PLANE",
|
|
403
|
+
"PLUS",
|
|
404
|
+
"SCIRCLE",
|
|
405
|
+
"SNAKE",
|
|
406
|
+
"SPADE",
|
|
407
|
+
"SQUARE",
|
|
408
|
+
"SSQUARE",
|
|
409
|
+
"STAR",
|
|
410
|
+
"STAR2",
|
|
411
|
+
"STAR3",
|
|
412
|
+
"STAR4",
|
|
413
|
+
"STARR",
|
|
414
|
+
"TRIANGLE",
|
|
415
|
+
"TRIANGLED",
|
|
416
|
+
"TRIANGLEZ",
|
|
417
|
+
"WCIRCLE",
|
|
418
|
+
"WDIAMOND",
|
|
419
|
+
"WTRIANGLE",
|
|
420
|
+
"WTRIANGLED",
|
|
421
|
+
"WSQUARE",
|
|
422
|
+
"WSTARR",
|
|
423
|
+
}
|
|
424
|
+
)
|