DCMD2GRAP(1) General Commands Manual DCMD2GRAP(1)

NAME

dcmd2grapgraph dives with grap

SYNOPSIS

dcmd2grap [-adv] [-m mode] [-s splitmode] [files...]

DESCRIPTION

The dcmd2grap utility accepts XML files generated by dcmd(1) and graphs each dive's depths in the grap(1) data format. By default, dives start at time zero through their maximum time. Multiple dives are superimposed (“stacked”). For analysing free dives, it's important that the exported dive profile be in Canonical free diving mode to make analysis useful (i.e., of each separate free dive within a sequence). The arguments of dcmd2grap are as follows:
 
 
-a
“Adjust” some split-graph values so that the y-axis is adjusted above and below the axis, and not linear. This is useful when y-values are clustered very close, but not near zero, thus looking like a horizontal line. This only applies to -m temp.
 
 
-d
Derivatives. Show change in velocity instead of depth. This only applies to aggr and stack modes.
 
 
-m mode
Graphing mode. May be one of the following:
 
 
all
Emit all graphs on a series of pages. This will print the graph title, then the graph, then a new page. If the graph was not printed (e.g., a temperature graph when there are no temperature values), the graph will be omitted.
 
 
aggr
Line graph connecting (“aggregating”) subsequent dives with real time (relative to the beginning of the first dive) on the x-axis and depth on the y-xais.
 
 
aggrtemp
The same as aggr, but with the temperature on the y-axis. Your dive computer(s) must support temperature readings.
 
 
rest
Impulse graph with each dive's rest time (surface interval) on the positive y-axis and dive time on the negative y-axis. The x-axis is independent. Needs at least two dives.
 
 
restscatter
Scatter graph with points corresponding to dive time and rest time. A line with minimum suggested free diving interval is shown (twice the dive time) if any of the dives are free dives. Needs at least two dives.
 
 
rsummary
Like summary, except dives are shown on an x-axis of their start time relative to the first dive in a grouped sequence.
 
 
scatter
Scatter graph with points at the intersection of dives' maximum depth and time.
 
 
stack
Default line graph with dives layered over one other, dive time on the x-axis, depth on the y-axis.
 
 
stacktemp
The same as stack, except with temperatures on the y-axis. Your dive computer(s) must support temperature readings.
 
 
summary
Each independent dive is shown on the x-axis with the maximum depth and time above and below, respectively, the y-axis. Dives on the x-axis are ordered by date; or if a -s split is specified, ordered between groups by relative offset from respective group's first dive time.
 
 
temp
Each independent dive is shown on the x-axis with the minimum temperature and time above and below, respectively, the y-axis. Consider using -a to de-linearise the y-axis. Dives on the x-axis are ordered by date; or if a -s split is specified, ordered between groups by relative offset from respective group's first dive time.
 
 
vector
With dive time on the x-axis and depth on the y-axis, draw each dive as a connected sequence (ordered by time) of dots. The connection is an line with an arrow. Needs at least two dives.
 
 
-s splitmode
Split up (“group”) dives according to a mode, which may be any one of the following.
 
 
diver
Group dives by diver This means having run dcmd(1) with -i.
 
 
none
The default of no splitting (all in one group).
 
 
date
Groups dives by date. The dive computer must support timestamped dives.
Dive groups are each shown in an individual colour. All graphing modes respond intelligently to group splits.
 
 
-v
Parse files in verbose mode.
 
 
files...
XML input files with one or more dives.
dcmd2grap exports to the data format accepted by grap(1). A simple grap(1) documented is also emitted with width 5 inches, height 3 inches. Use dcmd2pdf(1) or dcmd2ps(1) to avoid needing to prepare a groff(1) pipe.

Canonical free diving mode

Dive computers record free diving (“apnoea” mode, etc.) in two different ways: some split each dive into its own dive profile and ignore the surface interval; others simply record everything without stopping. The Suunto D6i is an example of the first, while the HW OSTC 2C is an example of the second.
The “canonical mode” for free diving is when dives are split at surface intervals. In dcmd2grap, output modes handy to free diving (e.g., rest) assume canonical free diving mode. The dcmdfind(1) utility is capable of “splitting” non-canonical free dive mode into canonical.

EXIT STATUS

The dcmd2grap utility exits 0 on success, and >0 if an error occurs.

EXAMPLES

This uses groff(1) and sets the paper size to A5. Note: the grap(1), pic(1), and groff(1) tools don't play nicely with landscape display.
dcmd2grap -msummary dives.xml | \ 
  groff -Gp -Tpdf -P-p5.8i,8.3i > foo.pdf
To compare free dive resting times across days:
dcmd2grap -sdate -mrestscatter day1.xml day2 | \ 
  groff -Gp -Tpdf -P-p5.8i,8.3i > foo.pdf
You can always use dcmd2pdf(1) or dcmd2ps(1) to make this call easier:
dcmd2pdf -sdate -mrestscatter day1.xml day2 > foo.pdf

SEE ALSO

dcmd(1), dcmd2pdf(1), dcmd2ps(1), dcmdfind(1), grap(1), groff(1)

AUTHORS

The dcmd2grap utility was written by Kristaps Dzonsons, kristaps@bsd.lv.

CAVEATS

Initial tests show that dcmd2grap doesn't play nicely with non-GNU troff.
August 13, 2018 OpenBSD 6.3