API Reference

telluric.constants module

Useful constants.

telluric.constants.DEFAULT_CRS = CRS({'init': 'epsg:4326'})

Default CRS, set to WGS84_CRS.

telluric.constants.EQUAL_AREA_CRS = CRS({'proj': 'eck4'})

Eckert IV CRS.

telluric.constants.WEB_MERCATOR_CRS = CRS({'init': 'epsg:3857'})

Web Mercator CRS.

telluric.constants.WGS84_CRS = CRS({'init': 'epsg:4326'})

WGS84 CRS.

telluric.vectors module

class telluric.vectors.GeoVector(shape, crs=CRS({'init': 'epsg:4326'}))

Geometric element with an associated CRS.

This class has also all the properties and methods of shapely.geometry.BaseGeometry.

__init__(shape, crs=CRS({'init': 'epsg:4326'}))

Initialize GeoVector.

Parameters:
almost_equals(other, decimal=6)

invariant to crs.

equals_exact(other, tolerance)

invariant to crs.

classmethod from_bounds(*, xmin, ymin, xmax, ymax, crs=CRS({'init': 'epsg:4326'}))

Creates GeoVector object from bounds.

This function only accepts keyword arguments.

Parameters:

Examples

>>> from telluric import GeoVector
>>> GeoVector.from_bounds(xmin=0, ymin=0, xmax=1, ymax=1)
GeoVector(shape=POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0)), crs=CRS({'init': 'epsg:4326'}))
>>> GeoVector.from_bounds(xmin=0, xmax=1, ymin=0, ymax=1)
GeoVector(shape=POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0)), crs=CRS({'init': 'epsg:4326'}))
classmethod from_geojson(filename)

Load vector from geojson.

get_shape(crs)

Gets the underlying Shapely shape in a specified CRS.

This method deliberately does not have a default crs=self.crs to force the user to specify it.

polygonize(width, cap_style_line=2, cap_style_point=1)

Turns line or point into a buffered polygon.

to_geojson(filename)

Save vector as geojson.

telluric.vectors.generate_tile_coordinates(roi, num_tiles)

Yields N x M rectangular tiles for a region of interest.

Parameters:
  • roi (GeoVector) – Region of interest
  • num_tiles (tuple) – Tuple (horizontal_tiles, vertical_tiles)
Yields:

~telluric.vectors.GeoVector
telluric.vectors.generate_tile_coordinates_from_pixels(roi, scale, size)

Yields N x M rectangular tiles for a region of interest.

Parameters:
  • roi (GeoVector) – Region of interest
  • scale (float) – Scale factor (think of it as pixel resolution)
  • size (tuple) – Pixel size in (width, height) to be multiplied by the scale factor
Yields:

~telluric.vectors.GeoVector
telluric.vectors.get_dimension(geometry)

Gets the dimension of a Fiona-like geometry element.

telluric.features module

class telluric.features.GeoFeature(geovector, attributes)

GeoFeature object.

__init__(geovector, attributes)

Initialize a GeoFeature object.

Parameters:
  • geovector (GeoVector) – Geometry.
  • attributes (dict) – Properties.
get_shape(crs)

Gets the underlying Shapely shape in a specified CRS.

telluric.collections module

class telluric.collections.BaseCollection
filter(intersects)

Filter results that intersect a given GeoFeature or Vector.

is_empty

True if all features are empty.

map(map_function)

Return a new FeatureCollection with the results of applying map_function to each element.

rasterize(dest_resolution, polygonize_width=0, crs=CRS({'init': 'epsg:3857'}), fill_value=None, nodata_value=None, bounds=None, **polygonize_kwargs)

Binarize a FeatureCollection and produce a raster with the target resolution.

Parameters:
  • dest_resolution (float) – Resolution in units of the CRS.
  • polygonize_width (float, optional) – Width for the polygonized features (lines and points) in pixels, default to 0 (they won’t appear).
  • crs (CRS, dict (optional)) – Coordinate system, default to telluric.constants.WEB_MERCATOR_CRS.
  • fill_value (float, optional) – Value that represents data, default to None (will default to telluric.rasterization.FILL_VALUE.
  • nodata_value (float, optional) – Nodata value, default to None (will default to telluric.rasterization.NODATA_VALUE.
  • bounds (GeoVector, optional) – Optional bounds for the target image, default to None (will use the FeatureCollection convex hull).
  • polygonize_kwargs (dict) – Extra parameters to the polygonize function.
save(filename, driver=None)

Saves collection to file.

class telluric.collections.FeatureCollection(results)
__init__(results)

Initialize FeatureCollection object.

Parameters:results (list) – List of GeoFeature objects.
classmethod from_geovectors(geovectors)

Builds new FeatureCollection from a sequence of GeoVector objects.

exception telluric.collections.FeatureCollectionIOError
class telluric.collections.FileCollection(filename, crs, schema, length)

FileCollection object.

__init__(filename, crs, schema, length)

Initialize a FileCollection object.

Use the open() method instead.

classmethod open(filename)

Creates a FileCollection from a file in disk.

Parameters:filename (str) – Path of the file to read.

telluric.georaster module

class telluric.georaster.GeoRaster2(image=None, affine=None, crs=None, filename=None, band_names=None, nodata=0, shape=None)

Represents multiband georeferenced image, supporting nodata pixels. The name “GeoRaster2” is temporary.

conventions:

  • .array is np.masked_array, mask=True on nodata pixels.
  • .array is [band, y, x]
  • .affine is affine.Affine
  • .crs is rasterio.crs.CRS
  • .band_names is list of strings, order corresponding to order in .array
__init__(image=None, affine=None, crs=None, filename=None, band_names=None, nodata=0, shape=None)

Create a GeoRaster object

Parameters:
  • filename – optional path/url to raster file for lazy loading
  • image – optional supported: np.ma.array, np.array, TODO: PIL image
  • affine – affine.Affine, or 9 numbers: [step_x, 0, origin_x, 0, step_y, origin_y, 0, 0, 1]
  • crs – wkt/epsg code, e.g. {‘init’: ‘epsg:32620’}
  • band_names – e.g. [‘red’, ‘blue’] or ‘red’
  • shape – raster image shape, optional
  • nodata – if provided image is array (not masked array), treat pixels with value=nodata as nodata
add_raster(other, merge_strategy, resampling)

Return merge of 2 rasters, in geography of the first one.

merge_strategy - for pixels with values in both rasters.

affine

Raster affine.

align_raster_to_mercator_tiles()

Return new raster aligned to compasing tile.

Returns:GeoRaster2
apply_transform(transformation, resampling)

Apply affine transformation on image & georeferencing.

as specific cases, implement ‘resize’, ‘rotate’, ‘translate’

astype(dst_type, stretch=False)

Returns copy of the raster, converted to desired type Supported types: uint8, uint16, uint32, int8, int16, int32 For integer types, pixel values are within min/max range of the type.

attributes(url)

Without opening image, return size/bitness/bands/geography/….

band_names

Raster affine.

bounds()

Return image rectangle in pixels, as shapely.Polygon.

center()

Return footprint center in world coordinates, as GeoVector.

copy_with(**kwargs)

Get a copy of this GeoRaster with some attributes changed. NOTE: image is shallow-copied!

corner(corner)

Return footprint origin in world coordinates, as GeoVector.

corners()

Return footprint corners, as {corner_type -> GeoVector}.

crop(vector, resolution=None)

crops raster outside vector (convex hull) :param vector: GeoVector :param output resolution in m/pixel, None for full resolution :return: GeoRaster

crs

Raster crs.

deepcopy_with(**kwargs)

Get a copy of this GeoRaster with some attributes changed.

footprint()

Return rectangle in world coordinates, as GeoVector.

classmethod from_bytes(image_bytes, affine, crs, band_names=None)

Create GeoRaster from image BytesIo object.

Parameters:
  • image_bytes – io.BytesIO object
  • affine – rasters affine
  • crs – rasters crs
  • band_names – e.g. [‘red’, ‘blue’] or ‘red’
classmethod from_tiles(tiles)

Compose raster from tiles. return GeoRaster.

get(point)

Get the pixel values at the requested point.

Parameters:point – A GeoVector(POINT) with the coordinates of the values to get
Returns:numpy array of values
get_tile(x_tile, y_tile, zoom, bands=None, blocksize=256, resampling=<Resampling.cubic: 2>)

convert mercator tile to raster window.

Parameters:
  • x_tile – x coordinate of tile
  • y_tile – y coordinate of tile
  • zoom – zoom level
  • bands – list of indices of requested bads, default None which returns all bands
  • blocksize – tile size (x & y) default 256, for full resolution pass None
  • resampling – which Resampling to use on reading, default Resampling.cubic
Returns:

GeoRaster2 of tile
get_window(window, bands=None, xsize=None, ysize=None, resampling=<Resampling.cubic: 2>, masked=True, boundless=False)

Get window from raster.

Parameters:
  • window – requested window
  • bands – list of indices of requested bads, default None which returns all bands
  • xsize – tile x size default None, for full resolution pass None
  • ysize – tile y size default None, for full resolution pass None
  • resampling – which Resampling to use on reading, default Resampling.cubic
  • masked – boolean, if True the return value will be a masked array. Default is True
Returns:

GeoRaster2 of tile
height

Raster height.

image

Raster bitmap in numpy array.

image_corner(corner)

Return image corner in pixels, as shapely.Point.

intersect(other)

Pixels outside either raster are set nodata

is_aligned_to_mercator_tiles()

Return True if image aligned to coordinates tiles.

mask(vector, mask_shape_nodata=False)

Set pixels outside vector as nodata.

Parameters:
  • vector – GeoVector, GeoFeature, FeatureCollection
  • mask_shape_nodata – if True - pixels inside shape are set nodata, if False - outside shape is nodata
Returns:

GeoRaster2
num_bands

Raster number of bands.

classmethod open(filename, band_names=None, lazy_load=True, **kwargs)

Read a georaster from a file.

Parameters:
  • filename – url
  • band_names – list of strings, or string. if None - will try to read from image, otherwise - these will be [‘0’, ..]
  • lazy_load – if True - do not load anything
Returns:

GeoRaster2
origin()

Return footprint origin in world coordinates, as GeoVector.

pixel_crop(bounds, xsize=None, ysize=None, window=None)

Crop raster outside vector (convex hull).

Parameters:
  • bounds – bounds of requester portion of the image in image pixels
  • xsize – output raster width, None for full resolution
  • ysize – output raster height, None for full resolution
  • windows – the bounds representation window on image in image pixels, optional
Returns:

GeoRaster
project(dst_crs, resampling)

Return reprojected raster.

rectify()

Rotate raster northwards.

reduce(op)

Reduce the raster to a score, using ‘op’ operation.

nodata pixels are ignored. op is currently limited to numpy.ma, e.g. ‘mean’, ‘std’ etc :returns list of per-band values

reproject(new_width, new_height, dest_affine, dtype=None, dst_crs=None, resampling=<Resampling.cubic: 2>)

Return re-projected raster to new raster.

Parameters:
  • new_width – new raster width in pixels
  • new_height – new raster height in pixels
  • dest_affine – new raster affine
  • dtype – new raster dtype, default current dtype
  • dst_crs – new raster crs, default current crs
  • resampling – reprojection resampling method, default cubic

:return GeoRaster2

resize(ratio=None, ratio_x=None, ratio_y=None, dest_width=None, dest_height=None, dest_resolution=None, resampling=<Resampling.cubic: 2>)

Provide either ratio, or ratio_x and ratio_y, or dest_width and/or dest_height.

Returns:GeoRaster2
resolution()

Return resolution. if different in different axis - return average.

save(filename, tags=None, **kwargs)

Save GeoRaster to a file.

Parameters:
  • filename – url
  • tags – tags to add to default namespace

optional parameters:

  • GDAL_TIFF_INTERNAL_MASK: specifies whether mask is within image file, or additional .msk
  • overviews: if True, will save with previews. default: True
  • factors: list of factors for the overview, default: [2, 4, 8, 16, 32, 64, 128]
  • resampling: to build overviews. default: cubic
  • tiled: if True raster will be saved tiled, default: False
  • compress: any supported rasterio.enums.Compression value, default to LZW
  • blockxsize: int, tile x size, default:256
  • blockysize: int, tile y size, default:256
  • creation_options: dict, key value of additional creation options
  • nodata: if passed, will save with nodata value (e.g. useful for qgis)
save_cloud_optimized(dest_url, blockxsize=256, blockysize=256, aligned_to_mercator=False, resampling=<Resampling.cubic: 2>, compress='DEFLATE')

Save as Cloud Optimized GeoTiff object to a new file.

Parameters:
  • dest_url – path to the new raster
  • blockxsize – tile x size default 256
  • blockysize – tile y size default 256
  • aligned_to_mercator – if True raster will be aligned to mercator tiles, default False
  • compress – compression method, default DEFLATE
Returns:

new VirtualGeoRaster of the tiled object
shape

Raster shape.

classmethod tags(filename, namespace=None)

Extract tags from file.

to_bytes(transparent=True, thumbnail_size=None, resampling=None, stretch=False, format='png')

Convert to selected format (discarding geo).

Optionally also resizes. Note: for color images returns interlaced. :param transparent: if True - sets alpha channel for nodata pixels :param thumbnail_size: if not None - resize to thumbnail size, e.g. 512 :param stretch: if true the if convert to uint8 is required it would stretch :param format : str, image format, default “png” :param resampling: one of Resampling enums

:return bytes

to_pillow_image(return_mask=False)

Return Pillow. Image, and optionally also mask.

to_png(transparent=True, thumbnail_size=None, resampling=None, stretch=False)

Convert to png format (discarding geo).

Optionally also resizes. Note: for color images returns interlaced. :param transparent: if True - sets alpha channel for nodata pixels :param thumbnail_size: if not None - resize to thumbnail size, e.g. 512 :param stretch: if true the if convert to uint8 is required it would stretch :param resampling: one of Resampling enums

:return bytes

to_raster(vector)

Return the vector in pixel coordinates, as shapely.Geometry.

to_tiles()

Yield slippy-map tiles.

to_world(shape, dst_crs=None)

Return the shape (provided in pixel coordinates) in world coordinates, as GeoVector.

transform

Raster affine.

vectorize(condition=None)

Return GeoVector of raster, excluding nodata pixels, subject to ‘condition’.

Parameters:condition – e.g. 42 < value < 142.

e.g. if no nodata pixels, and without condition - this == footprint().

width

Raster width.

exception telluric.georaster.GeoRaster2Error

Base class for exceptions in the GeoRaster class.

exception telluric.georaster.GeoRaster2IOError

Base class for exceptions in GeoRaster read/write.

exception telluric.georaster.GeoRaster2NotImplementedError

Base class for NotImplementedError in the GeoRaster class.

exception telluric.georaster.GeoRaster2Warning

Base class for warnings in the GeoRaster class.

class telluric.georaster.MergeStrategy

An enumeration.

telluric.georaster.merge(one, other, merge_strategy=<MergeStrategy.UNION: 2>)

Merge two rasters into one.

Parameters:
Returns:
Return type:

GeoRaster2
telluric.georaster.merge_all(rasters, roi, dest_resolution=None, merge_strategy=<MergeStrategy.UNION: 2>)

Merge a list of rasters, cropping by a region of interest.

telluric.plotting module

Code for interactive vector plots.

telluric.plotting.layer_from_element(element, style_function=None)

Return Leaflet layer from shape.

Parameters:element (telluric.vectors.GeoVector, telluric.features.GeoFeature, telluric.collections.BaseCollection) – Data to plot.
telluric.plotting.plot(feature, mp=None, style_function=None, **map_kwargs)

Plots a GeoVector in an ipyleaflet map.

Parameters:
  • feature (Any object with __geo_interface__) – Data to plot.
  • mp (ipyleaflet.Map, optional) – Map in which to plot, default to None (creates a new one).
  • style_function (func) – Function that returns an style dictionary for
  • map_kwargs (kwargs, optional) – Extra parameters to send to folium.Map.
telluric.plotting.simple_plot(feature, *, mp=None, **map_kwargs)

Plots a GeoVector in a simple Folium map.

For more complex and customizable plots using Jupyter widgets, use the plot function instead.

Parameters:feature (Any object with __geo_interface__) – Data to plot.
telluric.plotting.zoom_level_from_geometry(geometry, splits=4)

Generate optimum zoom level for geometry.

Notes

The obvious solution would be

>>> mercantile.bounding_tile(*geometry.get_shape(WGS84_CRS).bounds).z

However, if the geometry is split between two or four tiles, the resulting zoom level might be too big.