pyeo.raster_manipulation

Functions for working with raster data, including masks and platform-specific processing functions.

Key functions

create_matching_dataset() Creates an empty raster of the same shape as a source, ready for writing.

stack_images() Stacks a list of rasters into a single raster.

preprocess_sen2_images() Preprocesses a set of of Sentinel-2 images into single raster files.

clip_raster() Clips a raster to a shapefile

Rasters

When working with raster data (geotiff, .jp2, ect) using this module, the following assumptions have been made:

  • Any function that reads a raster can read from any gdal-readable format

  • All interim rasters are stored internally as a geotiff

  • All internal rasters have a .tif extension in the filename

  • Unless otherwise stated, all rasters are assumed to be in a projected coordinate system - i.e. in meters. Functions may fail if passed a raster in lat-long projection

Timestamps

Pyeo uses the same timestamp convention as ESA: yyyymmddThhmmss; for example, 1PM on 27th December 2020 would be 20201227T130000. All timestamps are in UTC

Supported datatypes

When a function in this library asks for a datatype, it can take one of the following

gdal.GDT_Unknown
gdal.GDT_Byte
gdal.GDT_UInt16
gdal.GDT_Int16
gdal.GDT_UInt32
gdal.GDT_Int32
gdal.GDT_Float32
gdal.GDT_Float64
gdal.GDT_CInt16
gdal.GDT_CInt32
gdal.GDT_CFloat32
gdal.GDT_CFloat64

Geotransforms

Every gdal raster has a geotransform associated with it; this defines it’s top-left hand corner in the projection and pixel size. In Pyeo, it takes the form of a 6-element tuple; for north-up images, these are the following.

geotransform[0] = top_left_x
geotransfrom[1] = pixel_width
geotransform[2] = 0
geotransform[3] = top_left_y
geotransform[4] = 0
geotransform[5] = pixel_height

A projection can be obtained from a raster with the following snippet:

image = gdal.Open("my_raster.tif")
gt = image.GetGeoTransform()

For more information, see the following: See the following: https://gdal.org/user/raster_data_model.html#affine-geotransform

Projections

Each Gdal raster also has a projection, defining (among other things) the unit of the geotransform. Projections in Pyeo are referred to either by EPSG number or passed around as a wkt( well-known text) string. You can look up EPSG values at https://epsg.io You can use the following snippet to extract the well-known text of a raster

projection = image.GetProjection()

Masks

Some functions in this module include options for creating and applying masks.

  • A raster may have an associated mask

  • A mask is a geotif with an identical name as the raster it’s masking with a .msk extension

    • For example, the mask for my_sat_image.tif is my_sat_image.msk

  • A mask is

    • a single band raster

    • of identical height, width and resolution of the related image

    • contains values 0 or 1

  • A mask is applied by multiplying it with each band of its raster

    • So any pixel with a 0 in its mask will be removed, and a 1 will be kept

Function reference

pyeo.raster_manipulation.align_image_in_place(image_path, target_path)

Adjusts the geotransform of the image at image_path with that of the one at target_path, so they align neatly with the smallest magnitude of movement

Parameters
  • image_path (str) – The path to the image to be adjusted.

  • target_path (str) – The image to align the image at image_path to.

Raises

NonSquarePixelException – Raised if either image does not have square pixels

pyeo.raster_manipulation.apply_array_image_mask(array, mask, fill_value=0)

Applies a mask of (y,x) to an image array of (bands, y, x). Replaces any masked pixels with fill_value Mask is an a 2 dimensional array of 1 (unmasked) and 0 (masked)

Parameters
  • array (array_like) – The array containing the raster data

  • mask (array_like) – The array containing the mask

  • fill_value (number, optional) – The value to replace any masked pixels with. Defaults to 0.

Returns

masked_array – The array with masked pixels replaced with fill_value

Return type

array_like

pyeo.raster_manipulation.apply_band_function(in_path, function, bands, out_path, out_datatype=5)

Applys an arbitrary band mathemtics function to an image at in_path and saves the result at out_map. Function should be a function object of the form f(band_input_A, band_input_B, …)

Parameters
  • in_path (str) – The image to process

  • function (Func) –

  • bands

  • out_path

  • out_datatype

Examples

Calculating the NDVI of an image with red band at band 0 and IR band at 4 First, define the function to be run across each pixel:

>>> def ndvi_function(r, i):
...     return (r-i)/(r+i)
>>> apply_band_function("my_raster.tif", ndvi_function, [0,1], "my_ndvi.tif")
pyeo.raster_manipulation.apply_image_function(in_paths, out_path, function, out_datatype=5)

Applies a pixel-wise function across every image. Assumes each image is exactly contiguous and, for now, single-banded. function() should take a list of values and return a single value.

Parameters
  • in_paths (list of str) – list of raster paths to process

  • out_path (str) – The path to the

  • function (function) – The function to apply to the list of images. Must take a list of numbers as an input and return a value.

  • out_datatype (gdal datatype, optional) – The datatype of the final raster. Defaults to gdal.gdt_Int32

Examples

Producing a raster where each pixel contains the sum of the corresponding pixels in a list of other rasters

>>> def sum_function(pixels_in):
...     return np.sum(pixels_in)
>>> in_paths = os.listdir("my_raster_dir")
>>> apply_image_function(in_paths, "sum_raster.tif", sum_function)
pyeo.raster_manipulation.apply_sen2cor(image_path, sen2cor_path, delete_unprocessed_image=False)

Applies sen2cor to the SAFE file at image_path. Returns the path to the new product.

Parameters
  • image_path (str) – Path to the L1 Sentinel 2 .SAFE file

  • sen2cor_path (str) – Path to the l2a_process script (Linux) or l2a_process.exe (Windows)

  • delete_unprocessed_image (bool, optional) – If True, delete the unprocessed image after processing is done. Defaults to False.

Returns

out_path – The path to the new L2 .SAFE file

Return type

str

pyeo.raster_manipulation.atmospheric_correction(in_directory, out_directory, sen2cor_path, delete_unprocessed_image=False)

Applies Sen2cor atmospheric correction to each L1 image in in_directory

Parameters
  • in_directory (str) – Path to the directory containing the L1 images

  • out_directory (str) – Path to the directory that will containg the new L2 images

  • sen2cor_path (str) – Path to the l2a_process script (Linux) or l2a_process.exe (Windows)

  • delete_unprocessed_image (bool, optional) – If True, delete the unprocessed image after processing is done. Defaults to False.

pyeo.raster_manipulation.average_images(raster_paths, out_raster_path, geometry_mode='intersect', format='GTiff', datatype=5)

When provided with a list of rasters, will stack them into a single raster. The nunmber of bands in the output is equal to the total number of bands in the input. Geotransform and projection are taken from the first raster in the list; there may be unexpected behavior if multiple differing proejctions are provided.

Parameters
  • raster_paths (list of str) – A list of paths to the rasters to be stacked, in order.

  • out_raster_path (str) – The path to the saved output raster.

  • geometry_mode ({'intersect' or 'union'}, optional) –

    Can be either ‘intersect’ or ‘union’. Defaults to ‘intersect’. - If ‘intersect’, then the output raster will only contain the pixels of the input rasters that overlap. - If ‘union’, then the output raster will contain every pixel in the outputs. Layers without data will

    have their pixel values set to 0.

  • format (str) – The GDAL image format for the output. Defaults to ‘GTiff’

  • datatype (gdal datatype) – The datatype of the gdal array - see note. Defaults to gdal.GDT_Int32

pyeo.raster_manipulation.buffer_mask_in_place(mask_path, buffer_size)

Expands a mask in-place, overwriting the previous mask

Parameters
  • mask_path (str) – Path to a multiplicative mask (0; masked, 1; unmasked)

  • buffer_size (int) – The radius of the buffer, in pixel units of the mask

pyeo.raster_manipulation.build_sen2cor_output_path(image_path, timestamp, version)

Creates a sen2cor output path dependent on the version ofr sen2cor

Parameters
  • image_path (str) – Path to the image

  • timestamp (str) – Timestamp that processing was started (required for v >= 2.8)

  • version (str) – String of the version of sen2cor (ex “2.05.05”)

Returns

new_path – The path of the finished sen2cor file

Return type

str

pyeo.raster_manipulation.calc_ndvi(raster_path, output_path)

Creates a raster of NDVI from the input raster at output_path

Parameters
  • raster_path (str) – Path to a raster with blue, green, red and infrared bands (in that order)

  • output_path (str) – Path to a location to save the output raster

pyeo.raster_manipulation.clip_raster(raster_path, aoi_path, out_path, srs_id=4326, flip_x_y=False, dest_nodata=0)

Clips a raster at raster_path to a shapefile given by aoi_path. Assumes a shapefile only has one polygon. Will np.floor() when converting from geo to pixel units and np.absolute() y resolution form geotransform. Will also reproject the shapefile to the same projection as the raster if needed.

Parameters
  • raster_path (str) – Path to the raster to be clipped.

  • aoi_path (str) – Path to a shapefile containing a single polygon

  • out_path (str) – Path to a location to save the final output raster

  • flip_x_y (bool, optional) – If True, swaps the x and y axis of the raster image before clipping. For compatability with Landsat. Default is False.

  • dest_nodata (number, optional) – The fill value for outside of the clipped area. Deafults to 0.

pyeo.raster_manipulation.clip_raster_to_intersection(raster_to_clip_path, extent_raster_path, out_raster_path, is_landsat=False)

Clips one raster to the extent proivded by the other raster, and saves the result at temp_file. Assumes both raster_to_clip and extent_raster are in the same projection.

Parameters
  • raster_to_clip_path (str) – The location of the raster to be clipped.

  • extent_raster_path (str) – The location of the raster that will provide the extent to clip to

  • out_raster_path (str) – A location for the finished raster

pyeo.raster_manipulation.combine_masks(mask_paths, out_path, combination_func='and', geometry_func='intersect')

ORs or ANDs several masks. Gets metadata from top mask. Assumes that masks are a Python true or false. Also assumes that all masks are the same projection for now.

Parameters
  • mask_paths (list of str) – A list of paths to the masks to combine

  • out_path (str) – The path to the new mask

  • combination_func ({'and' or 'or}, optional) – Whether the a pixel in the final mask will be masked if - any pixel (‘or’) is masked - or all pixels (‘and’) are masked ..in the corresponding pixels in the list of masks. Defaults to ‘and’

  • geometry_func ({'intersect' or 'union'}) – How to handle non-overlapping masks. Defaults to ‘intersect’

Returns

out_path – The path to the new mask

Return type

str

pyeo.raster_manipulation.composite_directory(image_dir, composite_out_dir, format='GTiff', generate_date_images=False)
Using composite_images_with_mask, creates a composite containing every image in image_dir. This will

place a file named composite_[last image date].tif inside composite_out_dir

Parameters
  • image_dir (str) – The directory containing the rasters and associated .msk files to be composited.

  • composite_out_dir (str) – The directory that will contain the final composite

  • format (str, optional) – The raster format of the output image. Defaults to ‘GTiff’

  • generate_date_images (bool, optional) – If true, generates a corresponding date image for the composite. See docs for composite_images_with_mask. Defaults to False.

Returns

composite_out_path – The path to the new composite

Return type

str

pyeo.raster_manipulation.composite_images_with_mask(in_raster_path_list, composite_out_path, format='GTiff', generate_date_image=False)

Works down in_raster_path_list, updating pixels in composite_out_path if not masked. Will also create a mask and (optionally) a date image in the same directory.

Parameters
  • in_raster_path_list (list of str) – A list of paths to rasters.

  • composite_out_path (str) – The path of the output image

  • format (str, optional) – The gdal format of the image. Defaults to “GTiff”

  • generate_date_image (bool, optional) – If true, generates a single-layer raster containing the dates of each image detected - see below.

Returns

composite_path – The path to the composite.

Return type

str

Notes

Masks are assumed to be a multiplicative .msk file with the same path as their corresponding image; see REFERENCE. All images must have the same number of layers and resolution, but do not have to be perfectly on top of each other. If it does not exist, composite_out_path will be created. Takes projection, resolution, ect from first band of first raster in list. Will reproject images and masks if they do not match initial raster.

If generate_date_images is True, an raster ending with the suffix .date will be created; each pixel will contain the timestamp (yyyymmdd) of the date that pixel was last seen in the composite.

pyeo.raster_manipulation.create_mask_from_class_map(class_map_path, out_path, classes_of_interest, buffer_size=0, out_resolution=None)

Creates a multiplicative mask from a classification mask: 1 for each pixel containing one of classes_of_interest, otherwise 0

Parameters
  • class_map_path (str) – Path to the classification map to build the mask from

  • out_path (str) – Path to the new mask

  • classes_of_interest (list of int) – The list of classes to count as clear pixels

  • buffer_size (int) – If greater than 0, applies a buffer to the masked pixels of this size. Defaults to 0.

  • out_resolution (int or None, optional) – If present, resamples the mask to this resoltion. Applied before buffering. Defaults to 0.

Returns

out_path – The path to the new mask.

Return type

str

pyeo.raster_manipulation.create_mask_from_confidence_layer(l2_safe_path, out_path, cloud_conf_threshold=0, buffer_size=3)

Creates a multiplicative binary mask where cloudy pixels are 0 and non-cloudy pixels are 1. If cloud_conf_threshold = 0, use scl mask else use confidence image

Parameters
  • l2_safe_path (str) – Path to the L1

  • out_path (str) – Path to the new path

  • cloud_conf_threshold (int, optional) – If 0, uses the sen2cor classification raster as the base for the mask - else uses the cloud confidence image. Defaults to 0

  • buffer_size (int, optional) – The size of the buffer to apply to the cloudy pixel classes

Returns

out_path – The path to the mask

Return type

str

pyeo.raster_manipulation.create_mask_from_fmask(in_l1_dir, out_path)

Creates a cloud mask from a level 1 Sentinel-2 product using fmask

Parameters
  • in_l1_dir (str) – The path to the l1 .SAFE folder

  • out_path (str) – The path to new mask

pyeo.raster_manipulation.create_mask_from_model(image_path, model_path, model_clear=0, num_chunks=10, buffer_size=0)

Returns a multiplicative mask (0 for cloud, shadow or haze, 1 for clear) built from the ML at model_path.

Parameters
  • image_path (str) – Path to the image

  • model_path (str) – Path to a pickled scikit-learn classification model

  • model_clear (int, optional) – The class from the model corresponding to non-cloudy pixels. Defaults to 0

  • num_chunks (int, optional) – The number of chunks to break the processing into. See classification.classify_image()

  • buffer_size (int, optional) – If present, will apply a buffer of this many pixels to the mask, expanding

Returns

mask_path – The path to the new mask

Return type

str

pyeo.raster_manipulation.create_mask_from_sen2cor_and_fmask(l1_safe_file, l2_safe_file, out_mask_path, buffer_size=0)

Creates a cloud mask from a combination of the sen2cor thematic mask and the fmask method. Requires corresponding level 1 and level 2 .SAFE files.

Parameters
  • l1_safe_file (str) – Path to the level 1 .SAFE file

  • l2_safe_file (str) – Path to the level 2 .SAFE file

  • out_mask_path (str) – Path to the new mask

  • buffer_size (int, optional) – If greater than 0, the buffer to apply to the Sentinel 2 thematic map

pyeo.raster_manipulation.create_matching_dataset(in_dataset, out_path, format='GTiff', bands=1, datatype=None)

Creates an empty gdal dataset with the same dimensions, projection and geotransform as in_dataset. Defaults to 1 band. Datatype is set from the first layer of in_dataset if unspecified

Parameters
  • in_dataset (gdal.Dataset) – A gdal.Dataset object

  • out_path (str) – The path to save the copied dataset to

  • format (str, optional) – The Ggal image format. Defaults to geotiff (“GTiff”); for a full list, see https://gdal.org/drivers/raster/index.html

  • bands (int, optional) – The number of bands in the dataset. Defaults to 1.

  • datatype (gdal constant, optional) – The datatype of the returned dataset. See the introduction for this module. Defaults to in_dataset’s datatype if not supplied.

Returns

new_dataset – An gdal.Dataset of the new, empty dataset that is ready for writing.

Return type

gdal.Dataset

pyeo.raster_manipulation.create_new_image_from_polygon(polygon, out_path, x_res, y_res, bands, projection, format='GTiff', datatype=5, nodata=- 9999)

Returns an empty image that covers the extent of the imput polygon.

Parameters
  • polygon (ogr.Geometry) – An OGR.Geometry object of a single polygon

  • out_path (str) – The path to save the new image to

  • x_res (number) – Pixel width in the new image

  • y_res (number) – Pixel height in the new image

  • bands (int) – Number of bands in the new image.

  • projection (str) – The projection, in wkt, of the output image.

  • format (str, optional) – The gdal raster format of the output image. Defaults to “Gtiff”

  • datatype (gdal datatype, optional) – The gdal datatype of the output image. Defaults to gdal.GDT_Int32

Returns

Return type

A gdal.Image object

pyeo.raster_manipulation.create_new_stacks(image_dir, stack_dir)

For each granule present in image_dir Saves the result in stacked_dir. Assumes that each image in image_dir is saved with a Sentinel-2 identifiter name - see merge_raster.

Parameters
  • image_dir (str) – A path to the directory containing the images to be stacked, all named as Sentinel 2 identifiers

  • stack_dir (str) – A path to a directory to save the stacked images to.

Returns

new_stacks – A list of paths to the new stacks

Return type

list of str

Notes

The pairing algorithm is as follows: Step 1: Group directory by tile number Step 2: For each tile number, sort by time Step 3: For each image in the sorted list, stack each image with it’s next oldest image.

Raises

CreateNewStacksException – If the image directory is empty

pyeo.raster_manipulation.filter_by_class_map(image_path, class_map_path, out_map_path, classes_of_interest, out_resolution=10)

Filters a raster with a set of classes for corresponding for pixels in filter_map_path containing only classes_of_interest. Assumes that filter_map_path and class_map_path are same resolution and projection.

Parameters
  • image_path (str) – Path to the raster to be filtered.

  • class_map_path (str) – Path to the map to use as the filter. Assumes a raster of integer class labels.

  • out_map_path (str) – Path to the filtered map

  • classes_of_interest (list of int) – The classes in class_map_path to keep present in the raster to be filtered

  • out_resolution (number, optional) – The resolution of the output image

Returns

out_map_path – The path to the new map

Return type

str

pyeo.raster_manipulation.flatten_probability_image(prob_image, out_path)

Takes a probability output from classify_image and flattens it into a single layer containing only the maximum value from each pixel.

Parameters
  • prob_image (str) – The path to a probability image.

  • out_path (str) – The place to save the flattened image.

pyeo.raster_manipulation.get_extent_as_shp(in_ras_path, out_shp_path)

Gets the extent of a raster as a shapefile

Parameters
  • in_ras_path (str) – The raster to get

  • out_shp_path (str) – The shape path

Returns

out_shp_path – The path to the new shapefile

Return type

str

pyeo.raster_manipulation.get_image_resolution(image_path)

Returns the resolution of the image in its native projection. Assumes square pixels.

Parameters

image_path (str) – Path to a raster

Returns

resolution – The size of each pixel in the image, in the units of its native projection.

Return type

number

pyeo.raster_manipulation.get_masked_array(raster, mask_path)

Returns a numpy.mask masked array for the raster. Masked pixels are FALSE in the mask image (multiplicateive map), but TRUE in the masked_array (nodata pixels). If the raster is multi-band and the mask is single-band, the mask will be applied to every raster.

Parameters
  • raster (gdal.Dataset) – A gdal.Dataset object

  • mask_path (str) – The path to the mask to use

Returns

masked_array – A numpy.masked array of the raster.

Return type

numpy.masked

pyeo.raster_manipulation.get_sen2cor_version(sen2cor_path)

Gets the version number of sen2cor from the help string.

Parameters

sen2cor_path (str) – Path the the sen2cor executable

Returns

version – A string of the version of sen2cor at sen2cor_path

Return type

str

pyeo.raster_manipulation.get_sen_2_band_path(safe_dir, band, resolution=None)

Returns the path to the raster of the specified band in the specified safe_dir.

Parameters
  • safe_dir (str) – Path to the directory containing the raster

  • band (str) – The band identifier (‘B01’, ‘B02’, ect)

  • resolution (int, optional) – If given, tries to get that band in that image - if not, tries for the highest resolution

Returns

band_path – The path to the raster containing the band.

Return type

str

pyeo.raster_manipulation.mosaic_images(raster_paths, out_raster_file, format='GTiff', datatype=5, nodata=0)

Mosaics multiple images with the same number of layers into one single image. Overwrites overlapping pixels with the value furthest down raster_paths. Takes projection from the first raster.

Parameters
  • raster_paths (str) – A list of paths of raster to be mosaiced

  • out_raster_file (str) – The path to the output file

  • format (str) – The image format of the output raster. Defaults to ‘GTiff’

  • datatype (gdal datatype) – The datatype of the output raster. Defaults to gdal.GDT_Int32

  • nodata (number) – The input nodata value; any pixels in raster_paths with this value will be ignored. Defaults to 0.

pyeo.raster_manipulation.open_dataset_from_safe(safe_file_path, band, resolution='10m')

Opens a dataset given a level 2 .SAFE file.

Parameters
  • safe_file_path (str) – The path to the .SAFE file

  • band (int) – The band to open

  • resolution ({'10m', '20m', '60m'}, optional) – The resolution of imagery to open. Defaults to “10m”.

Returns

band_raster – A Gdal dataset contining the band

Return type

gdal.Dataset

pyeo.raster_manipulation.preprocess_landsat_images(image_dir, out_image_path, new_projection=None, bands_to_stack='B2', 'B3', 'B4')

Stacks a set of Landsat images into a single raster and reorders the bands into [bands, y, x] - by default, Landsat uses [x,y] and bands are in seperate rasters. If given, will also reproject to an EPSG or .wkt

Parameters
  • image_dir (str) – The directory containing the Landsat images

  • out_image_path (str) – The path to the stacked image

  • new_projection (int or str, optional) – An EPSG number or a .wkt containing a projection. Defaults to None

  • bands_to_stack (list of str, optional) – The Landsat bands to put into the stacked

pyeo.raster_manipulation.preprocess_sen2_images(l2_dir, out_dir, l1_dir, cloud_threshold=60, buffer_size=0, epsg=None, bands='B02', 'B03', 'B04', 'B08', out_resolution=10)

For every .SAFE folder in l2_dir and L1_dir, stacks band 2,3,4 and 8 bands into a single geotif, creates a cloudmask from the combined fmask and sen2cor cloudmasks and reprojects to a given EPSG if provided.

Parameters
  • l2_dir (str) – The directory containing a set of L2 .SAFE folders to preprocess

  • out_dir (str) – The directory to store the preprocessed files

  • l1_dir (str) – The directory containing a set of L1 .SAFE files, corresponding to the L2 files in l2_dir

  • cloud_threshold (number) – DEPRECIATED; in for backwards compatibility.

  • buffer_size (int, optional) – The buffer to apply to the sen2cor mask - defaults to 0

  • epsg (int, optional) – If present, the EPSG number to reproject the final images to.

  • bands (list of str, optional) – List of names of bands to include in the final rasters. Defaults to (“B02”, “B03”, “B04”, “B08”)

  • out_resolution (number, optional) – Resolution to resample every image to - units are defined by the image projection. Default is 10.

Warning

This functions’ augment list is likely to be changed in the near future to (l1_dir, l2_dir, out_dir) - please be aware - September 2020.

pyeo.raster_manipulation.raster_sum(inRstList, outFn, outFmt='GTiff')

Creates a raster stack from a list of rasters. Adapted from Chris Gerard’s book ‘Geoprocessing with Python’. The out put data type is the same as the input data type.

Parameters
  • inRstList (list of str) – List of rasters to stack.

  • outFn (str) – Filename output as str including directory else image will be written to current working directory.

  • outFmt (str, optional.) – String specifying the input data format e.g. ‘GTiff’ or ‘VRT’. Defaults to GTiff.

pyeo.raster_manipulation.raster_to_array(rst_pth)

Reads in a raster file and returns a N-dimensional array.

Parameters

rst_pth (str) – Path to input raster.

Returns

out_array – An N-dimensional array.

Return type

array_like

pyeo.raster_manipulation.reproject_directory(in_dir, out_dir, new_projection, extension='.tif')

Reprojects every file ending with extension to new_projection and saves in out_dir

Parameters
  • in_dir (str) – A directory containing the rasters to be reprojected/

  • out_dir (str) – The directory to save the output files to. Output files will be saved in out_dir, with the same filenames.

  • new_projection (str) – The new projection in wkt.

  • extension (str, optional) – The file extension to reproject. Default is ‘.tif’

pyeo.raster_manipulation.reproject_image(in_raster, out_raster_path, new_projection, driver='GTiff', memory=2000.0, do_post_resample=True)

Creates a new, reprojected image from in_raster using the gdal.ReprojectImage function.

Parameters
  • in_raster (str or gdal.Dataset) – Either a gdal.Dataset object or a path to a raster

  • out_raster_path (str) – The path to the new output raster.

  • new_projection (str or int) – The new projection in .wkt or as an EPSG number

  • driver (str, optional) – The format of the output raster.

  • memory (float, optional) – The amount of memory to give to the reprojection. Defaults to 2e3

  • do_post_resample (bool, optional) – If set to false, do not resample the image back to the original projection. Defaults to True

Notes

The GDAL reprojection routine changes the size of the pixels by a very small amount; for example, a 10m pixel image can become a 10.002m pixel resolution image. To stop alignment issues, by default this function resamples the images back to their original resolution. If you are reprojecting from latlon to meters and get an outofmemory error from Gdal, set do_post_resample to False.

pyeo.raster_manipulation.resample_image_in_place(image_path, new_res)

Resamples an image in-place using gdalwarp to new_res in metres. WARNING: This will make a permanent change to an image! Use with care.

Parameters
  • image_path (str) – Path to the image to be resampled

  • new_res (number) – Pixel edge size in meters

pyeo.raster_manipulation.save_array_as_image(array, path, geotransform, projection, format='GTiff')

Saves a given array as a geospatial image to disk in the format ‘format’. The datatype will be of one corresponding to Array must be gdal format: [bands, y, x].

Parameters
  • array (array_like) – A Numpy array containing the values to be saved to a raster

  • path (str) – The path to the location to save the output raster to

  • geotransform (list) – The geotransform of the image to be saved. See note.

  • projection (str) – The projection, as wkt, of the image to be saved. See note.

  • format (str, optional) – The image format. Defaults to ‘GTiff’; see note for other types.

Returns

path_to_image – The path to the image

Return type

str

pyeo.raster_manipulation.stack_and_trim_images(old_image_path, new_image_path, aoi_path, out_image)

Stacks an old and new S2 image and trims to within an aoi.

Parameters
  • old_image_path (str) – Path to the image that will be the first set of bands in the output image

  • new_image_path (str) – Path to the image that will be the second set of bands in the output image

  • aoi_path (str) – Path to a shapefile containing the AOI

  • out_image (str) – Path to the location of the clipped and stacked image.

pyeo.raster_manipulation.stack_image_with_composite(image_path, composite_path, out_dir, create_combined_mask=True, skip_if_exists=True, invert_stack=False)

Creates a single 8-band geotif image with a cloud-free composite, and saves the result in out_dir. Images are named “composite_tile_timestamp-of-composite_timestamp-of-image”. Bands 1,2,3 and 4 are the B,G,R and I bands of the composite, and bands 5,6,7 and 8 are the B,G,R and I bands of the image.

Parameters
  • image_path (str) – Path to the image to be stacked

  • composite_path (str) – Path to the composite to stack the image with

  • out_dir (str) – The directory to save the resulting composite to

  • create_combined_mask (bool, optional) – If true, combines the cloud mask files associated with the images into a single mask. The mask will mask out clouds that exist in either image. Defaults to True.

  • skip_if_exists (bool, optional) – If true, skip stacking if a file with the same name is found. Defaults to True.

  • invert_stack (bool, optional.) – If true, changes the ordering of the bands to image BGRI - composite BGRI. Included to permit compatibility with older models - you can usually leave this alone.

Returns

out_path – The path to the new composite.

Return type

str

pyeo.raster_manipulation.stack_images(raster_paths, out_raster_path, geometry_mode='intersect', format='GTiff', datatype=5)

When provided with a list of rasters, will stack them into a single raster. The nunmber of bands in the output is equal to the total number of bands in the input. Geotransform and projection are taken from the first raster in the list; there may be unexpected behavior if multiple differing proejctions are provided.

Parameters
  • raster_paths (list of str) – A list of paths to the rasters to be stacked, in order.

  • out_raster_path (str) – The path to the saved output raster.

  • geometry_mode ({'intersect' or 'union'}) –

    Can be either ‘instersect’ or ‘union’. - If ‘intersect’, then the output raster will only contain the pixels of the input rasters that overlap. - If ‘union’, then the output raster will contain every pixel in the outputs. Layers without data will

    have their pixel values set to 0.

  • format (str, optional) – The GDAL image format for the output. Defaults to ‘GTiff’

  • datatype (gdal datatype, optional) – The datatype of the gdal array - see introduction. Defaults to gdal.GDT_Int32.

pyeo.raster_manipulation.stack_old_and_new_images(old_image_path, new_image_path, out_dir, create_combined_mask=True)

Stacks two images that cover the same tile into a single multi-band raster, old_image_path being the first set of bands and new_image_path being the second. The produced image will have the name {tile}_{old_date}_{new_date}.tif.

Parameters
  • old_image_path (str) – Path to the older image

  • new_image_path (str) – Path to the newer image

  • out_dir (str) – Directory to place the new stacked raster into

  • create_combined_mask (bool, optional) – If True, finds and combines the associated mask files between

Returns

out_image_path – The path to the new image

Return type

str

pyeo.raster_manipulation.stack_sentinel_2_bands(safe_dir, out_image_path, bands='B02', 'B03', 'B04', 'B08', out_resolution=10)

Stacks the specified bands of a .SAFE granule directory into a single geotiff

Parameters
  • safe_dir (str) – Path to the .SAFE file to stack

  • out_image_path (str) – Location of the new image

  • bands (list of str, optional) – The band IDs to be stacked

  • out_resolution – The final resolution of the geotif- bands will be resampled if needed.

Returns

out_image_path – The path to the new image

Return type

str

pyeo.raster_manipulation.strip_bands(in_raster_path, out_raster_path, bands_to_strip)

Removes bands from a raster and saves a copy.

Parameters
  • in_raster_path (str) – Path to the raster

  • out_raster_path (str) – Path to the output

  • bands_to_strip (list of int) – 0-indexed list of bands to remove

Returns

out_path – The path to the output

Return type

str

pyeo.raster_manipulation.trim_image(in_raster_path, out_raster_path, polygon, format='GTiff')

Trims a raster to a polygon.

Parameters
  • in_raster_path (str) – Path to the imput raster

  • out_raster_path (str) – Path of the output raster

  • polygon (ogr.Geometry) – A ogr.Geometry containing a single polygon

  • format (str) – Image format of the output raster. Defaults to ‘GTiff’.