1GMTCONVERT(1) GMT GMTCONVERT(1)
2
6 gmtconvert - Convert, Paste, and/or Extract columns from data tables
7
9 gmtconvert [ table ] [ -A ] [ -C[+lmin][+umax][+i]] [ -D[tem‐
10 plate[+oorig]] ] [ -E[f|l|mstride] ] [ -L ] [ -F[c|n|r|v][refpoint]
11 ] [ -I[tsr] ] [ -Q[~]selection] [ -S[~]"search string" | -S[~]/reg‐
12 exp/[i] ] [ -T ] [ -V[level] ] [ -aflags ] [ -bbinary ] [ -dnodata ]
13 [ -eregexp ] [ -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -oflags
14 ] [ -sflags ] [ -:[i|o] ]
15 Note: No space is allowed between the option flag and the associated
17 arguments.
18
20 gmtconvert reads its standard input [or input files] and writes out the
21 desired information to standard output. It can do a combination of nine
22 tasks: (1) convert between binary and ASCII data tables, (2) paste cor‐
23 responding records from multiple files horizontally into a single file,
24 (3) extract a subset of the available columns, (4) only extract seg‐
25 ments whose header record matches a text pattern search, (5) only list
26 segment headers and no data records, (6) extract first and/or last data
27 record for each segment, (7) reverse the order of items on output, (8)
28 output only ranges of segment numbers, and (9) output only segments
29 whose record count matches criteria. Input (and hence output) may have
30 multiple sub-headers, and ASCII tables may have regular headers as
31 well.
32
34 None
35
37 table One or more ASCII (or binary, see -bi[ncols][type]) data table
38 file(s) holding a number of data columns. If no tables are given
39 then we read from standard input.
40 -A The records from the input files should be pasted horizontally,
42 not appended vertically [Default]. All files must have the same
43 number of segments and number of rows per segment. Note for
44 binary input, all the files you want to paste must have the same
45 number of columns (as set with -bi); ASCII tables can have dif‐
46 ferent number of columns.
47 -C[+lmin][+umax][+i]
49 Only output segments whose number of records matches your given
50 criteria: Append +lmin to ensure all segment must have at least
51 min records to be written to output [0], and append +umax to
52 ensure all segments must have at most max records to be written
53 [inf]. You may append +i to invert the selection, i.e., only
54 segments with record counts outside the given range will be out‐
55 put.
56 -D[template[+oorig]]
58 For multiple segment data, dump each segment to a separate out‐
59 put file [Default writes a multiple segment file to stdout].
60 Append a format template for the individual file names; this
61 template must contain a C format specifier that can format an
62 integer argument (the running segment number across all tables);
63 this is usually %d but could be %08d which gives leading zeros,
64 etc. [Default is gmtconvert_segment_%d.{txt|bin}, depending on
65 -bo]. Append +oorig to start the numbering from orig instead of
66 zero. Alternatively, give a template with two C format speci‐
67 fiers and we will supply the table number and the segment number
68 within the table to build the file name. Append +otorig/sorig
69 to start the numbering of tables from torig and numbering of
70 segments within a table from sorig instead of zero. The +o mod‐
71 ifier will be stripped off before the template is used.
72 -E[f|l|mstride]
74 Only extract the first and last record for each segment of
75 interest [Default extracts all records]. Optionally, append f or
76 l to only extract the first or last record of each segment,
77 respectively. Alternatively, append mstride to extract only one
78 out of stride records.
79 -F[c|n|r|v][refpoint]
81 Alter the way points are connected (by specifying a scheme) and
82 data are grouped (by specifying a method). Append one of four
83 line connection schemes: c: Form continuous line segments for
84 each group [Default]. r: Form line segments from a reference
85 point reset for each group. n: Form networks of line segments
86 between all points in each group. v: Form vector line segments
87 suitable for psxy -Sv+s. Optionally, append the one of four
88 segmentation methods to define the group: a: Ignore all segment
89 headers, i.e., let all points belong to a single group, and set
90 group reference point to the very first point of the first file.
91 f: Consider all data in each file to be a single separate group
92 and reset the group reference point to the first point of each
93 group. s: Segment headers are honored so each segment is a
94 group; the group reference point is reset to the first point of
95 each incoming segment [Default]. r: Same as s, but the group
96 reference point is reset after each record to the previous point
97 (this method is only available with the -Fr scheme). Instead of
98 the codes a|f|s|r you may append the coordinates of a refpoint
99 which will serve as a fixed external reference point for all
100 groups.
101 -I[tsr]
103 Invert the order of items, i.e., output the items in reverse
104 order, starting with the last and ending up with the first item
105 [Default keeps original order]. Append up to three items that
106 should be reversed: t will reverse the order of tables, s will
107 reverse the order of segments within each table, and r will
108 reverse the order of records within each segment [Default].
109 -L Only output a listing of all segment header records and no data
111 records (requires ASCII data).
112 -Q[~]selection
114 Only write segments whose number is included in selection and
115 skip all others. Cannot be used with -S. The selection syntax is
116 range[,range,...] where each range of items is either a single
117 segment number or a range with stepped increments given via
118 start[:step:]:stop (step is optional and defaults to 1). A lead‐
119 ing ~ will invert the selection and write all segments but the
120 ones listed. Instead of a list of ranges, use +ffile to supply
121 a file list with one range per line.
122 -S[~]"search string" or -S[~]/regexp/[i]
124 Only output those segments whose header record contains the
125 specified text string. To reverse the search, i.e., to output
126 segments whose headers do not contain the specified pattern, use
127 -S~. Should your pattern happen to start with ~ you need to
128 escape this character with a backslash [Default output all seg‐
129 ments]. Cannot be used with -Q. For matching segments based on
130 aspatial values (via OGR/GMT format), give the search string as
131 varname=value and we will compare value against the value of
132 varname for each segment. Note: If the features are polygons
133 then a match of a particular polygon perimeter also means that
134 any associated polygon holes will also be matched. For matching
135 segment headers against extended regular expressions enclose the
136 expression in slashes. Append i for case-insensitive matching.
137 For a list of such patterns, give +ffile with one pattern per
138 line. To give a single pattern starting with +f, escape it with
139 a backslash.
140 -T Suppress the writing of segment headers on output.
142 -V[level] (more ...)
144 Select verbosity level [c].
145 -acol=name[...] (more ...)
147 Set aspatial column associations col=name.
148 -bi[ncols][t] (more ...)
150 Select native binary input.
151 -bo[ncols][type] (more ...)
153 Select native binary output. [Default is same as input].
154 -d[i|o]nodata (more ...)
156 Replace input columns that equal nodata with NaN and do the
157 reverse on output.
158 -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
160 Only accept data records that match the given pattern.
161 -f[i|o]colinfo (more ...)
163 Specify data types of input and/or output columns.
164 -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more ...)
166 Determine data gaps and line breaks.
167 -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
169 Skip or produce header record(s).
170 -icols[+l][+sscale][+ooffset][,...] (more ...)
172 Select input columns and transformations (0 is first column).
173 -ocols[,...] (more ...)
175 Select output columns (0 is first column).
176 -s[cols][a|r] (more ...)
178 Set handling of NaN records.
179 -:[i|o] (more ...)
181 Swap 1st and 2nd column on input and/or output.
182 -^ or just -
184 Print a short message about the syntax of the command, then
185 exits (NOTE: on Windows just use -).
186 -+ or just +
188 Print an extensive usage (help) message, including the explana‐
189 tion of any module-specific option (but not the GMT common
190 options), then exits.
191 -? or no arguments
193 Print a complete usage (help) message, including the explanation
194 of all options, then exits.
195
197 The ASCII output formats of numerical data are controlled by parameters
198 in your gmt.conf file. Longitude and latitude are formatted according
199 to FORMAT_GEO_OUT, absolute time is under the control of FOR‐
200 MAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point val‐
201 ues are formatted according to FORMAT_FLOAT_OUT. Be aware that the for‐
202 mat in effect can lead to loss of precision in ASCII output, which can
203 lead to various problems downstream. If you find the output is not
204 written with enough precision, consider switching to binary output (-bo
205 if available) or specify more decimals using the FORMAT_FLOAT_OUT set‐
206 ting.
207
209 To convert the binary file test.b (single precision) with 4 columns to
210 ASCII:
211 gmt convert test.b -bi4f > test.dat
213 To convert the multiple segment ASCII table test.d to a double preci‐
215 sion binary file:
216 gmt convert test.d -bo > test.b
218 You have an ASCII table with 6 columns and you want to plot column 5
220 versus column 0. Try
221 gmt convert table.d -o5,0 | psxy ...
223 If the file instead is the binary file results.b which has 9 sin‐
225 gle-precision values per record, we extract the last column and columns
226 4-6 and write ASCII with the command
227 gmt convert results.b -o8,4-6 -bi9s | psxy ...
229 You want to plot the 2nd column of a 2-column file left.d versus the
231 first column of a file right.d:
232 gmt convert left.d right.d -A -o1,2 | psxy ...
234 To extract all segments in the file big_file.d whose headers contain
236 the string "RIDGE AXIS", try
237 gmt convert big_file.d -S"RIDGE AXIS" > subset.d
239 To invert the selection of segments whose headers begin with "profile "
241 followed by an integer number and any letter between "g" and "l", try
242 gmt convert -S~"/^profile [0-9]+[g-l]$/"
244 To reverse the order of segments in a file without reversing the order
246 of records within each segment, try
247 gmt convert lots_of_segments.txt -Is > last_segment_first.txt
249 To extract segments 20 to 40 in steps of 2, plus segment 0 in a file,
251 try
252 gmt convert lots_of_segments.txt -Q0,20:2:40 > my_segments.txt
254 To extract the attribute ELEVATION from an ogr gmt file like this
256 # @VGMT1.0 @GPOINT
258 ...
259 # @NELEVATION|DISPX|DISPY
260 # @Tdouble|double|double
261 # FEATURE_DATA
262 # @D4.945000|-106500.00000000|-32700.00000000
263 -9.36890245902635 39.367156766570389
264 do
266 gmt convert file.gmt -a2=ELEVATION > xyz.dat
268 or just
270 gmt convert file.gmt -aELEVATION > xyz.dat
272 To connect all points in the file sensors.txt with the specified origin
274 at 23.5/19, try
275 gmt convert sensors.txt -F23.5/19 > lines.txt
277 To write all segments in the two files A.txt and B.txt to individual
279 files named profile_005000.txt, profile_005001.txt, etc., where we
280 reset the origin of the sequential numbering from 0 to 5000, try
281 gmt convert A.txt B.txt -Dprofile_%6.6d.txt+o5000
283
285 gmt, gmtinfo, gmtselect
286
288 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
2895.4.5 Feb 24, 2019 GMTCONVERT(1)