notcurses_plot(3)

✨ notcurses_plot — high level widget for plotting ✨

okay so this is the notcurses_plot(3) page from the notcurses fam, and bestie, it's giving data visualization but make it terminal 💅 like literally plotting histograms inside your TUI. buckle up 🎀

---

🌸 SYNOPSIS 🌸

#include <notcurses/notcurses.h>

the little flag besties, all six of them, yes we're listing every single one 👑:

#define NCPLOT_OPTION_LABELTICKSD   0x0001u
#define NCPLOT_OPTION_EXPONENTIALD  0x0002u
#define NCPLOT_OPTION_VERTICALI     0x0004u
#define NCPLOT_OPTION_NODEGRADE     0x0008u
#define NCPLOT_OPTION_DETECTMAXONLY 0x0010u
#define NCPLOT_OPTION_PRINTSAMPLE   0x0020u

and here's the options struct, the icon itself 🫶:

typedef struct ncplot_options {
  // channels for the maximum and minimum levels.
  // lerp across the domain between these two.
  uint64_t maxchannels;
  uint64_t minchannels;
  // styling used for labels (NCPLOT_OPTION_LABELTICKSD)
  uint16_t legendstyle;
  // pass NCBLIT_DEFAULT maps to NCBLIT_8x1 (assuming
  // UTF8) or NCBLIT_1x1 (in an ASCII environment)
  ncblitter_e gridtype;
  // independent variable can either be a contiguous range,
  // or a finite set of keys. for a time range, say the
  // previous hour sampled with second resolution, the
  // independent variable would be the range [0..3600): 3600.
  // if rangex is 0, it is dynamically set to the number
  // of columns.
  int rangex;
  const char* title;   // optional title
  uint64_t flags;      // bitfield over NCPLOT_OPTION_*
} ncplot_options;

and the functions, every last one, no skips 💖:

struct ncuplot* ncuplot_create(struct ncplane* n, const ncplot_options*
opts, uint64_t miny, uint64_t maxy);

struct ncdplot* ncdplot_create(struct ncplane* n, const ncplot_options*
opts, double miny, double maxy);

struct ncplane* ncuplot_plane(struct ncuplot* n);

struct ncplane* ncdplot_plane(struct ncdplot* n);

int ncuplot_add_sample(struct ncuplot* n, uint64_t x, uint64_t y);

int ncdplot_add_sample(struct ncuplot* n, uint64_t x, double y);

int ncuplot_set_sample(struct ncuplot* n, uint64_t x, uint64_t y);

int ncdplot_set_sample(struct ncuplot* n, uint64_t x, double y);

int ncuplot_sample(const struct ncuplot* n, uint64_t x, uint64_t* y);

int ncdplot_sample(const struct ncdplot* n, uint64_t x, double* y);

void ncuplot_destroy(struct ncuplot* n);

void ncdplot_destroy(struct ncdplot* n);

---

🦋 DESCRIPTION 🦋

so these functions support histograms — yes, actual histograms, in your terminal, slay 🔥 the independent variable is always a uint64_t. the samples are either uint64_ts (that's ncuplot) or doubles (that's ncdplot). only a window over the samples is retained at any given time, and here's the tea: this window can only move towards larger values of the independent variable. it moves forward whenever an x larger than the current window's maximum is handed to add_sample or set_sample ⭐

• add_sample increments the current value corresponding to this x by y.
• set_sample replaces the current value corresponding to this x.

if rangex is 0, or larger than the bound plane will support, it gets capped to the available space (rude but fair 🙈). the domain can either be specified as miny and maxy, or domain autodetection can be invoked by setting both to 0. if the domain is specified, samples outside the domain are an error and do not contribute to the plot. supplying an x below the current window is an error too, and has no effect 💀

more granular block glyphs means more resolution in your plots, but ngl they can be difficult to differentiate at small text sizes. octants, sextants, and Braille allow for more resolution on the independent variable. it can be difficult to predict how the Braille glyphs will look in a given font — font-dependent chaos, iykyk 😭

the same ncplot_options struct can be used with all ncplot types, one struct to rule them all 💅 the flags field is a bitmask composed of:

• NCPLOT_OPTION_LABELTICKSD — Label dependent axis ticks
• NCPLOT_OPTION_EXPONENTIALD — Use an exponential dependent axis
• NCPLOT_OPTION_VERTICALI — Vertical independent axis
• NCPLOT_OPTION_NODEGRADE — Fail rather than degrade blitter
• NCPLOT_OPTION_DETECTMAXONLY — Detect only max domain, not min
• NCPLOT_OPTION_PRINTSAMPLE — Print the most recent sample

if NCPLOT_OPTION_LABELTICKSD or NCPLOT_OPTION_PRINTSAMPLE is supplied, the legendstyle field will be used to style the labels. otherwise it's literally ignored, main character of nothing 🌈

the label is printed in the upper left, immediately to the right of the topmost axis tick (if NCPLOT_OPTION_LABELTICKSD was used). the most recent sample is printed opposite from the label along the independent axis (if NCPLOT_OPTION_PRINTSAMPLE was used). positioned, periodt ✨

---

🎀 NOTES 🎀

NCPLOT_OPTION_VERTICALI is not yet implemented. like it exists, it's in the bitmask, but it does not do the thing yet 🙈 don't come for me, I'm just the messenger 💀

---

💜 RETURN VALUES 💜

create will return an error if miny equals maxy, but they are non-zero. it will also return an error if maxy < miny. and an invalid gridtype will result in an error too — bestie the validation is not playing around 🫶

plane returns the ncplane on which the plot is drawn. it cannot fail. iconic. flawless. no notes 👑

---

🌟 SEE ALSO 🌟

notcurses(3), notcurses_plane(3), notcurses_visual(3)

---

🍓 AUTHORS 🍓

nick black nickblack@linux.com

---

and that's the whole page bestie, mwah 💋 this lil beauty is v3.0.17 of the notcurses_plot(3) manual — go plot something iconic and remember: respect the window, it only moves forward 💅✨