FIFO¶

To display real-time data you should use a FIFO. Both standard input and named pipes can be used. Standard input (used for simple pipelining purposes) can be opened by using - instead of a named file. A named FIFO can be created using the mkfifo(1) command. FIFOs are automatically re-opened upon EOF. See the EXAMPLES section.

Alternatively you can store your data in a plain file and simply display its last values non-interactively.

When new data is written, the value is plotted and the cursor position is advanced. That is, the graph scrolling speed is determined by the speed of the data flow. When the number of received values is above the specified horizontal size, the graph will wrap or scroll, depending on your settings.

ASCII DATA¶

The default data format is a space/tab/newline-separated series of parseable ASCII numbers; eg:

1 2 3 4 5.1 0642
0x12 -12.4E5 .987

The parser is very lenient, and will silently ignore whatever looks like garbage.

COUNTING MODES¶

By default all input values are considered absolute and displayed "as is" in a single graph.

The -c [N]mode flag sets an alternate counting mode and the number of available graphs. Available modes are:

In incremental and differential mode, each value is calculated using the previous value as a reference except for the first, which is taken as absolute. The number of graphs can be specified by prefixing a multiplier before the counting mode (eg: 2a draws two graphs in absolute mode). See MULTIPLE GRAPHS for more details on how this affects the input stream.

FORMAT TYPES¶

Different input formats are supported, as specified by the -f flag. Note however that only the ASCII parser (the default) silently ignores errors. NaNs and Infinity have special treatment. Internally, trend always works with double precision floating points: conversion toward these is performed with the default FPU conversion rules. The actual underlying binary format depends on the host architecture:

SPECIAL VALUES¶

ASCII and binary floating point input have special treatment for NaNs and Infinity (entered in any representable form). Both are considered as "undefined values". Undefined values can be highlighted, but aren't otherwise rendered. If the -e flag is set, Infinity enters an escape sequence instead (See ESCAPE SEQUENCES)

MULTIPLE GRAPHS¶

Multiple graphs can be displayed inside a single trend instance by specifying a prefix number N for the -c flag. The input is interleaved, but otherwise unchanged: the reference value, if needed, is expected to be seen N times, one for each graph. Thus, for three graphs (A, B and C), the input order is:

[A0 B0 C0]
A1 B1 C1
A2 B2 C2
.. .. ..

The display is updated only once all graph values are read. The color, label and origin for each graph can be specified through the usual command-line flags, separating each value with a comma; in the same order as the input. Default colors and labels are assigned if not completely specified.

All graphs share and are affected by the same settings, except for the origin (zero) which can be changed independently. Filling, values and the examiners only work on the current graph. The current graph can be cycled dynamically with the TAB key and differentiated using the K key, which cycles between "normal", "dim others" and "hide others" views. The graph key, if enabled, also highlights the current graph.

ESCAPE SEQUENCES¶

If escape sequences are enabled (through the -e flag), entering Infinity (in any representable form) will start an escape sequence. Currently, this feature is not yet implemented: Infinity is simply discarded. This is reserved for future use as a way to control the trend interface and parameters remotely.

FLAGS¶

-d

"dimmed" shading mode

-D

visible distribution graph

-S

enable anti-aliasing

-s

"scrolling" mode

-v

visible values

-l

visible visual/max sync latency

-m

visible marker

-F

enable filling

-g

visible grid

-G grid-spec

specify grid resolution

-z zero[,zero...]

specify y zero/s

-h

help and version info

-t str

specify a window title

-A colour

background colour

-E colour

text (values) colour

-R colour

grid colour

-I colour[,colour...]

trend colour/s

-M colour

marker colour

-N colour

interactive examiner colour

-T colour

edit mode colour

-L label[,label...]

trend label/s

-c mode

input number/counting mode (See COUNTING MODES)

-f format

input format (See FORMAT TYPES)

-p rate

polling rate (hz)

-u

show undefined values

-e

enable escape sequences (See ESCAPE SEQUENCES)

-display

See X(7).

-geometry

See X(7).

-iconic

See X(7).

HIST-SPEC¶

An history specification is another convenient form of defining the pair `hist-sz x-sz` for common cases. An history specification can be in either one of the following formats:

While this may seem hard at first, trend fifo '60x3' is an easier way of expressing "60 seconds for 3 minutes" and similar idioms.

COLOUR¶

A colour is specified in hex RGB format, as follows: #RRGGBB, RRGGBB or 0xRRGGBB; some examples:

GRID-SPEC¶

A grid specification is of the form:

(eg: 1.3, 10+5, 1x10+5, +5x+5; +1x+1 gets the old behaviour) where:

INTERACTIVE KEYS¶

AUTOSCALING¶

When autoscaling is enabled the graph will be scaled vertically to fit visible values. The grid resolution is used to add some vertical bounds to the graph. Disabling autoscaling interactively will retain current limits. When the grid is too dense to be displayed it's deactivated automatically.

LATENCY INDICATOR¶

The latency indicator shows a 5s average of the visual and maximal sync latency (in seconds). The visual latency is the time-frame between real value updates and the final output you're seeing: it includes copy/redraw times, which varies depending on enabled layers, plus video sync. The maximal sync latency is the maximal time ever required for any received value to be synced with the display: since the display is updated atomically, values received while redrawing are implicitly delayed. See the UPDATE POLICY section for further details.

SHADING MODES¶

The default is to shade uniformly old values to complete transparency. The "dimmed" shading mode draws the foreground values with full opacity and the others with half opacity.

SCROLLING MODES¶

The default visualisation mode is "wrap-around": newer values will simply wrap around the screen when new data arrives. The other available one is "scrolling": new data is always placed at the right edge of the screen, and older values scrolled on the left.

VALUE INDICATORS¶

Three value indicators are drawn on the screen: upper limit, lower limit and current value (respectively on the upper right, lower right and lower left of the screen).

INTERACTIVE EXAMINERS¶

You can query interactively the graph for any value in the history by clicking with the first mouse button. This will enable a permanent examiner in the selected position and display up to the three nearest values in the upper-left corner of the screen. Intersections are projected horizontally, while a small circle will show the position of the nearest sampled value. The mean value refers to the three intersections.

By holding down the CTRL key while clicking/dragging only "foreground" values will be considered.

When clicking inside the distribution graph, the current count for the selected value is displayed instead.

The examiners can be removed by clicking anywhere with the third mouse button.

DISTRIBUTION GRAPH¶

D or -D enable a distribution graph on the left side of the window. This is especially useful when analyzing the continuity of a function or signal. Intensity is proportional to the visible maximum.

FILLING¶

f or -F enable filling. In standard mode, or when hist-sz is smaller than x-sz, the area between the curve and zero will be filled. Otherwise, in dimmed mode, the area between the "foreground" and "background" values is filled instead.