pybob.GeoImg

pybob.GeoImg is a class to handle geospatial imagery, in particular satellite images and digital elevation models.

class pybob.GeoImg.GeoImg(in_filename, in_dir=None, datestr=None, datefmt='%m/%d/%y', dtype=<MagicMock id='140228516018776'>, attrs=None)

Create a GeoImg object from a GDAL-supported raster dataset.

__init__(in_filename, in_dir=None, datestr=None, datefmt='%m/%d/%y', dtype=<MagicMock id='140228516018776'>, attrs=None)

Parameters:

• in_filename (str, gdal.Dataset) – Filename or object to read in. If in_filename is a string, the GeoImg is created by reading the file corresponding to that filename. If in_filename is a gdal object, the GeoImg is created by operating on the corresponding object.
• in_dir (str) – (optional) directory where in_filename is located. If not given, the directory will be determined from the input filename.
• datestr (str) – (optional) string to pass to GeoImg, representing the date the image was acquired.
• datefmt – Format of datestr that datetime.datetime should use to parse datestr. Default is %m/%d/%y.
• dtype (numpy datatype) – numpy datatype to read input data as. Default is np.float32. See numpy docs for more details.

copy(new_raster=None, new_extent=None, driver='MEM', filename='', newproj=None, datatype=<MagicMock name='mock.GDT_Float32' id='140228515791984'>)

Copy the GeoImg, creating a new GeoImg, optionally updating the extent and raster.

Parameters:

• new_raster (array-like) – New raster to use. If not set, the new GeoImg will have the same raster as the old image.
• new_extent (array_like) – New extent to use, given as xmin, xmax, ymin, ymax. If not set, the old extent is used. If set, you must also include a new raster.
• driver (str) – gdal driver to use to create the new GeoImg. Default is ‘MEM’ (in-memory). See gdal docs for more options. If a different driver is used, filename must also be specified.
• filename (str) – Filename corresponding to the new image, if not created in memory.

Returns new_geo:  

A new GeoImg with the specified extent and raster.

crop_to_extent(extent, pixel_size=None, bands=None)

Crop image to given extent.

Parameters:

• extent (matplotlib.figure.Figure or array-like) – Extent to which image should be cropped. If extent is a matplotlib figure handle, the image extent is taken from the x and y limits of the current figure axes. If extent is array-like, it is assumed to be [xmin, xmax, ymin, ymax]
• pixel_size (float) – Set pixel size of output raster. Default is calculated based on current pixel size and extent.
• bands (array-like) – Image band(s) to crop - default assumes first (only) band. Remember that numpy indices start at 0 - i.e., the first band is band 0.

Returns cropped_img:  

new GeoImg object resampled to the given image extent.

display(fig=None, cmap='gray', extent=None, sfact=None, showfig=True, band=[0, 1, 2], **kwargs)

Display GeoImg in a matplotlib figure.

Parameters:

• fig (matplotlib.figure.Figure) – figure handle to show image in. If not set, creates a new figure.
• cmap (matplotlib colormap) – colormap to use for the image. Default is gray.
• extent (array-like) – spatial extent to limit the figure to, given as xmin, xmax, ymin, ymax.
• sfact (int) – Factor by which to reduce the number of pixels plotted. Default is 1 (i.e., all pixels are displayed).
• showfig (bool) – Open the figure window. Default is True.
• band (array-like) – Image bands to use, if GeoImg represents a multi-band image.
• kwargs – Optional keyword arguments to pass to matplotlib.pyplot.imshow

Returns fig:

Handle pointing to the matplotlib Figure created (or passed to display).

find_corners(nodata=<MagicMock id='140228515441240'>, mode='ij')

Find corner coordinates of valid image area.

Parameters:

• nodata (numeric) – nodata value to use. Default is numpy.nan
• mode (str) – Type of coordinates to return. Options are ‘ij’, row/column index, or ‘xy’, x,y coordinate. Default is ‘ij’.

Returns corners:  

Array corresponding to the corner coordinates, estimated from the convex hull of the valid data.

find_valid_bbox(nodata=<MagicMock id='140228515448928'>)

Find bounding box for valid data.

Parameters:nodata (numeric) – nodata value to use for the image. Default is numpy.nan Returns bbox:xmin, xmax, ymin, ymax of valid image area.

ij2xy(ij)

Return x,y coordinates for a given row, column index pair.

Parameters:ij (float) – row (i) and column (j) index of pixel. Returns xy:x,y coordinates of i,j in the GeoImg’s spatial reference system.

info()

Prints information about the GeoImg (filename, coordinate system, number of columns/rows, etc.).

is_area()

Check if pixel coordinates correspond to pixel corners.

Returns is_area:  True if pixel coordinates correspond to pixel corners.

is_point()

Check if pixel coordinates correspond to pixel centers.

Returns is_point:  True if pixel coordinates correspond to pixel centers.

is_rotated()

Determine whether GeoImg is rotated with respect to North.

mask(mask, mask_value=True)

Mask image values.

Parameters:

• mask (array-like) – Array of same size as self.img corresponding to values that should be masked.
• mask_value (bool or numeric) – Value within mask to mask. If True, masks image where mask is True. If numeric, masks image where mask == mask_value.

match_sensor(fname, datestr=None, datefmt='')

Attempts to pull metadata (e.g., sensor, date information) from fname, setting sensor_name, satellite, tile, datetime, and date attributes of GeoImg object.

Parameters:

• fname (str) – filename of image to parse
• datestr (str) – optional datestring to set date attributes
• datefmt (str) – optional datetime format for datestr

mean()

Returns mean (ignoring NaNs) of the image.

median()

Returns median (ignoring NaNs) of the image.

outside_image(ij, index=True)

Check whether a given point falls outside of the image.

Parameters:

• ij (array-like) – Indices (or coordinates) of point to check.
• index (bool) – Interpret ij as raster indices (default is True). If False, assumes ij is coordinates.

Returns is_outside:  

True if ij is outside of the image.

overlay(raster, extent=None, vmin=0, vmax=10, sfact=None, showfig=True, alpha=0.25, cmap='jet')

Overlay raster on top of GeoImg.

Parameters:

• raster (array-like) – raster to display on top of the GeoImg.
• extent (array-like) – Spatial of the raster. If not set, assumed to be same as the extent of the GeoImg. Given as xmin, xmax, ymin, ymax.
• vmin (float) – minimum color value for the raster. Default is 0.
• vmax (float) – maximum color value for the raster. Default is 10.
• sfact (int) – Factor by which to reduce the number of points plotted. Default is 1 (i.e., all points are plotted).
• showfig (bool) – Open the figure window. Default is True.
• alpha (float) – Alpha value to use for the overlay. Default is 0.25
• cmap (str) – matplotlib.pyplot colormap to use for the image. Default is jet.

Returns fig:

Handle pointing to the matplotlib Figure created (or passed to display).

random_points(Npts, edge_buffer=None)

Generate a random sample of points within the image.

Parameters:

• Npts (int) – number of random points to sample.
• edge_buffer (int) – Optional buffer around edge of image, where pixels shouldn’t be sampled. Default is zero.

Returns rand_pts:  

array of N random points from within the image.

raster_points(pts, nsize=1, mode='linear')

Interpolate raster values at a given point, or sets of points.

Parameters:

• pts (array-like) – Point(s) at which to interpolate raster value. If points fall outside of image, value returned is nan.’
• nsize (int) – Number of neighboring points to include in the interpolation. Default is 1.
• mode (str) – One of ‘linear’, ‘cubic’, or ‘quintic’. Determines what type of spline is used to interpolate the raster value at each point. For more information, see scipy.interpolate.interp2d. Default is linear.

Returns rpts:

Array of raster value(s) for the given points.

raster_points2(pts, nsize=1, mode='linear')

Interpolate raster values at a given point, or sets of points using multiprocessing for speed.

Parameters:

• pts (array-like) – Point(s) at which to interpolate raster value. If points fall outside of image, value returned is nan.’
• nsize (int) – Number of neighboring points to include in the interpolation. Default is 1.
• mode (str) – One of ‘linear’, ‘cubic’, or ‘quintic’. Determines what type of spline is used to interpolate the raster value at each point. For more information, see scipy.interpolate.interp2d.

Returns rpts:

Array of raster value(s) for the given points.

reproject(dst_raster, driver='MEM', filename='', method=<MagicMock name='mock.GRA_Bilinear' id='140228513945192'>)

Reproject the GeoImg to the same extent and coordinate system as another GeoImg.

Parameters:

• dst_raster (GeoImg) – GeoImg to project given raster to.
• driver (str) – gdal driver to use to create the new GeoImg. Default is ‘MEM’ (in-memory). See gdal docs for more options. If a different driver is used, filename must also be specified.
• filename (str) – Filename corresponding to the new image, if not created in memory.
• method (gdal_GRA) – gdal resampling algorithm to use. Default is GRA_Bilinear. Other options include: GRA_Average, GRA_Cubic, GRA_CubicSpline, GRA_NearestNeighbour. See gdal docs for more options and details.

Returns new_geo:  

reprojected GeoImg.

set_NDV(NDV)

Set nodata value to given value

Parameters:NDV (numeric) – value to set to nodata.

shift(xshift, yshift)

Shift the GeoImg in space by a given x,y offset.

Parameters:

• xshift (float) – x offset to shift GeoImg by.
• yshift (float) – y offset to shift GeoImg by.

std()

Returns standard deviation (ignoring NaNs) of the image.

subimages(N, Ny=None, sBuffer=0)

Split the GeoImg into sub-images.

Parameters:

• N (int) – number of column cells to split the image into.
• Ny (int) – number of row cells to split image into. Default is same as N.
• sBuffer (int) – number of pixels to overlap subimages by. Default is 0.

Returns sub_images:  

list of GeoImg tiles.

to_area()

Change pixel location from center (‘Point’) to corner (‘Area’). Shifts raster by half pixel in the -x, +y direction.

to_point()

Change pixel location from corner (‘Area’) to center (‘Point’). Shifts raster by half pixel in the +x, -y direction.

unmask()

Remove mask from image. If mask is not set, has no effect.

write(outfilename, out_folder=None, driver='GTiff', dtype=None, bands=None)

Write GeoImg to a gdal-supported raster file.

Parameters:

• outfilename (str) – string representing the filename to be written to.
• out_folder (str) – optional string representing the folder to be written to. If not set, folder is either guessed from outfilename, or assumed to be the current folder.
• driver (str) – optional string representing the gdal driver to use to write the raster file. Default is GTiff. Options include: HDF4, HDF5, JPEG, PNG, JPEG2000 (if enabled). See gdal docs for more options.
• datatype (numpy datatype) – Type of data to write the raster as. Check GeoImg.numpy2gdal.keys() to see numpy data types implemented.
• bands (array-like) – Specify band(s) to write to file. Default behavior is all bands.

xy(ctype='corner', grid=True)

Get x,y coordinates of all pixels in the GeoImg.

Parameters:

• ctype (str) – coordinate type. If ‘corner’, returns corner coordinates of pixels. If ‘center’, returns center coordinates. Default is corner.
• grid (bool) – Return gridded coordinates. Default is True.

Returns x,y:

numpy arrays corresponding to the x,y coordinates of each pixel.

xy2ij(xy)

Return row, column indices for a given x,y coordinate pair.

Parameters:xy (float) – x, y coordinates in the GeoImg’s spatial reference system. Returns ij:i,j indices of x,y in the image.