.\" trend.1: trend manual
.\" Copyright(c) 2006-2009 by wave++ "Yuri D'Elia" <wavexx@users.sf.net>
.\" Distributed under GNU LGPL WITHOUT ANY WARRANTY.
.\"
.Dd November 2, 2007
.Dt TREND 1
.\"
.\"
.Sh NAME
.Nm trend
.Nd a general-purpose, efficient trend graph
.\"
.\"
.Sh SYNOPSIS
.Nm
.Op Fl dDSsvlmFgGhtAERIMNTLzfcpue
.Op Fl display
.Op Fl geometry
.Op Fl iconic
.Aq Ar fifo | \-
.Aq Ar hist-spec | hist-sz x-sz
.Op Ar low high
.\"
.\"
.Sh DESCRIPTION
.Nm
is a general-purpose, efficient trend graph for "live" data. Data is read in
ASCII form from a file or continuously from a FIFO and displayed in real-time
into a multi-pass trend (much like a CRT oscilloscope).
.Nm
can be used as a rapid analysis tool for progressive or time-based data series
together with trivial scripting.
.Pp
.Nm
requires at least a valid
.Ar fifo
to read from and an history specification
.Ar ( hist-spec )
or, for advanced usage, a combination of history size and horizontal size
.Ar ( hist-sz No and Ar x-sz No respectively).
Optionally, to disable auto-scaling, the vertical limits can be specified
directly through the command line via
.Ar low No and Ar high .
The default input format is ASCII, in absolute counting mode. Many settings
can be changed directly during execution.
.\"
.\"
.Sh INPUT
.\"
.Ss 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
.Ar \-
instead of a named file. A named FIFO can be created using the
.Xr mkfifo 1
command. FIFOs are automatically re-opened upon EOF. See the
.Sx EXAMPLES
section.
.Pp
Alternatively you can store your data in a plain file and simply display its
last values non-interactively.
.Pp
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.
.\"
.Ss ASCII DATA
The default data format is a space/tab/newline-separated series of parseable
ASCII numbers; eg:
.Bd -literal -offset indent
1 2 3 4 5.1 0642
0x12 \-12.4E5 .987
.Ed
.Pp
The parser is very lenient, and will silently ignore whatever looks like
garbage.
.\"
.Ss COUNTING MODES
By default all input values are considered absolute and displayed "as is" in a
single graph.
.Pp
The
.Fl c Ar [N]mode
flag allows to specify an alternate counting mode and the number of available
graphs. Available modes are:
.Pp
.Bl -tag -offset indent -compact -width " a "
.It Ar a
absolute (default)
.It Ar i
incremental counter
.It Ar d
differential values
.El
.Pp
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:
.Ar 2a
draws two graphs in absolute mode). See
.Sx MULTIPLE GRAPHS
for more details on how this affects the input stream.
.\"
.Ss FORMAT TYPES
Different input formats are supported, as specified by the
.Fl f
flag. Note however that only the ASCII parser (the default) silently ignores
errors. NaNs and Infinity have special treatment. Internally,
.Nm
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:
.Pp
.Bl -tag -offset indent -compact -width " a "
.It Ar a
ASCII parser (default)
.It Ar f
binary float
.It Ar d
binary double
.It Ar s
binary short
.It Ar i
binary int
.It Ar l
binary long
.El
.\"
.Ss 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
.Fl e
flag is set, Infinity enters an escape sequence instead (See
.Sx ESCAPE SEQUENCES )
.\"
.Ss MULTIPLE GRAPHS
Multiple graphs can be displayed inside a single trend instance by specifying
a prefix number N for the
.Fl 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:
.Bd -literal -offset indent
.Op A0 B0 C0
A1 B1 C1
A2 B2 C2
\&.. .. ..
.Ed
.Pp
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.
.Pp
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
.Ic TAB
key and differentiated using the
.Ic K
key, which cycles between "normal", "dim others" and "hide others" views. The
graph key, if enabled, also highlights the current graph.
.\"
.Ss ESCAPE SEQUENCES
If escape sequences are enabled (through the
.Fl 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
.Nm
interface and parameters remotely.
.\"
.\"
.Sh OPTIONS
.\"
.Ss FLAGS
.Bl -tag -compact -width " \-I colour[,colour...] "
.It Fl d
"dimmed" shading mode
.It Fl D
visible distribution graph
.It Fl S
enable anti-aliasing
.It Fl s
"scrolling" mode
.It Fl v
visible values
.It Fl l
visible visual/max sync latency
.It Fl m
visible marker
.It Fl F
enable filling
.It Fl g
visible grid
.It Fl G Ar grid-spec
specify grid resolution
.It Fl z Ar zero[,zero...]
specify y zero/s
.It Fl h
help and version info
.It Fl t Ar str
specify a window title
.It Fl A Ar colour
background colour
.It Fl E Ar colour
text (values) colour
.It Fl R Ar colour
grid colour
.It Fl I Ar colour[,colour...]
trend colour/s
.It Fl M Ar colour
marker colour
.It Fl N Ar colour
interactive examiner colour
.It Fl T Ar colour
edit mode colour
.It Fl L Ar label[,label...]
trend label/s
.It Fl c Ar mode
input number/counting mode (See
.Sx COUNTING MODES )
.It Fl f Ar format
input format (See
.Sx FORMAT TYPES )
.It Fl p Ar rate
polling rate (hz)
.It Fl u
show undefined values
.It Fl e
enable escape sequences (See
.Sx ESCAPE SEQUENCES )
.It Fl display
.No See Xr X 7 .
.It Fl geometry
.No See Xr X 7 .
.It Fl iconic
.No See Xr X 7 .
.El
.\"
.Ss 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:
.Pp
.Bl -tag -compact -offset indent -width " NxM "
.It Ar N
Sets x-sz to N, and hist-sz to N+1.
.It Ar N/M
Sets hist-sz to N, and x-sz to N/M.
.It Ar NxM
Sets x-sz to N, and hist-sz to N*M.
.El
.Pp
While this may seem hard at first,
.Ic trend fifo '60x3'
is an easier way of
expressing "60 seconds for 3 minutes" and similar idioms.
.\"
.Ss COLOUR
A colour is specified in hex RGB format, as follows:
.Li #RRGGBB , RRGGBB No or Li 0xRRGGBB ;
some examples:
.Pp
.Bl -tag -compact -offset indent -width " #000000 "
.It Li #FF0000
red
.It Li #00FF00
green
.It Li #A020F0
purple
.El
.\"
.Ss GRID-SPEC
A grid specification is of the form:
.Pp
.Dl [[A][+C]][x[B][+C]]
.Pp
(eg:
.Li 1.3 , 10+5 , 1x10+5 , +5x+5 ; +1x+1
gets the old behaviour) where:
.Pp
.Bl -tag -compact -offset indent -width " A "
.It Va A
y grid resolution
.It Va B
x grid resolution
.It Va C
draw a mayor line every C normal grid lines
.El
.\"
.\"
.Sh DISPLAY
.\"
.Ss INTERACTIVE KEYS
.Bl -tag -compact -offset indent -width " space "
.It Ic ESC
quit/exit
.It Ic TAB
cycle current graph
.It Ic a
toggle auto-scaling
.It Ic A
re-scale the graph without activating auto-scaling
.It Ic d
toggle dimmed shading mode
.It Ic D
toggle distribution graph
.It Ic S
toggle anti-aliasing
.It Ic s
switch scrolling mode (wrap-around or scrolling)
.It Ic v
toggle values
.It Ic l
show visual and maximal sync latency
.It Ic L
set limits interactively
.It Ic m
activate a marker on the current cursor position
.It Ic f
toggle filling
.It Ic g
toggle grid
.It Ic G
change grid-spec interactively
.It Ic z
change zero interactively
.It Ic Z
set limits by center and amplitude
.It Ic p
change polling rate interactively
.It Ic u
toggle display of undefined values
.It Ic k
toggle the graph key
.It Ic K
cycle view mode (normal, dim others or hide others)
.It Ic space
pause visualisation (but still continue to consume input to preserve time
coherency)
.El
.\"
.Ss 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.
.\"
.Ss 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
.Sx UPDATE POLICY
section for further details.
.\"
.Ss 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.
.\"
.Ss 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.
.\"
.Ss 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).
.\"
.Ss 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.
.Pp
By holding down the CTRL key while clicking/dragging only "foreground" values
will be considered.
.Pp
When clicking inside the distribution graph, the current count for the selected
value is displayed instead.
.Pp
The examiners can be removed by clicking anywhere with the third mouse button.
.\"
.Ss DISTRIBUTION GRAPH
.Ic D No or Fl 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.
.\"
.Ss FILLING
.Ic f No or Fl 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.
.\"
.\"
.Sh UPDATE POLICY
.Bl -item
.It
The fifo is read and managed asynchronously from the graphics. Delays at the
display end will not interfere with the data feed.
.It
The fifo is unbuffered and the feeder thread is synchronously locked on it
waiting for new data.
.It
The value is put in the history buffer when a separator character is received
after the value, or, for binary input, when the needed amount of bytes is read
(in this case each value is read with a single read call).
.It
The polling rate (as defined by
.Ic p No or Fl p
and defaulting to 1000) defines how often the history buffer should be checked
for updates and kept in sync with the visual. Values greater than 1000 result
in continuous scanning (note that this only affects the maximal sync latency,
and not the display rate, which is handled automatically).
.It
Syncing occurs atomically, reflecting the actual state at the instant of the
update. Scheduler latencies apply.
.El
.\"
.\"
.Sh ENVIRONMENT
.Ev DISPLAY See Xr X 7 .
.\"
.\"
.Sh EXAMPLES
Running
.Nm
with a named FIFO:
.Pp
.Dl mkfifo fifo
.Dl command > fifo &
.Dl trend fifo ...
.Pp
Display the number of current active processes over time:
.Pp
.Dl (while true; do ps \-A | wc \-l; sleep 1; done) | \e
.Dl trend \- 60x24
.Pp
Display two graphs:
.Pp
.Dl trend \-c2a \-L"graph 1, graph 2" fifo ...
.\"
.\"
.Sh DIAGNOSTICS
.Ex -std
.\"
.\"
.Sh ERRORS
.Bl -diag
.It trend: producer thread exiting
The data stream finished for some reason (the specified file was invalid at
the time of the request). For regular or invalid files this warning is
normal.
.El
.\"
.\"
.Sh SEE ALSO
.Xr mkfifo 1 ,
.Xr stdin 4 ,
.Xr fd 4 ,
.Pa /usr/share/doc/trend/examples/
.\"
.\"
.Sh AUTHORS
.Nm
is distributed under LGPL (see COPYING)
.Em WITHOUT ANY WARRANTY .
Copyright(c) 2003-2009 by
.An "Yuri D'Elia" Aq wavexx@users.sf.net .