Files
MeshTerm/meshterm/ui/braillechart.py
T
Jean-Pierre MartineauandClaude Fable 5 072a4573fe Activity charts: a previous session's history dims to grey
timeline_rows and activity_sparkline accept per-column style overrides,
and the monitor exposes which histogram buckets this session actually
heard. The header pulse draws seeded history grey and live traffic
green, so a restart is visible in the chart instead of masquerading as
fresh reception; the dashboard chart follows in the next commit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-11 18:35:41 -04:00

393 lines
17 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""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.
* **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.
"""
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]]
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).
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]
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.
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.
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:
if 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",
) -> Text:
"""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:
A :class:`Text` exactly ``chars`` cells wide.
"""
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
ok = True
for frac, label in zip(fractions, labels):
if frac == 0.0:
start = 0
elif frac == 1.0:
start = chars - len(label)
else:
centre = round(frac * chars)
start = min(chars - len(label), max(0, centre - len(label) // 2))
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))
cells[start:end] = label
if ok:
return Text("".join(cells), style=style)
# 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)
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.
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).
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):
left = _column_bits(bars[i], floor, _LEFT_BITS)
right = _column_bits(bars[i + 1], floor, _RIGHT_BITS)
if left or right:
mask = left | right | base_bit_left | base_bit_right
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]
cell_style = style(present) if present else baseline_style
else:
cell_style = style
line.append(chr(0x2800 | mask), style=cell_style)
elif base_bit_left:
line.append(chr(0x2800 | base_bit_left | base_bit_right), style=baseline_style)
else:
line.append(chr(0x2800))
lines.append(line)
return lines