solaris.tile API reference

solaris.tile.raster_tile Raster image tiling functionality

class solaris.tile.raster_tile.RasterTiler(dest_dir=None, dest_crs=None, project_to_meters=False, channel_idxs=None, src_tile_size=(900, 900), use_src_metric_size=False, dest_tile_size=None, dest_metric_size=False, aoi_boundary=None, nodata=None, alpha=None, force_load_cog=False, resampling=None, tile_bounds=None, verbose=False)[source]

An object to tile geospatial image strips into smaller pieces.

Parameters
  • dest_dir (str, optional) – Path to save output files to. If not specified here, this must be provided when Tiler.tile_generator() is called.

  • src_tile_size (tuple of `int`s, optional) – The size of the input tiles in (y, x) coordinates. By default, this is in pixel units; this can be changed to metric units using the use_src_metric_size argument.

  • use_src_metric_size (bool, optional) – Is src_tile_size in pixel units (default) or metric? To set to metric use use_src_metric_size=True.

  • dest_tile_size (tuple of `int`s, optional) – The size of the output tiles in (y, x) coordinates in pixel units.

  • dest_crs (int, optional) – The EPSG code or rasterio.crs.CRS object for the CRS that output tiles are in. If not provided, tiles use the crs of src by default. Cannot be specified along with project_to_meters.

  • project_to_meters (bool, optional) – Specifies whether to project to the correct utm zone for the location. Cannot be specified along with dest_crs.

  • nodata (int, optional) – The value in src that specifies nodata. If this value is not provided, solaris will attempt to infer the nodata value from the src metadata.

  • alpha (int, optional) – The band to specify as alpha. If not provided, solaris will attempt to infer if an alpha band is present from the src metadata.

  • force_load_cog (bool, optional) – If src is a cloud-optimized geotiff, use this argument to force loading in the entire image at once.

  • aoi_boundary (shapely.geometry.Polygon or list-like [left, bottom, right, top]) – Defines the bounds of the AOI in which tiles will be created. If a tile will extend beyond the boundary, the “extra” pixels will have the value nodata. Can be provided at initialization of the Tiler instance or when the input is loaded. If not provided either upon initialization or when an image is loaded, the image bounds will be used; if provided, this value will override image metadata.

  • tile_bounds (list-like) – A list-like of [left, bottom, right, top] lists of coordinates defining the boundaries of the tiles to create. If not provided, they will be generated from the aoi_boundary based on src_tile_size.

  • verbose (bool, optional) – Verbose text output. By default, verbose text is not printed.

src

The source dataset to tile.

Type

rasterio.io.DatasetReader

src_path

The path or URL to the source dataset. Used for calling rio_cogeo.cogeo.cog_validate().

Type

str

dest_dir

The directory to save the output tiles to. If not

Type

str

dest_crs

The EPSG code for the output images. If not provided, outputs will keep the same CRS as the source image when Tiler.make_tile_images() is called.

Type

int

tile_size

A (y, x) tuple storing the dimensions of the output. These are in pixel units unless size_in_meters=True.

Type

tuple

size_in_meters

If True, the units of tile_size are in meters instead of pixels.

Type

bool

is_cog

Indicates whether or not the image being tiled is a Cloud-Optimized GeoTIFF (COG). Determined by checking COG validity using rio-cogeo.

Type

bool

nodata

The value for nodata in the outputs. Will be set to zero in outputs if None.

Type

int

alpha

The band index corresponding to an alpha channel (if one exists). None if there is no alpha channel.

Type

int

tile_bounds

A list containing [left, bottom, right, top] bounds sublists for each tile created.

Type

list

resampling

The resampling method for any resizing. Possible values are ['bilinear', 'cubic', 'nearest', 'lanczos', 'average'] (or any other option from rasterio.warp.Resampling).

Type

str

aoi_boundary

A shapely.geometry.Polygon defining the bounds of the AOI that tiles will be created for. If a tile will extend beyond the boundary, the “extra” pixels will have the value nodata. Can be provided at initialization of the Tiler instance or when the input is loaded.

Type

shapely.geometry.Polygon

fill_all_nodata(nodata_fill)[source]

Fills all tile nodata values with a fill value.

The standard workflow is to run this function only after generating label masks and using the original output from the raster tiler to filter out label pixels that overlap nodata pixels in a tile. For example, solaris.vector.mask.instance_mask will filter out nodata pixels from a label mask if a reference_im is provided, and after this step nodata pixels may be filled by calling this method.

nodata_fillint, float, or str, optional

Default is to not fill any nodata values. Otherwise, pixels outside of the aoi_boundary and pixels inside the aoi_boundary with the nodata value will be filled. “mean” will fill pixels with the channel-wise mean. Providing an int or float will fill pixels in all channels with the provided value.

Returns: list

The fill values, in case the mean of the src image should be used for normalization later.

get_tile_bounds()[source]

Get tile bounds for each tile to be created in the input CRS.

load_src_vrt()[source]

Load a source dataset’s VRT into the destination CRS.

save_tile(tile_data, mask, profile, dest_fname_base=None)[source]

Save a tile created by Tiler.tile_generator().

tile(src, dest_dir=None, channel_idxs=None, nodata=None, alpha=None, restrict_to_aoi=False, dest_fname_base=None, nodata_threshold=None)[source]

An object to tile geospatial image strips into smaller pieces.

Parameters
  • src (rasterio.io.DatasetReader or str) – The source dataset to tile.

  • nodata_threshold (float, optional) – Nodata percentages greater than this threshold will not be saved as tiles.

  • restrict_to_aoi (bool, optional) – Requires aoi_boundary. Sets all pixel values outside the aoi_boundary to the nodata value of the src image.

tile_generator(src, dest_dir=None, channel_idxs=None, nodata=None, alpha=None, aoi_boundary=None, restrict_to_aoi=False)[source]

Create the tiled output imagery from input tiles.

Uses the arguments provided at initialization to generate output tiles. First, tile locations are generated based on Tiler.tile_size and Tiler.size_in_meters given the bounds of the input image.

Parameters
  • src (str or Rasterio.DatasetReader) – The source data to tile from. If this is a “classic” (non-cloud-optimized) GeoTIFF, the whole image will be loaded in; if it’s cloud-optimized, only the required portions will be loaded during tiling unless force_load_cog=True was specified upon initialization.

  • dest_dir (str, optional) – The path to the destination directory to output images to. If the path doesn’t exist, it will be created. This argument is required if it wasn’t provided during initialization.

  • channel_idxs (list, optional) – The list of channel indices to be included in the output array. If not provided, all channels will be included. Note: per rasterio convention, indexing starts at 1, not 0.

  • nodata (int, optional) – The value in src that specifies nodata. If this value is not provided, solaris will attempt to infer the nodata value from the src metadata.

  • alpha (int, optional) – The band to specify as alpha. If not provided, solaris will attempt to infer if an alpha band is present from the src metadata.

  • aoi_boundary (list-like or shapely.geometry.Polygon, optional) – AOI bounds can be provided either as a [left, bottom, right, top] list-like or as a shapely.geometry.Polygon.

  • restrict_to_aoi (bool, optional) – Should output tiles be restricted to the limits of the AOI? If True, any tile that partially extends beyond the limits of the AOI will not be returned. This is the inverse of the boundless argument for rasterio.io.DatasetReader ‘s .read() method.

Yields

tile_data, mask, tile_bounds – tile_data : numpy.ndarray A list of lists of each tile’s bounds in the order they were created, to be used in tiling vector data. These data are also stored as an attribute of the Tiler instance named tile_bounds.

solaris.tile.vector_tile Vector tiling functionality

class solaris.tile.vector_tile.VectorTiler(dest_dir=None, dest_crs=None, output_format='GeoJSON', verbose=False, super_verbose=False)[source]

An object to tile geospatial vector data into smaller pieces.

tile(src, tile_bounds, tile_bounds_crs=None, geom_type='Polygon', split_multi_geoms=True, min_partial_perc=0.0, dest_fname_base='geoms', obj_id_col=None, output_ext='.geojson')[source]

Tile src into vector data tiles bounded by tile_bounds.

Parameters
  • src (str or geopandas.GeoDataFrame) – The source vector data to tile. Must either be a path to a GeoJSON or a geopandas.GeoDataFrame.

  • tile_bounds (list) – A list made up of ``[left, top, right, bottom] `` sublists (this can be extracted from solaris.tile.raster_tile.RasterTiler after tiling imagery)

  • tile_bounds_crs (int, optional) – The EPSG code or rasterio.crs.CRS object for the CRS that the tile bounds are in. RasterTiler.tile returns the CRS of the raster tiles and can be used here. If not provided, it’s assumed that the CRS is the same as in src. This argument must be provided if the bound coordinates and src are not in the same CRS, otherwise tiling will not occur correctly.

  • geom_type (str, optional (default: "Polygon")) – The type of geometries contained within src. Defaults to "Polygon", can also be "LineString".

  • split_multi_geoms (bool, optional (default: True)) – Should multi-polygons or multi-linestrings generated by clipping a geometry into discontinuous pieces be separated? Defaults to yes (True).

  • min_partial_perc (float, optional (default: 0.0)) – The minimum percentage of a shapely.geometry.Polygon ‘s area or shapely.geometry.LineString ‘s length that must be retained within a tile’s bounds to be included in the output. Defaults to 0.0, meaning that the contained portion of a clipped geometry will be included, no matter how small.

  • dest_fname_base (str, optional (default: 'geoms')) – The base filename to use when creating outputs. The lower left corner coordinates of the tile’s bounding box will be appended when saving.

  • obj_id_col (str, optional (default: None)) – If split_multi_geoms=True, the name of a column that specifies a unique identifier for each geometry (e.g. the "BuildingId" column in many SpaceNet datasets.) See solaris.utils.geo.split_multi_geometries() for more.

  • output_ext (str, optional, (default: geojson)) – Extension of output files, can be ‘geojson’ or ‘json’.

tile_generator(src, tile_bounds, tile_bounds_crs=None, geom_type='Polygon', split_multi_geoms=True, min_partial_perc=0.0, obj_id_col=None)[source]

Generate src vector data tiles bounded by tile_bounds.

Parameters
  • src (str or geopandas.GeoDataFrame) – The source vector data to tile. Must either be a path to a GeoJSON or a geopandas.GeoDataFrame.

  • tile_bounds (list) – A list made up of ``[left, top, right, bottom] `` sublists (this can be extracted from solaris.tile.raster_tile.RasterTiler after tiling imagery)

  • tile_bounds_crs (int, optional) – The EPSG code for the CRS that the tile bounds are in. If not provided, it’s assumed that the CRS is the same as in src. This argument must be provided if the bound coordinates and src are not in the same CRS, otherwise tiling will not occur correctly.

  • geom_type (str, optional (default: "Polygon")) – The type of geometries contained within src. Defaults to "Polygon", can also be "LineString".

  • split_multi_geoms (bool, optional (default: True)) – Should multi-polygons or multi-linestrings generated by clipping a geometry into discontinuous pieces be separated? Defaults to yes (True).

  • min_partial_perc (float, optional (default: 0.0)) – The minimum percentage of a shapely.geometry.Polygon ‘s area or shapely.geometry.LineString ‘s length that must be retained within a tile’s bounds to be included in the output. Defaults to 0.0, meaning that the contained portion of a clipped geometry will be included, no matter how small.

  • obj_id_col (str, optional (default: None)) – If split_multi_geoms=True, the name of a column that specifies a unique identifier for each geometry (e.g. the "BuildingId" column in many SpaceNet datasets.) See solaris.utils.geo.split_multi_geometries() for more.

Yields
  • tile_gdf (geopandas.GeoDataFrame) – A tile geodataframe.

  • tb (list) – A list with ``[left, top, right, bottom] `` coordinates for the boundaries contained by tile_gdf.

solaris.tile.vector_tile.clip_gdf(gdf, tile_bounds, min_partial_perc=0.0, geom_type='Polygon', use_sindex=True, verbose=False)[source]

Clip GDF to a provided polygon.

Clips objects within gdf to the region defined by poly_to_cut. Also adds several columns to the output:

`origarea`
    The original area of the polygons (only used if `geom_type` ==
    ``"Polygon"``).
`origlen`
    The original length of the objects (only used if `geom_type` ==
    ``"LineString"``).
`partialDec`
    The fraction of the object that remains after clipping
    (fraction of area for Polygons, fraction of length for
    LineStrings.) Can filter based on this by using `min_partial_perc`.
`truncated`
    Boolean indicator of whether or not an object was clipped.
Parameters
  • gdf (geopandas.GeoDataFrame) – A geopandas.GeoDataFrame of polygons to clip.

  • tile_bounds (list or shapely.geometry.Polygon) – The geometry to clip objects in gdf to. This can either be a ``[left, top, right, bottom] `` bounds list or a shapely.geometry.Polygon object defining the area to keep.

  • min_partial_perc (float, optional) – The minimum fraction of an object in gdf that must be preserved. Defaults to 0.0 (include any object if any part remains following clipping).

  • geom_type (str, optional) – Type of objects in gdf. Can be one of ["Polygon", "LineString"] . Defaults to "Polygon" .

  • use_sindex (bool, optional) – Use the gdf sindex be used for searching. Improves efficiency but requires libspatialindex .

  • verbose (bool, optional) – Switch to print relevant values.

Returns

cut_gdfgdf with all contained objects clipped to poly_to_cut . See notes above for details on additional clipping columns added.

Return type

geopandas.GeoDataFrame

solaris.tile.vector_tile.search_gdf_polygon(gdf, tile_polygon)[source]

Find polygons in a GeoDataFrame that overlap with tile_polygon .

Parameters
Returns

precise_matches – The subset of gdf that overlaps with tile_polygon . If there are no overlaps, this will return an empty geopandas.GeoDataFrame.

Return type

geopandas.GeoDataFrame