plot

tuios.dev/plot draws charts as terminal cells. It has eight chart kinds: bar (horizontal and vertical), line, area, sparkline, gauge, histogram, heatmap and pie (a donut or a full disc).

go get tuios.dev/plot

The API reference is on pkg.go.dev.

Draw a chart

A chart draws into a grid of the size you give it. Each cell holds one grapheme and a role, such as series1, mute or track. Your program maps each role to a colour at the colour depth of the terminal. The package holds no colour and writes no escape sequence.

bar := plot.Bar{
	Values:     []float64{6.2, 4.8, 3.1},
	Labels:     []string{"session", "app", "vt"},
	Horizontal: true,
}
g := bar.Draw(30, 3, plot.Blocks)
fmt.Println(g.String())

session ██████████████████ 6.2
app     █████████████▉     4.8
vt      █████████          3.1

g.At(x, y) gives a cell with its text, width and role.

Modes

A mode sets the glyphs a chart can use. Use the best mode that the terminal and its font can show.

Heatmaps use whole cells, or half blocks when the rows do not fit. A pie is a disc of half-block pixels. In ASCII, each series, slice and heat level has its own mark, so they stay apart without colour.

Axes and legends

• Columns, lines, areas and histograms can have a y axis with round tick labels, a base line, and the first, middle and last x label.
• Columns whose values all sit far above zero start from a round base under the smallest value. The axis labels that base.
• Horizontal bars keep a value column that never clips. Labels give way first.
• Line.Legend and Pie.Legend return legend items, and DrawLegend draws them.

Rules

• Every chart is total. NaN and infinite values count as missing. Empty data draws an empty grid.
• A grid is always the size you ask for, and each row is exactly that wide.
• Sizes that a caller could pass unchecked are bounded: a grid is at most 4096 cells a side, a histogram has at most one bin per cell and 1000 bins, a line draws at most 64 series, and a pie draws 12 slices, the rest folded into one called "other".
• Labels are cut with an ellipsis to fit. Control characters are dropped, and invalid UTF-8 shows as ?.
• A line chart with more values than cells is reduced with largest triangle three buckets, which keeps the peaks.

Widths come from charmbracelet/x/ansi, the same width functions that tuios uses. loom uses plot to draw the TML chart components.