DCMD2GRAP(1)

NAME
dcmd2grap - graph 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

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.