Provided by: gmt_4.5.11-1build1_amd64 bug


       gmt2kml - Convert GMT data tables to KML files for Google Earth


       gmt2kml  [ infile(s) ] [ -Aa|g|s[alt|xscale] ] [ -Ccpt ] [ -Ddescriptfile ] [ -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 ]


       gmt2kml 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.

              ASCII  (or binary, see -bi) data file(s) to be operated on.  If not given, standard
              input will be read.


       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 altitude relative to seafloor.  To  plot  the  features  at  a
              fixed  altitude,  append an altitude alt (in m). Use 0 to clamp the features 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 relative 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
     to the name.  [Default is a local icon with no
              directory 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
              available 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 supply 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

       -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 visibility 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 geographical 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
              (absolute 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.

       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 `.'.

       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
              hexadecimal color code (#rrggbb, as used in HTML).  See the gmtcolors  manpage  for
              more information and a full list of color names.


       To convert a file with point locations (lon, lat) into a KML file with red circle symbols,

       gmt2kml mypoints.txt -Gf red -Fs > mypoints.kml

       To convert a multisegment file with lines (lon, lat)  separated  by  multisegment  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  >

       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


       Google Earth has trouble displaying filled polygons across the Dateline.  For now you must
       manually break any polygon crossing the dateline into a west and  east  polygon  and  plot
       them separately.


       Using  the  KMZ  format is preferred as it takes less space.  KMZ is simply 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.


       GMT stores the different features in hierarchical folders, by feature type (when using -O,
       -K  or  -T/foldername),  by input file (if not standard 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>
                   <!--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><name>Line Features</name>
                   <!--One folder for each input file (not when standard input)>
                   <Placemark><name>Line 0</name>
                       <!--Here goes the first line segment>
                   <Placemark><name>Line 1</name>
                       <!--Here goes the second line segment>
       [ KML trailer information - not present if -K was given ]


       gmt2kml  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.


       gmtdefaults(1), GMT(1), img2google(1), kml2gmt(1), ps2raster(1)