API Reference#

This section is autogenerated from the package’s docstrings, and is intended as a reference for those that want a deeper understanding of the package.

tiling module#

Supporting functions for creating a tiler.

Based on code from TuiView.

Main function is getTile(). An application may want to call createColorMapFromIntervals()/createColorMapFromPoints() to obtain a colormap in the correct format to getTile().

The other functions in this module are for internal use and not intended for use by an application.

cibotiler.tiling.getTile(filename, z, x, y, bands=None, rescaling=None, colormap=None, resampling='near', fmt='PNG', tileSize=256, outTileType=numpy.uint8, metadata=None)#

Main function. By opening the given file the correct web mercator tile is selected and extracted and converted into an image format using the methods definited by the parameters to this function.

Parameters:

filenamestr or gdal.Dataset: The name of the file to extract the tile from or an open GDAL dataset object. This file should be in webmercator (EPSG:3857) projection. Use a path starting with /vsis3 to open from an S3 bucket. The Lambda must be set up with the correct permissions to access this file.
zint: Zoom level
xint: X position on the web mercator grid
yint: Y position on the web mercator grid
bandsNone or sequence of ints, optional: Passing None will result in all bands being read from the file. Otherwise a sequence of 1-based band indices are required. Note that if you are passing a colormap there needs to be only one band, otherwise 3 (and only 3) are required.
rescalingsequence of (float, float) tuples, optional: If the data is to be stretched, pass the range of values that the data is to be linearly stretched between. This should be the same length as ‘bands’. Cannot be passed if colormap is used.
colormapnumpy.array, optional: A numpy array of shape (4, maxPixelValue) that defines the colormap to be applied to a single band image.
resamplingstr, optional: Name of resampling method to be used when zoomed in more than the image supported. Currently only ‘near’ and ‘bilinear’ is supported.
fmtstr, optional: Name of GDAL driver that creates the image format that needs to be returned. Defaults to ‘PNG’
tileSizeint, optional: Size in pixels of the returned tile. The returned tile will be this size in both the x and y dimensions. Defaults to 256x256.
outTileTypenumpy dtype, optional: The type of the returned image. Defaults to uint8.
metadatainstance of Metadata, optional: If previously obtained, an instance of a Metadata for filename. Default is this will be obtained withing the function.
Returns:
io.BytesIO: The binary data that contains the image tile.

cibotiler.tiling.getDataForFile(filename, tileSize, tlx, tly, brx, bry, bands, resampling)#

Internal method. Intended to be called from a sub thread.

Parameters:

filenamestr or gdal.Dataset
tileSizeint: Size in pixels of the returned tile.
tlx, tly, brx, bry: int: Bounds of the tile in webmercator
bandssequence of ints
resampling: str

Returns:

tuple of (data, dataslice, list of nodata)

cibotiler.tiling.getTileMosaic(filenames, z, x, y, bands=None, rescaling=None, colormap=None, resampling='near', fmt='PNG', tileSize=256, outTileType=numpy.uint8, metadata=None)#

Similar to getTile() but takes a list of filenames. They are opened and read in parallel then mosaiced together.

Note that the nodata must be set on all the bands of the filenames so that the correct data can be mosaiced together.

Parameters:

filenameslist of str or gdal.Dataset: A list of filenames (or gdal.Datasets) to extract the tile from. These files should be in webmercator (EPSG:3857) projection. Use a path starting with /vsis3 to open from an S3 bucket. The Lambda must be set up with the correct permissions to access this file. The files are mosaiced in order first to last and later images only overwrite earlier ones when they are not the nodata value.
zint: Zoom level
xint: X position on the web mercator grid
yint: Y position on the web mercator grid
bandsNone or sequence of ints: A sequence of 1-based band indices are required. Note that if you are passing a colormap there needs to be only one band, otherwise 3 (and only 3) are required. Unlike getTile() this is NOT optional.
rescalingsequence of (float, float) tuples, optional: If the data is to be stretched, pass the range of values that the data is to be linearly stretched between. This should be the same length as ‘bands’. Cannot be passed if colormap is used.
colormapnumpy.array, optional: A numpy array of shape (4, maxPixelValue) that defines the colormap to be applied to a single band image.
resamplingstr, optional: Name of resampling method to be used when zoomed in more than the image supported. Currently only ‘near’ and ‘bilinear’ is supported.
fmtstr, optional: Name of GDAL driver that creates the image format that needs to be returned. Defaults to ‘PNG’
tileSizeint, optional: Size in pixels of the returned tile. The returned tile will be this size in both the x and y dimensions. Defaults to 256x256.
outTileTypenumpy dtype, optional: The type of the returned image. Defaults to uint8.
metadatainstance of Metadata, optional: If previously obtained, an instance of a Metadata for filename. Default is this will be obtained withing the function.

Returns:

io.BytesIO: The binary data that contains the image tile.

cibotiler.tiling.getExtentforWebMTile(z, x, y)#

Helper function for getting the projected extent for a web mercator tile (EPSG: 3857)

Parameters:

zint: Zoom level
xint: X position on the web mercator grid
yint: Y position on the web mercator grid

Returns:

tuple of floats:: (tlx, tly, brx, bry)

cibotiler.tiling.createColorMapFromIntervals(intervals)#

Helper function to convert a list of ((minVal, maxVal), (r, g, b, a)) tuples to a colormap expected by getTile() Note that the intervals list should be ordered by value.

Parameters:

intervalssequence of ((min, max), (r, g, b, a)) tuples.: This defines the colours for each interval. Is expected to be sorted. Note that undefined results will occur if there are missing ranges in the intervals. Note that the actual range set for each colour is (min - max-1). So the max for one range should be the min for the next range.

Returns:

numpy.ndarray: A colormap of shape (4, maxPixVal).

cibotiler.tiling.createColorMapFromPoints(points)#

Helper function to convert a list of (value, (r, g, b, a)) tuples to a colormap expected by getTile() colors between these values are interpolated. It is expected that the list is sorted.

Parameters:

pointssequence of (value, (r, g, b, a)) tuples: The points to interpolate the rest of the values from.

Returns:

numpy.ndarray: A colormap of shape (4, maxPixVal).

cibotiler.tiling.createColorMapFromRAT(filename, band=1)#

Helper function to create a colormap from the Raster Attribute Table of a file.

Parameters:

filenamestr or gdal.Dataset: The name of the file to extract the RAT from or an open GDAL dataset object.
bandint, optional: The 1-based index of the band to extrat the RAT from. Defaults to the first band.

Returns:

numpy.ndarray: A colormap of shape (4, maxPixVal).

cibotiler.tiling.createBytesIOFromMEM(mem, fmt)#

Given a GDAL in memory dataset (“MEM” driver) convert to the given format and dump as a io.BytesIO for returning to client.

Parameters:

memGDALDataset: An open GDAL Dataset object for the ‘MEM’ driver that has the data to be turned into a BytesIO.
fmtstr: Name of GDAL driver that creates the image format that needs to be returned.

Returns:

io.BytesIO: The binary data that contains the image tile.

class cibotiler.tiling.OverviewInfo(xsize, ysize, fullrespixperpix, index)#

Stores size and index of an overview.

Parameters:

xsizeint: Number of columns in the overview
ysizeint: Numer of rows inthe overview
fullrespixperpixfloat: Number of pixels at full resolution that each overview pixel covers
indexint: The index of the overview. 0 is the full res image.

class cibotiler.tiling.OverviewManager#

This class contains a list of valid overviews and allows the best overview to be retrieved

Attributes:

overviewslist of OverviewInfo instances: The overviews

loadOverviewInfo(ds, bands)#

Load the overviews from the GDAL dataset into a list bands should be a list or tuple of band indices. Checks are made that all lists bands contain the same sized overviews

Parameters:

dsGDALDataset object: The file to load the overviews in from
bandssequence of int: The bands we are interested in

findBestOverview(imgpixperwinpix)#

Finds the best overview for given imgpixperwinpix

Parameters:

imgpixperwinpixfloat: The number of image pixels per pixels we want to display

Returns:

Instance of OverviewInfo: The overview that most closely matches (but has more pixels than required) the requested imgpixperwinpix

class cibotiler.tiling.Metadata(ds)#

Class that holds all the ‘metadata’ about an object (ie size, projection etc) and can be passed around without re-requesting the data again.

Will raise an error if file not in web mercator (EPSG: 3857)

Parameters:

dsGDALDataset: Dataset to query

Attributes:

RasterXSizeint: X Size of raster
RasterYSizeint: Y Size of raster
RasterCountint: Number of bands
thematicbool: Whether image is thematic or not
transformsequence of floats: the geo transform of the image
allIgnoresequence of float: The ignore value (or None if not set) for each band
overviewsOverviewManager: Information about the overview
tlx, tly, brx, bryfloats: Bounding box of the image in projected coords
iInversesequence of floats: The inverse geo transform of the image

cibotiler.tiling.pixel2displayF(col, row, origCol, origRow, imgPixPerWinPix)#

From tuiview - convert pixel coordinates to display as float

Parameters:

colint: The column
rowint: The row
origColint: The column of the origin of the tile
origRowint: The row of the origin of the tile
imgPixPerWinPixfloat: The number of image pixels per tile pixel

Returns:

tuple of float: (x, y)

cibotiler.tiling.pixel2display(col, row, origCol, origRow, imgPixPerWinPix)#

From tuiview - convert pixel coordinates to display - integer version

Parameters:

colint: The column
rowint: The row
origColint: The column of the origin of the tile
origRowint: The row of the origin of the tile
imgPixPerWinPixfloat: The number of image pixels per tile pixel

Returns:

tuple of int: (x, y)

cibotiler.tiling.getRawImageChunk(ds, metadata, xsize, ysize, tlx, tly, brx, bry, bands, resampling)#

Also adapted from tuiview. returns requested chunk of image. Returns the data and the dataslice that the data fits into the (ysize, xsize) output data.

Parameters:

dsGDALDataset: File to read the data from
metadataMetadata: Metadata for the file
xsizeint: Number of columns to return
ysizeint: Number of rows to return
tlx, tly, brx, bryfloats: The bounds of the image in projected coords
bandssequence of ints: The bands to read from
resamplingstr: Name of resampling method to be used when zoomed in more than the image supported. Currently only ‘near’ is supported.

Returns:

tuple: The output data and slice. The first element of the tuple is the data read from the file. This may be None if the requested bounds are outside of the file. If a single band was requested this will be a 2 dimensional array, otherwise it will be 3 dimensional The second element of the tuple is a slice object that defines where in the output tile to write the data. If the size of the returned data array is smaller than (ysize, xsize) this will be the location in the tile to write the data. For situations where only part of the requested bounds is within the image.

class cibotiler.tiling.MarginsForResample(resampling, ovleft, ovtop, ovxsize, ovysize, band)#: handle the margin information. TODO: add this to resamplehelper.py

resamplehelper module#

Helper functions for doing resampling

cibotiler.resamplerhelper.replicateArray(arr, outsize, dspLeftExtra, dspTopExtra, dspRightExtra, dspBottomExtra, ignore)#

Replicate the data in the given 2-d array so that it increases in size to be outsize (ysize, xsize).

Replicates each pixel in both directions.

dspLeftExtra, dspTopExtra are the number of pixels to be shaved off the top and left. dspRightExtra, dspBottomExtra are the number of pixels to be shaved off the bottom and right of the result. This allows us to display fractional pixels.

Parameters:

arrnumpy.ndarray: 2 dimensional input data
outsizetuple of int: The output size (xsize, ysize)
dspLeftExtraint: number of pixels to be shaved off the left
dspTopExtraint: number of pixels to be shaved off the top
dspRightExtraint: number of pixels to be shaved off the right
dspBottomExtraint: number of pixels to be shaved off the bottom
ignore: float: ignore value for input - currently ignored

Returns:

numpy.ndarray

cibotiler.resamplerhelper.bilinearResample(arr, outsize, dspLeftExtra, dspTopExtra, dspRightExtra, dspBottomExtra, ignore)#

Use bilinear interpolation on the given 2-d array so that it increases in size to be outsize (ysize, xsize).

Parameters:

arrnumpy.ndarray: 2 dimensional input data
outsizetuple of int: The output size (xsize, ysize)
dspLeftExtraint: number of pixels to be shaved off the left
dspTopExtraint: number of pixels to be shaved off the top
dspRightExtraint: number of pixels to be shaved off the right
dspBottomExtraint: number of pixels to be shaved off the bottom
ignore: float: ignore value for input. Can be None.

Returns:

numpy.ndarray