Day bars now share the chart's dot columns via one floor-edge split (_day_spans), so widths never differ by more than one dot and the wider days interleave with the narrower ones instead of pooling on the left. Every day at least three dots wide opens with its notch — the oldest day's doubling as its clearance off the axis border. Axis ticks pack as dense as two blank cells between labels allow, claimed newest day first, oldest second, then right to left, so a crowded axis thins from the middle-left instead of down to an evenly spaced handful. Months are written on the calendar anchors (the oldest day and the first of a month) rather than tracked across placed ticks. The y-gutter's ┤ tick crosses a braille row at its third dot, so each mark now quotes the value of a bar peaking at that dot — computed with timeline_rows' own baseline math — instead of the row's top edge, which sat a dot above where the glyph points. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
598 lines
27 KiB
Python
598 lines
27 KiB
Python
"""Braille charts: the one way MeshTerm draws a value-over-time row or a meter.
|
||
|
||
Every timeline in the app — the header's activity pulse, the channel manager's
|
||
per-channel sparklines, the dashboard's tall packet chart, the Time Machine's
|
||
histories — renders through this module, so they all share the same three rules:
|
||
|
||
* **Time flows left → right.** The rightmost column is *now*; history trails away
|
||
to the left. Chronological (oldest-first) series feed :func:`timeline_rows`
|
||
directly; the newest-first histograms the monitor and repository keep are passed
|
||
as-is to :func:`activity_sparkline`, which reverses them into place.
|
||
* **Grey is zero.** Every chart draws a faint one-dot baseline at value zero and
|
||
bars grow *from that line*, so a silent stretch reads as a flatline, never a
|
||
hole. When a series carries negative values (an SNR history, say) the baseline
|
||
sits at zero's height inside the chart — positive readings rise above it,
|
||
negative ones hang below — rather than being nailed to the chart floor. The one
|
||
deliberate break in the line is :data:`GAP`, a column that renders *fully blank*
|
||
down to the axis, used to notch adjacent bars apart (the Time Machine's per-day
|
||
charts space one day from the next this way).
|
||
* **Two readings per cell.** Braille offers two dot columns per character cell;
|
||
every chart uses both, so each cell shows two consecutive readings and the
|
||
chart draws at twice the horizontal resolution of the cells it occupies.
|
||
|
||
The low-level cell assembly is shared: bars are expressed as inclusive dot-row
|
||
spans anchored on the baseline, and each character cell takes the bar style when
|
||
any bar dot falls in it, the faint baseline style when only the zero line does,
|
||
and stays blank braille otherwise (blank braille, not a space, so the grid stays
|
||
monospace under fonts with slightly odd braille metrics).
|
||
|
||
Beyond timelines, the module owns the app's two other braille conventions:
|
||
|
||
* :func:`meter` — the single-value horizontal bar (the dashboard's traffic
|
||
tallies, the SNR quality bars), always packing two fill steps per cell so a
|
||
``width``-cell meter resolves ``2 × width`` levels.
|
||
* :func:`axis_caption` — the ``oldest → now`` line under a timeline, which
|
||
fills in intermediate marks whenever the chart is wide enough to fit them.
|
||
* :func:`axis_chart` — frames :func:`timeline_rows` output in a mirrored
|
||
numeric y-axis (the dashboard's activity chart, the Time Machine's per-day
|
||
and rhythm charts), so a chart quotes its scale on the gutters instead of
|
||
just naming the peak in its heading.
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from bisect import bisect_right
|
||
from typing import Callable, Optional, Sequence, Union
|
||
|
||
from rich.text import Text
|
||
|
||
#: Braille dot bit for each dot row counted from the *bottom* of a cell (row 0 is
|
||
#: the cell's lowest dot), left and right columns. The Unicode braille block
|
||
#: numbers its rows top-down (dots 1,2,3,7 left / 4,5,6,8 right); these tables
|
||
#: flip that so chart math can stay in bottom-up "height" space throughout.
|
||
_LEFT_BITS = (0x40, 0x04, 0x02, 0x01)
|
||
_RIGHT_BITS = (0x80, 0x20, 0x10, 0x08)
|
||
|
||
#: How a lit cell is styled: a fixed Rich style name, or a callable given the
|
||
#: cell's present readings (one or two values) returning the style — the hook the
|
||
#: Time Machine uses to colour an SNR band by each slice's quality.
|
||
CellStyle = Union[str, Callable[[list[float]], str]]
|
||
|
||
|
||
class _Gap:
|
||
"""The type of :data:`GAP`; a private singleton, so ``value is GAP`` identifies it."""
|
||
|
||
__slots__ = ()
|
||
|
||
def __repr__(self) -> str: # pragma: no cover - a debugging aid only
|
||
return "GAP"
|
||
|
||
|
||
#: A timeline value marking a hard gap: the column renders *fully blank* — no bar and
|
||
#: no zero baseline — so it breaks the "grey is zero" flatline on purpose. ``None`` and
|
||
#: ``0`` still draw the faint zero line (a silent reading is still a reading); only
|
||
#: ``GAP`` punches a hole in it, used to notch adjacent day bars apart in the Time
|
||
#: Machine's per-day charts so same-height neighbours never fuse into one solid block.
|
||
GAP = _Gap()
|
||
|
||
|
||
def chart_span(
|
||
values: Sequence[Optional[float]], span: Optional[tuple[float, float]] = None
|
||
) -> tuple[float, float]:
|
||
"""The vertical range a chart of ``values`` draws over, zero always included.
|
||
|
||
The grey baseline *is* zero, so the span is the data's extent folded around it:
|
||
all-positive data spans ``0 → peak`` (the baseline on the floor), all-negative
|
||
data ``floor → 0`` (the baseline on the ceiling, bars hanging), mixed data both.
|
||
Callers that caption their chart's scale should quote this same span so the
|
||
label and the drawing can never disagree.
|
||
|
||
Args:
|
||
values: The chart's readings (``None`` marks an empty slot; :data:`GAP` a
|
||
hard gap — neither carries a magnitude, so both sit out the span).
|
||
span: An optional wider range to honour (it too is folded around zero).
|
||
|
||
Returns:
|
||
``(lo, hi)`` with ``lo <= 0 <= hi``; ``(0.0, 0.0)`` for an empty series.
|
||
"""
|
||
present = [v for v in values if v is not None and v is not GAP]
|
||
if span is not None:
|
||
present = [*present, *span]
|
||
lo = min([0.0, *present])
|
||
hi = max([0.0, *present])
|
||
return lo, hi
|
||
|
||
|
||
def timeline_rows(
|
||
values: Sequence[Optional[float]],
|
||
*,
|
||
rows: int = 1,
|
||
span: Optional[tuple[float, float]] = None,
|
||
style: CellStyle = "ok",
|
||
baseline_style: str = "faint",
|
||
column_styles: Optional[Sequence[str]] = None,
|
||
) -> list[Text]:
|
||
"""Render a chronological series as a braille bar chart, newest at the right.
|
||
|
||
``values`` is oldest-first, one reading per dot column (two per character
|
||
cell), scaled onto :func:`chart_span`'s zero-folded range: the series' peak
|
||
fills the space above the baseline, its floor the space below, and any
|
||
non-zero reading lights at least one dot so a lone packet never vanishes.
|
||
``None`` (no reading) and ``0`` alike draw only the faint zero baseline;
|
||
:data:`GAP` draws nothing at all, breaking the baseline into a clean notch.
|
||
|
||
Args:
|
||
values: Per-slot readings, oldest first (the rightmost is "now"). An odd
|
||
count is padded with one silent column so whole cells always render.
|
||
A :data:`GAP` slot renders fully blank (bar and baseline both).
|
||
rows: How many braille rows tall the chart is (four dot rows each).
|
||
span: A wider range to scale against (see :func:`chart_span`), so several
|
||
charts — or a chart and its caption — can share one scale.
|
||
style: Style for lit cells: a Rich style name, or a callable given each
|
||
cell's present readings (for per-slice colouring).
|
||
baseline_style: Style for the zero line where nothing covers it.
|
||
column_styles: Optional per-column styles, aligned with ``values``,
|
||
overriding ``style`` — how the activity charts dim history recorded by
|
||
an earlier session. A cell straddling two styles takes its newer
|
||
(right) lit column's.
|
||
|
||
Returns:
|
||
``rows`` :class:`Text` lines, top row first, ``ceil(len(values)/2)``
|
||
characters wide.
|
||
"""
|
||
lo, hi = chart_span(values, span)
|
||
total = rows * 4
|
||
base = _baseline_row(lo, hi, total)
|
||
up = total - base # dot rows available to a full-scale positive bar
|
||
down = base + 1 # …and to a full-scale negative one (baseline row included)
|
||
|
||
bars: list[Optional[tuple[int, int]]] = []
|
||
for value in values:
|
||
# GAP must short-circuit ahead of the numeric tests — it has no magnitude,
|
||
# so ``value == 0`` / ``value > 0`` would misfire (or raise) on the sentinel.
|
||
if value is GAP or value is None or value == 0:
|
||
bars.append(None)
|
||
elif value > 0:
|
||
height = max(1, round(value / hi * up))
|
||
bars.append((base, base + height - 1))
|
||
else:
|
||
height = max(1, round(value / lo * down))
|
||
bars.append((base - height + 1, base))
|
||
return _assemble(bars, list(values), rows, base, style, baseline_style, column_styles)
|
||
|
||
|
||
def activity_sparkline(
|
||
histogram: Sequence[int],
|
||
levels: tuple[int, ...],
|
||
buckets: int,
|
||
*,
|
||
style: str = "ok",
|
||
column_styles: Optional[Sequence[str]] = None,
|
||
) -> Text:
|
||
"""A one-row activity sparkline over a newest-first histogram, "now" rightmost.
|
||
|
||
Bar heights are absolute, stepped at ``levels`` (the count a bucket must reach
|
||
for each extra dot), so the same traffic always draws the same bar regardless
|
||
of what else is on screen and a lone packet never vanishes. The histogram
|
||
arrives newest-first — the natural order the monitor and repository keep — and
|
||
is reversed here, so the current bucket lands on the right edge and traffic
|
||
slides *left* as it ages, like every other MeshTerm timeline.
|
||
|
||
Args:
|
||
histogram: Per-bucket counts, newest first; padded/cropped to ``buckets``.
|
||
levels: Ascending count thresholds for bar heights 1..4.
|
||
buckets: How many buckets to draw (half this many characters).
|
||
style: Style for lit cells.
|
||
column_styles: Optional per-bucket styles aligned with ``histogram``
|
||
(newest first, reversed here alongside it), overriding ``style`` —
|
||
how the header pulse dims buckets recorded by an earlier session.
|
||
|
||
Returns:
|
||
A styled Rich :class:`Text` of ``buckets / 2`` braille characters.
|
||
"""
|
||
window = (tuple(histogram) + (0,) * buckets)[:buckets]
|
||
per_column: Optional[list[str]] = None
|
||
if column_styles is not None:
|
||
padded = (list(column_styles) + [style] * buckets)[:buckets]
|
||
per_column = list(reversed(padded))
|
||
bars: list[Optional[tuple[int, int]]] = []
|
||
for count in reversed(window):
|
||
height = bisect_right(levels, count)
|
||
bars.append((0, height - 1) if height else None)
|
||
return _assemble(
|
||
bars, [float(c) for c in reversed(window)], 1, 0, style, "faint", per_column
|
||
)[0]
|
||
|
||
|
||
#: The meter's fill glyphs, ``(full step, half step)``, by profile. A *full-height*
|
||
#: meter lights all four dot rows (``⣿`` both columns, ``⡇`` the left column alone),
|
||
#: reading as a solid tally bar. A *slim* meter lights only the middle two rows
|
||
#: (``⠶`` / ``⠆``), so the bar floats mid-cell and can sit over an unlit track of the
|
||
#: same glyph without turning into a solid block.
|
||
_METER_FULL = ("⣿", "⡇")
|
||
_METER_SLIM = ("⠶", "⠆")
|
||
|
||
|
||
def meter(
|
||
fraction: Optional[float],
|
||
width: int,
|
||
*,
|
||
style: str,
|
||
slim: bool = False,
|
||
track: Optional[str] = None,
|
||
) -> Text:
|
||
"""Render a single value as a horizontal braille meter, two fill steps per cell.
|
||
|
||
The one way MeshTerm draws a proportion as a bar. Both dot columns of every cell
|
||
are always exploited — a ``width``-cell meter resolves ``2 × width`` levels — and
|
||
any *reading* lights at least one half step, even one clamped to the floor of its
|
||
scale: a measured bottom is still a measurement, so it never vanishes (``None``
|
||
is how a truly empty meter is asked for). Two profiles cover the app's two cases:
|
||
|
||
* **full-height, no track** (the default): all four dot rows, unlit cells left
|
||
blank — a tally bar whose length *is* the reading (the dashboard's traffic
|
||
lanes).
|
||
* **slim, on a track** (``slim=True, track="track"``): only the middle two dot
|
||
rows, with the unlit remainder drawn in the same glyph dimmed to ``track`` — a
|
||
gauge whose reading fills in a visible background (the SNR quality bars). The
|
||
boundary half-step keeps the reading's colour, not the track's: it is still
|
||
part of what was measured.
|
||
|
||
Args:
|
||
fraction: The fill as a fraction of full scale, clamped to ``0 .. 1``;
|
||
``None`` draws an entirely unlit meter (just the track, if any).
|
||
width: The meter's full-scale span in character cells.
|
||
style: Style for the lit fill.
|
||
slim: Light only the middle two dot rows instead of all four.
|
||
track: Style for the unlit remainder, drawn in the full-step glyph; ``None``
|
||
pads with spaces instead, so the meter still occupies ``width`` cells.
|
||
|
||
Returns:
|
||
A :class:`Text` exactly ``width`` cells wide.
|
||
"""
|
||
full_glyph, half_glyph = _METER_SLIM if slim else _METER_FULL
|
||
if fraction is None:
|
||
steps = 0
|
||
else:
|
||
frac = min(1.0, max(0.0, fraction))
|
||
steps = max(1, round(frac * width * 2))
|
||
full, half = divmod(steps, 2)
|
||
bar = Text(full_glyph * full + half_glyph * half, style=style)
|
||
rest = width - full - half
|
||
if track is not None:
|
||
bar.append(full_glyph * rest, style=track)
|
||
else:
|
||
bar.append(" " * rest)
|
||
return bar
|
||
|
||
|
||
def axis_caption(
|
||
chars: int,
|
||
label_at: Callable[[float], str],
|
||
*,
|
||
style: str = "faint",
|
||
) -> tuple[Text, list[int]]:
|
||
"""The caption line under a timeline: edge labels plus whatever marks fit between.
|
||
|
||
Every chart used to caption only its ends (``oldest … now``); this asks
|
||
``label_at`` for the labels at the quarter points too and keeps the densest set
|
||
that fits — quarters, else the midpoint, else just the two ends — so a wide chart
|
||
reads its timescale without counting cells. The first label is left-aligned on the
|
||
chart's left edge, the last right-aligned on its right edge, and interior labels
|
||
are centred on the fraction they describe, each separated by at least two blank
|
||
cells so they never run together.
|
||
|
||
Args:
|
||
chars: The chart's width in character cells (the caption matches it).
|
||
label_at: Maps a position fraction (``0.0`` = the oldest column, ``1.0`` =
|
||
now) to its label.
|
||
style: Style the whole caption is drawn in.
|
||
|
||
Returns:
|
||
``(caption, tick_cells)`` — the caption :class:`Text` exactly ``chars`` cells
|
||
wide, and the chart column each placed label points at, so the axis border can
|
||
notch a ``┬`` under it (see :func:`axis_chart`).
|
||
"""
|
||
for segments in (4, 2, 1):
|
||
fractions = [i / segments for i in range(segments + 1)]
|
||
labels = [label_at(f) for f in fractions]
|
||
cells: list[str] = [" "] * chars
|
||
taken: list[tuple[int, int]] = [] # placed [start, end) spans, in order
|
||
ticks: list[int] = [] # the chart column each label points at
|
||
ok = True
|
||
for frac, label in zip(fractions, labels):
|
||
if frac == 0.0:
|
||
start = 0
|
||
ref = 0
|
||
elif frac == 1.0:
|
||
start = chars - len(label)
|
||
ref = chars - 1
|
||
else:
|
||
centre = round(frac * chars)
|
||
start = min(chars - len(label), max(0, centre - len(label) // 2))
|
||
ref = min(chars - 1, centre)
|
||
end = start + len(label)
|
||
if end > chars or any(start < e + 2 and s < end + 2 for s, e in taken):
|
||
ok = False
|
||
break
|
||
taken.append((start, end))
|
||
ticks.append(ref)
|
||
cells[start:end] = label
|
||
if ok:
|
||
return Text("".join(cells), style=style), ticks
|
||
# Even the two edge labels collide: keep the left one and let it stand alone.
|
||
label = label_at(0.0)[:chars]
|
||
return Text(label.ljust(chars), style=style), [0]
|
||
|
||
|
||
def y_axis_labels(peak: float, rows: int, *, lo: float = 0.0) -> list[str]:
|
||
"""Each chart row's ticked-dot value, top row first, dupes and zeros blanked.
|
||
|
||
The gutter's ``┤`` tick crosses a braille row at the third dot up from the
|
||
row's bottom, so each mark quotes the value of a bar peaking *at that dot* —
|
||
the reading the tick visibly points at, not the row's top edge — using the
|
||
same zero-folded scaling :func:`timeline_rows` draws bars with (baseline row
|
||
and all). A mark that would repeat the one above (a low peak makes
|
||
neighbouring dots round to the same value) or read zero is left blank, so the
|
||
scale never shows the same number twice. A signed chart passes its floor as
|
||
``lo`` (``< 0``): marks above the grey zero line quote rise heights, marks
|
||
below it hang depths, so the gutter shows both signs of a zero-crossing
|
||
series (an SNR band's ``+5 … −10 dB``) instead of only the positive peak.
|
||
"""
|
||
total = rows * 4
|
||
base = _baseline_row(lo, peak, total)
|
||
labels: list[str] = []
|
||
seen: set[int] = set()
|
||
for i in range(rows):
|
||
dot = (rows - 1 - i) * 4 + 2 # the dot row this row's ┤ tick crosses
|
||
if dot > base:
|
||
value = round(peak * (dot - base + 1) / (total - base))
|
||
elif dot < base:
|
||
value = round(lo * (base - dot + 1) / (base + 1))
|
||
else:
|
||
value = 0 # the tick sits on the zero baseline itself
|
||
if peak != lo and value and value not in seen:
|
||
labels.append(str(value))
|
||
seen.add(value)
|
||
else:
|
||
labels.append("")
|
||
return labels
|
||
|
||
|
||
#: Minimum blank cells kept between two column-axis labels, so a thinned tick row
|
||
#: reads as separate marks rather than a run of touching text.
|
||
_TICK_GAP = 2
|
||
|
||
|
||
def _tick_axis(
|
||
chars: int,
|
||
label_w: int,
|
||
ticks: Sequence[tuple[int, str]],
|
||
style: str,
|
||
) -> tuple[Text, str]:
|
||
"""Build the boxed border and its caption for a column chart with explicit ticks.
|
||
|
||
Each tick is a ``(cell, label)`` pointing at a chart column: the border draws a
|
||
``┬`` at that column and the label sits centred beneath it. Labels are placed
|
||
left to right and any that would land within :data:`_TICK_GAP` cells of the one
|
||
before it is dropped — tick and all — so a crowded axis thins to what fits
|
||
instead of overprinting. Callers pre-thin to roughly the right count (see the
|
||
Time Machine's ``_day_ticks``); this is the collision backstop.
|
||
|
||
Args:
|
||
chars: The chart's width in character cells.
|
||
label_w: The y-axis gutter width the border and caption indent past.
|
||
ticks: ``(cell, label)`` marks, any order; ``cell`` is a 0-based chart column.
|
||
style: Style for the border (and its ticks).
|
||
|
||
Returns:
|
||
``(border, caption_text)`` — the border :class:`Text` and the plain caption
|
||
string, ready to indent under the gutter.
|
||
"""
|
||
cells = [" "] * chars
|
||
marked: list[int] = []
|
||
last_end = -_TICK_GAP
|
||
for cell, label in sorted(ticks):
|
||
cell = max(0, min(chars - 1, cell))
|
||
start = max(0, min(chars - len(label), cell - len(label) // 2))
|
||
if start < last_end + _TICK_GAP:
|
||
continue # would crowd the label before it — drop this mark
|
||
cells[start : start + len(label)] = list(label)
|
||
marked.append(cell)
|
||
last_end = start + len(label)
|
||
return _tick_border(chars, label_w, marked, style), "".join(cells)
|
||
|
||
|
||
def _tick_border(chars: int, label_w: int, tick_cells: Sequence[int], style: str) -> Text:
|
||
"""The boxed bottom border, notched with a ``┬`` at each charted tick column."""
|
||
marked = {max(0, min(chars - 1, c)) for c in tick_cells}
|
||
bar = "".join("┬" if i in marked else "─" for i in range(chars))
|
||
return Text(" " * label_w + " └" + bar + "┘", style=style)
|
||
|
||
|
||
def axis_chart(
|
||
chart_rows: list[Text],
|
||
peak: float,
|
||
chars: int,
|
||
label_at: Optional[Callable[[float], str]] = None,
|
||
*,
|
||
label_w: Optional[int] = None,
|
||
style: str = "muted",
|
||
floor: float = 0.0,
|
||
ticks: Optional[Sequence[tuple[int, str]]] = None,
|
||
) -> list[Text]:
|
||
"""Frame :func:`timeline_rows` output with a mirrored y-axis and x-axis caption.
|
||
|
||
Each row's top-edge value is mirrored on both gutters (blank where it would
|
||
repeat the mark above or read zero), closed with a boxed bottom border, and
|
||
followed by an x-axis caption indented to clear the gutter.
|
||
|
||
The caption comes one of two ways. A *continuous* chart passes ``label_at`` and
|
||
the ends-plus-quarters marks of :func:`axis_caption` fill in whatever fits. A
|
||
*columnar* chart — bars of a fixed width apiece, a day or a slot each — instead
|
||
passes ``ticks``: explicit ``(cell, label)`` marks that centre a label under its
|
||
own column and notch the border with a ``┬`` beneath it (see :func:`_tick_axis`),
|
||
so a date sits under the bar it names rather than at an arbitrary fraction.
|
||
|
||
Args:
|
||
chart_rows: The chart's rows, as returned by :func:`timeline_rows`.
|
||
peak: The chart's full-scale ceiling (its tallest bar's value); each
|
||
row's gutter mark quotes the value at the dot its tick points at
|
||
(see :func:`y_axis_labels`), so the peak itself sizes the gutter
|
||
but is not necessarily printed.
|
||
chars: The chart's width in character cells.
|
||
label_at: Maps a position fraction to the x-axis caption at that point
|
||
(a continuous chart); ignored when ``ticks`` is given.
|
||
label_w: The gutter's digit width, when several stacked charts must
|
||
share one width so their gutters line up; sized from ``peak`` (and
|
||
``floor``) by default.
|
||
style: Style for the gutters, ticks, marks, and border.
|
||
floor: The value the bottom edge reads on a signed chart (``< 0``), so
|
||
the gutter quotes both extremes of a zero-crossing series (the Time
|
||
Machine's SNR band). Defaults to ``0`` — an all-positive chart whose
|
||
baseline sits on the floor, the common case.
|
||
ticks: Explicit ``(cell, label)`` column marks for a columnar chart; when
|
||
given they drive the border and caption instead of ``label_at``.
|
||
|
||
Returns:
|
||
``len(chart_rows) + 2`` :class:`Text` lines: the decorated rows, the
|
||
bottom border, and the caption.
|
||
"""
|
||
label_w = label_w or max(1, len(str(round(peak))), len(str(round(floor))))
|
||
marks = y_axis_labels(peak, len(chart_rows), lo=floor)
|
||
out: list[Text] = []
|
||
for mark, row in zip(marks, chart_rows):
|
||
line = Text(f"{mark:>{label_w}} " + ("┤" if mark else "│"), style=style)
|
||
line.append_text(row)
|
||
line.append("├" if mark else "│", style=style)
|
||
if mark:
|
||
line.append(f" {mark}", style=style)
|
||
out.append(line)
|
||
if ticks is not None:
|
||
border, caption_text = _tick_axis(chars, label_w, ticks, style)
|
||
caption = Text(" " * (label_w + 2))
|
||
caption.append(caption_text, style="faint")
|
||
else:
|
||
assert label_at is not None, "axis_chart needs label_at or ticks"
|
||
# A continuous axis notches the same ┬ ticks under its ends-and-quarters
|
||
# labels as a columnar one does under its bars — one axis grammar everywhere.
|
||
caption_body, tick_cells = axis_caption(chars, label_at)
|
||
border = _tick_border(chars, label_w, tick_cells, style)
|
||
caption = Text(" " * (label_w + 2))
|
||
caption.append_text(caption_body)
|
||
out.append(border)
|
||
out.append(caption)
|
||
return out
|
||
|
||
|
||
def _baseline_row(lo: float, hi: float, total: int) -> int:
|
||
"""The dot row (from the chart bottom) the zero baseline sits on.
|
||
|
||
All-positive data pins it to the floor, all-negative to the ceiling; a mixed
|
||
span places it proportionally, clamped one row in from either edge so both
|
||
directions keep at least one dot row to draw in.
|
||
|
||
Args:
|
||
lo: The span's floor (``<= 0``).
|
||
hi: The span's ceiling (``>= 0``).
|
||
total: The chart's height in dot rows.
|
||
|
||
Returns:
|
||
The baseline's dot row, ``0 .. total - 1``.
|
||
"""
|
||
if lo == 0:
|
||
return 0
|
||
if hi == 0:
|
||
return total - 1
|
||
return min(total - 2, max(1, round((total - 1) * -lo / (hi - lo))))
|
||
|
||
|
||
def _column_bits(bar: Optional[tuple[int, int]], floor: int, table: tuple[int, ...]) -> int:
|
||
"""The braille bits one column's bar lights within a cell row.
|
||
|
||
Args:
|
||
bar: The bar's inclusive dot-row span (chart coordinates), or ``None``.
|
||
floor: The cell row's bottom dot row in chart coordinates.
|
||
table: :data:`_LEFT_BITS` or :data:`_RIGHT_BITS`.
|
||
|
||
Returns:
|
||
The OR of the covered dots' bits (0 when the bar misses this cell row).
|
||
"""
|
||
if bar is None:
|
||
return 0
|
||
lo, hi = max(bar[0], floor), min(bar[1], floor + 3)
|
||
bits = 0
|
||
for dot in range(lo, hi + 1):
|
||
bits |= table[dot - floor]
|
||
return bits
|
||
|
||
|
||
def _assemble(
|
||
bars: list[Optional[tuple[int, int]]],
|
||
values: list[Optional[float]],
|
||
rows: int,
|
||
base: int,
|
||
style: CellStyle,
|
||
baseline_style: str,
|
||
column_styles: Optional[Sequence[str]] = None,
|
||
) -> list[Text]:
|
||
"""Assemble bar spans into styled braille rows (the shared cell walk).
|
||
|
||
Every bar span includes the baseline row by construction, so a half-silent
|
||
cell keeps the zero line continuous inside the lit character; a fully silent
|
||
cell shows just the faint baseline dots on whichever row holds them; anything
|
||
else stays blank braille to keep the grid monospace. The baseline is decided
|
||
per *dot column*, not per cell, so a :data:`GAP` column can go fully blank —
|
||
breaking the zero line into a notch — while its cell-mate keeps its own.
|
||
|
||
Args:
|
||
bars: Per-column inclusive dot-row spans (``None`` = no bar).
|
||
values: The readings behind the columns, aligned with ``bars`` (fed to a
|
||
callable ``style`` two at a time, per cell); a :data:`GAP` reading
|
||
suppresses that column's baseline so the notch reaches the axis.
|
||
rows: Chart height in braille rows.
|
||
base: The zero baseline's dot row.
|
||
style: Fixed style, or per-cell callable (see :data:`CellStyle`).
|
||
baseline_style: Style for baseline-only cells.
|
||
column_styles: Per-column style overrides aligned with ``bars``; a cell
|
||
takes its right column's style when that column is lit, else its
|
||
left's (the newer reading wins the shared cell).
|
||
|
||
Returns:
|
||
``rows`` :class:`Text` lines, top row first.
|
||
"""
|
||
if len(bars) % 2:
|
||
bars = [*bars, None]
|
||
values = [*values, None]
|
||
lines: list[Text] = []
|
||
for row in range(rows):
|
||
floor = (rows - 1 - row) * 4
|
||
base_bit_left = _LEFT_BITS[base - floor] if floor <= base <= floor + 3 else 0
|
||
base_bit_right = _RIGHT_BITS[base - floor] if floor <= base <= floor + 3 else 0
|
||
line = Text()
|
||
for i in range(0, len(bars), 2):
|
||
# A GAP column carries no baseline, so the zero line breaks there and the
|
||
# notch runs clean from the top edge down to the axis border.
|
||
bl = 0 if values[i] is GAP else base_bit_left
|
||
br = 0 if values[i + 1] is GAP else base_bit_right
|
||
left = _column_bits(bars[i], floor, _LEFT_BITS)
|
||
right = _column_bits(bars[i + 1], floor, _RIGHT_BITS)
|
||
if left or right:
|
||
mask = left | right | bl | br
|
||
if column_styles is not None and i + 1 < len(column_styles):
|
||
cell_style = column_styles[i + 1] if right else column_styles[i]
|
||
elif callable(style):
|
||
present = [
|
||
v for v in values[i : i + 2] if v is not None and v is not GAP
|
||
]
|
||
cell_style = style(present) if present else baseline_style
|
||
else:
|
||
cell_style = style
|
||
line.append(chr(0x2800 | mask), style=cell_style)
|
||
elif bl or br:
|
||
line.append(chr(0x2800 | bl | br), style=baseline_style)
|
||
else:
|
||
line.append(chr(0x2800))
|
||
lines.append(line)
|
||
return lines
|