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/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
+ )