API Reference#

This section is autogenerated from the package’s docstrings, and is intended as a reference for those that want a deeper understanding of the package.

Please start with the Tutorial to learn how to use the package. And read this API reference in conjunction with the Developer Guide.

drill module#

drill() is the main interface. Most interaction with this package should be through this interface.

pixdrill.drill.drill(points, images=None, stac_endpoint=None, raster_assets=None, collections=None, item_properties=None, nearest_n=0, std_stats=None, user_stats=None, ignore_val=None, concurrent=False)#

Given a list of Point objects, compute the zonal statistics around each point for the specified images.

Parameters:

pointslist of Point objects: Points to drill the specified STAC endpoint or images for.
imageslist of strings: GDAL-readable list of filenames to drill.
stac_endpointstring: The STAC catalogue’s URL.
raster_assetssequence of strings: The raster assets to read from each Item in the STAC catalogue.
collectionslist of strings: The STAC catalogue’s collections to query. You would normally only specify one catalogue.
item_propertiesa list of objects: These are for filtering the results of a STAC search. The list is passed to the pystac_client.Client search function using the query parameter.
nearest_ninteger: Only use up to n STAC Items that are nearest-in-time to the Point. A value of 0 means use all items found.
std_statssequence of integers: Constants from the drillstats module (STATS_MEAN, STATS_STDEV etc) defining which ‘standard’ statistics to extract.
user_statsa list of tuples: A user defined list of statistic names and functions. See the notes section below for a description of the function signatures.
ignore_valfloat or list of floats: A value to use for the ignore value for rasters. Should only be used to override the image’s no data values. See the notes below.
concurrentbool: If True, will call calc_stats() for each Item to be drilled concurrently in a concurrent.futures.ThreadPoolExecutor.

Returns:

None: Instead, the Points’ pixdrill.drillstats.PointStats objects are updated.

See also

pixdrill.example: a script that shows two usage patterns

Notes

Images are specified in one of two ways. You may use either or both. The first method is to use images parameter to supply a list of paths to rasters. A path is any string understood by GDAL. All bands in each image are read.

The second method is to search a STAC endpoint for the raster. In this case, you must supply:

a list of raster_assets
preferably, a name of one collection in the STAC catalogue
optionally, a list of item properties to filter the search by

create_stac_drillers() is called to find all STAC items that intersect the survey points within their time-window; only up to the n nearest-in-time Items are used.

For each raster, the pixels are drilled and zonal statistics calculated using the list of standard stats and user stats.

std_stats is a list of standard stats, as defined in the pixdrill.drillstats module with the STATS_* attributes. To use the standard statistics, every image must only contain one band.

user_stats is a list of (name, function) pairs. The function is used to calculate a user-specified statistic. The signature of a user-supplied function must be:

def user_func(array_info, item, pt):

where:

array_info is a list of ArrayInfo objects, one element for each image/asset read
item is the pystac.Item object (for STAC rasters) or ImageItem for an image.
pt is the Point object from around which the pixels were extracted

Each ArrayInfo instance has a data attribute that contains a 3D numpy masked array with the pixel data for the asset defined by the instance’s asset_id attribute. Note that each element in array_info corresponds to the raster_assets passed to drill().

The user function must return a value. It can be any data type.

The value(s) returned from the stats functions are stored with the Point’s PointStats object. See the examples section below for how to retrieve them.

item_properties allows you to filter your STAC search results if the STAC endpoint supports the Query extension. An Item's properties are specific to the STAC collection. So you need to inspect the properties of a STAC Item in the collection to determine sensible values for this parameter. For example, the sentinel2-s2-l2a-cogs collection in the STAC Catalogue at endpoint https://earth-search.aws.element84.com/v0, has Sentinel2-specific properties that allow you to filter by the tile ID:

tile = '54JVR'
zone = tile[:2]
lat_band = tile[2]
grid_sq = tile[3:]
item_properties = [
    f'sentinel:utm_zone={zone}',
    f'sentinel:latitude_band={lat_band}',
    f'sentinel:grid_square={grid_sq}']

The ignore_val parameter allows you to set or override the pixel values to be ignored when calculating statistics. Whereever possible though, you should use the image’s no data values. ignore_val is treated differently depending on whether the assets of a pystac.Item are being read or a ImageItem is being read.

When reading from the assets of a pystac.Item, ignore_val can be a list of values, a single values, or None. A list of values is the null value per asset. It assumes all bands in an asset use the same null value. A single value is used for all bands of all assets. None means to use the no data value set on each the assets’ bands.

When reading the image of a pixdrill.drill.ImageItem, ignore_val can be a single value or None. A single value is used for all bands in the image. None means to use the each band’s no data value.

ignore_val is used for:

the mask value when ‘removing’ pixels from the raw arrays that are outside the region of interest, e.g. if the Point’s footprint is a circle then we remove pixels from the raw rectangular arrays
excluding pixels from the stats calculations, those both within and outside the Point’s footprint

Examples

With the statistics calculated, you retrieve them point-by-point. Use the Point’s stats attribute. It is an instance of PointStats. Use its get_stats() function, which returns a dictionary, keyed by the Item’s ID. So, the dictionary’s length matches the number of Items that the Point intersects. For example:

point_stats = pt.stats.get_stats()
for item_id, item_stats in point_stats.items():
    print(f"    Item ID={item_id}")
    print(f"        Raw arrays : {item_stats[drillstats.STATS_RAW]}")
    print(f"        Mean values: {item_stats[drillstats.STATS_MEAN]}")
    print(f"        Counts     : {item_stats[drillstats.STATS_COUNT]}")
    print(f"        My Stat    : {item_stats["MY_STAT"]})

A few things to note in this example:

the std_stats argument passed to drill() would have been [drillstats.STATS_MEAN, drillstats.STATS_COUNT]
the user_stats argument defines the MY_STAT statistic and its corresponding function name: [('MY_STAT', my_stat_function)]
retrieve the numpy masked arrays using the key pixdrill.drillstats.STATS_RAW; these are always supplied
likewise, retrieve the ArrayInfo object using pixdrill.drillstats.STATS_ARRAYINFO (not shown)

pixdrill.drill.create_image_drillers(points, images, image_ids=None)#

Return a list of ItemDriller objects, one for each image in the images list.

Parameters:

pointssequence of Point objects: Points to drill the image for.
imagessequence of strings: GDAL-readable filenames to drill.
image_idssequence of strings: ID to use for each image. If not specified the image filename is used.

Returns:

drillerslist of ItemDriller objects: The ItemDriller for each image.

pixdrill.drill.create_stac_drillers(stac_client, points, collections, raster_assets=None, item_properties=None, nearest_n=0)#

Search the list of collections in a STAC endpoint for items that intersect the x, y coordinate of the list of points and are within the Points’ image-acquisition windows.

Parameters:

stac_clientstr or pystac.Client object: The endpoint URL to the STAC catalogue (str) or the pystac_client.Client object returned from calling its open() function.
pointslist of Point objects: Points to drill the endpoint for.
collectionslist of strings: The names of the collections to query, normally only collection is given.
raster_assetslist of strings, required: Raster assets to use from the STAC endpoint.
item_propertiesa list of objects, optional: These are passed to the pystac_client.Client search() function using its query parameter.
nearest_ninteger: Only use up to n STAC Items that are nearest-in-time to the Point. A value of 0 means use all items found.

Returns:

drillerslist of ItemDriller objects: Each driller is the ItemDriller for a STAC Item.

pixdrill.drill.calc_stats(driller, std_stats=None, user_stats=None, ignore_val=None)#

Calculate the statistics for all points in the ItemDriller objects. It reads the rasters and calculates the stats.

Parameters:

drillera ItemDriller.: The driller for the Item to be drilled.
std_statssequence of integers: Constants from the drillpoints module `(STATS_MEAN, STATS_STDEV etc) defining which ‘standard’ statistics to extract.
user_statsfunction: A list of (stat_name, stat_function) tuples containing the user defined function as specified by drill().

class pixdrill.drill.ImageItem(filepath, id=None)#

Analogous to a pystac.Item object, use an ImageItem object when constructing ItemDriller objects for an image file.

Parameters:

filepath: str: Path to the GDAL-readable file.
id:: An optional ID for the ImageItem. If not given, filepath is used.

Attributes:

filepathstring: Path to the GDAL file
idString: ID to use for this item. Is the same as filepath unless overridden.

exception pixdrill.drill.PixelStacError#

drillpoints module#

Contains the Point and ItemDriller classes which define the survey point’s properties and are used to drill an Item's pixels.

pixdrill.drillpoints.ROI_SHP_SQUARE = 'square'#: Define a square region of interest

pixdrill.drillpoints.ROI_SHP_CIRCLE = 'circle'#: Define a circle region of interest

exception pixdrill.drillpoints.PointError#

class pixdrill.drillpoints.Point(x, y, t, sp_ref, t_delta, buffer, shape, buffer_degrees=False)#

A structure for an X-Y-Time point with a coordinate reference system, spatial shape, and image-acquisition window.

The statistics for a Point are retrievable using its stats attribute, which is an instance of PointStats.

Parameters:

xfloat: The x-coordinate of the survey’s centre (e.g. longitude or easting).
yfloat: The y-coordinate of the survey’s centre (e.g. latitude or northing).
tdatetime.datetime: The point’s survey date and time. If t is time zone unaware, then UTC is assumed.
sp_refint or osr.SpatialReference: The coordinate reference system of the point’s x, y location. Integer’s are interpreted as EPSG codes and used to create a GDAL osr.SpatialReference object.
t_deltadatetime.timedelta object: For searching STAC catalogues. An Item acquired within this time window either side of the point’s time will be drilled, provided it is one of the nearest_n Items (see pixdrill.drill.drill()).
bufferint or float: Together with the shape parameter, buffer defines the region of interest about the point.
shape{ROI_SHP_SQUARE, ROI_SHP_CIRCLE}: The shape of the region of interest. If shape is ROI_SHP_SQUARE, then buffer is half the length of the square’s side. If shape is ROI_SHP_CIRCLE, then buffer is the circle’s radius.
buffer_degreesbool: If True, then the units for the point’s buffer are assumed to be in degrees, otherwise they are assumed to be in metres. The default is False (metres).

Attributes:

xfloat: The survey point’s x-coordinate.
yfloat: The survey point’s y-coordinate.
tdatetime.datetime: The survey point’s date and time.
x_ytuple of float: The point’s (x, y) location.
sp_refosr.SpatialReference: The osr.SpatialReference of (x, y).
wgs84_xfloat: The point’s x location in WGS84 coordinates.
wgs84_yfloat: The point’s y location in WGS84 coordinates.
start_datedatetime.datetime: The start date of the image-acquistion window.
end_datedatetime.datetime: The end date of the image-acquisition window.
bufferfloat: The distance from the point that defines the region of interest.
shapeint: ROI_SHP_SQUARE or ROI_SHP_CIRCLE.
buffer_degreesbool: True if the buffer distance is in degrees or False if it is in metres.
statsdrillstats.PointStats: Holds the drilled data and statistics.
itemsdictionary: The items associated with this point, keyed by the Item ID.

intersects(ds)#

Return True if the point intersects the GDAL dataset. The comparison is made using the image’s coordinate reference system.

Parameters:

dsAn osgeo.gdal.Dataset object or str: The file to check intersection with, it can be an open GDAL Dataset or a filepath.

Returns:

bool

transform(dst_srs, src_srs=None, x=None, y=None)#

Transform the point’s x, y location to the destination osr.SpatialReference coordinate reference system.

Parameters:

dst_srsosr.SpatialReference: The destination SRS
src_srsosr.SpatialReference, optional: The source SRS
xfloat, optional: The x coord to be transformed.
yfloat, optional: The y coord to be transformed.

Returns:

tuple with the transformed (x, y) coords

Notes

You may supply an alternative src_srs for the (x, y) Point. If not supplied this Point’s sp_ref is used.

You may supply alternative x, y coordinates. If not supplied the Point’s x, y coordinates are used.

Under the hood, use GDAL’s OAMS_TRADITIONAL_GIS_ORDER axis mapping strategies to guarantee x, y point ordering of the input and output points.

to_wgs84()#

Return the x, y coordinates of this Point in the WGS84 coordinate reference system, EPSG:4326.

Returns:

tuple of the new coords

change_buffer_units(dst_srs)#

Given the destination (target) spatial reference system, change the buffer’s units and estimate a new distance in the dst_srs.

Parameters:

dst_srsosr.SpatialReference: The target SRS.

Returns:

float: The buffer distance.

Notes

Handles two cases:

convert the point’s buffer distance to metres if it is in degrees and the dst_srs is a projected reference system.
convert the point’s buffer distance to degrees if it is in metres and the dst_srs is a geographic reference system.

If the buffer’s units and dst_srs are compatible; then do nothing, returning self.buffer as is.

exception pixdrill.drillpoints.ItemDrillerError#

class pixdrill.drillpoints.ItemDriller(item, asset_ids=None)#

Drills an Item, extracting pixels for a list of Points.

Parameters:

itema pystac.Item object or a drill.ImageItem object: The Item to be drilled.
asset_idsa list of strings: The IDs of the pystac.Item’s raster assets to read; leave this as None (the default) if item is an instance of ImageItem or you want to set the assets later using set_asset_ids().

Attributes:

itempystac.Item or ImageItem: The Item to be drilled.
pointslist of Point objects
asset_idslist of strings: the IDs of the pystac.Item’s raster assets to read.

set_asset_ids(asset_ids)#

Set which asset IDs to read data from on the next call to read_data().

Parameters:

asset_idslist of ids

Notes

This function is irrelevant when self.item is an instance of ImageItem. If self.item is a pystac.Item, then you must set the asset_ids using this function or the constructor.

Using this function probably only makes sense in the context of setting the asset IDs for the first time or reusing the pystac.Item to calculate statistics for an entirely new set of raster assets. In the latter case, you would call this function after calling reset_stats() and before calling read_data() and calc_stats().

You may experience strange side effects if you don’t call reset_stats() when the ItemDriller previously had assets assigned. The underlying behaviour is that arrays for the new set of asset_ids will be appended to the existing arrays for each point’s PointStats object. Then, on the next calc_stats() call, the stats for all previously read data will be recalculated in addition to the new stats for the new assets.

add_point(pt)#

Append the Point to this object’s points list.

Parameters:

ptPoint object

read_data(ignore_val=None)#

Read the pixels around every point for the given raster assets. On completion, each Point’s stats object will have a masked array for the Item.

Parameters:

ignore_valnumber or None, optional: Use the given number to define the pixels to be masked when creating the numpy masked arrays. See the notes below.

Returns:

bool: True if data is read or False if there’s an error reading the data.

Notes

When reading from the assets of a pystac.Item, ignore_val can be a list of values, a single values, or None. A list of values is the null value per asset. It assumes all bands in an asset use the same null value. A single value is used for all bands of all assets. None means to use the no data value set on each the assets’ bands.

When reading the image of a ImageItem, ignore_val can be a single value or None. A single value is used for all bands in the image. None means to use the each band’s no data value.

The reading is delegated to pixdrill.image_reader.ImageReader.read_data().

get_points()#

Get the list of Point objects in this collection.

Returns:

list of Point objects

calc_stats(std_stats=None, user_stats=None)#

Calculate the statistics for every Point. Call this after calling read_data().

On completion, each Point’s stats object will be populated with the statistics.

Parameters:

std_statslist of int, optional: The list of standard statistics to calculate. Each element must be one of the STATS_* constants defined in pixdrill.drillstats.
user_statslist of (name, func) tuples: name is a string and is the name of the statistic. func is the name of the function used to calculate the statistic.

drillstats module#

Contains the PointStats class and standard functions for calculating and storing the drilled pixel data and statistics for a Point.

pixdrill.drillstats.STATS_RAW = 'raw'#: Raw Data to be passsed to userFunc

pixdrill.drillstats.STATS_ARRAYINFO = 'arrayinfo'#: Information about the array

pixdrill.drillstats.STATS_MEAN = 'mean'#: Calculate the mean

pixdrill.drillstats.STATS_STDEV = 'stddev'#: Calculate the standard deviation

pixdrill.drillstats.STATS_COUNT = 'count'#: The number of non-null pixels used in stats calcs.

pixdrill.drillstats.STATS_COUNTNULL = 'countnull'#: The number of null pixels in an array. Together, STATS_COUNT and STATS_COUNTNULL sum to the size of the array.

pixdrill.drillstats.STATS_STD = ['mean', 'stddev', 'count', 'count']#: List of standard statistics.

pixdrill.drillstats.ITEM_KEY = 'ITEM'#: For internal use only, it is the symbol used as the key for storing the reference to the Item in PointStats.

class pixdrill.drillstats.PointStats(pt)#

Holds the statistics of the pixel arrays for a Point for one or more Items.

Parameters:

ptPoint object: The point associated with this PointStats object.

Attributes:

ptthe Point object
item_statsdictionary: a dictionary containing the raster statistics within the region of interest of the associated point. The key is the Item ID, and the value is another dictionary. The second dictionary’s keys are the names of the std_stats and user_stats passed to calc_stats(). Its values are a list of the return values of the corresponding stats functions. If the item is a pystac.Item, there may be multiple elements in the list corresponding to the drilled Item's assets.

add_data(item, arr_info)#

Add the ArrayInfo object as read from an Item's raster.

Parameters:

itemImageItem or pystac.Item
arr_infopixdrill.image_reader.ArrayInfo

Notes

Elements are appended to the lists that store the Item's statistics:

item_stats[item.id][STATS_RAW].append(arr_info.data)
item_stats[item.id][STATS_ARRAYINFO].append(arr_info)

where arr_info.data is the masked array of data containing the pixels for one of the assets of the item.

If item is a pystac.Item, then add_data() may be called multiple times, once for each raster asset that is drilled.

calc_stats(item_id, std_stats=None, user_stats=None)#

Calculate the given list of standard and user-defined statistics for the given item.

Parameters:

item_id: str: The Item's ID, for which stats will be calculated.
std_statsint, optional: A list of STATS_* constants defined in the pixdrill.drillstats module, defining the standard stats to calculate.
user_statslist of (name, func) tuples, optional: name is the name of the statistic. func is the user-defined function to calculate the statistic.

image_reader module#

For reading pixel data and metadata from images.

class pixdrill.image_reader.ImageInfo(ds, omit_per_band=False)#

An object with metadata for the given image, in GDAL conventions.

Parameters:

dsgdal.Dataset or string: If string, file will be opened
omit_per_bandbool: If True, won’t calculate per band information. See the notes below.

Notes

The omit_per_band parameter on the constructor is provided in order to speed up the access of very large VRT stacks. The information which is normally extracted from each band will, in that case, trigger a gdal.Open() for each band, which can be quite slow. So, if none of that information is actually required, then setting omit_per_band=True will omit that information, but will return as quickly as for a normal single file.

Sourced from rios.fileinfo.ImageInfo.

Attributes:

x_minfloat: Map X coord of left edge of left-most pixel.
x_maxfloat: Map X coord of right edge of right-most pixel.
y_minfloat: Map Y coord of bottom edge of bottom pixel.
y_maxfloat: Map Y coord of top edge of top-most pixel.
x_resfloat: Map coord size of each pixel, in X direction.
y_resfloat: Map coord size of each pixel, in Y direction.
nrowsint: Number of rows in image.
ncolsint: Number of columns in image.
transformlist of floats: Transformation params to map between pixel and map coords, in GDAL form.
projectionstring: WKT string of projection.
raster_countint: Number of rasters in file.
lnameslist of strings: Names of the layers as a list.
layer_typestring: thematic or athematic, if it is set.
data_typeint: Data type for the first band (as a GDAL integer constant).
data_type_namestring: Data type for the first band (as a human-readable string).
nodatavallist of floats: Value used as the no-data indicator (per band).

class pixdrill.image_reader.ArrayInfo(data, asset_id, xoff, yoff, win_xsize, win_ysize, ulx, uly, lrx, lry, x_res, y_res)#

Contains information about the array read from the image around a point.

Parameters:

datamasked array: The numpy masked array containing the pixel data.
asset_idstring: The ID of the STAC Item’s asset from which the data was read.
xoff, yoff, win_xsize, win_ysizeint: The pixel window read from the raster asset in pixel coordinates. xoff and yoff are the coordinates of the upper left pixel in the array.
ulx, uly, lrx, lryfloat: The bounding box of the array in image coordinates, as (upper-left x, upper-left y, lower-right x, lower-right y).
x_res, y_resfloat: The pixel size in the same units as the image’s coordinate reference system.

Attributes:

The same as the above list of parameters.

isempty()#: Return True if the ArrayInfo’s data array contains no data.

exception pixdrill.image_reader.ImageReaderError#

pixdrill.image_reader.get_asset_filepath(item, asset_id)#: Construct a GDAL filepath to the STAC Item’s asset.

class pixdrill.image_reader.ImageReader(item, asset_id=None)#

Encapsulates the GDAL Dataset object and metadata (an ImageInfo object) for a STAC raster asset or raster image. It also contains the algorithms used to read arrays of pixels around a list of points

Parameters:

itempystac.Item or ImageItem object: Item to read from.
asset_idstring: The raster asset ID. If None, then it’s assumed that item is an ImageItem.

Attributes:

itempystac.Item or ImageItem: Item to read from.
asset_idstring: Asset ID. If None, then item is an ImageItem.
filepathstring: The GDAL-readable filepath.
datasetgdal.Dataset: The GDAL dataset for filepath.
infoImageInfo: The ImageInfo object for the dataset.

read_data(points, ignore_val=None)#

Read the pixel data around each of the given points.

Parameters:

pointslist of Point objects: Points to read from.
ignore_valfloat: ignore value to use, if None then the image’s no data value is used.

Notes

The data is read using read_roi(), passing it the ignore_val.

Once read, the PointStats object (corresponding to this asset’s Item ID) of every Point will contain an ArrayInfo object.

read_roi(pt, ignore_val=None)#

Extract the smallest number of pixels required to cover the region of interest.

Parameters:

ptPoint: Point to use
ignore_valfloat: ignore value to use, if None then the image’s no data value is used.

Returns:

ArrayInfo

Notes

We use an ‘all-touched’ approach, whereby any pixel inside or touched by the ROI’s boundary is returned. Any pixels outside or not touched by the ROI’s boundary are masked using ignore_val.

The ArrayInfo object contains a 3D masked array with the pixel data.

If ignore_val is None, the no-data value set on each band in the image is used. If ignore_val is set then the same value is used for every band in the image.

If the point’s footprint straddles the image’s extents, the ROI is clipped to the extents. That is, only that portion of the image that is within the extents is returned.

get_pix_window(pt)#

Return the rectangular bounds of the region of interest in the image’s pixel coordinate space as.

Parameters:

ptPoint: Point to use

Returns:

tuple of floats: The rectangular bounds in pixel coordinates as (xoff, yoff, win_xsize, win_ysize).

Notes

If a pixel touches the image’s bounds it is included.

In the returned tuple, (xoff, yoff) defines the grid location of the top-left pixel of the pixel window to read. win_xsize and win_ysize are the number of columns and rows to read from the image.

An (xoff, yoff) of (0, 0) corresponds to the top-left pixel of the image. An (xoff, yoff) of (ImageInfo.ncols-1, ImageInfo.nrows-1) corresponds to the bottom-right pixel of the image.

If the window straddles the image’s extents bounds, the returned window is clipped to the image’s extents.

If the returned win_xsize or win_ysize is 0, it means the window was entirely outside of the image’s extents.

mask_roi_shape(pt, arr_info, ignore_val)#

Mask the pixels in the arr_info.data’s array that are outside the region of interest.

Parameters:

ptPoint: Point to use.
arr_infoArrayInfo: The ArrayInfo object with the data to be masked.
ignore_valfloat: ignore value to use, if None then the image’s no data value is used.

Returns:

None: arr_info.data is updated in place.

Raises:

ImageReaderError: If pt.shape==drillpoints.ROI_SHP_CIRCLE and the size of arr_info.data is less than 5.

Notes

The pixels outside the shape are set to ignore_val. If ignore_val is None, the no-data value set on each band of the image is used. If ignore_val is set, use the same value for every image band.

Currently only supports points with a shape attribute of ROI_SHP_SQUARE or ROI_SHP_CIRCLE. No masking is done in the case of squares.

wld2pix(geox, geoy)#

Convert a set of map coords to pixel coords.

Parameters:

geox, geoyfloat: The input coordinates.

Returns:

tuple of (x, y)

pix2wld(x, y)#

Convert a set of pixel coords to map coords.

Parameters:

x, yint: The input coordinates

Returns:

tuple of (geox, geoy)

example module#

An example script:

python3 -m pixdrill.example

Work through this example, starting in the run_typical() function, in conjunction with the documentation for pixdrill.drill.drill().

pixdrill.example.pt_1()#: Create a point in Australian albers.

pixdrill.example.pt_2()#: Create a point in WGS 84.

pixdrill.example.pt_3()#: Create a point in WGS 84. This point intersects one item and contains a mix of null and non-null pixels.

pixdrill.example.pt_4()#: Create a point in WGS 84. This point intersects two items. Its region of interest is only partially within the extents of one of the items, so the pixel counts are less than for the other item, which contains the entire ROI.

pixdrill.example.create_sp_ref(epsg_code)#: Return an osr.SpatialReference instance with a coordinate reference system determined from the epsg code.

pixdrill.example.create_date(d_days)#: Create a datetime.datetime instance for 28 July 2022 in UTC and a datetime.timedelta object of d_days.

pixdrill.example.user_range(array_info, item, pt)#

Example of a function for a customised statistics.

array_info is a list of image_reader.ArrayInfo objects, item is the pystac.Item or drill.ImageItem object, and pt is the drillpoints.Point object that intersects the item.

The numpy.ma.masked_array objects are stored in ArrayInfo.data.

The function returns a list where each element in the range (max-min) of the values in each array.

item and pt are included in the function signature for use cases where the Item or Point’s properties are needed.

pixdrill.example.get_image_path(stac_id, asset_id)#

Get a path to the image represented by the stac_id and asset_id.

stac_id is the ID of a item on the EarthSearch endpoint: https://earth-search.aws.element84.com/v0. For example: S2A_54HVE_20220730_0_L2A

pixdrill.example.run_typical()#: Demonstrate running the typical usage pattern to support the tutorial in the docs.

pixdrill.example.run_alternative()#: Demonstrate running an alternative usage pattern to support the tutorial in the docs.