-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathdcmd2grap.1
245 lines (245 loc) · 6.44 KB
/
dcmd2grap.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
.\" $Id$
.\"
.\" Copyright (c) 2017 Kristaps Dzonsons <[email protected]>
.\"
.\" This library is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU Lesser General Public
.\" License as published by the Free Software Foundation; either
.\" version 2.1 of the License, or (at your option) any later version.
.\"
.\" This library is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
.\" Lesser General Public License for more details.
.\"
.\" You should have received a copy of the GNU Lesser General Public
.\" License along with this library; if not, write to the Free Software
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
.\" MA 02110-1301 USA
.\"
.Dd $Mdocdate$
.Dt DCMD2GRAP 1
.Os
.Sh NAME
.Nm dcmd2grap
.Nd graph dives with grap
.Sh SYNOPSIS
.Nm dcmd2grap
.Op Fl adv
.Op Fl m Ar mode
.Op Fl s Ar splitmode
.Op Ar files...
.Sh DESCRIPTION
The
.Nm
utility accepts XML files generated by
.Xr dcmd 1
and graphs each dive's depths in the
.Xr grap 1
data format.
By default, dives start at time zero through their maximum time.
Multiple dives are superimposed
.Pq Dq stacked .
For analysing free dives, it's important that the exported dive profile
be in
.Sx Canonical free diving mode
to make analysis useful (i.e., of each separate free dive within a
sequence).
The arguments of
.Nm
are as follows:
.Bl -tag -width Ds
.It Fl a
.Dq 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
.Fl m Ar temp .
.It Fl d
Derivatives.
Show change in velocity instead of depth.
This only applies to
.Ar aggr
and
.Ar stack
modes.
.It Fl m Ar mode
Graphing mode.
May be one of the following:
.Bl -tag -width Ds
.It Ar 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.
.It Ar aggr
Line graph connecting
.Pq Dq aggregating
subsequent dives with real time (relative to the beginning of the first
dive) on the x-axis and depth on the y-xais.
.It Ar aggrtemp
The same as
.Ar aggr ,
but with the temperature on the y-axis.
Your dive computer(s) must support temperature readings.
.It Ar 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.
.It Ar 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.
.It Ar rsummary
Like
.Ar summary ,
except dives are shown on an x-axis of their start time relative to the
first dive in a grouped sequence.
.It Ar scatter
Scatter graph with points at the intersection of dives' maximum depth
and time.
.It Ar stack
Default line graph with dives layered over one other, dive time on the
x-axis, depth on the y-axis.
.It Ar stacktemp
The same as
.Ar stack ,
except with temperatures on the y-axis.
Your dive computer(s) must support temperature readings.
.It Ar 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
.Fl s
split is specified, ordered between groups by relative offset from
respective group's first dive time.
.It Ar 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
.Fl a
to de-linearise the y-axis.
Dives on the x-axis are ordered by date; or if a
.Fl s
split is specified, ordered between groups by relative offset from
respective group's first dive time.
.It Ar 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.
.El
.It Fl s Ar splitmode
Split up
.Pq Dq group
dives according to a mode, which may be any one of the following.
.Bl -tag -width Ds
.It Ar diver
Group dives by diver
This means having run
.Xr dcmd 1
with
.Fl i .
.It Ar none
The default of no splitting (all in one group).
.It Ar date
Groups dives by date.
The dive computer must support timestamped dives.
.El
.Pp
Dive groups are each shown in an individual colour.
All graphing modes respond intelligently to group splits.
.It Fl v
Parse files in verbose mode.
.It Ar files...
XML input files with one or more dives.
.El
.Pp
.Nm
exports to the data format accepted by
.Xr grap 1 .
A simple
.Xr grap 1
documented is also emitted with width 5 inches, height 3 inches.
Use
.Xr dcmd2pdf 1
or
.Xr dcmd2ps 1
to avoid needing to prepare a
.Xr groff 1
pipe.
.Ss Canonical free diving mode
Dive computers record free diving
.Pq Do apnoea Dc 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.
.Pp
The
.Dq canonical mode
for free diving is when dives are split at surface intervals.
In
.Nm ,
output modes handy to free diving (e.g.,
.Ar rest )
assume canonical free diving mode.
The
.Xr dcmdfind 1
utility is capable of
.Dq splitting
non-canonical free dive mode into canonical.
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
This uses
.Xr groff 1
and sets the paper size to A5.
.Em Note :
the
.Xr grap 1 ,
.Xr pic 1 ,
and
.Xr groff 1
tools don't play nicely with landscape display.
.Bd -literal -offset indent
dcmd2grap -msummary dives.xml | \e
groff -Gp -Tpdf -P-p5.8i,8.3i > foo.pdf
.Ed
.Pp
To compare free dive resting times across days:
.Bd -literal -offset indent
dcmd2grap -sdate -mrestscatter day1.xml day2 | \e
groff -Gp -Tpdf -P-p5.8i,8.3i > foo.pdf
.Ed
.Pp
You can always use
.Xr dcmd2pdf 1
or
.Xr dcmd2ps 1
to make this call easier:
.Bd -literal -offset indent
dcmd2pdf -sdate -mrestscatter day1.xml day2 > foo.pdf
.Ed
.Sh SEE ALSO
.Xr dcmd 1 ,
.Xr dcmd2pdf 1 ,
.Xr dcmd2ps 1 ,
.Xr dcmdfind 1 ,
.Xr grap 1 ,
.Xr groff 1
.Sh AUTHORS
The
.Nm
utility was written by
.An Kristaps Dzonsons ,
.Mt [email protected] .
.Sh CAVEATS
Initial tests show that
.Nm
doesn't play nicely with non-GNU troff.