1GMT2KML(1) GMT GMT2KML(1)
2
6 gmt2kml - Convert GMT data tables to KML files for Google Earth
7
9 gmt2kml [ table ] [ -Aa|g|s[alt|xscale] ] [ -Ccpt ] [ -Ddescriptfile
10 ] [ -E[altitude] ] [ -Fe|s|t|l|p|w ] [ -Gf|n-|fill ] [ -Iicon ] [
11 -K] [ -Lcol1:name1,col2:name2,... ] [ -N[+|name_template|name] ] [
12 -O] [ -Qa|iaz ] [ -Qsscale[unit] ] [ -Ra|w/e/s/n ] [ -Sc|nscale] ]
13 [ -Ttitle[/foldername] ] [ -V[level] ] [ -W[pen][attr] ] [ -Zargs ]
14 [ -bibinary ] [ -dinodata ] [ -eregexp ] [ -fflags ] [ -hheaders ] [
15 -iflags ] [ -:[i|o] ] [ > output.kml ]
16 Note: No space is allowed between the option flag and the associated
18 arguments.
19
21 gmt2kml reads one or more GMT table file and converts them to a single
22 output file using Google Earth's KML format. Data may represent points,
23 lines, polygons, or wiggles, and you may specify additional attributes
24 such as title, altitude mode, colors, pen widths, transparency,
25 regions, and data descriptions. You may also extend the feature down to
26 ground level (assuming it is above it) and use custom icons for point
27 symbols. Finally, there are controls on visibility depending on level
28 of detail settings, altitude, regions, including the status upon load‐
29 ing into Google Earth as well as fading depending on zoom.
30 The input files should contain the following columns:
32 lon lat [ alt ] [ timestart [ timestop ] ]
34 where lon and lat are required for all features, alt is optional for
36 all features (see also -A and -C), and timestart and timestop apply to
37 events and timespan features. For wiggles, the alt column is required
38 but is expected to represent an along-track data anomaly such as grav‐
39 ity, magnetics, etc. These values will be scaled to yield distances
40 from the line in degrees.
41
43 None.
44
46 table One or more ASCII (or binary, see -bi[ncols][type]) data table
47 file(s) holding a number of data columns. If no tables are given
48 then we read from standard input.
49 -Aa|g|s[alt|xscale]
51 Select one of three altitude modes recognized by Google Earth
52 that determines the altitude (in m) of the feature: a absolute
53 altitude, g altitude relative to sea surface or ground, s alti‐
54 tude relative to seafloor or ground. To plot the features at a
55 fixed altitude, append an altitude alt (in m). Use 0 to clamp
56 the features to the chosen reference surface. Append xscale to
57 scale the altitude from the input file by that factor. If no
58 value is appended, the altitude (in m) is read from the 3rd col‐
59 umn of the input file. [By default the features are clamped to
60 the sea surface or ground].
61 -Ccpt Use the CPT for assigning colors to the symbol, event, or times‐
63 pan icons, based on the value in the 3rd column of the input
64 file. For lines or polygons we examine the segment header for
65 -Z<value> statements and obtain the color via the cpt lookup.
66 Note only discrete colors are possible.
67 -Ddescriptfile
69 File with HTML snippets that will be included as part of the
70 main description content for the KML file [no description]. See
71 SEGMENT INFORMATION below for feature-specific descriptions.
72 -E[altitude]
74 Extrude feature down to ground level [no extrusion].
75 -Fe|s|t|l|p|w
77 Sets the feature type. Choose from points (event, symbol, or
78 timespan), line, polygon, or wiggle [symbol]. The first two col‐
79 umns of the input file should contain (lon, lat). When altitude
80 or value is required (i.e., no altitude value was given with -A,
81 or -C is set), the third column needs to contain the altitude
82 (in m) or value. The event (-Fe) is a symbol that should only be
83 active at a particular time, given in the next column. Timespan
84 (-Ft) is a symbol that should only be active during a particular
85 time period indicated by the next two columns (timestart,
86 timestop). Use NaN to indicate unbounded time limits. If used,
87 times should be in ISO format yyyy-mm-ddThh:mm:ss[.xxx] or in
88 GMT relative time format (see -f). For wiggles, the data anom‐
89 aly is required to be in the 3rd input column. If you also need
90 to plot the track itself then do that separately with -Fl.
91 -Gf|nfill
93 Sets color fill (-Gf) or label font color (-Gn). Fill: Set fill
94 color for symbols, extrusions, polygons and positive anomaly
95 wiggles [Default is light orange at 75% transparency]. Option‐
96 ally, use -Gf- to turn off polygon fill. Text labels: Specify
97 color for font [Default is white]. Optionally use -Gn- to dis‐
98 able labels.
99 -Iicon Specify the URL to an alternative icon that should be used for
101 the symbol [Default is a Google Earth circle]. If the URL starts
102 with + then we will prepend http://maps.google.com/mapfiles/kml/
103 to the name. To turn off icons entirely (e.g., when just wanting
104 a text label), use -I-. [Default is a local icon with no direc‐
105 tory path].
106 -K Allow more KML code to be appended to the output later [finalize
108 the KML file].
109 -Lname1,name2,...
111 Extended data given. Append one or more column names separated
112 by commas. We will expect the listed data columns to exist in
113 the input immediately following the data coordinates and they
114 will be encoded in the KML file as Extended Data sets, whose
115 attributes will be available in a Google Earth balloon when the
116 item is selected. This option is not available unless input is
117 an ASCII file.
118 -N[-|+|name_template|name]
120 By default, if segment headers contain a -L"label string" then
121 we use that for the name of the KML feature (polygon, line seg‐
122 ment or set of symbols). Default names for these segments are
123 "Line %d" and "Point Set %d", depending on the feature, where %d
124 is a sequence number of line segments within a file. Each point
125 within a line segment will be named after the line segment plus
126 a sequence number. Default is simply "Point %d". Alterna‐
127 tively, select one of these options: (1) append - to supply
128 individual symbol labels (single word) via the field immediately
129 following the data coordinates, (2) append + to supply individ‐
130 ual symbol labels as everything to the end of the data record
131 following the data coordinates, (3) append a string that may
132 include %d or a similar integer format to assign unique name IDs
133 for each feature, with the segment number (for lines and poly‐
134 gons) or point number (symbols) appearing where %d is placed,
135 (4) give no arguments to turn symbol labeling off; line segments
136 will still be named. Note: if -N- is used with -L then the label
137 must appear before the extended data columns. Also note that
138 options (1) and (2) are not available unless input is an ASCII
139 file.
140 -O Append KML code to an existing KML file [initialize a new KML
142 file].
143 -Qa|iazimuth
145 Option in support of wiggle plots (requires -Fw). You may con‐
146 trol which directions the positive wiggles will tend to point to
147 with -Qa. The provided azimuth defines a half-circle centered
148 on the selected azimuth [0] where positive anomalies will plot.
149 If outside then switch by 180 degrees. Alternatively, use -Qi
150 to set a fixed direction with no further variation.
151 -Qsscale[unit]
153 Required setting for wiggle plots (i.e., it requires -Fw). Sets
154 a wiggle scale in z-data units per the user's units (given via
155 the trailing unit taken from d|m|s|e|f|k|M|n|u [e]). This scale
156 is then inverted to yield degrees per user z-unit and used to
157 convert wiggle anomalies to map distances and positions.
158 -Ra|w/e/s/n
160 Issue a single Region tag. Append w/e/s/n to set a particular
161 region (will ignore points outside the region), or append a to
162 determine and use the actual domain of the data (single file
163 only) [no region tags issued].
164 -Sc|nscale]
166 Scale icons or labels. Here, -Sc sets a scale for the symbol
167 icon, whereas -Sn sets a scale for the name labels [1 for both].
168 -Ttitle[/foldername]
170 Sets the document title [default is unset]. Optionally, append
171 /FolderName; this allows you, with -O, -K, to group features
172 into folders within the KML document. [The default folder name
173 is "Name Features", where Name is Point, Event, Timespan, Line,
174 Polygon or Wiggle].
175 -V[level] (more ...)
177 Select verbosity level [c].
178 -W[pen][attr] (more ...)
180 Set pen attributes for lines, wiggles or polygon outlines.
181 Append pen attributes to use [Defaults: width = default, color =
182 black, style = solid]. If the modifier +cl is appended then the
183 color of the line are taken from the CPT (see -C). If instead
184 modifier +cf is appended then the color from the cpt file is
185 applied to symbol fill. Use just +c for both effects. Note
186 that for KML the pen width is given in (fractional) pixels and
187 not in points (1/72 inch).
188 -Zargs Set one or more attributes of the Document and Region tags.
190 Append +aalt_min/alt_max to specify limits on visibility based
191 on altitude. Append +llod_min/lod_max to specify limits on visi‐
192 bility based on Level Of Detail, where lod_max == -1 means it is
193 visible to infinite size. Append +ffade_min/fade_max to fade in
194 and out over a ramp [abrupt]. Append +v to make a feature not
195 visible when loaded [visible]. Append +o to open a folder or
196 document in the sidebar when loaded [closed].
197 -bi[ncols][t] (more ...)
199 Select native binary input. [Default is 2 or more input columns,
200 depending on settings].
201 -dinodata (more ...)
203 Replace input columns that equal nodata with NaN.
204 -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
206 Only accept data records that match the given pattern.
207 -f[i|o]colinfo (more ...)
209 Specify data types of input and/or output columns.
210 -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more ...)
212 Determine data gaps and line breaks.
213 -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
215 Skip or produce header record(s).
216 -icols[+l][+sscale][+ooffset][,...] (more ...)
218 Select input columns and transformations (0 is first column).
219 -:[i|o] (more ...)
221 Swap 1st and 2nd column on input and/or output.
222 -^ or just -
224 Print a short message about the syntax of the command, then
225 exits (NOTE: on Windows just use -).
226 -+ or just +
228 Print an extensive usage (help) message, including the explana‐
229 tion of any module-specific option (but not the GMT common
230 options), then exits.
231 -? or no arguments
233 Print a complete usage (help) message, including the explanation
234 of all options, then exits.
235
237 To convert a file with point locations (lon, lat) into a KML file with
238 red circle symbols, try
239 gmt2kml mypoints.txt -Gfred -Fs > mypoints.kml
241 To convert a multisegment file with lines (lon, lat) separated by seg‐
243 ment headers that contain a -Llabelstring with the feature name,
244 selecting a thick white pen, and title the document, try
245 gmt2kml mylines.txt -Wthick,white -Fl -T"Lines from here to there" > mylines.kml
247 To convert a multisegment file with polygons (lon, lat) separated by
249 segment headers that contain a -Llabelstring with the feature name,
250 selecting a thick black pen and semi-transparent yellow fill, giving a
251 title to the document, and prescribing a particular region limit, try
252 gmt gmt2kml mypolygons.txt -Gfyellow@50 -Fp -T"My polygons" -R30/90/-20/40 > mypolygons.kml
254 To convert a file with point locations (lon, lat, time) into a KML file
256 with green circle symbols that will go active at the specified time and
257 stay active going forward, try
258 awk '{print $1, $2, $3, "NaN"}' mypoints.txt | gmt gmt2kml -Gfgreen -Ft > mytimepoints.kml
260 To extract contours and labels every 10 units from the grid temp.nc and
262 plot them in KML, using red lines at 75% transparency and red labels
263 (no transparency), try
264 gmt grdcontour temp.nc -Jx1id -A10+tlabel.txt -C10 -Dcontours.txt
266 gmt gmt2kml contours.txt -Fl -W1p,red@75 -K > contours.kml
267 gmt gmt2kml -O -N+ -Fs -Sn2 -Gnred@0 label.txt -I- >> contours.kml
268 To instead plot the contours as lines with colors taken from the cpt
270 file contours.cpt, try
271 gmt gmt2kml contours.txt -Fl -Ccontours.cpt > contours.kml
273 To plot magnetic anomalies as wiggles along track, with positive wig‐
275 gles painted orange and the wiggle line drawn with a black pen of width
276 2p, scaling the magnetic anomalies (in nTesla) so that 50 nT equals 1
277 nm on the map, and place the wiggles 50m above the sea surface, use
278 gmt gmt2kml magnetics_lon_lat_mag.txt -Fw -Gforange -W2p -Ag50 -Qs50n > wiggles.kml
280
282 Google Earth has trouble displaying filled polygons across the Date‐
283 line. For now you must manually break any polygon crossing the date‐
284 line into a west and east polygon and plot them separately. Google
285 Earth also has other less obvious limitations on file size or line
286 length. These do not seem to be documented. If features do not show
287 and you are not getting an error, try to reduce the size of the file by
288 splitting things up.
289
291 Using the KMZ format is preferred as it takes less space. KMZ is simply
292 a KML file and any data files, icons, or images referenced by the KML,
293 contained in a zip archive. One way to organize large data sets is to
294 split them into groups called Folders. A Document can contain any num‐
295 ber of folders. Using scripts you can create a composite KML file using
296 the -K, -O options just like you do with GMT plots. See -T for switch‐
297 ing between folders and documents. The gmt_shell_scripts.sh contains
298 function gmt_build_kmz that can assist in building a KMZ file from any
299 number of KML files (and optionally images they may refer to).
300
302 GMT stores the different features in hierarchical folders by feature
303 type (when using -O, -K or -T/foldername), by input file (if not stan‐
304 dard input), and by line segment (using the name from the segment
305 header, or -N). This makes it more easy in Google Earth to switch on or
306 off parts of the contents of the Document. The following is a crude
307 example:
308 [ KML header information; not present if -O was used ]
310 <Document><name>GMT Data Document</name>
312 <Folder><name>Point Features</name>
314 <!--This level of folder is inserted only when using -O, -K>
316 <Folder><name>file1.dat</name>
318 <!--One folder for each input file (not when standard input)>
320 <Folder><name>Point Set 0</name>
322 <!--One folder per line segment>
324 <!--Points from the first line segment in file file1.dat go here>
326 <Folder><name>Point Set 1</name>
328 <!--Points from the second line segment in file file1.dat go here>
330 </Folder>
332 </Folder>
334 <Folder><name>Line Features</name>
336 <Folder><name>file1.dat</name>
338 <!--One folder for each input file (not when standard input)>
340 <Placemark><name>Line 0</name>
342 <!--Here goes the first line segment>
344 </Placemark>
346 <Placemark><name>Line 1</name>
348 <!--Here goes the second line segment>
350 </Placemark>
352 </Folder>
354 <Folder>
356 </Document>
358 [ KML trailer information; not present if -K was used ]
360
362 gmt2kml will scan the segment headers for substrings of the form
363 -L"some label" [also see -N discussion] and -T"some text description".
364 If present, these are parsed to supply name and description tags,
365 respectively, for the current feature.
366
368 If you have made a series of KML files (which may depend on other items
369 like local PNG images), you can consolidate these into a single KMZ
370 file for saving space and for grouping related files together. The
371 bash function gmt_build_kmz in the gmt_shell_functions.sh can be used
372 to do this. You need to source gmt_shell_functions.sh first before you
373 can use it.
374
376 gmt , gmt.conf, gmt_shell_functions.sh, img2google, kml2gmt , psconvert
377
379 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
3805.4.5 Feb 24, 2019 GMT2KML(1)