GMT2KML(1) Generic Mapping Tools GMT2KML(1)NAMEgmt2kml - Convert GMT data tables to KML files for Google Earth
SYNOPSISgmt2kml [ infile(s) ] [ -Aa|g|s[alt|xscale] ] [ -Ccpt ] [ -Ddescript‐
file ] [ -E[altitude] ] [ -Fe|s[cpt]|t|l|p ] [ -Gf|n[-|fill] ] [
-H[i][nrec] ] [ -Iicon ] [ -K] [ -Lcol1:name1,col2:name2,... ] [
-N[+|name_template|name] ] [ -O] [ -Q[s|l|p]transparency ] [
-Ra|w/e/s/n ] [ -Sc|nscale] ] [ -Ttitle[/foldername] ] [ -V ] [ -W-|pen
] [ -Zargs ] [ -:[i|o] ] [ -bi[s|S|d|D[ncol]|c[var1/...]] ] [
-f[i|o]colinfo ] [ -m[i|o][flag] ] [ > output.kml ]
DESCRIPTIONgmt2kml reads one or more GMT table file and converts them to a single
output file using Google Earth's KML format. Data may represent
points, lines, or polygons, and you may specify additional attributes
such as title, altitude mode, colors, pen widths, transparency,
regions, and data descriptions. You may also extend the feature down
to ground level (assuming it is above it) and use custom icons for
point symbols.
The input file should contain the following columns:
lon lat [ alt ] [ timestart [ timestop ] ]
where lon and lat are required for all features, alt is optional for
all features (see also -A and -C), and timestart and timestop apply to
events and timespan features.
infile(s)
ASCII (or binary, see -bi) data file(s) to be operated on. If
not given, standard input will be read.
OPTIONS
No space between the option flag and the associated arguments.
-A Select one of three altitude modes recognized by Google Earth
that determines the altitude (in m) of the feature: a absolute
altitude, g altitude relative to sea surface or ground, s alti‐
tude relative to seafloor. To plot the features at a fixed
altitude, append an altitude alt (in m). Use 0 to clamp the fea‐
tures to the chosen reference surface. Append xscale to scale
the altitude from the input file by that factor. If no value is
appended, the altitude (in m) is read from the 3rd column of the
input file. [By default the features are clamped to the sea
surface or ground].
-C Use color palette for assigning colors to the symbol, event, or
timespan icons, based on the value in the 3rd column of the
input file. Ignored when plotting lines or polygons.
-D File with HTML snippets that will be included as part of the
main description content for the KML file [no description]. See
SEGMENT INFORMATION below for feature-specific descriptions.
-E Extrude feature down to ground level [no extrusion].
-F Sets the feature type. Choose from points (event, symbol, or
timespan), line, or polygon [symbol]. The first two columns of
the input file should contain (lon, lat). When altitude or
value is required (i.e., no altitude value was given with -A, or
-C is set), the third column needs to contain the altitude (in
m). The event (-Fe) is a symbol that should only be active at a
particular time, given in the next column. Timespan (-Ft) is a
symbol that should only be active during a particular time
period indicated by the next two columns (timestart, timestop).
Use NaN to indicate unbounded time limits. If used, times
should be in ISO format yyyy-mm-ddThh:mm:ss[.xxx] or in GMT rel‐
ative time format (see -f).
-G Set fill color for symbols, extrusions and polygons (-Gf)
[Default is lightorange] or text labels (-Gn) [Default is
white]. Optionally, use -Gf- to turn off polygon fill, and -Gn-
to disable labels. (See SPECIFYING FILL below).
-H Input file(s) has header record(s). If used, the default number
of header records is N_HEADER_RECS. Use -Hi if only input data
should have header records [Default will write out header
records if the input data have them]. Blank lines and lines
starting with # are always skipped.
-I Specify the URL to an alternative icon that should be used for
the symbol [Default is a Google Earth circle]. If the URL
starts with + then we will prepend http://maps.google.com/map‐
files/kml/ to the name. [Default is a local icon with no direc‐
tory path].
-K Allow more KML code to be appended to the output later [finalize
the KML file].
-L Extended data given. Append one or more strings of the form
col:name separated by commas. We will expect the listed data
columns to exist in the input and they will be encoded in the
KML file as Extended Data sets, whose attributes will be avail‐
able in the Google Earth balloon when the item is selected.
-N By default, if multisegment headers contain a -L"label string"
then we use that for the name of the KML feature (polygon, line
segment or set of symbols). Default names for these segments are
"Line %d" and "Point Set %d", depending on the feature, where %d
is a sequence number of line segments within a file. Each point
within a line segment will be named after the line segment plus
a sequence number. Default is simply "Point %d".
Alternatively, select one of these options: (1) append + to sup‐
ply individual symbol labels directly at the end of the data
record, (2) append a string that may include %d or a similar
integer format to assign unique name IDs for each feature, with
the segment number (for lines and polygons) or point number
(symbols) appearing where %d is placed, (3) give no arguments to
turn symbol labeling off; line segments will still be named.
-O Appended KML code to an existing KML file [initialize a new KML
file].
-Q Set the transparency level for the selected feature (e, s, t, l,
or p, plus n for name labels). Transparency goes from 0 (fully
transparent) to 1 (opaque) [0.75 for polygons, 1 for symbols,
lines, and labels].
-R Issue a single Region tag. Append w/e/s/n to set a particular
region (will ignore points outside the region), or append a to
determine and use the actual domain of the data (single file
only) [no region tags issued].
-S Scale icons or labels. Here, -Sc sets a scale for the symbol
icon, whereas -Sn sets a scale for the name labels [1 for both].
-T Sets the document title [GMT Data Document]. Optionally, append
/FolderName; this allows you, with -O, -K, to group features
into folders within the KML document. [The default folder name
is "Name Features", where Name is Point, Event, Timespan, Line,
or Polygon].
-V Selects verbose mode, which will send progress reports to stderr
[Default runs "silently"].
-W Set pen attributes for lines or polygon outlines. Append pen
attributes to use [Defaults: width = 1p, color = black, texture
= solid]. Optionally, use -W- to turn off polygon outline Note
that for KML the pen width is given as integer pixel widths so
you must specify pen width as np, where n is an integer. (See
SPECIFYING PENS below).
-Z Set one or more attributes of the Document and Region tags.
Append +aalt_min/alt_max to specify limits on visibility based
on altitude. Append +llod_min/lod_max to specify limits on vis‐
ibility based on Level Of Detail, where lod_max == -1 means it
is visible to infinite size. Append +ffade_min/fade_max to fade
in and out over a ramp [abrupt]. Append +v to make a feature
not visible when loaded [visible]. Append +o to open a folder
or document in the sidebar when loaded [closed].
-: Toggles between (longitude,latitude) and (latitude,longitude)
input and/or output. [Default is (longitude,latitude)]. Append
i to select input only or o to select output only. [Default
affects both].
-bi Selects binary input. Append s for single precision [Default is
d (double)]. Uppercase S or D will force byte-swapping.
Optionally, append ncol, the number of columns in your binary
input file if it exceeds the columns needed by the program. Or
append c if the input file is netCDF. Optionally, append
var1/var2/... to specify the variables to be read. [Default is
2 input columns].
-f Special formatting of input and/or output columns (time or geo‐
graphical data). Specify i or o to make this apply only to
input or output [Default applies to both]. Give one or more
columns (or column ranges) separated by commas. Append T (abso‐
lute calendar time), t (relative time in chosen TIME_UNIT since
TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
to each column or column range item. Shorthand -f[i|o]g means
-f[i|o]0x,1y (geographic coordinates).
-m Multiple segment file(s). Segments are separated by a special
record. For ASCII files the first character must be flag
[Default is '>']. For binary files all fields must be NaN and
-b must set the number of output columns explicitly. By default
the -m setting applies to both input and output. Use -mi and
-mo to give separate settings to input and output. The -m
option make sure that segment headers in the input files are
copied to output, but it has no effect on the data selection.
Selection is always done point by point, not by segment.
SPECIFYING PENS
pen The attributes of lines and symbol outlines as defined by pen is
a comma delimetered list of width, color and texture, each of
which is optional. width can be indicated as a measure (points,
centimeters, inches) or as faint, thin[ner|nest], thick[er|est],
fat[ter|test], or obese. color specifies a gray shade or color
(see SPECIFYING COLOR below). texture is a combination of
dashes `-' and dots `.'.
SPECIFYING COLOR
color The color of lines, areas and patterns can be specified by a
valid color name; by a gray shade (in the range 0-255); by a
decimal color code (r/g/b, each in range 0-255; h-s-v, ranges
0-360, 0-1, 0-1; or c/m/y/k, each in range 0-1); or by a hexa‐
decimal color code (#rrggbb, as used in HTML). See the gmtcol‐
ors manpage for more information and a full list of color names.
EXAMPLES
To convert a file with point locations (lon, lat) into a KML file with
red circle symbols, try
gmt2kml mypoints.txt -Gf red -Fs > mypoints.kml
To convert a multisegment file with lines (lon, lat) separated by mul‐
tisegment headers that contain a -L labelstring with the feature name,
selecting a thick white pen, and title the document, try
gmt2kml mylines.txt -W thick,white -Fl -T"Lines from here to there" >
mylines.kml
To convert a multisegment file with polygons (lon, lat) separated by
multisegment headers that contain a -L labelstring with the feature
name, selecting a thick black pen and semi-transparent yellow fill,
giving a title to the document, and prescribing a particular region
limit, try
gmt2kml mypolygons.txt -Gf yellow -Qp 0.5 -Fp -T"My polygons" -R
30/90/-20/40 > mypolygons.kml
To convert a file with point locations (lon, lat, time) into a KML file
with green circle symbols that will go active at the specified time and
stay active going forward, try
awk '{print $1, $2, $3, "NaN"}' mypoints.txt | gmt2kml-Gf green -Ft >
mytimepoints.kml
LIMITATIONS
Google Earth has trouble displaying filled polygons across the Date‐
line. For now you must manually break any polygon crossing the date‐
line into a west and east polygon and plot them separately.
MAKING KMZ FILES
Using the KMZ format is preferred as it takes less space. KMZ is sim‐
ply a KML file and any data files, icons, or images referenced by the
KML, contained in a zip archive. One way to organize large data sets
is to split them into groups called Folders. A Document can contain
any number of folders. Using scripts you can create a composite KML
file using the -K, -O options just like you do with GMT plots. See -T
for switching between folders and documents.
KML HIERARCHY
GMT stores the different features in hierarchical folders, by feature
type (when using -O, -K or -T/foldername), by input file (if not stan‐
dard input), and by line segment (using the name from the segment
header, or -N). This makes it more easy in Google Earth to switch on
or off parts of the contents of the Document. The following is a crude
example:
[ KML header information - not present if -O was given ]
<Document><name>GMT Data Document</name>
<Folder><name>Point Features</name>
<!--This level of folder is inserted only when using -O, -K>
<Folder><name>file1.dat</name>
<!--One folder for each input file (not when standard
input)>
<Folder><name>Point Set 0</name>
<!--One folder per line segment>
<!--Points from the first line segment in file file1.dat go
here>
<Folder><name>Point Set 1</name>
<!--Points from the second line segment in file file1.dat
go here>
</Folder>
</Folder>
<Folder><name>Line Features</name>
<Folder><name>file1.dat</name>
<!--One folder for each input file (not when standard
input)>
<Placemark><name>Line 0</name>
<!--Here goes the first line segment>
</Placemark>
<Placemark><name>Line 1</name>
<!--Here goes the second line segment>
</Placemark>
</Folder>
<Folder>
</Document>
[ KML trailer information - not present if -K was given ]
SEGMENT INFORMATIONgmt2kml will scan the segment headers for substrings of the form
-L"some label" [also see -N discussion] and -D"some description". If
present, these are parsed to supply name and description tags for the
current feature.
SEE ALSOgmtdefaults(1), GMT(1), img2google(1), kml2gmt(1), ps2raster(1)GMT 4.5.14 1 Nov 2015 GMT2KML(1)
