LibGrid

Grid Files

← The Viewer | ● | Tools →

Grid File Syntax

In the following, all the options of the grid file format will be described by means of a more sophisticated version of the sample tileset. We are basically going to add more layers to cover the bathymetry around Oahu. We are also adding high-resolution imagery of Manana Island off the eastern coast. And we are going to improve the appearance of the tileset by pre-shading the terrain. This is a precondition to render bathymetry, as there is no imagery naturally available for the sea floor. Before diving into the details, here is the resulting example grid file: 

“Oahu-Tileset”                # tileset name
repo “data”                   # input repo
path “data/tilesets”          # output path
level 0                       # output level
shade fill reproject compress # output attributes

# elevation
“elev/Oahu-10m.tif”
# bathymetry
“bthy/Oahu-50m-W.tif”
“bthy/Oahu-50m-E.tif”
“bthy/Hawaii-1km.tif” keep_bathy
# islands
“elev/Oahu-Islands/KapapaIsland.tif”
“elev/Oahu-Islands/MananaIsland.tif”
“elev/Oahu-Islands/MokuliiIsland.tif”
“elev/Oahu-Islands/MokuluaIslands.tif”
“elev/Oahu-Islands/MokumanuIsland.tif”
“elev/Oahu-Islands/MokuoloeIsland.tif”
“elev/Oahu-Islands/SandIsland.tif”
# etc
“elev/MakaiPier.tif” spacing 5

# imagery
“imag/Oahu-25m.tif” extents
# islands
“imag/Oahu-Islands/MananaIsland.tif” spacing 6 move 100 30
“imag/Oahu-Islands/MokuluaIslands.jpgintif” spacing 1.5
“imag/Oahu-Islands/FlatIsland.jpgintif” spacing 1.5
“elev/Oahu-Islands/MokuoloeIsland.tif” apply_shading 4 0

After the tileset name in the top line of the grid file, a variety of attributes can be specified, which control the properties of the output tileset. The attributes are as follows:

  • repo dir: Specifies an output path prefix for the tileset.
  • path dir: Specifies an input path prefix for all layers.
  • level value: Specifies the output resolution of the tileset. Level 0 corresponds to the original resolution of the layers, level 1 corresponds to half of that and so forth. Can be used to quickly test the tileset output at a faster resampling lower resolution.
  • float: Output elevation as float, otherwise use 16bit integer. Default: On. 16bit elevation may introduce quantization artifacts. In that case, bump up to float.
  • shade: Shade the imagery based on available elevation data to emphasize interesting structures like ridges. Default: On. Used mainly to shade bathymetry, where imagery is unavailable.
  • fill: Fill undefined grid cells (elevation and imagery) by extrapolating from the neighbor cells. Default: Off. Automatically gets rid of small glitches in the input data.
  • reproject: Reproject all layers before resampling. Default: Off. May speed up resampling, but comes at the expense of an additional interpolation, which may degrade data crispness.
  • compress: Compress output imagery with the S3TC algorithm. Default: On. Reduces size by a factor of 6. Note: Output imagery is always mip-mapped to ensure proper display at any level of detail at which the tiles are paged in. Side note: If the output imagery contains areas with undefined cells (no-data values), the output imagery will be amended with an alpha channel to mask those areas.
  • zcompress: Compress output elevation with the ZLIB library. Default: On. Reduces size by a factor of approximately 2. Elevation is compressed losslessly. This has no measurable performance impact.

Likewise, after each layer, a variety of layer attributes can be specified, which alter the appearance of each layer:

  • extents: Specifying that keyword after a layer means that the area of interest is the extents of the corresponding layer. If no extents are specified explicitly, the area of interest is set to the entire coverage of all layers.
  • spacing value: Overrides the cell spacing of a layer to be the specified value given in meters. Useful for oversampled data, where the native resolution is too high for display.
  • move off_x off_y: Moves the layer by the specified offset to correct certain displacements where the geo-referenced position does not correspond exactly with reality (or does not match other layers).
  • treat_black: Treats black as transparent, when black has been used to encode no-data values instead of naturally utilizing an alpha channel.
  • treat_white: Same as above, except for white being treated as transparent.
  • remove_bathy: Removes all elevation values below the sea level and replaces them with no-data.
  • keep_bathy: Removes all elevation values above the sea level and replaces them with no-data.
  • apply_shading: Transforms an elevation layer into an imagery layer by shading it. Useful to generate b/w imagery for areas where there is no native imagery available.

The above example grid file is supplied as “data/tilesets/Oahu.grid”, so you can generate the corresponding tileset and check out the effects of the above options with the following command: 

grid/gridder data/tilesets/Oahu.grid

At the original output level the resampling process will take a while, so please be patient. For testing purposes, you can bump up the output level via: 

grid/gridder data/tilesets/Oahu.grid 1

The default output level is 0. For each higher level, the output resolution is halved so that processing time is reduced to a quarter.

← The Viewer | ● | Tools →

Options: