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
|
|
|
|
|
2020-04-03 11:47:36 +00:00
|
|
|
notcurses_plot - high level widget for plotting
|
2020-04-01 07:44:32 +00:00
|
|
|
|
|
|
|
# SYNOPSIS
|
|
|
|
|
2020-04-19 22:46:32 +00:00
|
|
|
**#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-05-09 15:23:49 +00:00
|
|
|
|
2020-04-01 09:05:29 +00:00
|
|
|
typedef struct ncplot_options {
|
2020-04-03 05:05:28 +00:00
|
|
|
// channels for the maximum and minimum levels.
|
|
|
|
// lerp across the domain between these two.
|
2020-08-23 16:44:53 +00:00
|
|
|
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.
|
2020-04-09 01:26:15 +00:00
|
|
|
int rangex;
|
2020-08-23 16:44:53 +00:00
|
|
|
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
|
|
|
```
|
|
|
|
|
2020-11-06 21:49:35 +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
|
|
|
|
2020-11-06 21:49:35 +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
|
|
|
|
2020-11-06 21:49:35 +00:00
|
|
|
**struct ncplane* ncuplot_plane(struct ncuplot* ***n***);**
|
2020-04-24 07:18:47 +00:00
|
|
|
|
2020-11-06 21:49:35 +00:00
|
|
|
**struct ncplane* ncdplot_plane(struct ncdplot* ***n***);**
|
2020-04-01 07:44:32 +00:00
|
|
|
|
2020-11-06 21:49:35 +00:00
|
|
|
**int ncuplot_add_sample(struct ncuplot* ***n***, uint64_t ***x***, uint64_t ***y***);**
|
2020-04-24 07:18:47 +00:00
|
|
|
|
2020-11-06 21:49:35 +00:00
|
|
|
**int ncdplot_add_sample(struct ncdplot* ***n***, uint64_t ***x***, double ***y***);**
|
2020-04-03 05:05:28 +00:00
|
|
|
|
2020-11-06 21:49:35 +00:00
|
|
|
**int ncuplot_set_sample(struct ncuplot* ***n***, uint64_t ***x***, uint64_t ***y***);**
|
2020-04-24 07:18:47 +00:00
|
|
|
|
2020-11-06 21:49:35 +00:00
|
|
|
**int ncdplot_set_sample(struct ncdplot* ***n***, uint64_t ***x***, double ***y***);**
|
2020-04-23 07:52:07 +00:00
|
|
|
|
2020-11-06 21:49:35 +00:00
|
|
|
**int ncuplot_sample(const struct ncuplot* ***n***, uint64_t ***x***, uint64_t* ***y***);**
|
2020-06-12 04:13:01 +00:00
|
|
|
|
2020-11-06 21:49:35 +00:00
|
|
|
**int ncdplot_sample(const struct ncdplot* ***n***, uint64_t ***x***, double* ***y***);**
|
2020-06-12 04:13:01 +00:00
|
|
|
|
2020-11-06 21:49:35 +00:00
|
|
|
**void ncuplot_destroy(struct ncuplot* ***n***);**
|
2020-04-24 07:18:47 +00:00
|
|
|
|
2020-11-06 21:49:35 +00:00
|
|
|
**void ncdplot_destroy(struct ncdplot* ***n***);**
|
2020-04-01 07:44:32 +00:00
|
|
|
|
|
|
|
# DESCRIPTION
|
|
|
|
|
2020-04-23 07:52:07 +00:00
|
|
|
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
|
2020-04-23 07:52:07 +00:00
|
|
|
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.
|
2020-04-23 07:52:07 +00:00
|
|
|
|
2020-05-09 15:23:49 +00:00
|
|
|
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-23 07:52:07 +00:00
|
|
|
|
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-03 11:47:36 +00:00
|
|
|
|
2020-04-01 07:44:32 +00:00
|
|
|
# RETURN VALUES
|
|
|
|
|
2020-04-23 07:52:07 +00:00
|
|
|
**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
|
2020-04-04 12:56:31 +00:00
|
|
|
**gridtype** will result in an error.
|
2020-04-03 05:16:16 +00:00
|
|
|
|
2020-04-23 07:52:07 +00:00
|
|
|
**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)**
|