geowombat.radiometry package#

Submodules#

geowombat.radiometry.angles module#

class geowombat.radiometry.angles.AngleInfo(vza, vaa, sza, saa)[source]#

Bases: object

Parameters:

  • vza (ndarray | DataArray | Array | Delayed | DelayedAttr | DelayedLeaf) –

  • vaa (ndarray | DataArray | Array | Delayed | DelayedAttr | DelayedLeaf) –

  • sza (ndarray | DataArray | Array | Delayed | DelayedAttr | DelayedLeaf) –

  • saa (ndarray | DataArray | Array | Delayed | DelayedAttr | DelayedLeaf) –

saa: Union[ndarray, DataArray, Array, Delayed, DelayedAttr, DelayedLeaf]#
sza: Union[ndarray, DataArray, Array, Delayed, DelayedAttr, DelayedLeaf]#
vaa: Union[ndarray, DataArray, Array, Delayed, DelayedAttr, DelayedLeaf]#
vza: Union[ndarray, DataArray, Array, Delayed, DelayedAttr, DelayedLeaf]#
geowombat.radiometry.angles.estimate_cloud_shadows(data, clouds, solar_za, solar_az, sensor_za, sensor_az, heights=None, num_workers=1)[source]#

Estimates shadows from a cloud mask and adds to the existing mask

Parameters:

  • data (DataArray) – The wavelengths, scaled 0-1.

  • clouds (DataArray) – The cloud mask, where clouds=1 and clear sky=0.

  • solar_za (DataArray) – The solar zenith angle.

  • solar_az (DataArray) – The solar azimuth angle.

  • sensor_za (DataArray) – The sensor, or view, zenith angle.

  • sensor_az (DataArray) – The sensor, or view, azimuth angle.

  • heights (Optional[list]) – The cloud heights, in kilometers.

  • num_workers (Optional[int]) – The number of dask workers.

Returns:

xarray.DataArray

References

For the angle offset calculations, see [Fis14]. For the shadow test, see [SLY+18].

geowombat.radiometry.angles.get_sentinel_angle_shape(metadata)[source]#

Gets the Sentinel scene angle array shape.

Parameters:

metadata (str | Path) – The Sentinel metadata XML file path.

Return type:

tuple

geowombat.radiometry.angles.get_sentinel_crs_transform(metadata, resample_res=10.0)[source]#

Gets the Sentinel scene transformation information.

Parameters:

  • metadata (str | Path) – The Sentinel metadata XML file path.

  • resample_res (float | int) – The cell resample resolution. Default is 10.0.

Return type:

tuple

geowombat.radiometry.angles.get_sentinel_sensor(metadata)[source]#

Gets the Sentinel sensor from metadata.

Parameters:

metadata (str | Path) – The Sentinel metadata XML file path.

Return type:

str

geowombat.radiometry.angles.landsat_angle_prep(ref_file, out_dir, l57_angles_path=None, l8_angles_path=None)[source]#
Return type:

Tuple[Path, namedtuple, str, str]

Parameters:

  • ref_file (str | Path) –

  • out_dir (str | Path) –

  • l57_angles_path (Path | str | None) –

  • l8_angles_path (Path | str | None) –

geowombat.radiometry.angles.landsat_pixel_angles(angles_file, ref_file, out_dir, sensor, l57_angles_path=None, l8_angles_path=None, subsample=1, resampling='bilinear', num_workers=1, verbose=0, chunks=256)[source]#

Generates Landsat pixel angle files.

Parameters:

  • angles_file (str) – The angles file.

  • ref_file (str) – A reference file.

  • out_dir (str) – The output directory.

  • sensor (str) – The sensor.

  • l57_angles_path (str) – The path to the Landsat 5 and 7 angles bin.

  • l8_angles_path (str) – The path to the Landsat 8 angles bin.

  • subsample (Optional[int]) – The sub-sample factor when calculating the angles.

  • resampling (Optional[str]) – The resampling method if filename is a list. Choices are [‘average’, ‘bilinear’, ‘cubic’, ‘cubic_spline’, ‘gauss’, ‘lanczos’, ‘max’, ‘med’, ‘min’, ‘mode’, ‘nearest’].

  • num_workers (Optional[int]) – The maximum number of concurrent workers.

  • verbose (Optional[int]) – The verbosity level.

  • chunks (Optional[int]) – The file chunk size. Default is 256.

Return type:

AngleInfo

Returns:

zenith and azimuth angles as a namedtuple of angle file names

geowombat.radiometry.angles.open_angle_file(in_angle_path, chunks, band_pos, nodata, subsample)[source]#
Return type:

DataArray

Parameters:

  • in_angle_path (str | Path) –

  • chunks (int) –

  • band_pos (int) –

  • nodata (float | int) –

  • subsample (int) –

geowombat.radiometry.angles.parse_sentinel_angles(metadata, proc_angles, nodata)[source]#

Gets the Sentinel-2 solar angles from metadata.

Reference:

hevgyrt/safe_to_netcdf

Parameters:

  • metadata (str | Path) – The Sentinel metadata XML file path.

  • proc_angles (str) – The angles to parse. Choices are [‘solar’, ‘view’].

  • nodata (int or float) – The ‘no data’ value.

Returns:

zenith and azimuth angles as a tuple of 2d numpy arrays

geowombat.radiometry.angles.postprocess_espa_angles(ref_file, angle_paths_in, angle_paths_out, subsample, resampling, num_workers, chunks)[source]#
Return type:

AngleInfo

Parameters:

  • ref_file (str | Path) –

  • angle_paths_in (namedtuple) –

  • angle_paths_out (namedtuple) –

  • subsample (int) –

  • resampling (str) –

  • num_workers (int) –

  • chunks (int) –

geowombat.radiometry.angles.relative_azimuth(saa, vaa)[source]#

Calculates the relative azimuth angle.

Parameters:

  • saa (DataArray) – The solar azimuth angle (in degrees).

  • vaa (DataArray) – The view azimuth angle (in degrees).

Return type:

DataArray

Reference:

http://stcorp.github.io/harp/doc/html/algorithms/derivations/relative_azimuth_angle.html

Return type:

DataArray

Returns:

Relative azimuth (in degrees) as an xarray.DataArray

Parameters:

  • saa (DataArray) –

  • vaa (DataArray) –

geowombat.radiometry.angles.resample_angles(angle_array, nrows, ncols, data_shape, chunksize)[source]#

Resamples an angle array.

Return type:

Array

Parameters:

  • angle_array (ndarray) –

  • nrows (int) –

  • ncols (int) –

  • data_shape (Tuple[int, int]) –

  • chunksize (Tuple[int, int]) –

geowombat.radiometry.angles.run_espa_command(ref_angle_file, angles_file, sensor, l57_angles_path, l8_angles_path, subsample, out_dir, verbose)[source]#
Return type:

namedtuple

Parameters:

  • ref_angle_file (str | Path) –

  • angles_file (str | Path) –

  • sensor (str) –

  • l57_angles_path (str | Path) –

  • l8_angles_path (str | Path) –

  • subsample (float | int) –

  • out_dir (str | Path) –

  • verbose (int) –

geowombat.radiometry.angles.scattering_angle(cos_sza, cos_vza, sin_sza, sin_vza, cos_raa)[source]#

Calculates the scattering angle.

Parameters:

  • cos_sza (DataArray) – The cosine of the solar zenith angle.

  • cos_vza (DataArray) – The cosine of the view zenith angle.

  • sin_sza (DataArray) – The sine of the solar zenith angle.

  • sin_vza (DataArray) – The sine of the view zenith angle.

  • cos_raa (DataArray) – The cosine of the relative azimuth angle.

Return type:

DataArray

Equation:

\[ \begin{align}\begin{aligned}\Theta = scattering angle\\\theta_0 = solar zenith angle\\\theta_S = sensor zenith angle\\\zeta = relative azimuth angle\\\Theta_s = \arccos{- \cos{\theta_0} \cos{\theta_S} - \sin{\theta_0} \sin{\theta_S} \cos{\zeta}}\end{aligned}\end{align} \]

References

scattering angle = the angle between the direction of incident and scattered radiation Liu, CH and Liu GR (2009) AEROSOL OPTICAL DEPTH RETRIEVAL FOR SPOT HRV IMAGES, Journal of Marine Science and Technology http://stcorp.github.io/harp/doc/html/algorithms/derivations/scattering_angle.html

Return type:

DataArray

Returns:

Scattering angle (in radians) as an xarray.DataArray

Parameters:

  • cos_sza (DataArray) –

  • cos_vza (DataArray) –

  • sin_sza (DataArray) –

  • sin_vza (DataArray) –

  • cos_raa (DataArray) –

geowombat.radiometry.angles.sentinel_pixel_angles(metadata, ref_file, nodata=-32768, resampling='bilinear', num_workers=1, resample_res=60.0, chunksize=None)[source]#

Generates Sentinel pixel angle files.

Parameters:

  • metadata (str) – The metadata file.

  • ref_file (str) – A reference image to use for geo-information.

  • nodata (Optional[int or float]) – The ‘no data’ value.

  • num_workers (Optional[int]) – The maximum number of concurrent workers.

  • resample_res (Optional[float]) – The resolution to resample to.

  • resampling (str) –

  • chunksize (Tuple[int, int] | None) –

Return type:

AngleInfo

References

https://www.sentinel-hub.com/faq/how-can-i-access-meta-data-information-sentinel-2-l2a marujore/sentinel_angle_bands

Return type:

AngleInfo

Returns:

zenith and azimuth angles as a namedtuple of angle file names

Parameters:

  • metadata (str | Path) –

  • ref_file (str | Path) –

  • nodata (float | int) –

  • resampling (str) –

  • num_workers (int) –

  • resample_res (float | int) –

  • chunksize (Tuple[int, int] | None) –

geowombat.radiometry.angles.shift_objects(data, solar_za, solar_az, sensor_za, sensor_az, object_height, num_workers)[source]#

Shifts objects along x and y dimensions.

Parameters:

  • data (DataArray) – The data to shift.

  • solar_za (DataArray) – The solar zenith angle.

  • solar_az (DataArray) – The solar azimuth angle.

  • sensor_za (DataArray) – The sensor, or view, zenith angle.

  • sensor_az (DataArray) – The sensor, or view, azimuth angle.

  • object_height (float) – The object height.

  • num_workers (Optional[int]) – The number of dask workers.

Returns:

xarray.DataArray

geowombat.radiometry.angles.transform_angles(ref_file, data, nodata, resampling, num_workers, angle_array_dict, angle_name)[source]#

Transforms angles to a new CRS.

Return type:

dict

Parameters:

  • ref_file (str | Path) –

  • data (DataArray) –

  • nodata (float | int) –

  • resampling (str) –

  • num_workers (int) –

  • angle_array_dict (dict) –

  • angle_name (str) –

geowombat.radiometry.brdf module#

class geowombat.radiometry.brdf.Angles[source]#

Bases: object

Methods

get_angle_info(vza, sza, raa, m_pi)

Gets the angle information.

get_pangles(tan1, br, nearly_zero)

Get the prime angles.

get_phaang(cos_vza, cos_sza, sin_vza, ...)

Gets the phase angle.
static get_angle_info(vza, sza, raa, m_pi)[source]#

Gets the angle information.

static get_pangles(tan1, br, nearly_zero)[source]#

Get the prime angles.

static get_phaang(cos_vza, cos_sza, sin_vza, sin_sza, cos_raa)[source]#

Gets the phase angle.

class geowombat.radiometry.brdf.BRDF[source]#

Bases: GeoVolKernels

A class for Bidirectional Reflectance Distribution Function (BRDF) normalization.

Methods

get_mean_sza(central_latitude)

Returns the mean solar zenith angle (SZA) as a function of the central latitude.

norm_brdf(data, solar_za, solar_az, ...[, ...])

Applies Nadir Bidirectional Reflectance Distribution Function (BRDF) normalization using the global c-factor method

get_kernels
norm_brdf(data, solar_za, solar_az, sensor_za, sensor_az, central_latitude=None, sensor=None, wavelengths=None, src_nodata=-32768, dst_nodata=-32768, mask=None, scale_factor=1.0, out_range=None, scale_angles=True, vol_weight=1.0)[source]#

Applies Nadir Bidirectional Reflectance Distribution Function (BRDF) normalization using the global c-factor method

Parameters:

  • data (2d or 3d DataArray) – The data to normalize.

  • solar_za (2d DataArray) – The solar zenith angles (degrees).

  • solar_az (2d DataArray) – The solar azimuth angles (degrees).

  • sensor_za (2d DataArray) – The sensor azimuth angles (degrees).

  • sensor_az (2d DataArray) – The sensor azimuth angles (degrees).

  • central_latitude (Optional[float or 2d DataArray]) – The central latitude.

  • sensor (Optional[str]) – The satellite sensor.

  • wavelengths (str list) – The wavelength(s) to normalize.

  • src_nodata (Optional[int or float]) – The input ‘no data’ value.

  • dst_nodata (Optional[int or float]) – The output ‘no data’ value.

  • mask (Optional[DataArray]) – A data mask, where clear values are 0.

  • scale_factor (Optional[float]) – A scale factor to apply to the input data.

  • out_range (Optional[float]) – The out data range. If not given, the output data are return in a 0-1 range.

  • scale_angles (Optional[bool]) – Whether to scale the pixel angle arrays.

  • vol_weight (Optional[float]) – Weight to be applied to the volumetric kernel in the c-factor equation

References

See [RZJ+16] for the c-factor method.

For further background on BRDF:

Returns:

xarray.DataArray

Examples

>>> import geowombat as gw
>>> from geowombat.radiometry import BRDF
>>>
>>> brdf = BRDF()
>>>
>>> # Example where pixel angles are stored in separate GeoTiff files
>>> with gw.config.update(sensor='l7', scale_factor=0.0001):
>>>
>>>     with gw.open('solarz.tif') as solarz,
>>>         gw.open('solara.tif') as solara,
>>>             gw.open('sensorz.tif') as sensorz,
>>>                 gw.open('sensora.tif') as sensora:
>>>
>>>         with gw.open('landsat.tif') as src:
>>>             src_norm = brdf.norm_brdf(src, solarz, solara, sensorz, sensora)
class geowombat.radiometry.brdf.BRDFKernels(vza, sza, raa, li_type='sparse', ross_type='thick', li_recip=True, br=1.0, hb=2.0, hs=False)[source]#

Bases: LiKernel, RossKernel

A class for the Li and Ross BRDF kernels.

Parameters:

  • vza (dask.array) – The view zenith angle.

  • sza (dask.array) – The solar zenith angle.

  • raa (dask.array) – The relative azimuth angle.

  • li_type (Optional[str]) – The Li kernel type. Choices are [‘sparse’, ‘dense’].

  • ross_type (Optional[str]) – The Ross kernel type. Choices are [‘thin’, ‘thick’].

  • br (Optional[float]) – The BR ratio.

  • hb (Optional[float]) – The HB ratio.

Methods

get_angle_info(vza, sza, raa, m_pi)

Gets the angle information.

get_distance(tan1, tan2, cos3)

Gets distance component of Li kernels.

get_overlap(cos1, cos2, tan1, tan2, sin3, ...)

Applies the HB ratio transformation.

get_pangles(tan1, br, nearly_zero)

Get the prime angles.

get_phaang(cos_vza, cos_sza, sin_vza, ...)

Gets the phase angle.

ross_part(angle_info, global_args)

Calculates the main part of Ross kernel.

get_li

get_ross

ross_thick

ross_thin
class geowombat.radiometry.brdf.GeoVolKernels[source]#

Bases: object

Methods

get_mean_sza(central_latitude)

Returns the mean solar zenith angle (SZA) as a function of the central latitude.

get_kernels
get_kernels(central_latitude, solar_za, solar_az, sensor_za, sensor_az)[source]#
static get_mean_sza(central_latitude)[source]#

Returns the mean solar zenith angle (SZA) as a function of the central latitude.

Parameters:

central_latitude (float) – The central latitude.

Reference:

See [ZRK16]

Returns:

float

class geowombat.radiometry.brdf.LiKernel[source]#

Bases: Special, Angles

Methods

get_angle_info(vza, sza, raa, m_pi)

Gets the angle information.

get_distance(tan1, tan2, cos3)

Gets distance component of Li kernels.

get_overlap(cos1, cos2, tan1, tan2, sin3, ...)

Applies the HB ratio transformation.

get_pangles(tan1, br, nearly_zero)

Get the prime angles.

get_phaang(cos_vza, cos_sza, sin_vza, ...)

Gets the phase angle.

get_li
get_li(kernel_type, li_recip)[source]#
class geowombat.radiometry.brdf.RossKernel[source]#

Bases: Special, Angles

Methods

get_angle_info(vza, sza, raa, m_pi)

Gets the angle information.

get_distance(tan1, tan2, cos3)

Gets distance component of Li kernels.

get_overlap(cos1, cos2, tan1, tan2, sin3, ...)

Applies the HB ratio transformation.

get_pangles(tan1, br, nearly_zero)

Get the prime angles.

get_phaang(cos_vza, cos_sza, sin_vza, ...)

Gets the phase angle.

ross_part(angle_info, global_args)

Calculates the main part of Ross kernel.

get_ross

ross_thick

ross_thin
get_ross(kernel_type)[source]#
ross_part(angle_info, global_args)[source]#

Calculates the main part of Ross kernel.

static ross_thick(ross_outputs)[source]#
static ross_thin(ross_outputs)[source]#
class geowombat.radiometry.brdf.Special[source]#

Bases: object

Methods

get_distance(tan1, tan2, cos3)

Gets distance component of Li kernels.

get_overlap(cos1, cos2, tan1, tan2, sin3, ...)

Applies the HB ratio transformation.
static get_distance(tan1, tan2, cos3)[source]#

Gets distance component of Li kernels.

static get_overlap(cos1, cos2, tan1, tan2, sin3, distance, hb, m_pi)[source]#

Applies the HB ratio transformation.

geowombat.radiometry.mask module#

class geowombat.radiometry.mask.CloudShadowMasker[source]#

Bases: object

Methods

mask_s2(data, solar_za, solar_az[, ...])

Masks Sentinel 2 data.
static mask_s2(data, solar_za, solar_az, cloud_heights=None, nodata=None, scale_factor=1, num_workers=1, **kwargs)[source]#

Masks Sentinel 2 data.

Parameters:

  • data (DataArray) – The Sentinel 2 data to mask.

  • solar_za (DataArray) – The solar zenith angle.

  • solar_az (DataArray) – The solar azimuth angle.

  • cloud_heights (Optional[list]) – A list of potential cloud heights.

  • nodata (Optional[int or float]) – A ‘no data’ value to fill NAs with.

  • scale_factor (Optional[float]) – A scale factor to apply to the data.

  • num_workers (Optional[int]) – The number of parallel compute workers.

  • kwargs (Optional[dict]) – Keyword arguments for s2cloudless.S2PixelCloudDetector.

Returns:

Data range: 0 to 4, where 0=clear; 2=shadow; 4=cloud

Return type:

xarray.DataArray

Example

>>> import geowombat as gw
>>> from geowombat.radiometry import mask_s2
>>>
>>> with gw.config.update(sensor='s2f', scale_factor=0.0001):
>>>
>>>     with gw.open('image.tif') as src,             >>>         gw.open('solar_zenith.tif') as sza,             >>>             gw.open('solar_azimuth.tif') as saa:
>>>
>>>         s2_mask = mask_s2(src, sza, saa)
geowombat.radiometry.mask.estimate_shadows(data, cloud_mask, solar_zenith, solar_azimuth, cloud_heights, nodata, scale_factor, num_workers)[source]#

Estimates shadows from masked clouds, solar angle, and solar azimuth.

Parameters:

  • data (DataArray) –

  • cloud_mask (DataArray) –

  • solar_zenith (DataArray) –

  • solar_azimuth (DataArray) –

  • cloud_heights (list) –

  • nodata (int | float) –

  • scale_factor (float) –

  • num_workers (int) – The number of parallel compute workers.

Reference:

samsammurphy/cloud-masking-sentinel2

Returns:

Data range: 0 to 1, where 0=non-shadow; 1=shadow

Return type:

xarray.DataArray

geowombat.radiometry.qa module#

class geowombat.radiometry.qa.QABits(value)[source]#

Bases: Enum

QA bits.

Reference:

https://www.usgs.gov/landsat-missions/landsat-project-documents

landsat_c2_l2 = {'cirrus': 2, 'clear': 6, 'cloud': 3, 'cloud_shadow': 4, 'dilated_cloud': 1, 'fill': 0, 'snow': 5, 'water': 7}#
class geowombat.radiometry.qa.QAMasker(qa, sensor, mask_items=None, modis_qa_band=1, modis_quality=2, confidence_level='yes')[source]#

Bases: object

A class for masking bit-packed quality flags.

Parameters:

  • qa (DataArray) – The band quality array.

  • sensor (str) –

    The sensor name. Choices are [‘ard’, ‘hls’, ‘l8-pre’, ‘l8-c1’, ‘l-c1’, ‘modis’, ‘s2a’, ‘s2c’].

    Codes:
    ’ard’:

    USGS Landsat Analysis Ready Data <https://www.usgs.gov/land-resources/nli/landsat/us-landsat-analysis-ready-data?qt-science_support_page_related_con=0#qt-science_support_page_related_con>`_

    ’hls’:

    NASA Harmonized Landsat Sentinel

    ’l-c1’:

    Landsat Collection 1 L4-5 and L7

    ’l8-c1’:

    Landsat Collection 1 L8

    ’s2a’:

    Sentinel 2A (surface reflectance)

    ’s2c’:

    Sentinel 2C (top of atmosphere)

  • mask_items (str list) – A list of items to mask.

  • modis_qa_position (Optional[int]) – The MODIS QA band position. Default is 1.

  • modis_quality (Optional[int]) – The MODIS quality level. Default is 2.

  • confidence_level (Optional[str]) – The confidence level. Choices are [‘notdet’, ‘no’, ‘maybe’, ‘yes’].

References

Landsat Collection 1:

https://landsat.usgs.gov/collectionqualityband

Examples

>>> import geowombat as gw
>>> from geowombat.radiometry import QAMasker
>>>
>>> # Get the MODIS cloud mask.
>>> with gw.open('qa.tif') as qa:
>>>     mask = QAMasker(qs, 'modis').to_mask()
>>>
>>> # NASA HLS
>>> with gw.open('qa.tif') as qa:
>>>     mask = QAMasker(qs, 'hls', ['cloud']).to_mask()

Methods

to_mask()

Converts QA bit-packed data to an integer mask.
to_mask()[source]#

Converts QA bit-packed data to an integer mask.

Returns:

0: clear, 1: water, 2: shadow, 3: snow or ice, 4: cloud, 5: cirrus cloud, 6: adjacent cloud, 7: saturated, 8: dropped, 9: terrain occluded, 255: fill

Return type:

xarray.DataArray

geowombat.radiometry.sixs module#

interpolated_LUTs.py.

The Interpolated_LUTs class handles loading, downloading and interpolating of LUTs (look up tables) used by the 6S emulator

Reference:

samsammurphy/6S_emulator

class geowombat.radiometry.sixs.AOT[source]#

Bases: SixSMixin

Methods

get_optimized_aot(blue_rad_dark, ...[, max_aot])

Gets the optimal aerosol optical thickness.
get_optimized_aot(blue_rad_dark, blue_p_dark, sensor, wavelength, interp_method, sza, doy, h2o, o3, altitude, max_aot=0.5)[source]#

Gets the optimal aerosol optical thickness.

Parameters:

  • blue_rad_dark (DataArray) –

  • blue_p_dark (DataArray) –

  • sensor (str) –

  • wavelength (str) –

  • interp_method (str) –

  • sza (float) – The solar zenith angle (in degrees).

  • doy (int) – The day of year.

  • h2o (float) – The water vapor (g/m^2). [0,8.5].

  • o3 (float) – The ozone (cm-atm). [0,8].

  • altitude (float) –

  • max_aot (float) –

class geowombat.radiometry.sixs.Altitude[source]#

Bases: object

Methods

get_mean_altitude
static get_mean_altitude(data, out_dir, username=None, key_file=None, code_file=None, chunks=512, n_jobs=1, delete_downloaded=False)[source]#
class geowombat.radiometry.sixs.LUTNames(name, path)#

Bases: tuple

Methods

count(value, /)

Return number of occurrences of value.

index(value[, start, stop])

Return first index of value.
name#

Alias for field number 0

path#

Alias for field number 1

class geowombat.radiometry.sixs.SixS[source]#

Bases: Altitude, SixSMixin

A class to handle loading, downloading and interpolating of LUTs (look up tables) used by the 6S emulator.

Parameters:

  • sensor (str) – The sensor to adjust.

  • rad_scale (Optional[float]) – The radiance scale factor. Scaled values should be in the range [0,1000].

  • angle_factor (Optional[float]) – The angle scale factor.

Example

>>> sixs = SixS('l5', verbose=1)
>>>
>>> with gw.config.update(sensor='l7'):
>>>     with gw.open('image.tif') as src, gw.open('solar_za') as sza:
>>>         sixs.rad_to_sr(src, 'blue', sza, doy, h2o=1.0, o3=0.4, aot=0.3)

Methods

rad_to_sr(data, sensor, wavelength, sza, doy)

Converts radiance to surface reflectance using a 6S radiative transfer model lookup table.

toar_to_sr(data, sensor, wavelength, sza, doy)

Converts top of atmosphere reflectance to surface reflectance using 6S outputs.

get_mean_altitude

prepare_coeff
static prepare_coeff(band_data, coeffs, cindex)[source]#
rad_to_sr(data, sensor, wavelength, sza, doy, src_nodata=-32768, dst_nodata=-32768, angle_factor=0.01, interp_method='fast', h2o=1.0, o3=0.4, aot=0.3, altitude=0.0, n_jobs=1)[source]#

Converts radiance to surface reflectance using a 6S radiative transfer model lookup table.

Parameters:

  • data (DataArray) – The data to correct, in radiance.

  • sensor (str) – The sensor name.

  • wavelength (str) – The band wavelength to process.

  • sza (float | DataArray) – The solar zenith angle.

  • doy (int) – The day of year.

  • src_nodata (Optional[int or float]) – The input ‘no data’ value.

  • dst_nodata (Optional[int or float]) – The output ‘no data’ value.

  • angle_factor (Optional[float]) – The scale factor for angles.

  • interp_method (Optional[str]) – The LUT interpolation method. Choices are [‘fast’, ‘slow’]. ‘fast’: Uses nearest neighbor lookup with scipy.interpolate.NearestNDInterpolator. ‘slow’: Uses linear interpolation with scipy.interpolate.LinearNDInterpolator.

  • h2o (Optional[float]) – The water vapor (g/m^2). [0,8.5].

  • o3 (Optional[float]) – The ozone (cm-atm). [0,8].

  • aot (Optional[float | DataArray]) – The aerosol optical thickness (unitless). [0,3].

  • altitude (Optional[float]) – The altitude over the sensor acquisition location.

  • n_jobs (Optional[int]) – The number of parallel jobs for dask.compute.

Returns:

Data range: 0-1

Return type:

xarray.DataArray

toar_to_sr(data, sensor, wavelength, sza, doy, src_nodata=-32768, dst_nodata=-32768, angle_factor=0.01, interp_method='fast', h2o=1.0, o3=0.4, aot=0.3, altitude=0.0, n_jobs=1)[source]#

Converts top of atmosphere reflectance to surface reflectance using 6S outputs.

Parameters:

  • data (DataArray) – The top of atmosphere reflectance.

  • sensor (str) – The sensor name.

  • wavelength (str) – The band wavelength to process.

  • sza (float | DataArray) – The solar zenith angle.

  • doy (int) – The day of year.

  • src_nodata (Optional[int or float]) – The input ‘no data’ value.

  • dst_nodata (Optional[int or float]) – The output ‘no data’ value.

  • angle_factor (Optional[float]) – The scale factor for angles.

  • interp_method (Optional[str]) – The LUT interpolation method. Choices are [‘fast’, ‘slow’]. ‘fast’: Uses nearest neighbor lookup with scipy.interpolate.NearestNDInterpolator. ‘slow’: Uses linear interpolation with scipy.interpolate.LinearNDInterpolator.

  • h2o (Optional[float]) – The water vapor (g/m^2). [0,8.5].

  • o3 (Optional[float]) – The ozone (cm-atm). [0,8].

  • aot (Optional[float | DataArray]) – The aerosol optical thickness (unitless). [0,3].

  • altitude (Optional[float]) – The altitude over the sensor acquisition location.

  • n_jobs (Optional[int]) – The number of parallel jobs for dask.compute.

6S model outputs:
t_g (float): The total gaseous transmission of the atmosphere.

s.run() –> s.outputs.total_gaseous_transmittance

p_alpha (float): The atmospheric reflectance.

s.run() –> s.outputs.atmospheric_intrinsic_reflectance

s (float): The spherical albedo of the atmosphere.

s.run() –> s.outputs.spherical_albedo

t_s (float): The atmospheric transmittance from sun to target.

s.run() –> s.outputs.transmittance_total_scattering.downward

t_v (float): The atmospheric transmittance from target to satellite.

s.run() –> s.outputs.transmittance_total_scattering.upward

class geowombat.radiometry.sixs.SixSMixin[source]#

Bases: object

geowombat.radiometry.sr module#

class geowombat.radiometry.sr.DOS[source]#

Bases: AOT, RadTransforms

Methods

dn_to_radiance(dn, gain, bias)

Converts digital numbers to radiance.

dn_to_sr(dn, solar_za, solar_az, sensor_za, ...)

Converts digital numbers to surface reflectance.

dn_to_toar(dn, gain, bias[, solar_za, ...])

Converts digital numbers to top-of-atmosphere reflectance.

get_aot(data, sza, meta[, data_values, ...])

Gets the aerosol optical thickness (AOT) from dark objects.

get_landsat_coefficients(meta_file)

Gets coefficients from a Landsat metadata file.

get_optimized_aot(blue_rad_dark, ...[, max_aot])

Gets the optimal aerosol optical thickness.

get_sentinel_coefficients(meta_file)

Gets coefficients from a Sentinel metadata file.

radiance_to_toar(radiance, solar_za, global_args)

Converts radiance to top-of-atmosphere reflectance.

toar_to_rad(toar, meta)

Converts top of atmosphere reflectance to top of atmosphere radiance.

toar_to_sr(toar, solar_za, solar_az, ...[, ...])

Converts top-of-atmosphere reflectance to surface reflectance.
get_aot(data, sza, meta, data_values='dn', angle_factor=0.01, dn_interp=None, interp_method='fast', aot_fallback=0.3, h2o=2.0, o3=0.3, altitude=0.0, w=None, n_jobs=1)[source]#

Gets the aerosol optical thickness (AOT) from dark objects.

Parameters:

  • data (DataArray) – The digital numbers or top of atmosphere reflectance at a coarse resolution.

  • sza (float | DataArray) – The solar zenith angle.

  • meta (Optional[namedtuple]) – A metadata object with gain and bias coefficients.

  • data_values (Optional[str]) – The values of data. Choices are [‘dn’, ‘toar’].

  • angle_factor (Optional[float]) – The scale factor for angles.

  • dn_interp (Optional[DataArray]) – A source DataArray at the target resolution.

  • interp_method (Optional[str]) – The LUT interpolation method. Choices are [‘fast’, ‘slow’]. ‘fast’: Uses nearest neighbor lookup with scipy.interpolate.NearestNDInterpolator. ‘slow’: Uses linear interpolation with scipy.interpolate.LinearNDInterpolator.

  • aot_fallback (Optional[float | DataArray]) – The aerosol optical thickness fallback if no dark objects are found (unitless). [0,3].

  • h2o (Optional[float]) – The water vapor (g/m^2). [0,8.5].

  • o3 (Optional[float]) – The ozone (cm-atm). [0,8].

  • altitude (Optional[float]) – The altitude over the sensor acquisition location (km above sea level).

  • w (Optional[int]) – The smoothing window size (in pixels).

  • n_jobs (Optional[int]) – The number of parallel jobs for moving_window and dask.compute.

Returns:

Data range: 0-3

Return type:

xarray.DataArray

References

See [MVS+06], [KWR+97], and [OV99].

class geowombat.radiometry.sr.LinearAdjustments[source]#

Bases: object

A class for linear bandpass adjustments.

Methods

bandpass(data[, sensor, to, band_names, ...])

Applies a bandpass adjustment by applying a linear function to surface reflectance values.
bandpass(data, sensor=None, to='l8', band_names=None, scale_factor=1, src_nodata=0, dst_nodata=0)[source]#

Applies a bandpass adjustment by applying a linear function to surface reflectance values.

Parameters:

  • data (DataArray) – The data to adjust.

  • sensor (Optional[str]) – The sensor to adjust.

  • to (Optional[str]) – The sensor to adjust to.

  • band_names (Optional[list]) – The bands to adjust. If not given, all bands are adjusted.

  • scale_factor (Optional[float]) – A scale factor to apply to the input data.

  • src_nodata (Optional[int or float]) – The input ‘no data’ value.

  • dst_nodata (Optional[int or float]) – The output ‘no data’ value.

Reference:

Sentinel-2 and Landsat 8:

Landsat 7 and Landsat 8:

See [RZJ+16] (Table 2)

Returns:

xarray.DataArray

Examples

>>> import geowombat as gw
>>> from geowombat.radiometry import LinearAdjustments
>>>
>>> la = LinearAdjustments()
>>>
>>> # Adjust all Sentinel-2 bands to Landsat 8
>>> with gw.config.update(sensor='s2'):
>>>     with gw.open('sentinel-2.tif') as ds:
>>>         ds_adjusted = la.bandpass(ds, to='l8')
class geowombat.radiometry.sr.MetaData[source]#

Bases: object

A class for sensor metadata.

Methods

get_landsat_coefficients(meta_file)

Gets coefficients from a Landsat metadata file.

get_sentinel_coefficients(meta_file)

Gets coefficients from a Sentinel metadata file.
static get_landsat_coefficients(meta_file)[source]#

Gets coefficients from a Landsat metadata file.

Parameters:

meta_file (str) – The text metadata file.

Returns:

sensor, m_l, a_l, m_p, a_p, date_acquired, sza

Return type:

namedtuple

static get_sentinel_coefficients(meta_file)[source]#

Gets coefficients from a Sentinel metadata file.

Parameters:

meta_file (str) – The XML metadata file.

Returns:

sensor, date_acquired, sza

Return type:

namedtuple

class geowombat.radiometry.sr.RadTransforms[source]#

Bases: MetaData

A class for radiometric transformations.

Methods

dn_to_radiance(dn, gain, bias)

Converts digital numbers to radiance.

dn_to_sr(dn, solar_za, solar_az, sensor_za, ...)

Converts digital numbers to surface reflectance.

dn_to_toar(dn, gain, bias[, solar_za, ...])

Converts digital numbers to top-of-atmosphere reflectance.

get_landsat_coefficients(meta_file)

Gets coefficients from a Landsat metadata file.

get_sentinel_coefficients(meta_file)

Gets coefficients from a Sentinel metadata file.

radiance_to_toar(radiance, solar_za, global_args)

Converts radiance to top-of-atmosphere reflectance.

toar_to_rad(toar, meta)

Converts top of atmosphere reflectance to top of atmosphere radiance.

toar_to_sr(toar, solar_za, solar_az, ...[, ...])

Converts top-of-atmosphere reflectance to surface reflectance.
dn_to_radiance(dn, gain, bias)[source]#

Converts digital numbers to radiance.

Parameters:

  • dn (DataArray) – The digital number data to calibrate.

  • gain (DataArray) – A gain value.

  • bias (DataArray) – A bias value.

Returns:

xarray.DataArray

dn_to_sr(dn, solar_za, solar_az, sensor_za, sensor_az, src_nodata=-32768, dst_nodata=-32768, sensor=None, method='srem', angle_factor=0.01, meta=None, interp_method='fast', **kwargs)[source]#

Converts digital numbers to surface reflectance.

Parameters:

  • dn (DataArray) – The digital number data to calibrate.

  • solar_za (DataArray) – The solar zenith angle.

  • solar_az (DataArray) – The solar azimuth angle.

  • sensor_za (DataArray) – The sensor, or view, zenith angle.

  • sensor_az (DataArray) – The sensor, or view, azimuth angle.

  • src_nodata (Optional[int or float]) – The input ‘no data’ value.

  • dst_nodata (Optional[int or float]) – The output ‘no data’ value.

  • sensor (Optional[str]) – The data’s sensor.

  • method (Optional[str]) – The correction method to use. Choices are [‘srem’, ‘6s’].

  • angle_factor (Optional[float]) – The scale factor for angles.

  • meta (Optional[namedtuple]) – A metadata object with gain and bias coefficients.

  • interp_method (Optional[str]) – The LUT interpolation method if method = ‘6s’. Choices are [‘fast’, ‘slow’]. ‘fast’: Uses nearest neighbor lookup with scipy.interpolate.NearestNDInterpolator. ‘slow’: Uses linear interpolation with scipy.interpolate.LinearNDInterpolator.

  • kwargs (Optional[dict]) – Extra keyword arguments passed to radiometry.sixs.SixS().rad_to_sr.

References

https://www.usgs.gov/land-resources/nli/landsat/using-usgs-landsat-level-1-data-product

Returns:

Data range: 0-1

Return type:

xarray.DataArray

Examples

>>> from geowombat.radiometry import RadTransforms
>>>
>>> sr = RadTransforms()
>>> meta = sr.get_landsat_coefficients('file.MTL')
>>>
>>> # Convert DNs to surface reflectance using Landsat metadata
>>> with gw.open('dn.tif') as ds:
>>>     sr_data = sr.dn_to_sr(ds, solar_za, sensor_za, meta=meta)
dn_to_toar(dn, gain, bias, solar_za=None, angle_factor=0.01, sun_angle=True)[source]#

Converts digital numbers to top-of-atmosphere reflectance.

Parameters:

  • dn (DataArray) – The digital number data to calibrate.

  • gain (DataArray | dict) – A gain value.

  • bias (DataArray | dict) – A bias value.

  • solar_za (DataArray) – The solar zenith angle.

  • angle_factor (Optional[float]) – The scale factor for angles.

  • sun_angle (Optional[bool]) – Whether to correct for the sun angle.

Returns:

xarray.DataArray

static radiance_to_toar(radiance, solar_za, global_args)[source]#

Converts radiance to top-of-atmosphere reflectance.

Parameters:

  • radiance (DataArray) – The radiance data to calibrate.

  • solar_za (DataArray) – The solar zenith angle.

  • global_args (namedtuple) – Global arguments.

Returns:

xarray.DataArray

static toar_to_rad(toar, meta)[source]#

Converts top of atmosphere reflectance to top of atmosphere radiance.

Parameters:

  • toar (DataArray) – The top of atmosphere reflectance (0-1).

  • sza (float | DataArray) – The solar zenith angle (in degrees).

  • meta (Optional[namedtuple]) – A metadata object with gain and bias coefficients.

Returns:

xarray.DataArray

toar_to_sr(toar, solar_za, solar_az, sensor_za, sensor_az, sensor=None, src_nodata=-32768, dst_nodata=-32768, method='srem', angle_factor=0.01, meta=None, interp_method='fast', **kwargs)[source]#

Converts top-of-atmosphere reflectance to surface reflectance.

Parameters:

  • toar (DataArray) – The top-of-atmosphere reflectance (0-1).

  • solar_za (float | DataArray) – The solar zenith angle.

  • solar_az (DataArray) – The solar azimuth angle.

  • sensor_za (DataArray) – The sensor zenith angle.

  • sensor_az (DataArray) – The sensor azimuth angle.

  • sensor (Optional[str]) – The data’s sensor.

  • src_nodata (Optional[int or float]) – The input ‘no data’ value.

  • dst_nodata (Optional[int or float]) – The output ‘no data’ value.

  • method (Optional[str]) –

    The method to use. Choices are [‘srem’, ‘6s’].

    Choices:

    ’srem’: A Simplified and Robust Surface Reflectance Estimation Method (SREM)

  • angle_factor (Optional[float]) – The scale factor for angles.

  • meta (Optional[namedtuple]) – A metadata object with gain and bias coefficients.

  • interp_method (Optional[str]) – The LUT interpolation method if method = ‘6s’. Choices are [‘fast’, ‘slow’]. ‘fast’: Uses nearest neighbor lookup with scipy.interpolate.NearestNDInterpolator. ‘slow’: Uses linear interpolation with scipy.interpolate.LinearNDInterpolator.

  • kwargs (Optional[dict]) – Extra keyword arguments passed to radiometry.sixs.SixS().toar_to_sr.

References

See [BNN+19] for the SREM method.

See [PFRS10] and [LLS+20] for the 6S method.

Returns:

Data range: 0-1

Return type:

xarray.DataArray

geowombat.radiometry.sr.coeffs_to_array(coeffs, band_names)[source]#

Converts coefficients to a DataArray.

geowombat.radiometry.sr.p_r(m, r, rphase, cos_solar_za, cos_sensor_za)[source]#

Calculates atmospheric reflectance due to Rayleigh scattering.

Parameters:

  • m (float) – The air mass.

  • r (float) – The Rayleigh optical depth.

  • rphase (float) – The Rayleigh phase function.

  • cos_solar_za (DataArray) – The cosine of the solar zenith angle.

  • cos_sensor_za (DataArray) – The cosine of the sensor zenith angle.

Returns:

xarray.DataArray

geowombat.radiometry.sr.s_atm(r)[source]#

Calculates atmospheric backscattering ratio to count multiple reflections between the surface and atmosphere.

Parameters:

r (float) – The Rayleigh optical depth.

Returns:

float

geowombat.radiometry.sr.t_sv(r, cos_zenith)[source]#

Calculates atmospheric transmittance of sun-surface path.

Parameters:

  • r (float) – The Rayleigh optical depth.

  • cos_zenith (DataArray) – The cosine of the zenith angle.

Returns:

xarray.DataArray

geowombat.radiometry.topo module#

class geowombat.radiometry.topo.Topo[source]#

Bases: object

A class for topographic normalization.

Methods

norm_topo(data, elev, solar_za, solar_az[, ...])

Applies topographic normalization.
norm_topo(data, elev, solar_za, solar_az, slope=None, aspect=None, method='empirical-rotation', slope_thresh=2, nodata=0, elev_nodata=-32768, scale_factor=1, angle_scale=0.01, n_jobs=1, robust=False, min_samples=100, slope_kwargs=None, aspect_kwargs=None, band_coeffs=None)[source]#

Applies topographic normalization.

Parameters:

  • data (2d or 3d DataArray) – The data to normalize, in the range 0-1.

  • elev (2d DataArray) – The elevation data.

  • solar_za (2d DataArray) – The solar zenith angles (degrees).

  • solar_az (2d DataArray) – The solar azimuth angles (degrees).

  • slope (2d DataArray) – The slope data. If not given, slope is calculated from elev.

  • aspect (2d DataArray) – The aspect data. If not given, aspect is calculated from elev.

  • method (Optional[str]) – The method to apply. Choices are [‘c’, ‘empirical-rotation’].

  • slope_thresh (Optional[float or int]) – The slope threshold. Any samples with values < slope_thresh are not adjusted.

  • nodata (Optional[int or float]) – The ‘no data’ value for data.

  • elev_nodata (Optional[float or int]) – The ‘no data’ value for elev.

  • scale_factor (Optional[float]) – A scale factor to apply to the input data.

  • angle_scale (Optional[float]) – The angle scale factor.

  • n_jobs (Optional[int]) – The number of parallel workers for LinearRegression.fit.

  • robust (Optional[bool]) – Whether to fit a robust regression.

  • min_samples (Optional[int]) – The minimum number of samples required to fit a regression.

  • slope_kwargs (Optional[dict]) – Keyword arguments passed to gdal.DEMProcessingOptions to calculate the slope.

  • aspect_kwargs (Optional[dict]) – Keyword arguments passed to gdal.DEMProcessingOptions to calculate the aspect.

  • band_coeffs (Optional[dict]) – Slope and intercept coefficients for each band.

References

See [TGG82] for the C-correction method. See [TWM+10] for the Empirical Rotation method.

Returns:

xarray.DataArray

Examples

>>> import geowombat as gw
>>> from geowombat.radiometry import Topo
>>>
>>> topo = Topo()
>>>
>>> # Example where pixel angles are stored in separate GeoTiff files
>>> with gw.config.update(sensor='l7', scale_factor=0.0001, nodata=0):
>>>
>>>     with gw.open('landsat.tif') as src,
>>>         gw.open('srtm') as elev,
>>>             gw.open('solarz.tif') as solarz,
>>>                 gw.open('solara.tif') as solara:
>>>
>>>         src_norm = topo.norm_topo(src, elev, solarz, solara, n_jobs=-1)
geowombat.radiometry.topo.calc_aspect(elev, proc_dims=None, w=None, **kwargs)[source]#

Calculates aspect from elevation.

Parameters:

  • elev (2d array) – The elevation data.

  • proc_dims (Optional[tuple]) – Dimensions to resize to.

  • w (Optional[int]) – The smoothing window size when proc_dims is given.

  • kwargs (Optional[dict]) – Keyword arguments passed to gdal.DEMProcessingOptions.

Returns:

numpy.ndarray

geowombat.radiometry.topo.calc_slope(elev, proc_dims=None, w=None, **kwargs)[source]#

Calculates slope from elevation.

Parameters:

  • elev (2d array) – The elevation data.

  • proc_dims (Optional[tuple]) – Dimensions to resize to.

  • w (Optional[int]) – The smoothing window size when proc_dims is given.

  • kwargs (Optional[dict]) – Keyword arguments passed to gdal.DEMProcessingOptions.

Returns:

numpy.ndarray

Module contents#

class geowombat.radiometry.BRDF[source]#

Bases: GeoVolKernels

A class for Bidirectional Reflectance Distribution Function (BRDF) normalization.

Methods

get_mean_sza(central_latitude)

Returns the mean solar zenith angle (SZA) as a function of the central latitude.

norm_brdf(data, solar_za, solar_az, ...[, ...])

Applies Nadir Bidirectional Reflectance Distribution Function (BRDF) normalization using the global c-factor method

get_kernels
norm_brdf(data, solar_za, solar_az, sensor_za, sensor_az, central_latitude=None, sensor=None, wavelengths=None, src_nodata=-32768, dst_nodata=-32768, mask=None, scale_factor=1.0, out_range=None, scale_angles=True, vol_weight=1.0)[source]#

Applies Nadir Bidirectional Reflectance Distribution Function (BRDF) normalization using the global c-factor method

Parameters:

  • data (2d or 3d DataArray) – The data to normalize.

  • solar_za (2d DataArray) – The solar zenith angles (degrees).

  • solar_az (2d DataArray) – The solar azimuth angles (degrees).

  • sensor_za (2d DataArray) – The sensor azimuth angles (degrees).

  • sensor_az (2d DataArray) – The sensor azimuth angles (degrees).

  • central_latitude (Optional[float or 2d DataArray]) – The central latitude.

  • sensor (Optional[str]) – The satellite sensor.

  • wavelengths (str list) – The wavelength(s) to normalize.

  • src_nodata (Optional[int or float]) – The input ‘no data’ value.

  • dst_nodata (Optional[int or float]) – The output ‘no data’ value.

  • mask (Optional[DataArray]) – A data mask, where clear values are 0.

  • scale_factor (Optional[float]) – A scale factor to apply to the input data.

  • out_range (Optional[float]) – The out data range. If not given, the output data are return in a 0-1 range.

  • scale_angles (Optional[bool]) – Whether to scale the pixel angle arrays.

  • vol_weight (Optional[float]) – Weight to be applied to the volumetric kernel in the c-factor equation

References

See [RZJ+16] for the c-factor method.

For further background on BRDF:

Returns:

xarray.DataArray

Examples

>>> import geowombat as gw
>>> from geowombat.radiometry import BRDF
>>>
>>> brdf = BRDF()
>>>
>>> # Example where pixel angles are stored in separate GeoTiff files
>>> with gw.config.update(sensor='l7', scale_factor=0.0001):
>>>
>>>     with gw.open('solarz.tif') as solarz,
>>>         gw.open('solara.tif') as solara,
>>>             gw.open('sensorz.tif') as sensorz,
>>>                 gw.open('sensora.tif') as sensora:
>>>
>>>         with gw.open('landsat.tif') as src:
>>>             src_norm = brdf.norm_brdf(src, solarz, solara, sensorz, sensora)
class geowombat.radiometry.DOS[source]#

Bases: AOT, RadTransforms

Methods

dn_to_radiance(dn, gain, bias)

Converts digital numbers to radiance.

dn_to_sr(dn, solar_za, solar_az, sensor_za, ...)

Converts digital numbers to surface reflectance.

dn_to_toar(dn, gain, bias[, solar_za, ...])

Converts digital numbers to top-of-atmosphere reflectance.

get_aot(data, sza, meta[, data_values, ...])

Gets the aerosol optical thickness (AOT) from dark objects.

get_landsat_coefficients(meta_file)

Gets coefficients from a Landsat metadata file.

get_optimized_aot(blue_rad_dark, ...[, max_aot])

Gets the optimal aerosol optical thickness.

get_sentinel_coefficients(meta_file)

Gets coefficients from a Sentinel metadata file.

radiance_to_toar(radiance, solar_za, global_args)

Converts radiance to top-of-atmosphere reflectance.

toar_to_rad(toar, meta)

Converts top of atmosphere reflectance to top of atmosphere radiance.

toar_to_sr(toar, solar_za, solar_az, ...[, ...])

Converts top-of-atmosphere reflectance to surface reflectance.
get_aot(data, sza, meta, data_values='dn', angle_factor=0.01, dn_interp=None, interp_method='fast', aot_fallback=0.3, h2o=2.0, o3=0.3, altitude=0.0, w=None, n_jobs=1)[source]#

Gets the aerosol optical thickness (AOT) from dark objects.

Parameters:

  • data (DataArray) – The digital numbers or top of atmosphere reflectance at a coarse resolution.

  • sza (float | DataArray) – The solar zenith angle.

  • meta (Optional[namedtuple]) – A metadata object with gain and bias coefficients.

  • data_values (Optional[str]) – The values of data. Choices are [‘dn’, ‘toar’].

  • angle_factor (Optional[float]) – The scale factor for angles.

  • dn_interp (Optional[DataArray]) – A source DataArray at the target resolution.

  • interp_method (Optional[str]) – The LUT interpolation method. Choices are [‘fast’, ‘slow’]. ‘fast’: Uses nearest neighbor lookup with scipy.interpolate.NearestNDInterpolator. ‘slow’: Uses linear interpolation with scipy.interpolate.LinearNDInterpolator.

  • aot_fallback (Optional[float | DataArray]) – The aerosol optical thickness fallback if no dark objects are found (unitless). [0,3].

  • h2o (Optional[float]) – The water vapor (g/m^2). [0,8.5].

  • o3 (Optional[float]) – The ozone (cm-atm). [0,8].

  • altitude (Optional[float]) – The altitude over the sensor acquisition location (km above sea level).

  • w (Optional[int]) – The smoothing window size (in pixels).

  • n_jobs (Optional[int]) – The number of parallel jobs for moving_window and dask.compute.

Returns:

Data range: 0-3

Return type:

xarray.DataArray

References

See [MVS+06], [KWR+97], and [OV99].

class geowombat.radiometry.LinearAdjustments[source]#

Bases: object

A class for linear bandpass adjustments.

Methods

bandpass(data[, sensor, to, band_names, ...])

Applies a bandpass adjustment by applying a linear function to surface reflectance values.
bandpass(data, sensor=None, to='l8', band_names=None, scale_factor=1, src_nodata=0, dst_nodata=0)[source]#

Applies a bandpass adjustment by applying a linear function to surface reflectance values.

Parameters:

  • data (DataArray) – The data to adjust.

  • sensor (Optional[str]) – The sensor to adjust.

  • to (Optional[str]) – The sensor to adjust to.

  • band_names (Optional[list]) – The bands to adjust. If not given, all bands are adjusted.

  • scale_factor (Optional[float]) – A scale factor to apply to the input data.

  • src_nodata (Optional[int or float]) – The input ‘no data’ value.

  • dst_nodata (Optional[int or float]) – The output ‘no data’ value.

Reference:

Sentinel-2 and Landsat 8:

Landsat 7 and Landsat 8:

See [RZJ+16] (Table 2)

Returns:

xarray.DataArray

Examples

>>> import geowombat as gw
>>> from geowombat.radiometry import LinearAdjustments
>>>
>>> la = LinearAdjustments()
>>>
>>> # Adjust all Sentinel-2 bands to Landsat 8
>>> with gw.config.update(sensor='s2'):
>>>     with gw.open('sentinel-2.tif') as ds:
>>>         ds_adjusted = la.bandpass(ds, to='l8')
class geowombat.radiometry.QABits(value)[source]#

Bases: Enum

QA bits.

Reference:

https://www.usgs.gov/landsat-missions/landsat-project-documents

landsat_c2_l2 = {'cirrus': 2, 'clear': 6, 'cloud': 3, 'cloud_shadow': 4, 'dilated_cloud': 1, 'fill': 0, 'snow': 5, 'water': 7}#
class geowombat.radiometry.QAMasker(qa, sensor, mask_items=None, modis_qa_band=1, modis_quality=2, confidence_level='yes')[source]#

Bases: object

A class for masking bit-packed quality flags.

Parameters:

  • qa (DataArray) – The band quality array.

  • sensor (str) –

    The sensor name. Choices are [‘ard’, ‘hls’, ‘l8-pre’, ‘l8-c1’, ‘l-c1’, ‘modis’, ‘s2a’, ‘s2c’].

    Codes:
    ’ard’:

    USGS Landsat Analysis Ready Data <https://www.usgs.gov/land-resources/nli/landsat/us-landsat-analysis-ready-data?qt-science_support_page_related_con=0#qt-science_support_page_related_con>`_

    ’hls’:

    NASA Harmonized Landsat Sentinel

    ’l-c1’:

    Landsat Collection 1 L4-5 and L7

    ’l8-c1’:

    Landsat Collection 1 L8

    ’s2a’:

    Sentinel 2A (surface reflectance)

    ’s2c’:

    Sentinel 2C (top of atmosphere)

  • mask_items (str list) – A list of items to mask.

  • modis_qa_position (Optional[int]) – The MODIS QA band position. Default is 1.

  • modis_quality (Optional[int]) – The MODIS quality level. Default is 2.

  • confidence_level (Optional[str]) – The confidence level. Choices are [‘notdet’, ‘no’, ‘maybe’, ‘yes’].

References

Landsat Collection 1:

https://landsat.usgs.gov/collectionqualityband

Examples

>>> import geowombat as gw
>>> from geowombat.radiometry import QAMasker
>>>
>>> # Get the MODIS cloud mask.
>>> with gw.open('qa.tif') as qa:
>>>     mask = QAMasker(qs, 'modis').to_mask()
>>>
>>> # NASA HLS
>>> with gw.open('qa.tif') as qa:
>>>     mask = QAMasker(qs, 'hls', ['cloud']).to_mask()

Methods

to_mask()

Converts QA bit-packed data to an integer mask.
to_mask()[source]#

Converts QA bit-packed data to an integer mask.

Returns:

0: clear, 1: water, 2: shadow, 3: snow or ice, 4: cloud, 5: cirrus cloud, 6: adjacent cloud, 7: saturated, 8: dropped, 9: terrain occluded, 255: fill

Return type:

xarray.DataArray

class geowombat.radiometry.RadTransforms[source]#

Bases: MetaData

A class for radiometric transformations.

Methods

dn_to_radiance(dn, gain, bias)

Converts digital numbers to radiance.

dn_to_sr(dn, solar_za, solar_az, sensor_za, ...)

Converts digital numbers to surface reflectance.

dn_to_toar(dn, gain, bias[, solar_za, ...])

Converts digital numbers to top-of-atmosphere reflectance.

get_landsat_coefficients(meta_file)

Gets coefficients from a Landsat metadata file.

get_sentinel_coefficients(meta_file)

Gets coefficients from a Sentinel metadata file.

radiance_to_toar(radiance, solar_za, global_args)

Converts radiance to top-of-atmosphere reflectance.

toar_to_rad(toar, meta)

Converts top of atmosphere reflectance to top of atmosphere radiance.

toar_to_sr(toar, solar_za, solar_az, ...[, ...])

Converts top-of-atmosphere reflectance to surface reflectance.
dn_to_radiance(dn, gain, bias)[source]#

Converts digital numbers to radiance.

Parameters:

  • dn (DataArray) – The digital number data to calibrate.

  • gain (DataArray) – A gain value.

  • bias (DataArray) – A bias value.

Returns:

xarray.DataArray

dn_to_sr(dn, solar_za, solar_az, sensor_za, sensor_az, src_nodata=-32768, dst_nodata=-32768, sensor=None, method='srem', angle_factor=0.01, meta=None, interp_method='fast', **kwargs)[source]#

Converts digital numbers to surface reflectance.

Parameters:

  • dn (DataArray) – The digital number data to calibrate.

  • solar_za (DataArray) – The solar zenith angle.

  • solar_az (DataArray) – The solar azimuth angle.

  • sensor_za (DataArray) – The sensor, or view, zenith angle.

  • sensor_az (DataArray) – The sensor, or view, azimuth angle.

  • src_nodata (Optional[int or float]) – The input ‘no data’ value.

  • dst_nodata (Optional[int or float]) – The output ‘no data’ value.

  • sensor (Optional[str]) – The data’s sensor.

  • method (Optional[str]) – The correction method to use. Choices are [‘srem’, ‘6s’].

  • angle_factor (Optional[float]) – The scale factor for angles.

  • meta (Optional[namedtuple]) – A metadata object with gain and bias coefficients.

  • interp_method (Optional[str]) – The LUT interpolation method if method = ‘6s’. Choices are [‘fast’, ‘slow’]. ‘fast’: Uses nearest neighbor lookup with scipy.interpolate.NearestNDInterpolator. ‘slow’: Uses linear interpolation with scipy.interpolate.LinearNDInterpolator.

  • kwargs (Optional[dict]) – Extra keyword arguments passed to radiometry.sixs.SixS().rad_to_sr.

References

https://www.usgs.gov/land-resources/nli/landsat/using-usgs-landsat-level-1-data-product

Returns:

Data range: 0-1

Return type:

xarray.DataArray

Examples

>>> from geowombat.radiometry import RadTransforms
>>>
>>> sr = RadTransforms()
>>> meta = sr.get_landsat_coefficients('file.MTL')
>>>
>>> # Convert DNs to surface reflectance using Landsat metadata
>>> with gw.open('dn.tif') as ds:
>>>     sr_data = sr.dn_to_sr(ds, solar_za, sensor_za, meta=meta)
dn_to_toar(dn, gain, bias, solar_za=None, angle_factor=0.01, sun_angle=True)[source]#

Converts digital numbers to top-of-atmosphere reflectance.

Parameters:

  • dn (DataArray) – The digital number data to calibrate.

  • gain (DataArray | dict) – A gain value.

  • bias (DataArray | dict) – A bias value.

  • solar_za (DataArray) – The solar zenith angle.

  • angle_factor (Optional[float]) – The scale factor for angles.

  • sun_angle (Optional[bool]) – Whether to correct for the sun angle.

Returns:

xarray.DataArray

static radiance_to_toar(radiance, solar_za, global_args)[source]#

Converts radiance to top-of-atmosphere reflectance.

Parameters:

  • radiance (DataArray) – The radiance data to calibrate.

  • solar_za (DataArray) – The solar zenith angle.

  • global_args (namedtuple) – Global arguments.

Returns:

xarray.DataArray

static toar_to_rad(toar, meta)[source]#

Converts top of atmosphere reflectance to top of atmosphere radiance.

Parameters:

  • toar (DataArray) – The top of atmosphere reflectance (0-1).

  • sza (float | DataArray) – The solar zenith angle (in degrees).

  • meta (Optional[namedtuple]) – A metadata object with gain and bias coefficients.

Returns:

xarray.DataArray

toar_to_sr(toar, solar_za, solar_az, sensor_za, sensor_az, sensor=None, src_nodata=-32768, dst_nodata=-32768, method='srem', angle_factor=0.01, meta=None, interp_method='fast', **kwargs)[source]#

Converts top-of-atmosphere reflectance to surface reflectance.

Parameters:

  • toar (DataArray) – The top-of-atmosphere reflectance (0-1).

  • solar_za (float | DataArray) – The solar zenith angle.

  • solar_az (DataArray) – The solar azimuth angle.

  • sensor_za (DataArray) – The sensor zenith angle.

  • sensor_az (DataArray) – The sensor azimuth angle.

  • sensor (Optional[str]) – The data’s sensor.

  • src_nodata (Optional[int or float]) – The input ‘no data’ value.

  • dst_nodata (Optional[int or float]) – The output ‘no data’ value.

  • method (Optional[str]) –

    The method to use. Choices are [‘srem’, ‘6s’].

    Choices:

    ’srem’: A Simplified and Robust Surface Reflectance Estimation Method (SREM)

  • angle_factor (Optional[float]) – The scale factor for angles.

  • meta (Optional[namedtuple]) – A metadata object with gain and bias coefficients.

  • interp_method (Optional[str]) – The LUT interpolation method if method = ‘6s’. Choices are [‘fast’, ‘slow’]. ‘fast’: Uses nearest neighbor lookup with scipy.interpolate.NearestNDInterpolator. ‘slow’: Uses linear interpolation with scipy.interpolate.LinearNDInterpolator.

  • kwargs (Optional[dict]) – Extra keyword arguments passed to radiometry.sixs.SixS().toar_to_sr.

References

See [BNN+19] for the SREM method.

See [PFRS10] and [LLS+20] for the 6S method.

Returns:

Data range: 0-1

Return type:

xarray.DataArray

class geowombat.radiometry.SixS[source]#

Bases: Altitude, SixSMixin

A class to handle loading, downloading and interpolating of LUTs (look up tables) used by the 6S emulator.

Parameters:

  • sensor (str) – The sensor to adjust.

  • rad_scale (Optional[float]) – The radiance scale factor. Scaled values should be in the range [0,1000].

  • angle_factor (Optional[float]) – The angle scale factor.

Example

>>> sixs = SixS('l5', verbose=1)
>>>
>>> with gw.config.update(sensor='l7'):
>>>     with gw.open('image.tif') as src, gw.open('solar_za') as sza:
>>>         sixs.rad_to_sr(src, 'blue', sza, doy, h2o=1.0, o3=0.4, aot=0.3)

Methods

rad_to_sr(data, sensor, wavelength, sza, doy)

Converts radiance to surface reflectance using a 6S radiative transfer model lookup table.

toar_to_sr(data, sensor, wavelength, sza, doy)

Converts top of atmosphere reflectance to surface reflectance using 6S outputs.

get_mean_altitude

prepare_coeff
static prepare_coeff(band_data, coeffs, cindex)[source]#
rad_to_sr(data, sensor, wavelength, sza, doy, src_nodata=-32768, dst_nodata=-32768, angle_factor=0.01, interp_method='fast', h2o=1.0, o3=0.4, aot=0.3, altitude=0.0, n_jobs=1)[source]#

Converts radiance to surface reflectance using a 6S radiative transfer model lookup table.

Parameters:

  • data (DataArray) – The data to correct, in radiance.

  • sensor (str) – The sensor name.

  • wavelength (str) – The band wavelength to process.

  • sza (float | DataArray) – The solar zenith angle.

  • doy (int) – The day of year.

  • src_nodata (Optional[int or float]) – The input ‘no data’ value.

  • dst_nodata (Optional[int or float]) – The output ‘no data’ value.

  • angle_factor (Optional[float]) – The scale factor for angles.

  • interp_method (Optional[str]) – The LUT interpolation method. Choices are [‘fast’, ‘slow’]. ‘fast’: Uses nearest neighbor lookup with scipy.interpolate.NearestNDInterpolator. ‘slow’: Uses linear interpolation with scipy.interpolate.LinearNDInterpolator.

  • h2o (Optional[float]) – The water vapor (g/m^2). [0,8.5].

  • o3 (Optional[float]) – The ozone (cm-atm). [0,8].

  • aot (Optional[float | DataArray]) – The aerosol optical thickness (unitless). [0,3].

  • altitude (Optional[float]) – The altitude over the sensor acquisition location.

  • n_jobs (Optional[int]) – The number of parallel jobs for dask.compute.

Returns:

Data range: 0-1

Return type:

xarray.DataArray

toar_to_sr(data, sensor, wavelength, sza, doy, src_nodata=-32768, dst_nodata=-32768, angle_factor=0.01, interp_method='fast', h2o=1.0, o3=0.4, aot=0.3, altitude=0.0, n_jobs=1)[source]#

Converts top of atmosphere reflectance to surface reflectance using 6S outputs.

Parameters:

  • data (DataArray) – The top of atmosphere reflectance.

  • sensor (str) – The sensor name.

  • wavelength (str) – The band wavelength to process.

  • sza (float | DataArray) – The solar zenith angle.

  • doy (int) – The day of year.

  • src_nodata (Optional[int or float]) – The input ‘no data’ value.

  • dst_nodata (Optional[int or float]) – The output ‘no data’ value.

  • angle_factor (Optional[float]) – The scale factor for angles.

  • interp_method (Optional[str]) – The LUT interpolation method. Choices are [‘fast’, ‘slow’]. ‘fast’: Uses nearest neighbor lookup with scipy.interpolate.NearestNDInterpolator. ‘slow’: Uses linear interpolation with scipy.interpolate.LinearNDInterpolator.

  • h2o (Optional[float]) – The water vapor (g/m^2). [0,8.5].

  • o3 (Optional[float]) – The ozone (cm-atm). [0,8].

  • aot (Optional[float | DataArray]) – The aerosol optical thickness (unitless). [0,3].

  • altitude (Optional[float]) – The altitude over the sensor acquisition location.

  • n_jobs (Optional[int]) – The number of parallel jobs for dask.compute.

6S model outputs:
t_g (float): The total gaseous transmission of the atmosphere.

s.run() –> s.outputs.total_gaseous_transmittance

p_alpha (float): The atmospheric reflectance.

s.run() –> s.outputs.atmospheric_intrinsic_reflectance

s (float): The spherical albedo of the atmosphere.

s.run() –> s.outputs.spherical_albedo

t_s (float): The atmospheric transmittance from sun to target.

s.run() –> s.outputs.transmittance_total_scattering.downward

t_v (float): The atmospheric transmittance from target to satellite.

s.run() –> s.outputs.transmittance_total_scattering.upward

class geowombat.radiometry.Topo[source]#

Bases: object

A class for topographic normalization.

Methods

norm_topo(data, elev, solar_za, solar_az[, ...])

Applies topographic normalization.
norm_topo(data, elev, solar_za, solar_az, slope=None, aspect=None, method='empirical-rotation', slope_thresh=2, nodata=0, elev_nodata=-32768, scale_factor=1, angle_scale=0.01, n_jobs=1, robust=False, min_samples=100, slope_kwargs=None, aspect_kwargs=None, band_coeffs=None)[source]#

Applies topographic normalization.

Parameters:

  • data (2d or 3d DataArray) – The data to normalize, in the range 0-1.

  • elev (2d DataArray) – The elevation data.

  • solar_za (2d DataArray) – The solar zenith angles (degrees).

  • solar_az (2d DataArray) – The solar azimuth angles (degrees).

  • slope (2d DataArray) – The slope data. If not given, slope is calculated from elev.

  • aspect (2d DataArray) – The aspect data. If not given, aspect is calculated from elev.

  • method (Optional[str]) – The method to apply. Choices are [‘c’, ‘empirical-rotation’].

  • slope_thresh (Optional[float or int]) – The slope threshold. Any samples with values < slope_thresh are not adjusted.

  • nodata (Optional[int or float]) – The ‘no data’ value for data.

  • elev_nodata (Optional[float or int]) – The ‘no data’ value for elev.

  • scale_factor (Optional[float]) – A scale factor to apply to the input data.

  • angle_scale (Optional[float]) – The angle scale factor.

  • n_jobs (Optional[int]) – The number of parallel workers for LinearRegression.fit.

  • robust (Optional[bool]) – Whether to fit a robust regression.

  • min_samples (Optional[int]) – The minimum number of samples required to fit a regression.

  • slope_kwargs (Optional[dict]) – Keyword arguments passed to gdal.DEMProcessingOptions to calculate the slope.

  • aspect_kwargs (Optional[dict]) – Keyword arguments passed to gdal.DEMProcessingOptions to calculate the aspect.

  • band_coeffs (Optional[dict]) – Slope and intercept coefficients for each band.

References

See [TGG82] for the C-correction method. See [TWM+10] for the Empirical Rotation method.

Returns:

xarray.DataArray

Examples

>>> import geowombat as gw
>>> from geowombat.radiometry import Topo
>>>
>>> topo = Topo()
>>>
>>> # Example where pixel angles are stored in separate GeoTiff files
>>> with gw.config.update(sensor='l7', scale_factor=0.0001, nodata=0):
>>>
>>>     with gw.open('landsat.tif') as src,
>>>         gw.open('srtm') as elev,
>>>             gw.open('solarz.tif') as solarz,
>>>                 gw.open('solara.tif') as solara:
>>>
>>>         src_norm = topo.norm_topo(src, elev, solarz, solara, n_jobs=-1)
geowombat.radiometry.landsat_pixel_angles(angles_file, ref_file, out_dir, sensor, l57_angles_path=None, l8_angles_path=None, subsample=1, resampling='bilinear', num_workers=1, verbose=0, chunks=256)[source]#

Generates Landsat pixel angle files.

Parameters:

  • angles_file (str) – The angles file.

  • ref_file (str) – A reference file.

  • out_dir (str) – The output directory.

  • sensor (str) – The sensor.

  • l57_angles_path (str) – The path to the Landsat 5 and 7 angles bin.

  • l8_angles_path (str) – The path to the Landsat 8 angles bin.

  • subsample (Optional[int]) – The sub-sample factor when calculating the angles.

  • resampling (Optional[str]) – The resampling method if filename is a list. Choices are [‘average’, ‘bilinear’, ‘cubic’, ‘cubic_spline’, ‘gauss’, ‘lanczos’, ‘max’, ‘med’, ‘min’, ‘mode’, ‘nearest’].

  • num_workers (Optional[int]) – The maximum number of concurrent workers.

  • verbose (Optional[int]) – The verbosity level.

  • chunks (Optional[int]) – The file chunk size. Default is 256.

Return type:

AngleInfo

Returns:

zenith and azimuth angles as a namedtuple of angle file names

geowombat.radiometry.sentinel_pixel_angles(metadata, ref_file, nodata=-32768, resampling='bilinear', num_workers=1, resample_res=60.0, chunksize=None)[source]#

Generates Sentinel pixel angle files.

Parameters:

  • metadata (str) – The metadata file.

  • ref_file (str) – A reference image to use for geo-information.

  • nodata (Optional[int or float]) – The ‘no data’ value.

  • num_workers (Optional[int]) – The maximum number of concurrent workers.

  • resample_res (Optional[float]) – The resolution to resample to.

  • resampling (str) –

  • chunksize (Tuple[int, int] | None) –

Return type:

AngleInfo

References

https://www.sentinel-hub.com/faq/how-can-i-access-meta-data-information-sentinel-2-l2a marujore/sentinel_angle_bands

Return type:

AngleInfo

Returns:

zenith and azimuth angles as a namedtuple of angle file names

Parameters:

  • metadata (str | Path) –

  • ref_file (str | Path) –

  • nodata (float | int) –

  • resampling (str) –

  • num_workers (int) –

  • resample_res (float | int) –

  • chunksize (Tuple[int, int] | None) –