notcurses/doc/man/man3/notcurses_plot.3.md

127 lines
4.9 KiB
Markdown
Raw Normal View History

2020-04-01 07:44:32 +00:00
% notcurses_plot(3)
% nick black <nickblack@linux.com>
2021-03-08 12:10:50 +00:00
% v2.2.3
2020-04-01 07:44:32 +00:00
# NAME
notcurses_plot - high level widget for plotting
2020-04-01 07:44:32 +00:00
# SYNOPSIS
**#include <notcurses/notcurses.h>**
2020-04-01 07:44:32 +00:00
```c
2020-08-21 11:34:50 +00:00
#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
2020-12-06 11:33:54 +00:00
#define NCPLOT_OPTION_PRINTSAMPLE 0x0020u
2020-04-01 09:05:29 +00:00
typedef struct ncplot_options {
// channels for the maximum and minimum levels.
// lerp across the domain between these two.
uint64_t maxchannels;
uint64_t minchannels;
2020-08-21 11:34:50 +00:00
// styling used for labels (NCPLOT_OPTION_LABELTICKSD)
uint16_t legendstyle;
2020-09-13 18:40:18 +00:00
// pass NCBLIT_DEFAULT maps to NCBLIT_8x1 (assuming
// UTF8) or NCBLIT_1x1 (in an ASCII environment)
Fully general ncvisual layer (#647) This represents an essentially complete rewrite of ncvisual and associated code. It had two major goals: Improve the ncvisual API based off lessons learned, pursuant to the upcoming API freeze. In particular, I wanted to: decouple ncvisuals from ncplanes. It should be possible to render a ncvisual to multiple planes, with different scaling each time. It should be possible to create an ncvisual without a plane, etc. normalize the various ways of constructing an ncvisual -- file, memory, plane, etc. Support multiple blitters, from 7-bit ASCII to Sixel. This required writing the blitters in several cases, and they're not yet in their final implementations (but the API is fine) I have not yet unified Plots and Visuals, and might not, given that the Plot code works fine. We could at this point implement Plots in terms of Visuals, though -- the blitter backend range has been unified. Sixel is not yet implemented, though it is listed. There is a new POC tool, blitter. It renders its arguments using all possible blitter+scaling combinations. Another new POC, resize, displays its argument, then resizes it to the screen size and displays that, explicitly making use of ncvisual_resize() rather than a scaling parameter to ncvisual_render(). This also eliminates some memory leaks and bugs we were seeing in trunk, and brings in Sixel scaffolding. The C++ wrapper will also need patching back up; I cut most of it down while wrestling with this crap, urk. Closes #638, #562, and #622.
2020-05-29 01:16:58 +00:00
ncblitter_e gridtype;
2020-09-13 18:40:18 +00:00
// 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
2020-09-13 18:40:18 +00:00
uint64_t flags; // bitfield over NCPLOT_OPTION_*
2020-04-01 09:05:29 +00:00
} ncplot_options;
2020-04-01 07:44:32 +00:00
```
**struct ncuplot* ncuplot_create(struct ncplane* ***n***, const ncplot_options* ***opts***, uint64_t ***miny***, uint64_t ***maxy***);**
2020-04-24 07:18:47 +00:00
**struct ncdplot* ncdplot_create(struct ncplane* ***n***, const ncplot_options* ***opts***, double ***miny***, double ***maxy***);**
2020-04-01 09:05:29 +00:00
**struct ncplane* ncuplot_plane(struct ncuplot* ***n***);**
2020-04-24 07:18:47 +00:00
**struct ncplane* ncdplot_plane(struct ncdplot* ***n***);**
2020-04-01 07:44:32 +00:00
**int ncuplot_add_sample(struct ncuplot* ***n***, uint64_t ***x***, uint64_t ***y***);**
2020-04-24 07:18:47 +00:00
**int ncdplot_add_sample(struct ncdplot* ***n***, uint64_t ***x***, double ***y***);**
**int ncuplot_set_sample(struct ncuplot* ***n***, uint64_t ***x***, uint64_t ***y***);**
2020-04-24 07:18:47 +00:00
**int ncdplot_set_sample(struct ncdplot* ***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***);**
2020-04-24 07:18:47 +00:00
**void ncdplot_destroy(struct ncdplot* ***n***);**
2020-04-01 07:44:32 +00:00
# DESCRIPTION
These functions support histograms. The independent variable is always an
**uint64_t**. The samples are either **uint64_t**s (**ncuplot**) or **double**s
(**ncdplot**). Only a window over the samples is retained at any given time,
and this window can only move towards larger values of the independent
variable. The window is moved forward whenever an **x** larger than the current
window's maximum is supplied 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 is capped
to the available space. The domain can either be specified as **miny** and
**maxy**, or domain autodetection can be invoked via 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, and has no effect.
More granular block glyphs means more resolution in your plots, but they can
2020-12-06 11:33:54 +00:00
be difficult to differentiate at small text sizes. Sextants and Braille allow
for more resolution on the independent variable. It can be difficult to predict
2020-12-06 11:33:54 +00:00
how the Braille glyphs will look in a given font.
The same **ncplot_options** struct can be used with all ncplot types. The
**flags** field is a bitmask composed of:
2020-08-21 11:34:50 +00:00
* **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
2020-12-06 11:33:54 +00:00
* **NCPLOT_OPTION_PRINTSAMPLE**: Print the most recent sample
2020-08-21 11:34:50 +00:00
2020-12-06 11:33:54 +00:00
If **NCPLOT_OPTION_LABELTICKSD** or **NCPLOT_OPTION_PRINTSAMPLE** is supplied,
the **legendstyle** field will be used to style the labels. It is otherwise
ignored.
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
2020-12-10 14:22:26 +00:00
recent sample is printed opposite from the label along the independent axis
(if **NCPLOT_OPTION_PRINTSAMPLE** was used).
2020-04-01 07:44:32 +00:00
# NOTES
2020-12-06 11:33:54 +00:00
**NCPLOT_OPTION_VERTICALI** is not yet implemented.
2020-04-01 07:44:32 +00:00
# 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**. An invalid
**gridtype** will result in an error.
**plane** returns the **ncplane** on which the plot is drawn. It cannot fail.
2020-04-01 09:05:29 +00:00
2020-04-01 07:44:32 +00:00
# SEE ALSO
**notcurses(3)**,
Fully general ncvisual layer (#647) This represents an essentially complete rewrite of ncvisual and associated code. It had two major goals: Improve the ncvisual API based off lessons learned, pursuant to the upcoming API freeze. In particular, I wanted to: decouple ncvisuals from ncplanes. It should be possible to render a ncvisual to multiple planes, with different scaling each time. It should be possible to create an ncvisual without a plane, etc. normalize the various ways of constructing an ncvisual -- file, memory, plane, etc. Support multiple blitters, from 7-bit ASCII to Sixel. This required writing the blitters in several cases, and they're not yet in their final implementations (but the API is fine) I have not yet unified Plots and Visuals, and might not, given that the Plot code works fine. We could at this point implement Plots in terms of Visuals, though -- the blitter backend range has been unified. Sixel is not yet implemented, though it is listed. There is a new POC tool, blitter. It renders its arguments using all possible blitter+scaling combinations. Another new POC, resize, displays its argument, then resizes it to the screen size and displays that, explicitly making use of ncvisual_resize() rather than a scaling parameter to ncvisual_render(). This also eliminates some memory leaks and bugs we were seeing in trunk, and brings in Sixel scaffolding. The C++ wrapper will also need patching back up; I cut most of it down while wrestling with this crap, urk. Closes #638, #562, and #622.
2020-05-29 01:16:58 +00:00
**notcurses_plane(3)**,
**notcurses_visual(3)**