large_image_source_gdal package

Submodules

large_image_source_gdal.girder_source module

class large_image_source_gdal.girder_source.GDALGirderTileSource(*args, **kwargs)[source]

Bases: GDALFileTileSource, GirderTileSource

Provides tile access to Girder items for gdal layers.

Initialize the tile class. See the base class for other available parameters.

Parameters
  • path – a filesystem path for the tile source.

  • projection – None to use pixel space, otherwise a proj4 projection string or a case-insensitive string of the form ‘EPSG:<epsg number>’. If a string and case-insensitively prefixed with ‘proj4:’, that prefix is removed. For instance, ‘proj4:EPSG:3857’, ‘PROJ4:+init=epsg:3857’, and ‘+init=epsg:3857’, and ‘EPSG:3857’ are all equivalent.

  • unitsPerPixel – The size of a pixel at the 0 tile size. Ignored if the projection is None. For projections, None uses the default, which is the distance between (-180,0) and (180,0) in EPSG:4326 converted to the projection divided by the tile size. Proj4 projections that are not latlong (is_geographic is False) must specify unitsPerPixel.

cacheName = 'tilesource'
static getLRUHash(*args, **kwargs)[source]

Return a string hash used as a key in the recently-used cache for tile sources.

Returns

a string hash value.

name = 'gdal'

Name of the tile source

Module contents

class large_image_source_gdal.GDALFileTileSource(*args, **kwargs)[source]

Bases: FileTileSource

Provides tile access to geospatial files.

Initialize the tile class. See the base class for other available parameters.

Parameters
  • path – a filesystem path for the tile source.

  • projection – None to use pixel space, otherwise a proj4 projection string or a case-insensitive string of the form ‘EPSG:<epsg number>’. If a string and case-insensitively prefixed with ‘proj4:’, that prefix is removed. For instance, ‘proj4:EPSG:3857’, ‘PROJ4:+init=epsg:3857’, and ‘+init=epsg:3857’, and ‘EPSG:3857’ are all equivalent.

  • unitsPerPixel – The size of a pixel at the 0 tile size. Ignored if the projection is None. For projections, None uses the default, which is the distance between (-180,0) and (180,0) in EPSG:4326 converted to the projection divided by the tile size. Proj4 projections that are not latlong (is_geographic is False) must specify unitsPerPixel.

cacheName = 'tilesource'
extensions = {None: 4, 'geotiff': 1, 'ntf': 1, 'nitf': 1, 'tif': 5, 'tiff': 5, 'vrt': 1}

A dictionary of known file extensions and the SourcePriority given to each. It must contain a None key with a priority for the tile source when the extension does not match.

geospatial = True
getBandInformation(statistics=True, dataset=None, **kwargs)[source]

Get information about each band in the image.

Parameters
  • statistics – if True, compute statistics if they don’t already exist. Ignored: always treated as True.

  • dataset – the dataset. If None, use the main dataset.

Returns

a list of one dictionary per band. Each dictionary contains known values such as interpretation, min, max, mean, stdev, nodata, scale, offset, units, categories, colortable, maskband.

getBounds(srs=None)[source]

Returns bounds of the image.

Parameters

srs – the projection for the bounds. None for the default.

Returns

an object with the four corners and the projection that was used. None if we don’t know the original projection.

static getHexColors(palette)[source]

Returns list of hex colors for a given color palette

Returns

List of colors

getInternalMetadata(**kwargs)[source]

Return additional known metadata about the tile source. Data returned from this method is not guaranteed to be in any particular format or have specific values.

Returns

a dictionary of data or None.

static getLRUHash(*args, **kwargs)[source]

Return a string hash used as a key in the recently-used cache for tile sources.

Returns

a string hash value.

getMetadata()[source]

Return metadata about this tile source. This contains

levels

number of tile levels in this image.

sizeX

width of the image in pixels.

sizeY

height of the image in pixels.

tileWidth

width of a tile in pixels.

tileHeight

height of a tile in pixels.

magnification

if known, the magnificaiton of the image.

mm_x

if known, the width of a pixel in millimeters.

mm_y

if known, the height of a pixel in millimeters.

In addition to the keys that listed above, tile sources that expose multiple frames will also contain

frames

a list of frames. Each frame entry is a dictionary with

Frame

a 0-values frame index (the location in the list)

Channel

optional. The name of the channel, if known

IndexC

optional if unique. A 0-based index into the channel list

IndexT

optional if unique. A 0-based index for time values

IndexZ

optional if unique. A 0-based index for z values

IndexXY

optional if unique. A 0-based index for view (xy) values

Index

a 0-based index of non-channel unique sets. If the frames vary only by channel and are adjacent, they will have the same index.

IndexRange

a dictionary of the number of unique index values from frames if greater than 1 (e.g., if an entry like IndexXY is not present, then all frames either do not have that value or have a value of 0).

channels

optional. If known, a list of channel names

channelmap

optional. If known, a dictionary of channel names with their offset into the channel list.

Note that this does nto include band information, though some tile sources may do so.

getNativeMagnification()[source]

Get the magnification at the base level.

Returns

width of a pixel in mm, height of a pixel in mm.

getPixel(**kwargs)[source]

Get a single pixel from the current tile source.

Parameters

kwargs – optional arguments. Some options are region, output, encoding, jpegQuality, jpegSubsampling, tiffCompression, fill. See tileIterator.

Returns

a dictionary with the value of the pixel for each channel on a scale of [0-255], including alpha, if available. This may contain additional information.

getPixelSizeInMeters()[source]

Get the approximate base pixel size in meters. This is calculated as the average scale of the four edges in the WGS84 ellipsoid.

Returns

the pixel size in meters or None.

getProj4String()[source]

Returns proj4 string for the given dataset

Returns

The proj4 string or None.

getRegion(format=('image',), **kwargs)[source]

Get a rectangular region from the current tile source. Aspect ratio is preserved. If neither width nor height is given, the original size of the highest resolution level is used. If both are given, the returned image will be no larger than either size.

Parameters
  • format – the desired format or a tuple of allowed formats. Formats are members of (TILE_FORMAT_PIL, TILE_FORMAT_NUMPY, TILE_FORMAT_IMAGE). If TILE_FORMAT_IMAGE, encoding may be specified.

  • kwargs – optional arguments. Some options are region, output, encoding, jpegQuality, jpegSubsampling, tiffCompression, fill. See tileIterator.

Returns

regionData, formatOrRegionMime: the image data and either the mime type, if the format is TILE_FORMAT_IMAGE, or the format.

getState()[source]

Return a string reflecting the state of the tile source. This is used as part of a cache key when hashing function return values.

Returns

a string hash value of the source state.

getThumbnail(width=None, height=None, **kwargs)[source]

Get a basic thumbnail from the current tile source. Aspect ratio is preserved. If neither width nor height is given, a default value is used. If both are given, the thumbnail will be no larger than either size. A thumbnail has the same options as a region except that it always includes the entire image if there is no projection and has a default size of 256 x 256.

Parameters
  • width – maximum width in pixels.

  • height – maximum height in pixels.

  • kwargs – optional arguments. Some options are encoding, jpegQuality, jpegSubsampling, and tiffCompression.

Returns

thumbData, thumbMime: the image data and the mime type.

getTile(x, y, z, pilImageAllowed=False, numpyAllowed=False, **kwargs)[source]

Get a tile from a tile source, returning it as an binary image, a PIL image, or a numpy array.

Parameters
  • x – the 0-based x position of the tile on the specified z level. 0 is left.

  • y – the 0-based y position of the tile on the specified z level. 0 is top.

  • z – the z level of the tile. May range from [0, self.levels], where 0 is the lowest resolution, single tile for the whole source.

  • pilImageAllowed – True if a PIL image may be returned.

  • numpyAllowed – True if a numpy image may be returned. ‘always’ to return a numpy array.

  • sparseFallback – if False and a tile doesn’t exist, raise an error. If True, check if a lower resolution tile exists, and, if so, interpolate the needed data for this tile.

  • frame – the frame number within the tile source. None is the same as 0 for multi-frame sources.

Returns

either a numpy array, a PIL image, or a memory object with an image file.

getTileCorners(z, x, y)[source]

Returns bounds of a tile for a given x,y,z index.

Parameters
  • z – tile level

  • x – tile offset from left.

  • y – tile offset from right

Returns

(xmin, ymin, xmax, ymax) in the current projection or base pixels.

mimeTypes = {None: 8, 'image/geotiff': 1, 'image/tiff': 5, 'image/x-tiff': 5}

A dictionary of common mime-types handled by the source and the SourcePriority given to each. This are used in place of or in additional to extensions.

name = 'gdalfile'

Name of the tile source

pixelToProjection(x, y, level=None)[source]

Convert from pixels back to projection coordinates.

Parameters
  • y (x,) – base pixel coordinates.

  • level – the level of the pixel. None for maximum level.

Returns

x, y in projection coordinates.

toNativePixelCoordinates(x, y, proj=None, roundResults=True)[source]

Convert a coordinate in the native projection (self.getProj4String) to pixel coordinates.

Parameters
  • x – the x coordinate it the native projection.

  • y – the y coordinate it the native projection.

  • proj – input projection. None to use the sources’s projection.

  • roundResults – if True, round the results to the nearest pixel.

Returns

(x, y) the pixel coordinate.

validateCOG(check_tiled=True, full_check=False, strict=True, warn=True)[source]

Check if this image is a valid Cloud Optimized GeoTiff.

This will raise a large_image.exceptions.TileSourceInefficientError if not a valid Cloud Optimized GeoTiff. Otherwise, returns True.

Requires the osgeo_utils package.

Parameters
  • check_tiled (bool) – Set to False to ignore missing tiling.

  • full_check (bool) – Set to True to check tile/strip leader/trailer bytes. Might be slow on remote files

  • strict (bool) – Enforce warnings as exceptions. Set to False to only warn and not raise exceptions.

  • warn (bool) – Log any warnings

large_image_source_gdal.canRead(*args, **kwargs)[source]

Check if an input can be read by the module class.

large_image_source_gdal.make_vsi(url: str, **options)[source]
large_image_source_gdal.open(*args, **kwargs)[source]

Create an instance of the module class.