grd2kml

Create KML image quadtree from single grid

Synopsis

gmt grd2kml ingrid -Nprefix [ -Aa|g|s[altitude] ] [ -C[section/]master|cpt|color\(_1\),color\(_2\)[,color\(_3\),…][+h[hinge]][+idz][+u|Uunit][+sfname] ] [ -EURL ] [ -Ffiltercode ] [ -Hscale ] [ -I[file|intens|+aazimuth][+d][+mambient][+nargs] ] [ -Ltilesize ] [ -S[extra] ] [ -Ttitle ] [ -Wcfile|pen[+sscale/limit] ] [ -V[level] ] [ -fflags ] [ -nflags ] [ --PAR=value ]

Note: No space is allowed between the option flag and the associated arguments.

Description

grd2kml reads a 2-D grid file and makes a quadtree of PNG or JPG images and KML wrappers for Google Earth using the selected tile size. We downsample the grid depending on the viewing level in the quadtree using a Gaussian filter, but other filters can be selected as well. Optionally, illumination may be added by providing a grid file with intensities in the ±1 range or by giving instructions to derive intensities from the input data grid automatically (see -I). Values outside the ±1 intensity range will be clipped. Map colors are specified via a color palette lookup table. Contour overlays are optional. If plain tiles are selected (i.e., no contours specified) then the PNG tiles are written directly from grdimage. Otherwise, we must first make a PostScript plot that is then converted to raster image via psconvert.

Required Arguments

ingrid[=ID|?varname][+bband][+ddivisor][+ninvalid][+ooffset][+sscale]

Optionally, append =ID for reading a specific file format [Default is =nf] or ?varname for a specific netCDF variable [Default is the first 2-D grid found by GMT]. The following modifiers are supported:

  • +b - Select a band [Default is 0].

  • +d - Divide data values by the given divisor [Default is 1].

  • +n - Replace data values matching invalid with NaN.

  • +o - Offset data values by the given offset [Default is 0].

  • +s - Scale data values by the given scale [Default is 1].

Note: Any offset is added after any scaling.

-Nprefix

Sets a unique name prefixed used for the top-level KML filename and the directory where all referenced KML files and raster images will be written [GMT_Quadtree].

Optional Arguments

-Aa|g|s[altitude]

Select one of three altitude modes recognized by Google Earth that determines the altitude (in m) of the tile layer: a absolute altitude, g altitude relative to ground, or s altitude relative to seafloor. To plot the tiles at a fixed altitude, append an altitude altitude (in m). Use 0 to clamp the features to the chosen reference surface. [By default the tiles are clamped to the sea surface or ground].

-C[section/]master|cpt|color\(_1\),color\(_2\)[,color\(_3\),…][+h[hinge]][+idz][+u|Uunit][+sfname]

Name of a master CPT, an input CPT file or a comma-separated list of colors from which to build a CPT. If no argument is given then under modern mode we select the current CPT, if it is available. Generally, the input can be many things:

  1. A standard GMT master CPT file, e.g., earth (see Of Colors and Color Legends) and can be either addressed by master or section/master (without any .cpt extension).

  2. File name of already custom-made cpt file (e.g, my_colors.cpt).

  3. Build a linear continuous CPT from color\(_1\),color\(_2\)[,color\(_3\),…] automatically, where z starts at 0 and is incremented by one for each color. In this case, color\(_i\) can be a r/g/b (e.g., 255/100/75), h-s-v triplet (e.g., 180-0.8-1), a c/m/y/k quadruple (e.g., 80/50/40/30), an HTML hexadecimal color (e.g. #aabbcc), or a color name. No spaces between commas are allowed.

A few modifiers pertains to hinges and units:

  • +h - If given a master CPT with soft hinges then you can enable the hinge at data value hinge [0], whereas for hard-hinge CPTs you can adjust the location of the hinge [0] but not disable it.

  • +i - Append increment dz to quantize the grid range [Default uses the exact grid range].

  • +s - Append fname to save the finalized CPT in a disk file. This is useful when the CPT is generated automatically, but if used, must be at the end of the -C option.

  • +u - For any other master CPT, you may convert their z-values from other distance Units to meter by appending the original unit code.

  • +U - Likewise, you may convert their z-values from meter to other Units by appending the desired unit code.

-EURL

Instead of hosting all files on your computer, you may prepend a remote site URL. Then, the top-level prefix.kml file will use this URL to find all other files it references. After building completes you must place the entire prefix directory at the remote location pointed to by the URL [local files only]. With this arrangement you can share the prefix.kml with others (say, via email or for download) and users can open the file in their Google Earth and access the remote files from your server as needed.

-Ffiltercode

Specifies the filter to use for the downsampling of the grid for more distant viewing. Choose among boxcar, cosine arch, gaussian, or median [Gaussian]. The filter width is set automatically depending on the level.

-Hscale

Improve the quality of rasterization by passing the sub-pixel smoothing scale to psconvert (same as -H option in psconvert) [no sub-pixel smoothing]. Ignored when -W is not used.

-I[file|intens|+aazimuth][+d][+mambient][+nargs]

Apply illumination for the input grid. Several methods are available:

  • Give the file name of a co-registered grid with intensities in the ±1 range.

  • Give a constant intens to apply everywhere (affects the ambient light).

Alternatively, derive intensities from the main input data grid via a call to grdgradient by appending +aazimuth, +nargs and +mambient for the arguments needed by that module, or just give +d to select the default [+a-45+nt1+m0]. For more specific intensity scenarios run grdgradient separately first. If we should derive intensities from another file than the main grid, specify that file as the file and add suitable modifiers [Default is no illumination]. Note: If the input grid actually is an image then file or constant intens must be provided since derivatives are not available.

-Ltilesize

Sets the fixed size of the image building blocks. Must be an integer that is radix 2. Typical values are 256 or 512 [256]. Note: For global grids (here meaning 360-degree longitude range), we will select a tilesize of 360 if -L is not specified.

-S[extra]

Add extra layers beyond that necessary to capture the full resolution of the data [none]. This will let GMT interpolate your grid and make more tiles, versus letting Google Earth interpolate the last resolution raster images.

-Ttitle

Sets the title of the top-level document (i.e., its description).

-V[level]

Select verbosity level [w]. (See full description) (See technical reference).

-Wcfile|pen[+sscale/limit]

Supply a file with records each holding a contour value and a contour pen. We then overlay the selected contour lines on top of the image [no contours]. Consequently, -W triggers the tile creation via PostScript and thus is slower. If cfile is not a valid file we assume you instead gave a pen and want to draw all the contours implied by the cpt specified in -C. The contours are overlain via calls to grdcontour. Note: The contour pen width(s) refer to the highest tile level and are reduced by a factor of scale [sqrt(2)] for each lower level. Contours with scaled pen widths < limit [0.1] points are skipped (except for pen widths that exactly equal 0 or “faint”). Use +s to change these values.

-f[i|o]colinfo (more …)

Specify data types of input and/or output columns.

-n[b|c|l|n][+a][+bBC][+c][+tthreshold] (more …)

Select interpolation mode for grids.

-^ or just -

Print a short message about the syntax of the command, then exit (Note: on Windows just use -).

-+ or just +

Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.

-? or no arguments

Print a complete usage (help) message, including the explanation of all options, then exit.

--PAR=value

Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Units

For map distance unit, append unit d for arc degree, m for arc minute, and s for arc second, or e for meter [Default unless stated otherwise], f for foot, k for km, M for statute mile, n for nautical mile, and u for US survey foot. By default we compute such distances using a spherical approximation with great circles (-jg) using the authalic radius (see PROJ_MEAN_RADIUS). You can use -jf to perform “Flat Earth” calculations (quicker but less accurate) or -je to perform exact geodesic calculations (slower but more accurate; see PROJ_GEODESIC for method used).

Quadtree building

We extend the input grid vi grdcut to obtain a square dimension that can be repeatedly divided by 2 until we arrive at tiles with the original grid increments. For global grids this mean we extend the grid to a 360 x 360 Cartesian region and an initial grid increment of one degree. This is the first global tile. As the quartering of tiles and halving of grid increment continue we may not end exactly at the original grid spacing but at the largest increment less than or equal to the original increment. For non-global grids, e.g., smaller (local or regional) grids, we extend the domain to a radix-2 multiple of the tilesize times the grid increment. This initial tile is then quartered and the grid increment halved until we reach the original grid increment. Tiles that have all NaNs are not produced. THe tiles are inherently pixel-registered. Thus, if a global grid has gridline-registration then we are down-sampling the extended grid onto a pixel-registered coarser grid. Because these nodes do not coincide with the original nodes we widen the filter width by a factor of sqrt(2). We detect if NaNs are present in any tile and if so produce a transparent PNG tile; otherwise we make an opaque JPG tile.

Contour overlays

Because each tile is a fixed size image (e.g., 512x512 pixels) but the amount of data represented changes by factors of 4 for each new level, we cannot use a constant thickness contour pen for all levels. Thus, the pen you supply must be considered the final pen applied to the highest resolution map overlays. Furthermore, because the dpi here is very small compared to regular GMT plots, it is important to improve the appearance of the contours by using sub-pixel smoothing (-H). Both generating PostScript tiles and using sub-pixel smoothing adds considerable processing time over plain tiles.

Notes

The intensity grid can be created from the data grid using grdgradient and, optionally, modified by grdmath or grdhisteq. Custom intensity grids built with several different illumination angles can be combined with grdmath. For a single illumination angle the automatic illumination can be used instead.

Examples

Note: Below are some examples of valid syntax for this module. The examples that use remote files (file names starting with @) can be cut and pasted into your terminal for testing. Other commands requiring input files are just dummy examples of the types of uses that are common but cannot be run verbatim as written.

To test a quadtree image representation of the coarse topography grid earth_relief_06m, using the optimally determined tile size, auto color, and supplying a suitable title, try:

gmt grd2kml @earth_relief_06m -NEarth6m -T"Earth Relief 6x6 arc minutes" -Cearth

To make a quadtree image representation of the large topography grid file ellice_basin.nc, supplying automatic shading based on the topography, and using 512x512 tiles, supplying a suitable title, and using color masking for unmapped area, try:

gmt grd2kml ellice_basin.nc -I+d -Nellice -L512 -T"Ellice Basin Bathymetry"

See Also

gmt, gmt.conf, gmt2kml, grdgradient, grdhisteq, grdimage, grdmath, kml2gmt, psconvert