Tile Source Options

Each tile source can have custom options that affect how tiles are generated from that tile source. All tile sources have a basic set of options:

Format

Python tile functions can return tile data as images, numpy arrays, or PIL Image objects. The format parameter is one of the TILE_FORMAT_* constants.

Encoding

The encoding parameter can be one of JPEG, PNG, TIFF, or JFIF. When the tile is output as an image, this is the preferred format. Note that JFIF is a specific variant of JPEG that will always use either the Y or YCbCr color space as well as constraining other options.

The encoding only affects output when format is TILE_FORMAT_IMAGE.

Associated with encoding, some image formats have additional parameters.

  • JPEG and JFIF can specify jpegQuality, a number from 0 to 100 where 0 is small and 100 is higher-quality, and jpegSubsampling, where 0 is full chrominance data, 1 is half-resolution chrominance, and 2 is quarter-resolution chrominance.

  • TIFF can specify tiffCompression, which is one of the libtiff_ctypes.COMPRESSION* options.

Edges

When a tile is requested at the right or bottom edge of the image, the tile could extend past the boundary of the image. If the image is not an even multiple of the tile size, the edge parameter determines how the tile is generated. A value of None or False will generate a standard sized tile where the area outside of the image space could have pixels of any color. An edge value of 'crop' or True will return a tile that is smaller than the standard size. A value if the form of a hexadecimal encoded 8-bit-per-channel color (e.g., #rrggbb) will ensure that the area outside of the image space is all that color.

Style

Often tiles are desired as 8-bit-per-sample images. However, if the tile source is more than 8 bits per sample or has more than 3 channels, some data will be lost. Similarly, if the data is returned as a numpy array, the range of values returned can vary by tile source. The style parameter can remap samples values and determine how channels are composited.

If style is not specified or None, the default style for the file is used. Otherwise, this is a json-encoded string that contains an object with a key of bands consisting of an array of band definitions. If only one band is needed, a json-encoded string of just the band definition can be used.

A band definition is an object which can contain the following keys:

  • band: if -1 or None, the greyscale value is used. Otherwise, a 1-based numerical index into the channels of the image or a string that matches the interpretation of the band (‘red’, ‘green’, ‘blue’, ‘gray’, ‘alpha’). Note that ‘gray’ on an RGB or RGBA image will use the green band.

  • frame: if specified, override the frame parameter used in the tile query for this band. Note that it is more efficient to have at least one band not specify a frame parameter or use the same value as the basic query. Defaults to the frame value of the core query.

  • framedelta: if specified, and frame is not specified, override the frame parameter used in the tile query for this band by adding the value to the current frame number. If many different frames are being requested, all with the same framedelta, this is more efficient than varying the frame within the style.

  • min: the value to map to the first palette value. Defaults to 0. ‘auto’ to use 0 if the reported minimum and maximum of the band are between [0, 255] or use the reported minimum otherwise. ‘min’ or ‘max’ to always uses the reported minimum or maximum. ‘min:<threshold>’ and ‘max:<threshold>’ pick a value that excludes a threshold amount from the histogram; for instance, ‘min:0.02’ would exclude at most the dimmest 2% of values by using an appropriate value for the minimum based on a computed histogram with some default binning options. ‘auto:<threshold>’ works like auto, though it applies the threshold if the reported minimum would otherwise be used.

  • max: the value to map to the last palette value. Defaults to 255. ‘auto’ to use 0 if the reported minimum and maximum of the band are between [0, 255] or use the reported maximum otherwise. ‘min’ or ‘max’ to always uses the reported minimum or maximum. ‘min:<threshold>’ and ‘max:<threshold>’ pick a value that excludes a threshold amount from the histogram; for instance, ‘max:0.02’ would exclude at most the brightest 2% of values by using an appropriate value for the maximum based on a computed histogram with some default binning options. ‘auto:<threshold>’ works like auto, though it applies the threshold if the reported maximum would otherwise be used.

  • palette: This is a list or two or more colors. The values between min and max are interpolated using a piecewise linear algorithm or a nearest value algorithm (depending on the scheme) to map to the specified palette values. It can be specified in a variety of ways: - a list of two or more color values, where the color values are css-style strings (e.g., of the form #RRGGBB, #RRGGBBAA, #RGB, #RGBA, or a css rgb, rgba, hsl, or hsv string, or a css color name), or, if matplotlib is available, a matplotlib color name, or a list or tuple of RGB(A) values on a scale of [0-1]. - a single string that is a color string as above. This is functionally a two-color palette with the first color as solid black (#000), and the second color the specified value - a named color palette from the palettable library (e.g., matplotlib.Plasma_6) or, if available, from the matplotlib library or one of its plugins (e.g., viridis).

  • scheme: This is either linear (the default) or discrete. If a palette is specified, linear uses a piecewise linear interpolation, and discrete uses exact colors from the palette with the range of the data mapped into the specified number of colors (e.g., a palette with two colors will split exactly halfway between the min and max values).

  • nodata: the value to use for missing data. null or unset to not use a nodata value.

  • composite: either ‘lighten’ or ‘multiply’. Defaults to ‘lighten’ for all except the alpha band.

  • clamp: either True to clamp (also called clip or crop) values outside of the [min, max] to the ends of the palette or False to make outside values transparent.

Note that some tile sources add additional options to the style parameter.

Examples

Swap the red and green channels of a three color image

style = {"bands": [
  {"band": 1, "palette": ["#000", "#0f0"]},
  {"band": 2, "palette": ["#000", "#f00"]},
  {"band": 3, "palette": ["#000", "#00f"]}
]}

Apply a gamma correction to the image

This used a precomputed sixteen entry greyscale palette, computed as (value / 255) ** gamma * 255, where value is one of [0, 17, 34, 51, 68, 85, 102, 119, 136, 153, 170, 187, 204, 221, 238, 255] and gamma is 0.5.

style = {"palette": [
  "#000000", "#414141", "#5D5D5D", "#727272",
  "#838383", "#939393", "#A1A1A1", "#AEAEAE",
  "#BABABA", "#C5C5C5", "#D0D0D0", "#DADADA",
  "#E4E4E4", "#EDEDED", "#F6F6F6", "#FFFFFF"
]}