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.

levels: int
name = 'gdal'
projection: str | bytes
projectionOrigin: Tuple[float, float]
sizeX: int
sizeY: int
sourceLevels: int
sourceSizeX: int
sourceSizeY: int
tileHeight: int
tileWidth: int
unitsAcrossLevel0: float

Module contents

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

Bases: GDALBaseFileTileSource

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.

classmethod addKnownExtensions()[source]
cacheName = 'tilesource'
property geospatial

This is true if the source has geospatial information.

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

Returns:

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

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.

dtype:

if known, the type of values in this image.

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<axis>:

optional if unique. A 0-based index for an arbitrary axis.

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

IndexStride:

a dictionary of the spacing between frames where unique axes values change.

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 not include band information, though some tile sources may do so.

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.

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.

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.

static isGeospatial(path)[source]

Check if a path is likely to be a geospatial file.

Parameters:

path – The path to the file

Returns:

True if geospatial.

levels: int
name = 'gdal'
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.

projection: str | bytes
projectionOrigin: Tuple[float, float]
sizeX: int
sizeY: int
sourceLevels: int
sourceSizeX: int
sourceSizeY: int
tileHeight: int
tileWidth: int
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 source’s projection.

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

Returns:

(x, y) the pixel coordinate.

unitsAcrossLevel0: float
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.open(*args, **kwargs)[source]

Create an instance of the module class.