grd2kml¶

Create KML image quadtree from single grid

Synopsis¶

gmt grd2kml ingrid -Nprefix [ -Aa|g|s[altitude] ] [ -Ccpt ] [ -EURL ] [ -Ffiltercode ] [ -Hscale ] [ -I[intensfile|intensity|modifiers] ] [ -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,+1) range or by giving instructions to derive intensities from the input data grid automatically (see -I). Values outside the (-1,+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]

2-D gridded data set. 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] (See full description). The following modifiers are supported:

+b - Select a band (for images only) [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 sea surface or ground, s altitude relative to seafloor or ground. 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[cpt|master[+h[hinge]][+izinc][+u|Uunit] |color1,color2[,color3,…]]: Name of a CPT file. Alternatively, supply the name of a GMT color master dynamic CPT [turbo, but we use geo for @earth_relief and srtm for @srtm_relief data] to automatically determine a continuous CPT from the grid’s z-range; you may round the range to the nearest multiple of zinc by adding +izinc. If given a GMT Master soft-hinge CPT (see Of Colors and Color Legends) then you can enable the hinge at data value hinge [0] via +h, whereas for hard-hinge CPTs you can adjust the location of the hinge [0]. For other CPTs, you may convert their z-values from meter to another distance unit (append +Uunit) or from another unit to meter (append +uunit), with unit taken from e|f|k|M|n|u. Yet another option is to specify -Ccolor1,color2[,color3,…] to build a linear continuous CPT from those colors automatically. In this case colorn can be a r/g/b triplet, a color name, or an HTML hexadecimal color (e.g. #aabbcc). If no argument is given to -C then under modern mode we select the current CPT.

-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[intensfile|intensity|modifiers]: Gives the name of a grid file with intensities in the (-1,+1) range, or a constant intensity to apply everywhere (affects the ambient light). Alternatively, derive an intensity grid from the input data grid grid via a call to grdgradient; append +aazimuth and +nargs to specify azimuth and intensity arguments for that module or just give +d to select the default arguments (+a-45+nt1). If you want a more specific intensity scenario then run grdgradient separately first. [Default is no illumination].

-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 cookbook information).

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

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"