solaris.tile
API reference¶
Contents
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 theTiler
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.
-
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
-
tile_size
¶ A
(y, x)
tuple
storing the dimensions of the output. These are in pixel units unlesssize_in_meters=True
.- Type
-
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
-
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
-
resampling
¶ The resampling method for any resizing. Possible values are
['bilinear', 'cubic', 'nearest', 'lanczos', 'average']
(or any other option fromrasterio.warp.Resampling
).- Type
-
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 theTiler
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.
-
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 unlessforce_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 at1
, not0
.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 ashapely.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 theboundless
argument forrasterio.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 theTiler
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 ageopandas.GeoDataFrame
.tile_bounds (list) – A
list
made up of ``[left, top, right, bottom] `` sublists (this can be extracted fromsolaris.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 orshapely.geometry.LineString
‘s length that must be retained within a tile’s bounds to be included in the output. Defaults to0.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.) Seesolaris.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 ageopandas.GeoDataFrame
.tile_bounds (list) – A
list
made up of ``[left, top, right, bottom] `` sublists (this can be extracted fromsolaris.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 orshapely.geometry.LineString
‘s length that must be retained within a tile’s bounds to be included in the output. Defaults to0.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.) Seesolaris.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
) – Ageopandas.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 ashapely.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_gdf – gdf with all contained objects clipped to poly_to_cut . See notes above for details on additional clipping columns added.
- Return type
-
solaris.tile.vector_tile.
search_gdf_polygon
(gdf, tile_polygon)[source]¶ Find polygons in a GeoDataFrame that overlap with tile_polygon .
- Parameters
gdf (
geopandas.GeoDataFrame
) – Ageopandas.GeoDataFrame
of polygons to search.tile_polygon (
shapely.geometry.Polygon
) – Ashapely.geometry.Polygon
denoting a tile’s bounds.
- 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