1GMT2KML(1) Generic Mapping Tools GMT2KML(1)
2
6 gmt2kml - Convert GMT data tables to KML files for Google Earth
7
9 gmt2kml [ infile(s) ] [ -Aa|g|s[alt|xscale] ] [ -Ccpt ] [ -Ddescript‐
10 file ] [ -E[altitude] ] [ -Fe|s[cpt]|t|l|p ] [ -Gf|nfill ] [
11 -H[i][nrec] ] [ -Iicon ] [ -K] [ -Lcol1:name1,col2:name2,... ] [
12 -N[+|name_template|name] ] [ -O] [ -Q[s|l|p]transparency ] [
13 -Ra|w/e/s/n ] [ -Sc|nscale] ] [ -Ttitle[/foldername] ] [ -V ] [ -W-|pen
14 ] [ -Zargs ] [ -:[i|o] ] [ -bi[s|S|d|D[ncol]|c[var1/...]] ] [
15 -f[i|o]colinfo ] [ -m[i|o][flag] ] [ > output.kml ]
16
18 gmt2kml reads one or more GMT table file and converts them to a single
19 output file using Google Earth's KML format. Data may represent
20 points, lines, or polygons, and you may specify additional attributes
21 such as title, altitude mode, colors, pen widths, transparency,
22 regions, and data descriptions. You may also extend the feature down
23 to ground level (assuming it is above it) and use custom icons for
24 point symbols.
25 The input file should contain the following columns:
26 lon lat [ alt ] [ timestart [ timestop ] ]
27 where lon and lat are required for all features, alt is optional for
28 all features (see also -A and -C), and timestart and timestop apply to
29 events and timespan features.
30 infile(s)
32 ASCII (or binary, see -bi) data file(s) to be operated on. If
33 not given, standard input will be read.
34
36 No space between the option flag and the associated arguments.
37 -A Select one of three altitude modes recognized by Google Earth
39 that determines the altitude (in m) of the feature: a absolute
40 altitude, g altitude relative to sea surface or ground, s alti‐
41 tude relative to seafloor. To plot the features at a fixed
42 altitude, append an altitude alt (in m). Use 0 to clamp the fea‐
43 tures to the chosen reference surface. Append xscale to scale
44 the altitude from the input file by that factor. If no value is
45 appended, the altitude (in m) is read from the 3rd column of the
46 input file. [By default the features are clamped to the sea
47 surface or ground].
48 -C Use color palette for assigning colors to the symbol, event, or
50 timespan icons, based on the value in the 3rd column of the
51 input file. Ignored when plotting lines or polygons.
52 -D File with HTML snippets that will be included as part of the
54 main description content for the KML file [no description]. See
55 SEGMENT INFORMATION below for feature-specific descriptions.
56 -E Extrude feature down to ground level [no extrusion].
58 -F Sets the feature type. Choose from points (event, symbol, or
60 timespan), line, or polygon [symbol]. The first two columns of
61 the input file should contain (lon, lat). When altitude or
62 value is required (i.e., no altitude value was given with -A, or
63 -C is set), the third column needs to contain the altitude (in
64 m). The event (-Fe) is a symbol that should only be active at a
65 particular time, given in the next column. Timespan (-Ft) is a
66 symbol that should only be active during a particular time
67 period indicated by the next two columns (timestart, timestop).
68 Use NaN to indicate unbounded time limits. If used, times
69 should be in ISO format yyyy-mm-ddThh:mm:ss[.xxx] or in GMT rel‐
70 ative time format (see -f).
71 -G Set fill color for symbols, extrusions and polygons (-Gf)
73 [Default is lightorange] or text labels (-Gn) [Default is
74 white]. Optionally, use -Gf- to turn off polygon fill, and -Gn-
75 to disable labels. (See SPECIFYING FILL below).
76 -H Input file(s) has header record(s). If used, the default number
78 of header records is N_HEADER_RECS. Use -Hi if only input data
79 should have header records [Default will write out header
80 records if the input data have them]. Blank lines and lines
81 starting with # are always skipped.
82 -I Specify the URL to an alternative icon that should be used for
84 the symbol [Default is a Google Earth circle]. If the URL
85 starts with + then we will prepend http://maps.google.com/map‐
86 files/kml/ to the name. [Default is a local icon with no direc‐
87 tory path].
88 -K Allow more KML code to be appended to the output later [finalize
90 the KML file].
91 -L Extended data given. Append one or more strings of the form
93 col:name separated by commas. We will expect the listed data
94 columns to exist in the input and they will be encoded in the
95 KML file as Extended Data sets, whose attributes will be avail‐
96 able in the Google Earth balloon when the item is selected.
97 -N By default, if multisegment headers contain a -L"label string"
99 then we use that for the name of the KML feature (polygon, line
100 segment or set of symbols). Default names for these segments are
101 "Line %d" and "Point Set %d", depending on the feature, where %d
102 is a sequence number of line segments within a file. Each point
103 within a line segment will be named after the line segment plus
104 a sequence number. Default is simply "Point %d".
105 Alternatively, select one of these options: (1) append + to sup‐
106 ply individual symbol labels directly at the end of the data
107 record, (2) append a string that may include %d or a similar
108 integer format to assign unique name IDs for each feature, with
109 the segment number (for lines and polygons) or point number
110 (symbols) appearing where %d is placed, (3) give no arguments to
111 turn symbol labeling off; line segments will still be named.
112 -O Appended KML code to an existing KML file [initialize a new KML
114 file].
115 -Q Set the transparency level for the selected feature (e, s, t, l,
117 or p, plus n for name labels). Transparency goes from 0 (fully
118 transparent) to 1 (opaque) [0.75 for polygons, 1 for symbols,
119 lines, and labels].
120 -R Issue a single Region tag. Append w/e/s/n to set a particular
122 region (will ignore points outside the region), or append a to
123 determine and use the actual domain of the data (single file
124 only) [no region tags issued].
125 -S Scale icons or labels. Here, -Sc sets a scale for the symbol
127 icon, whereas -Sn sets a scale for the name labels [1 for both].
128 -T Sets the document title [GMT Data Document]. Optionally, append
130 /FolderName; this allows you, with -O, -K, to group features
131 into folders within the KML document. [The default folder name
132 is "Name Features", where Name is Point, Event, Timespan, Line,
133 or Polygon].
134 -V Selects verbose mode, which will send progress reports to stderr
136 [Default runs "silently"].
137 -W Set pen attributes for lines or polygon outlines. Append pen
139 attributes to use [Defaults: width = 1, color = black, texture =
140 solid]. Optionally, use -W- to turn off polygon outline (See
141 SPECIFYING PENS below).
142 -Z Set one or more attributes of the Document and Region tags.
144 Append +aalt_min/alt_max to specify limits on visibility based
145 on altitude. Append +llod_min/lod_max to specify limits on vis‐
146 ibility based on Level Of Detail, where lod_max == -1 means it
147 is visible to infinite size. Append +ffade_min/fade_max to fade
148 in and out over a ramp [abrupt]. Append +v to make a feature
149 not visible when loaded [visible]. Append +o to open a folder
150 or document in the sidebar when loaded [closed].
151 -: Toggles between (longitude,latitude) and (latitude,longitude)
153 input and/or output. [Default is (longitude,latitude)]. Append
154 i to select input only or o to select output only. [Default
155 affects both].
156 -bi Selects binary input. Append s for single precision [Default is
158 d (double)]. Uppercase S or D will force byte-swapping.
159 Optionally, append ncol, the number of columns in your binary
160 input file if it exceeds the columns needed by the program. Or
161 append c if the input file is netCDF. Optionally, append
162 var1/var2/... to specify the variables to be read. [Default is
163 2 input columns].
164 -f Special formatting of input and/or output columns (time or geo‐
166 graphical data). Specify i or o to make this apply only to
167 input or output [Default applies to both]. Give one or more
168 columns (or column ranges) separated by commas. Append T (abso‐
169 lute calendar time), t (relative time in chosen TIME_UNIT since
170 TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
171 to each column or column range item. Shorthand -f[i|o]g means
172 -f[i|o]0x,1y (geographic coordinates).
173 -m Multiple segment file(s). Segments are separated by a special
175 record. For ASCII files the first character must be flag
176 [Default is '>']. For binary files all fields must be NaN and
177 -b must set the number of output columns explicitly. By default
178 the -m setting applies to both input and output. Use -mi and
179 -mo to give separate settings to input and output. The -m
180 option make sure that segment headers in the input files are
181 copied to output, but it has no effect on the data selection.
182 Selection is always done point by point, not by segment.
183 SPECIFYING PENS
185 pen The attributes of lines and symbol outlines as defined by pen is
186 a comma delimetered list of width, color and texture, each of
187 which is optional. width can be indicated as a measure (points,
188 centimeters, inches) or as faint, thin[ner|nest], thick[er|est],
189 fat[ter|test], or obese. color specifies a gray shade or color
190 (see SPECIFYING COLOR below). texture is a combination of
191 dashes `-' and dots `.'.
192 SPECIFYING COLOR
194 color The color of lines, areas and patterns can be specified by a
195 valid color name; by a gray shade (in the range 0-255); by a
196 decimal color code (r/g/b, each in range 0-255; h-s-v, ranges
197 0-360, 0-1, 0-1; or c/m/y/k, each in range 0-1); or by a hexa‐
198 decimal color code (#rrggbb, as used in HTML). See the gmtcol‐
199 ors manpage for more information and a full list of color names.
200
202 To convert a file with point locations (lon, lat) into a KML file with
203 red circle symbols, try
204 gmt2kml mypoints.txt -Gfred -Fs > mypoints.kml
206 To convert a multisegment file with lines (lon, lat) separated by mul‐
208 tisegment headers that contain a -Llabelstring with the feature name,
209 selecting a thick white pen, and title the document, try
210 gmt2kml mylines.txt -Wthick,white -Fl -T"Lines from here to there" >
212 mylines.kml
213 To convert a multisegment file with polygons (lon, lat) separated by
215 multisegment headers that contain a -Llabelstring with the feature
216 name, selecting a thick black pen and semi-transparent yellow fill,
217 giving a title to the document, and prescribing a particular region
218 limit, try
219 gmt2kml mypolygons.txt -Gfyellow -Qp0.5 -Fp -T"My polygons"
221 -R30/90/-20/40 > mypolygons.kml
222 To convert a file with point locations (lon, lat, time) into a KML file
224 with green circle symbols that will go active at the specified time and
225 stay active going forward, try
226 awk '{print $1, $2, $3, "NaN"}' mypoints.txt | gmt2kml -Gfgreen -Ft >
228 mytimepoints.kml
229
231 Google Earth has trouble displaying filled polygons across the Date‐
232 line. For now you must manually break any polygon crossing the date‐
233 line into a west and east polygon and plot them separately.
234
236 Using the KMZ format is preferred as it takes less space. KMZ is sim‐
237 ply a KML file and any data files, icons, or images referenced by the
238 KML, contained in a zip archive. One way to organize large data sets
239 is to split them into groups called Folders. A Document can contain
240 any number of folders. Using scripts you can create a composite KML
241 file using the -K, -O options just like you do with GMT plots. See -T
242 for switching between folders and documents.
243
245 GMT stores the different features in hierarchical folders, by feature
246 type (when using -O, -K or -T/foldername), by input file (if not stan‐
247 dard input), and by line segment (using the name from the segment
248 header, or -N). This makes it more easy in Google Earth to switch on
249 or off parts of the contents of the Document. The following is a crude
250 example:
251 [ KML header information - not present if -O was given ]
253 <Document><name>GMT Data Document</name>
254 <Folder><name>Point Features</name>
255 <!--This level of folder is inserted only when using -O, -K>
256 <Folder><name>file1.dat</name>
257 <!--One folder for each input file (not when standard
258 input)>
259 <Folder><name>Point Set 0</name>
260 <!--One folder per line segment>
261 <!--Points from the first line segment in file file1.dat go
262 here>
263 <Folder><name>Point Set 1</name>
264 <!--Points from the second line segment in file file1.dat
265 go here>
266 </Folder>
267 </Folder>
268 <Folder><name>Line Features</name>
269 <Folder><name>file1.dat</name>
270 <!--One folder for each input file (not when standard
271 input)>
272 <Placemark><name>Line 0</name>
273 <!--Here goes the first line segment>
274 </Placemark>
275 <Placemark><name>Line 1</name>
276 <!--Here goes the second line segment>
277 </Placemark>
278 </Folder>
279 <Folder>
280 </Document>
281 [ KML trailer information - not present if -K was given ]
282
284 gmt2kml will scan the segment headers for substrings of the form
285 -L"some label" [also see -N discussion] and -D"some description". If
286 present, these are parsed to supply name and description tags for the
287 current feature.
288
290 gmtdefaults(1), GMT(1), img2google(1), kml2gmt(1), ps2raster(1)
291GMT 4.5.6 10 Mar 2011 GMT2KML(1)