geeViz.getImagesLib¶

Get images and organize them so they are easier to work with.

geeViz.getImagesLib is the core module for setting up ImageCollections from Google Earth Engine. It facilitates Landsat, Sentinel-2, and MODIS data organization and normalization — matching band names across sensors, resampling defaults, date wrapping, and cloud / cloud-shadow masking.

Recommended entry points (high-level wrappers):

getProcessedLandsatScenes() — Landsat 4-9 scene collection, cloud- masked and band-normalized. Companion: getLandsatWrapper() for annual composites.
getProcessedSentinel2Scenes() — Sentinel-2 SR scenes, cloud-masked. Companion: getSentinel2Wrapper() for annual composites.
getProcessedModisScenes() — MODIS 8-day surface reflectance, normalized to a Landsat-like band naming scheme.
getLandsatAndSentinel2HybridWrapper() — merged Landsat + Sentinel-2 composites when either alone isn’t dense enough.

Common helpers:

simpleAddIndices() — adds NDVI/NBR/tasseled-cap/etc. bands.
addWaterIndices() — MNDWI, AWEI, and other water-detection indices.
getModisAndProducts() — MODIS 8-day products (LST, snow, fire, etc.)
vizParamsFalse(), vizParamsTrue(), and other module-level viz dicts — sensible defaults for Map.addLayer.

Terminology: “wrappers” produce annual composites; “processed scenes” produce per-scene collections you compositen yourself.

Functions

`HoCalcAlgorithm1`(image)	Apply the Ho et al. algal bloom detection algorithm to a satellite image.
`HoCalcAlgorithm2`(image)	Applies an algal bloom detection algorithm to an image.
`HoCalcGreenness`(img)	Compute the hue component for algal bloom greenness detection.
`RefinedLee`(img)	Applies the Refined Lee speckle filter to a Sentinel-1 image.
`addAbsDiff`(inCollection, qualityBand, ...)	Add a band with the absolute difference from a percentile-based quality target.
`addDateBand`(img[, maskTime])	Adds a `"year"` band containing the fractional year (year + day-of-year fraction).
`addFullYearJulianDayBand`(img)	Adds a `"yearJulian"` band encoding the full 4-digit year and Julian day (YYYYDD).
`addIndices`(img)	Adds a comprehensive set of spectral indices to an image.
`addJulianDayBand`(img)	Adds a `"julianDay"` band containing the day of the year (1--366).
`addSAVIandEVI`(img)	Adds SAVI, EVI, and NIRv vegetation indices to an image.
`addSensorBand`(img, whichProgram, toaOrSR)	Adds a band encoding the satellite sensor as a numeric value.
`addSoilIndices`(img)	Adds soil-related spectral indices to an image.
`addTCAngles`(image)	Adds Tasseled Cap angles and distances to an image.
`addWaterIndices`(in_image)	Add water detection indices (MNDWI, AWEI_nsh) to an image.
`addYearBand`(img)	Adds a `"year"` band containing the integer year of the image acquisition.
`addYearFractionBand`(img)	Adds a `"year"` band containing only the fractional part of the year (0 to 1).
`addYearJulianDayBand`(img)	Adds a `"yearJulian"` band encoding the 2-digit year and Julian day (YYDD).
`addYearYearFractionBand`(img)	Adds a `"year"` band containing the full fractional year (year + fraction).
`addZenithAzimuth`(img, toaOrSR[, zenithDict, ...])	Adds solar zenith and azimuth angles in radians as bands to an image.
`applyBitMask`(img, bit[, bitMaskBandName])	Masks pixels where a specific bit is set in a QA bitmask band.
`applyCloudScoreAlgorithm`(collection, ...[, ...])	Applies a cloud score algorithm to an image collection and masks cloudy pixels.
`applyScaleFactors`(image, ...)	Rescales Landsat reflectance bands to 0-1 and thermal bands to Kelvin.
`cFmask`(img, fmaskClass[, bitMaskBandName])	Applies the CFMask algorithm to mask a specific class in a Landsat image.
`cFmaskCloud`(img, landsatCollectionVersion[, ...])	Applies the CFMask cloud mask to a Landsat image.
`cFmaskCloudShadow`(img, landsatCollectionVersion)	Applies the CFMask cloud shadow mask to a Landsat image.
`coRegisterCollection`(images[, referenceBands])	Co-register all images in a collection to the first image.
`coRegisterGroups`(imgs[, fieldName, ...])	Co-register images within groups defined by a metadata field.
`collectionToImage`(collection)	Converts an image collection to a single multiband image.
`compositeDates`(images, composite[, bandNames])	Finds the acquisition dates corresponding to each band in a composite image.
`compositeTimeSeries`(ls, startYear, endYear, ...)	Creates annual composites from an image collection over a year range.
`customQualityMosaic`(inCollection, ...)	Create a quality mosaic using a specified percentile rather than the max.
`dailyMosaics`(imgs)	Creates daily mosaics from an image collection grouped by date and orbit.
`defringeLandsat`(img)	Defringes a Landsat 7 image by masking fringe pixels with insufficient valid neighbors.
`despikeCollection`(c, absoluteSpike, bandNo)	Removes spike artifacts from a time series image collection.
`dir0Regression`(img, slopes, intercepts)	Applies a forward linear regression model: `corrected = img * slopes + intercepts`.
`dir1Regression`(img, slopes, intercepts)	Applies an inverse linear regression model: `corrected = (img - intercepts) / slopes`.
`exportCollection`(exportPathRoot, outputName, ...)	Exports yearly composites from an image collection to EE assets or Cloud Storage.
`exportCompositeCollection`(collection, ...[, ...])	Exports yearly composites to Earth Engine assets with scaled integer values.
`exportToAssetWrapper`(imageForExport, ...[, ...])	Exports an image to an Earth Engine asset with overwrite handling.
`exportToCloudStorageWrapper`(imageForExport, ...)	Exports an image to Google Cloud Storage with overwrite handling.
`exportToDriveWrapper`(imageForExport, ...[, ...])	Exports an image to Google Drive as a GeoTIFF.
`fillEmptyCollections`(inCollection, dummyImage)	Fills empty image collections with a fully-masked dummy image.
`formatArgs`(args)	Formats arguments as strings for setting as Earth Engine image properties.
`getAreaUnderCurve`(harmCoeffs[, t0, t1])	Compute the definite integral (area under curve) of a single-harmonic model.
`getClimateWrapper`(collectionName, studyArea, ...)	Wrapper function to retrieve and process climate data from various Earth Engine collections.
`getDateStack`(startYear, endYear, ...)	Generate a synthetic date image stack for predicting harmonic time series.
`getHarmonicCoefficientsAndFit`(allImages, ...)	Fit harmonic regression to an ImageCollection and return coefficients and fitted values.
`getHarmonicList`(yearDateImg, ...)	Compute sin and cos harmonic predictor bands for a year-fraction image.
`getHarmonics2`(collection, transformBandName, ...)	Prepare an ImageCollection with harmonic predictor bands for regression.
`getImageCollection`(studyArea, startDate, endDate)	Retrieves Landsat imagery for a specified study area and date range.
`getLandsat`(studyArea, startDate, endDate[, ...])	Retrieves Landsat imagery for a specified study area and date range.
`getLandsatAndSentinel2HybridWrapper`(...[, ...])	Get annual Landsat + Sentinel-2 hybrid composites.
`getLandsatWrapper`(studyArea, startYear, ...)	Retrieve cloud-masked Landsat annual composites for a study area and date range.
`getModisData`(startYear, endYear, ...[, ...])	Retrieves MODIS imagery from Earth Engine for a specified period.
`getPeakDate`(coeffs[, peakDirection])	Compute the Julian day, month, and day-of-month of peak vegetation vigor.
`getPhaseAmplitudePeak`(coeffs[, t0, t1])	Extract phase, amplitude, peak date, and AUC from harmonic regression coefficients.
`getPrecomputedCloudScoreOffsets`([cloudScorePctl])	Retrieves precomputed cloud score offset images for Landsat and Sentinel-2.
`getPrecomputedTDOMStats`()	Retrieves precomputed TDOM (Temporal Dark Outlier Mask) statistics for Landsat and Sentinel-2.
`getProcessedLandsatAndSentinel2Scenes`(...[, ...])	Get cloud/shadow-masked Landsat + Sentinel-2 scenes merged together.
`getProcessedLandsatScenes`(studyArea, ...[, ...])	Retrieves, processes, and filters Landsat scenes for a specified area and time period.
`getProcessedModis`(startYear, endYear, ...[, ...])	Retrieves, processes, and filters MODIS imagery for a specified period.
`getProcessedSentinel2Scenes`(studyArea, ...)	Get cloud/shadow-masked Sentinel-2 scenes for a date range.
`getQABits`(image, start, end, name)	Extracts a range of bits from a QA band image.
`getS1`(studyArea, startYear, endYear, ...[, ...])	Loads Sentinel-1 GRD data for a given area and time period.
`getS2`(studyArea, startDate, endDate[, ...])	Loads Sentinel-2 data for a given area and time period and joins cloud score information.
`getSentinel2`(studyArea, startDate, endDate)	Loads Sentinel-2 data for a given area and time period and joins cloud score information.
`getSentinel2Wrapper`(studyArea, startYear, ...)	Get annual Sentinel-2 composites with cloud/shadow masking.
`getTasseledCap`(image)	Computes the Tasseled Cap transformation using Crist 1985 coefficients.
`getUTMEpsg`(location[, datum])	Return the EPSG code string for a UTM zone given a location and datum.
`getUTMZone`(longitude)	Return the UTM zone number (1-60) for a given longitude.
`harmonizationChastain`(img, fromSensor, toSensor)	Harmonizes cross-sensor reflectance using Chastain et al. (2018) coefficients.
`harmonizationRoy`(oli)	Harmonizes Landsat 8 OLI to Landsat 7 ETM+ using Roy et al. (2016) coefficients.
`illuminationCorrection`(img, scale, studyArea)	Applies SCSc topographic correction to specified bands of an image.
`joinCollections`(c1, c2[, maskAnyNullValues, ...])	Joins two image collections by a shared property using an inner join.
`joinFeatureCollections`(primary, secondary, ...)	Joins two feature collections by matching property values using an inner join.
`landsatCloudScore`(img)	Computes a cloud score for a Landsat image based on spectral indicators.
`maskCloudsWQA`(image)	Masks cloudy pixels using the MODIS state_1km QA band.
`maskEmptyPixels`(image)	Masks pixels that have zero observations in a MODIS-style image.
`maskS2clouds`(image)	Masks clouds and cirrus in a Sentinel-2 image using the QA60 band.
`medoidMosaicMSD`(inCollection[, ...])	Creates a medoid mosaic using the Mean Squared Difference (MSD) method.
`modisCloudScore`(img)	Computes a cloud score (0-100) for a MODIS image.
`nDayComposites`(images, startYear, endYear, ...)	Creates median composites at regular n-day intervals from an image collection.
`newPredict`(coeffs, harmonics)	Apply harmonic regression coefficients to predict values for each image.
`newRobustMultipleLinear2`(dependentsIndependents)	Fit a linear regression model across an ImageCollection with labeled bands.
`offsetImageDate`(img, n, unit)	Offsets the `system:time_start` property of an image by a specified amount.
`printEE`(eeObject[, message])	Asynchronously prints an Earth Engine object by fetching its value in a background thread.
`projectShadows`(cloudMask, image, ...[, yMult])	Projects cloud shadows based on solar geometry and masks them along with clouds.
`projectShadowsWrapper`(img[, cloudThresh, ...])	Wrapper that computes a cloud mask and projects cloud shadows for a Sentinel-2 image.
`rescale`(img, thresholds)	Rescales pixel values in an image using min-max normalization.
`sentinel2CloudScore`(img)	Computes a cloud score (0-100) for a Sentinel-2 image.
`sentinel2SnowMask`(img[, dilatePixels])	Masks snow-covered pixels in a Sentinel-2 image using NDSI thresholds.
`setNoData`(image, noDataValue)	Sets null values for an image, replacing masked pixels with a constant.
`sieve`(image, mmu)	Performs clumping and elimination (sieving) on a classified image.
`simpleAddIndices`(in_image)	Adds common spectral indices (NDVI, NBR, NDMI, NDSI) to an image.
`simpleAddTCAngles`(image)	Adds the Tasseled Cap brightness-greenness angle as in Powell et al. (2009).
`simpleGetTasseledCap`(image)	Computes a simplified Tasseled Cap with brightness, greenness, and wetness only.
`simpleMask`(image[, mask_type, threshold, invert])	Create a simple spectral mask from standard optical bands.
`simpleTDOM2`(collection[, zScoreThresh, ...])	Applies Temporal Dark Outlier Mask (TDOM) to detect and mask cloud shadows.
`simpleWaterMask`(img[, contractPixels, ...])	Performs a basic on-the-fly water masking for TOA reflectance imagery.
`smartJoin`(primary, secondary, hourDiff)	Joins two image collections by closest timestamp within a time window.
`spatioTemporalJoin`(primary, secondary[, ...])	Joins two image collections by spatial intersection and closest timestamp.
`superSimpleGetS2`(studyArea, startDate, endDate)	Retrieve cloud-masked Sentinel-2 imagery — preferred S2 function.
`synthImage`(coeffs, dateImage, indexNames, ...)	Predict band values at a single date using harmonic regression coefficients.
`toDB`(img)	Converts a Sentinel-1 image from natural (linear power) units to dB.
`toNatural`(img)	Converts a Sentinel-1 image from dB to natural (linear power) units.
`uniqueValues`(collection, field)	Finds unique values of a field in an image collection.
`wrapDates`(startJulian, endJulian)	Computes date-wrapping parameters when startJulian > endJulian.

geeViz.getImagesLib.getUTMZone(longitude: float) → int[source]¶

Return the UTM zone number (1-60) for a given longitude.

Parameters:: longitude – Longitude in decimal degrees (-180 to 180).
Returns:: UTM zone number (1-60).

Examples

>>> getUTMZone(-113.15)
12
>>> getUTMZone(2.35)
31

geeViz.getImagesLib.getUTMEpsg(location, datum: str = 'WGS84') → str[source]¶

Return the EPSG code string for a UTM zone given a location and datum.

Combines getUTMZone() with a datum lookup to produce the full EPSG code (e.g. "EPSG:32612" for WGS84 UTM Zone 12N).

Parameters:

location – One of: - [longitude, latitude] list/tuple (GEE convention: lon first). - ee.Geometry.Point — coordinates are extracted via .getInfo().
datum – Datum name. One of "WGS84" (default), "NAD83", "NAD27", "WGS72", "ETRS89", "GDA94", "GDA2020", "SIRGAS2000". Case-insensitive.

Returns:

EPSG code string, e.g. "EPSG:32612".

Raises:

ValueError – If the datum is not recognized or location is not a supported type.

Examples

>>> getUTMEpsg([-113.15, 47.15])
'EPSG:32612'
>>> getUTMEpsg([-113.15, 47.15], datum="NAD83")
'EPSG:26912'
>>> getUTMEpsg([151.21, -33.86])
'EPSG:32756'
>>> getUTMEpsg(ee.Geometry.Point([-113.15, 47.15]))
'EPSG:32612'

geeViz.getImagesLib.getPrecomputedCloudScoreOffsets(cloudScorePctl=10)[source]¶

Retrieves precomputed cloud score offset images for Landsat and Sentinel-2.

These offsets represent a lower percentile of cloud scores on a pixel-wise basis, precomputed for all CONUS. They are appropriate for any time period within the growing season.

Parameters:: cloudScorePctl (int, optional) – The cloud score percentile to use. Defaults to 10.
Returns:: A dictionary with keys "landsat" and "sentinel2", each containing an ee.Image of the cloud score offset for that sensor.
Return type:: dict

Examples

>>> offsets = getPrecomputedCloudScoreOffsets(10)
>>> landsat_offset = offsets["landsat"]
>>> sentinel2_offset = offsets["sentinel2"]

geeViz.getImagesLib.getPrecomputedTDOMStats()[source]¶

Retrieves precomputed TDOM (Temporal Dark Outlier Mask) statistics for Landsat and Sentinel-2.

Returns the mean and standard deviation of the NIR and SWIR1 bands, precomputed for all CONUS. These are used by the TDOM cloud shadow masking algorithm.

Returns:: A nested dictionary with keys "landsat" and "sentinel2", each containing "mean" and "stdDev" keys mapped to ee.Image objects with the corresponding band statistics.
Return type:: dict

Examples

>>> stats = getPrecomputedTDOMStats()
>>> landsat_mean = stats["landsat"]["mean"]
>>> sentinel2_stddev = stats["sentinel2"]["stdDev"]

geeViz.getImagesLib.printEE(eeObject, message='')[source]¶

Asynchronously prints an Earth Engine object by fetching its value in a background thread.

Parameters:

eeObject (ee.ComputedObject) – Any Earth Engine object to print (e.g., ee.Image, ee.Number, ee.Dictionary).
message (str, optional) – A message to print before the object value. Defaults to "".

Returns:

None

Examples

>>> img = ee.Image("USGS/SRTMGL1_003")
>>> printEE(img.bandNames(), "Band names:")

geeViz.getImagesLib.setNoData(image: Image, noDataValue: float) → Image[source]¶

Sets null values for an image, replacing masked pixels with a constant.

Useful for preparing images for export or conversion to arrays where null values are not supported.

Parameters:

image (ee.Image) – The input Earth Engine image.
noDataValue (float) – The value to assign to null (masked) pixels.

Returns:

The image with null pixels replaced by noDataValue.

Return type:

ee.Image

Examples

>>> img = ee.Image("USGS/SRTMGL1_003")
>>> filled = setNoData(img, -9999)

geeViz.getImagesLib.formatArgs(args: dict) → dict[source]¶

Formats arguments as strings for setting as Earth Engine image properties.

Converts booleans, lists, dicts, and None values to their string representations. Strings and ints are kept as-is. Other types are omitted.

Parameters:: args (dict) – A dictionary of arguments to format.
Returns:: A dictionary with values converted to strings or kept as str/int.
Return type:: dict

Examples

>>> formatted = formatArgs({"threshold": 0.5, "apply": True, "bands": ["nir", "swir1"]})
>>> print(formatted)
{'apply': 'True', 'bands': "['nir', 'swir1']"}

geeViz.getImagesLib.sieve(image: Image, mmu: float) → Image[source]¶

Performs clumping and elimination (sieving) on a classified image.

Removes patches smaller than the minimum mapping unit by replacing them with the focal mode of surrounding pixels.

Parameters:

image (ee.Image) – The input classified Earth Engine image.
mmu (float) – The minimum mapping unit in pixels. Patches smaller than this will be replaced by the focal mode.

Returns:

The sieved image with small patches eliminated.

Return type:

ee.Image

Examples

>>> classified = ee.Image("USGS/NLCD/NLCD2019").select("landcover")
>>> sieved = sieve(classified, 5)

geeViz.getImagesLib.harmonizationRoy(oli: Image) → Image[source]¶

Harmonizes Landsat 8 OLI to Landsat 7 ETM+ using Roy et al. (2016) coefficients.

Applies reduced major axis (RMA) regression coefficients from Roy, D.P. et al. (2016) to transform OLI reflectance to ETM+ equivalent. Operates on the blue, green, red, nir, swir1, and swir2 bands.

Parameters:: oli (ee.Image) – A Landsat 8 OLI image with bands named "blue", "green", "red", "nir", "swir1", "swir2".
Returns:: The image with spectral bands adjusted to ETM+ equivalents.
Return type:: ee.Image

Examples

>>> oli_image = ee.Image("LANDSAT/LC08/C02/T1_L2/LC08_044034_20200101")
>>> harmonized = harmonizationRoy(oli_image)

geeViz.getImagesLib.dir0Regression(img, slopes, intercepts)[source]¶

Applies a forward linear regression model: corrected = img * slopes + intercepts.

Used internally by harmonizationChastain() to apply Chastain et al. (2018) cross-sensor harmonization in the forward direction.

Parameters:

img (ee.Image) – The input image with spectral bands to correct.
slopes (list[float]) – Regression slope coefficients for each band in chastainBandNames.
intercepts (list[float]) – Regression intercept coefficients for each band in chastainBandNames.

Returns:

The image with corrected spectral bands and all other bands preserved.

Return type:

ee.Image

Examples

>>> img = ee.Image("LANDSAT/LC08/C02/T1_L2/LC08_044034_20200101")
>>> corrected = dir0Regression(img, msiOLISlopes, msiOLIIntercepts)

geeViz.getImagesLib.dir1Regression(img, slopes, intercepts)[source]¶

Applies an inverse linear regression model: corrected = (img - intercepts) / slopes.

Used internally by harmonizationChastain() to apply Chastain et al. (2018) cross-sensor harmonization in the reverse direction.

Parameters:

img (ee.Image) – The input image with spectral bands to correct.
slopes (list[float]) – Regression slope coefficients for each band in chastainBandNames.
intercepts (list[float]) – Regression intercept coefficients for each band in chastainBandNames.

Returns:

The image with corrected spectral bands and all other bands preserved.

Return type:

ee.Image

Examples

>>> img = ee.Image("LANDSAT/LE07/C02/T1_L2/LE07_044034_20200101")
>>> corrected = dir1Regression(img, oliETMSlopes, oliETMIntercepts)

geeViz.getImagesLib.harmonizationChastain(img: Image, fromSensor: str, toSensor: str) → Image[source]¶

Harmonizes cross-sensor reflectance using Chastain et al. (2018) coefficients.

Supports pairwise harmonization between MSI (Sentinel-2), OLI (Landsat 8/9), and ETM (Landsat 7) using Model 2 (Major Axis) linear regression coefficients from Chastain et al. (2018).

Parameters:

img (ee.Image) – The input image with bands named "blue", "green", "red", "nir", "swir1", "swir2".
fromSensor (str) – Source sensor identifier. One of "MSI", "OLI", or "ETM".
toSensor (str) – Target sensor identifier. One of "MSI", "OLI", or "ETM".

Returns:

The harmonized image with properties "fromSensor" and "toSensor" set.

Return type:

ee.Image

Examples

>>> oli_img = ee.Image("LANDSAT/LC08/C02/T1_L2/LC08_044034_20200101")
>>> harmonized = harmonizationChastain(oli_img, "OLI", "ETM")

geeViz.getImagesLib.collectionToImage(collection: ImageCollection) → Image[source]¶

Converts an image collection to a single multiband image.

Deprecated since version Use: ee.ImageCollection.toBands() instead, which is more efficient.

Iterates over the collection and stacks all bands into a single image.

Parameters:: collection (ee.ImageCollection) – The input Earth Engine image collection.
Returns:: A multiband image containing all bands from all images in the collection.
Return type:: ee.Image

Examples

>>> col = ee.ImageCollection("LANDSAT/LC08/C02/T1_L2").limit(3)
>>> stacked = collectionToImage(col)

geeViz.getImagesLib.compositeDates(images: ImageCollection, composite: Image, bandNames: list = None) → Image[source]¶

Finds the acquisition dates corresponding to each band in a composite image.

Works on composites computed with methods that may include different dates across different bands (e.g., median). For medoid composites, only a single band needs to be passed through. A known limitation is that if the same pixel value occurs on two different dates, only one date will be selected.

Parameters:

images (ee.ImageCollection) – The original image collection used to create the composite.
composite (ee.Image) – The composite image whose per-band dates are to be found.
bandNames (list[str] or ee.List, optional) – Band names to consider. If None, uses all bands from the first image in the collection. Defaults to None.

Returns:

A multiband image where each band contains the date (as YYYYDD float) of the source image that contributed to that band of the composite.

Return type:

ee.Image

Examples

>>> col = ee.ImageCollection("LANDSAT/LC08/C02/T1_L2").filterDate("2020-06-01", "2020-09-01")
>>> composite = col.median()
>>> dates = compositeDates(col, composite, ["SR_B4", "SR_B5"])

geeViz.getImagesLib.fillEmptyCollections(inCollection: ImageCollection, dummyImage: Image) → ImageCollection[source]¶

Fills empty image collections with a fully-masked dummy image.

Prevents downstream errors from empty collections by substituting a single fully-masked dummy image when the input collection contains no images.

Parameters:

inCollection (ee.ImageCollection) – The input image collection that may be empty.
dummyImage (ee.Image) – A template image whose band structure matches the expected output. It will be fully masked (all pixels set to 0) if used.

Returns:

The original collection if non-empty, otherwise a collection containing the fully-masked dummyImage.

Return type:

ee.ImageCollection

Examples

>>> col = ee.ImageCollection("LANDSAT/LC08/C02/T1_L2").filterDate("2000-01-01", "2000-01-02")
>>> dummy = ee.Image("LANDSAT/LC08/C02/T1_L2/LC08_044034_20200101")
>>> safe_col = fillEmptyCollections(col, dummy)

geeViz.getImagesLib.addSensorBand(img: Image, whichProgram: str, toaOrSR: str) → Image[source]¶

Adds a band encoding the satellite sensor as a numeric value.

Maps satellite names (e.g., LANDSAT_8, Sentinel-2A) to integer codes (e.g., 8, 21) and adds the result as a "sensor" band. Also sets the "sensor" property on the image.

Parameters:

img (ee.Image) – The input Earth Engine image with appropriate spacecraft metadata.
whichProgram (str) – The satellite program. One of "C1_landsat", "C2_landsat", or "sentinel2".
toaOrSR (str) – The processing level, "TOA" or "SR".

Returns:

The input image with an added "sensor" band (byte type) and "sensor" property.

Return type:

ee.Image

Examples

>>> img = ee.Image("LANDSAT/LC08/C02/T1_L2/LC08_044034_20200101")
>>> with_sensor = addSensorBand(img, "C2_landsat", "SR")

geeViz.getImagesLib.addDateBand(img: Image, maskTime: bool = False) → Image[source]¶

Adds a "year" band containing the fractional year (year + day-of-year fraction).

The band value is computed as year + fraction_of_year (e.g., 2020.5 for approximately July 2, 2020).

Parameters:

img (ee.Image) – The input Earth Engine image with a "system:time_start" property.
maskTime (bool, optional) – If True, masks the date band to match the first band’s mask of the input image. Defaults to False.

Returns:

The input image with an added "year" band (float).

Return type:

ee.Image

Examples

>>> img = ee.Image("LANDSAT/LC08/C02/T1_L2/LC08_044034_20200701")
>>> with_date = addDateBand(img)
>>> with_masked_date = addDateBand(img, maskTime=True)

geeViz.getImagesLib.addYearFractionBand(img: Image) → Image[source]¶

Adds a "year" band containing only the fractional part of the year (0 to 1).

Unlike addDateBand(), this does not include the integer year component. A value of 0.5 corresponds to approximately July 2.

Parameters:: img (ee.Image) – The input Earth Engine image with a "system:time_start" property.
Returns:: The input image with an added "year" band (float, range 0–1).
Return type:: ee.Image

Examples

>>> img = ee.Image("LANDSAT/LC08/C02/T1_L2/LC08_044034_20200701")
>>> with_frac = addYearFractionBand(img)

geeViz.getImagesLib.addYearYearFractionBand(img: Image) → Image[source]¶

Adds a "year" band containing the full fractional year (year + fraction).

Functionally equivalent to addDateBand() with maskTime=False, but computed by explicitly adding the integer year and fractional year components.

Parameters:: img (ee.Image) – The input Earth Engine image with a "system:time_start" property.
Returns:: The input image with an added "year" band (float, e.g., 2020.5).
Return type:: ee.Image

Examples

>>> img = ee.Image("LANDSAT/LC08/C02/T1_L2/LC08_044034_20200701")
>>> with_year_frac = addYearYearFractionBand(img)

geeViz.getImagesLib.addYearBand(img: Image) → Image[source]¶

Adds a "year" band containing the integer year of the image acquisition.

Parameters:: img (ee.Image) – The input Earth Engine image with a "system:time_start" property.
Returns:: The input image with an added "year" band (float, e.g., 2020.0).
Return type:: ee.Image

Examples

>>> img = ee.Image("LANDSAT/LC08/C02/T1_L2/LC08_044034_20200701")
>>> with_year = addYearBand(img)

geeViz.getImagesLib.addJulianDayBand(img: Image) → Image[source]¶

Adds a "julianDay" band containing the day of the year (1–366).

Parameters:: img (ee.Image) – The input Earth Engine image with a "system:time_start" property.
Returns:: The input image with an added "julianDay" band (float).
Return type:: ee.Image

Examples

>>> img = ee.Image("LANDSAT/LC08/C02/T1_L2/LC08_044034_20200701")
>>> with_julian = addJulianDayBand(img)

geeViz.getImagesLib.addYearJulianDayBand(img: Image) → Image[source]¶

Adds a "yearJulian" band encoding the 2-digit year and Julian day (YYDD).

The band value is a number in the format YYDD, where YY is the 2-digit year and DD is the day of the year. For example, January 15, 2020 yields 2015.

Parameters:: img (ee.Image) – The input Earth Engine image with a "system:time_start" property.
Returns:: The input image with an added "yearJulian" band (float).
Return type:: ee.Image

Examples

>>> img = ee.Image("LANDSAT/LC08/C02/T1_L2/LC08_044034_20200115")
>>> with_yj = addYearJulianDayBand(img)

geeViz.getImagesLib.addFullYearJulianDayBand(img: Image) → Image[source]¶

Adds a "yearJulian" band encoding the full 4-digit year and Julian day (YYYYDD).

The band value is a number in the format YYYYDD, where YYYY is the 4-digit year and DD is the day of the year. For example, July 1, 2020 yields 2020182.

Parameters:: img (ee.Image) – The input Earth Engine image with a "system:time_start" property.
Returns:: The input image with an added "yearJulian" band (int64, cast to float).
Return type:: ee.Image

Examples

>>> img = ee.Image("LANDSAT/LC08/C02/T1_L2/LC08_044034_20200701")
>>> with_full_yj = addFullYearJulianDayBand(img)

geeViz.getImagesLib.offsetImageDate(img: Image, n: int, unit: str) → Image[source]¶

Offsets the system:time_start property of an image by a specified amount.

Useful for shifting image dates when creating synthetic time series or aligning images from different years.

Parameters:

img (ee.Image) – The input Earth Engine image with a "system:time_start" property.
n (int) – The number of units to offset. Can be negative to shift backward.
unit (str) – The time unit for the offset. One of "year", "month", "week", "day", "hour", "minute", or "second".

Returns:

The image with its "system:time_start" property updated.

Return type:

ee.Image

Examples

>>> img = ee.Image("LANDSAT/LC08/C02/T1_L2/LC08_044034_20200701")
>>> shifted = offsetImageDate(img, -1, "year")

geeViz.getImagesLib.defringeLandsat(img: Image) → Image[source]¶

Defringes a Landsat 7 image by masking fringe pixels with insufficient valid neighbors.

Parameters:: img (ee.Image) – The input Landsat 7 image to defringe.
Returns:: The defringed Landsat 7 image with fringe pixels masked out.
Return type:: ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> l7 = ee.ImageCollection("LANDSAT/LE07/C02/T1").first()
>>> defringed = gil.defringeLandsat(l7)

geeViz.getImagesLib.uniqueValues(collection: ImageCollection, field: str) → List[source]¶

Finds unique values of a field in an image collection.

Parameters:

collection (ee.ImageCollection) – The input Earth Engine image collection.
field (str) – The metadata field name to extract unique values from.

Returns:

A list of unique values for the specified field.

Return type:

ee.List

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> col = ee.ImageCollection("LANDSAT/LC08/C02/T1").filterDate("2023-06-01", "2023-06-30")
>>> paths = gil.uniqueValues(col, "WRS_PATH")

geeViz.getImagesLib.dailyMosaics(imgs: ImageCollection) → ImageCollection[source]¶

Creates daily mosaics from an image collection grouped by date and orbit.

Groups images by acquisition date and Sentinel-2 orbit number, then mosaics them to remove redundant observations in MGRS tile overlap areas.

Parameters:: imgs (ee.ImageCollection) – The input Earth Engine image collection. Must contain the SENSING_ORBIT_NUMBER property (Sentinel-2).
Returns:: A collection of daily mosaic images, one per unique date-orbit combination.
Return type:: ee.ImageCollection

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> s2 = ee.ImageCollection("COPERNICUS/S2_HARMONIZED").filterDate("2023-06-01", "2023-06-10")
>>> daily = gil.dailyMosaics(s2)

geeViz.getImagesLib.toNatural(img: Image) → Image[source]¶

Converts a Sentinel-1 image from dB to natural (linear power) units.

Applies the formula: 10^(dB / 10).

Parameters:: img (ee.Image) – The input Sentinel-1 image in dB units.
Returns:: The converted image in natural (linear power) units.
Return type:: ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> s1 = ee.ImageCollection("COPERNICUS/S1_GRD").first()
>>> natural = gil.toNatural(s1)

geeViz.getImagesLib.toDB(img: Image) → Image[source]¶

Converts a Sentinel-1 image from natural (linear power) units to dB.

Applies the formula: 10 * log10(value).

Parameters:: img (ee.Image) – The input Sentinel-1 image in natural (linear power) units.
Returns:: The converted image in dB units.
Return type:: ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> natural_img = gil.toNatural(ee.ImageCollection("COPERNICUS/S1_GRD").first())
>>> db_img = gil.toDB(natural_img)

geeViz.getImagesLib.RefinedLee(img: Image) → Image[source]¶

Applies the Refined Lee speckle filter to a Sentinel-1 image.

Implements the Refined Lee filter as coded in SNAP 3.0 S1TBX. Uses directional statistics in 7x7 neighborhoods to reduce speckle noise while preserving edges. The input image must be in natural (linear) units, not dB.

Parameters:: img (ee.Image) – The input Sentinel-1 image in natural (linear power) units. Use toNatural() to convert from dB first.
Returns:: The speckle-filtered image with a single band named "sum".
Return type:: ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> s1 = ee.ImageCollection("COPERNICUS/S1_GRD").first().select("VV")
>>> filtered = gil.RefinedLee(gil.toNatural(s1))

geeViz.getImagesLib.getS1(studyArea: Geometry | Feature | FeatureCollection, startYear: int, endYear: int, startJulian: int, endJulian: int, polarization: str = 'VV', pass_direction: str = 'ASCENDING') → ImageCollection[source]¶

Loads Sentinel-1 GRD data for a given area and time period.

Filters the COPERNICUS/S1_GRD collection by date, bounds, IW instrument mode, polarization, pass direction, and 10m resolution.

Parameters:

studyArea (ee.Geometry | ee.Feature | ee.FeatureCollection) – The geographic area of interest.
startYear (int) – The start year (inclusive).
endYear (int) – The end year (inclusive).
startJulian (int) – The start Julian day of year (1-365).
endJulian (int) – The end Julian day of year (1-365).
polarization (str, optional) – The desired polarization band. Defaults to "VV". Other option is "VH".
pass_direction (str, optional) – The orbit pass direction. Defaults to "ASCENDING". Other option is "DESCENDING".

Returns:

A collection of Sentinel-1 GRD images filtered by the specified criteria.

Return type:

ee.ImageCollection

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CA"]
>>> s1 = gil.getS1(studyArea, 2023, 2023, 1, 365)
>>> print(s1.size().getInfo())

geeViz.getImagesLib.getS2(studyArea: Geometry | Feature | FeatureCollection, startDate: Date | datetime | str, endDate: Date | datetime | str, startJulian: int = 1, endJulian: int = 365, resampleMethod: str = 'nearest', toaOrSR: str = 'TOA', convertToDailyMosaics: bool = True, addCloudProbability: bool = False, addCloudScorePlus: bool = True, cloudScorePlusScore: str = 'cs') → ImageCollection[source]¶

Loads Sentinel-2 data for a given area and time period and joins cloud score information. Partially deprecated in favor of the simpler superSimpleGetS2.

Parameters:

studyArea – The geographic area of interest.
startDate – The start date of the desired data. Can be an ee.Date object, datetime object, or date string.
endDate – The end date of the desired data. Can be an ee.Date object, datetime object, or date string.
startJulian – The start Julian day of the desired data.
endJulian – The end Julian day of the desired data.
resampleMethod – The resampling method (default: “nearest”).
toaOrSR – Whether to load TOA or SR data (default: “TOA”).
convertToDailyMosaics – Whether to convert the data to daily mosaics (default: True).
addCloudProbability – Whether to add cloud probability data (default: False).
addCloudScorePlus – Whether to add cloud score plus data (default: True).
cloudScorePlusScore – The band name for cloud score plus (default: “cs”).

Returns:

A collection of Sentinel-2 satellite images filtered by the specified criteria.

Return type:

ee.ImageCollection

>>> import geeViz.getImagesLib as gil
>>> Map = gil.Map
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CA"]
>>> composite = gil.getS2(studyArea, "2024-01-01", "2024-12-31", 190, 250).median()
>>> Map.addLayer(composite, gil.vizParamsFalse, "Sentinel-2 Composite")
>>> Map.addLayer(studyArea, {"canQuery": False}, "Study Area")
>>> Map.centerObject(studyArea)
>>> Map.turnOnInspector()
>>> Map.view()

geeViz.getImagesLib.getSentinel2(studyArea: Geometry | Feature | FeatureCollection, startDate: Date | datetime | str, endDate: Date | datetime | str, startJulian: int = 1, endJulian: int = 365, resampleMethod: str = 'nearest', toaOrSR: str = 'TOA', convertToDailyMosaics: bool = True, addCloudProbability: bool = False, addCloudScorePlus: bool = True, cloudScorePlusScore: str = 'cs') → ImageCollection¶

Loads Sentinel-2 data for a given area and time period and joins cloud score information. Partially deprecated in favor of the simpler superSimpleGetS2.

Parameters:

studyArea – The geographic area of interest.
startDate – The start date of the desired data. Can be an ee.Date object, datetime object, or date string.
endDate – The end date of the desired data. Can be an ee.Date object, datetime object, or date string.
startJulian – The start Julian day of the desired data.
endJulian – The end Julian day of the desired data.
resampleMethod – The resampling method (default: “nearest”).
toaOrSR – Whether to load TOA or SR data (default: “TOA”).
convertToDailyMosaics – Whether to convert the data to daily mosaics (default: True).
addCloudProbability – Whether to add cloud probability data (default: False).
addCloudScorePlus – Whether to add cloud score plus data (default: True).
cloudScorePlusScore – The band name for cloud score plus (default: “cs”).

Returns:

A collection of Sentinel-2 satellite images filtered by the specified criteria.

Return type:

ee.ImageCollection

>>> import geeViz.getImagesLib as gil
>>> Map = gil.Map
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CA"]
>>> composite = gil.getS2(studyArea, "2024-01-01", "2024-12-31", 190, 250).median()
>>> Map.addLayer(composite, gil.vizParamsFalse, "Sentinel-2 Composite")
>>> Map.addLayer(studyArea, {"canQuery": False}, "Study Area")
>>> Map.centerObject(studyArea)
>>> Map.turnOnInspector()
>>> Map.view()

geeViz.getImagesLib.applyScaleFactors(image, landsatCollectionVersion)[source]¶

Rescales Landsat reflectance bands to 0-1 and thermal bands to Kelvin.

Applies collection-specific scale factors and offsets to optical and thermal bands. Adapted from the method provided by Google for rescaling Collection 2.

Parameters:

image (ee.Image) – The input Landsat image with common band names (blue, green, red, nir, swir1, swir2, temp).
landsatCollectionVersion (str) – The Landsat collection version, either "C1" or "C2".

Returns:

The image with optical bands scaled to 0-1 reflectance and the thermal band scaled to Kelvin.

Return type:

ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> img = ee.Image("LANDSAT/LC08/C02/T1_L2/LC08_044034_20210508")
>>> img = img.select(["SR_B2","SR_B3","SR_B4","SR_B5","SR_B6","ST_B10","SR_B7"],
...                  ["blue","green","red","nir","swir1","temp","swir2"])
>>> scaled = gil.applyScaleFactors(img, "C2")

geeViz.getImagesLib.getLandsat(studyArea: Geometry | Feature | FeatureCollection, startDate: Date | datetime | str, endDate: Date | datetime | str, startJulian: int = 1, endJulian: int = 365, toaOrSR: str = 'SR', includeSLCOffL7: bool = False, defringeL5: bool = False, addPixelQA: bool = False, resampleMethod: str = 'near', landsatCollectionVersion: str = 'C2')[source]¶

Retrieves Landsat imagery for a specified study area and date range.

Parameters:

studyArea (ee.Geometry, ee.Feature, or ee.FeatureCollection) – The geographic area of interest.
startDate (ee.Date, datetime.datetime, or str) – The start date of the desired image range.
endDate (ee.Date, datetime.datetime, or str) – The end date of the desired image range.
startJulian (int, optional) – The start Julian day of the desired image range. Defaults to 1.
endJulian (int, optional) – The end Julian day of the desired image range. Defaults to 365.
toaOrSR (str, optional) – Whether to retrieve TOA or SR data. Defaults to “SR”.
includeSLCOffL7 (bool, optional) – Whether to include SLC-off L7 data. Defaults to False.
defringeL5 (bool, optional) – Whether to defringe L5 data. Defaults to False.
addPixelQA (bool, optional) – Whether to add pixel QA band. Defaults to False.
resampleMethod (str, optional) – Resampling method. Options are “near”, “bilinear”, or “bicubic”. Defaults to “near”.
landsatCollectionVersion (str, optional) – Landsat collection version. Options are “C1” or “C2”. Defaults to “C2”.

Returns:

A collection of Landsat images meeting the specified criteria.

Return type:

ee.ImageCollection

>>> import geeViz.getImagesLib as gil
>>> Map = gil.Map
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CA"]
>>> composite = gil.getLandsat(studyArea, "2024-01-01", "2024-12-31", 190, 250).median()
>>> Map.addLayer(composite, gil.vizParamsFalse, "Landsat Composite")
>>> Map.addLayer(studyArea, {"canQuery": False}, "Study Area")
>>> Map.centerObject(studyArea)
>>> Map.turnOnInspector()
>>> Map.view()

geeViz.getImagesLib.getImageCollection(studyArea: Geometry | Feature | FeatureCollection, startDate: Date | datetime | str, endDate: Date | datetime | str, startJulian: int = 1, endJulian: int = 365, toaOrSR: str = 'SR', includeSLCOffL7: bool = False, defringeL5: bool = False, addPixelQA: bool = False, resampleMethod: str = 'near', landsatCollectionVersion: str = 'C2')¶

Retrieves Landsat imagery for a specified study area and date range.

Parameters:

studyArea (ee.Geometry, ee.Feature, or ee.FeatureCollection) – The geographic area of interest.
startDate (ee.Date, datetime.datetime, or str) – The start date of the desired image range.
endDate (ee.Date, datetime.datetime, or str) – The end date of the desired image range.
startJulian (int, optional) – The start Julian day of the desired image range. Defaults to 1.
endJulian (int, optional) – The end Julian day of the desired image range. Defaults to 365.
toaOrSR (str, optional) – Whether to retrieve TOA or SR data. Defaults to “SR”.
includeSLCOffL7 (bool, optional) – Whether to include SLC-off L7 data. Defaults to False.
defringeL5 (bool, optional) – Whether to defringe L5 data. Defaults to False.
addPixelQA (bool, optional) – Whether to add pixel QA band. Defaults to False.
resampleMethod (str, optional) – Resampling method. Options are “near”, “bilinear”, or “bicubic”. Defaults to “near”.
landsatCollectionVersion (str, optional) – Landsat collection version. Options are “C1” or “C2”. Defaults to “C2”.

Returns:

A collection of Landsat images meeting the specified criteria.

Return type:

ee.ImageCollection

>>> import geeViz.getImagesLib as gil
>>> Map = gil.Map
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CA"]
>>> composite = gil.getLandsat(studyArea, "2024-01-01", "2024-12-31", 190, 250).median()
>>> Map.addLayer(composite, gil.vizParamsFalse, "Landsat Composite")
>>> Map.addLayer(studyArea, {"canQuery": False}, "Study Area")
>>> Map.centerObject(studyArea)
>>> Map.turnOnInspector()
>>> Map.view()

geeViz.getImagesLib.rescale(img: Image, thresholds: tuple) → Image[source]¶

Rescales pixel values in an image using min-max normalization.

Computes (img - min) / (max - min) for linear rescaling. Used internally by cloud scoring functions.

Parameters:

img (ee.Image) – The input Earth Engine image (typically single-band).
thresholds (tuple[float, float]) – A tuple of (min, max) values for the rescaling range.

Returns:

The rescaled image with values nominally between 0 and 1.

Return type:

ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> img = ee.Image.constant(0.2)
>>> rescaled = gil.rescale(img, (0.1, 0.3))

geeViz.getImagesLib.projectShadows(cloudMask, image, irSumThresh, contractPixels, dilatePixels, cloudHeights, yMult=None)[source]¶

Projects cloud shadows based on solar geometry and masks them along with clouds.

Uses solar azimuth and zenith angles to cast shadows from a cloud mask at multiple cloud heights, then combines the shadow mask with a dark-pixel test.

Parameters:

cloudMask (ee.Image) – A binary cloud mask image (1 = cloud).
image (ee.Image) – The input satellite image with bands nir, swir1, swir2 and metadata properties MEAN_SOLAR_AZIMUTH_ANGLE and MEAN_SOLAR_ZENITH_ANGLE.
irSumThresh (float) – Threshold for the sum of infrared bands to identify dark pixels (e.g., 0.35).
contractPixels (float) – Number of pixels to erode the shadow mask.
dilatePixels (float) – Number of pixels to dilate the shadow mask.
cloudHeights (ee.List) – List of cloud heights (in meters) to test for shadow projection (e.g., ee.List.sequence(500, 10000, 500)).
yMult (int | None, optional) – Multiplier for the Y shadow direction. Automatically determined from projection if None. Defaults to None.

Returns:

The input image with cloud and cloud shadow pixels masked out and a cloudShadowMask band appended.

Return type:

ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> heights = ee.List.sequence(500, 10000, 500)
>>> # Typically called via projectShadowsWrapper rather than directly

geeViz.getImagesLib.projectShadowsWrapper(img, cloudThresh=20, irSumThresh=0.35, contractPixels=1.5, dilatePixels=3.5, cloudHeights=<ee.ee_list.List object>)[source]¶

Wrapper that computes a cloud mask and projects cloud shadows for a Sentinel-2 image.

Combines cloud scoring with shadow projection in a single step. Uses sentinel2CloudScore to generate a cloud mask, then calls projectShadows to find and mask cloud shadows.

Parameters:

img (ee.Image) – The input Sentinel-2 image with common band names.
cloudThresh (float, optional) – Cloud score threshold (0-100). Pixels above this are considered cloud. Defaults to 20.
irSumThresh (float, optional) – IR sum threshold for dark pixel detection. Defaults to 0.35.
contractPixels (float, optional) – Erosion kernel size in pixels. Defaults to 1.5.
dilatePixels (float, optional) – Dilation kernel size in pixels. Defaults to 3.5.
cloudHeights (ee.List, optional) – Cloud heights to test in meters. Defaults to ee.List.sequence(500, 10000, 500).

Returns:

The image with clouds and cloud shadows masked out.

Return type:

ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CA"]
>>> s2 = gil.getS2(studyArea, "2023-06-01", "2023-09-01", 152, 244)
>>> masked = s2.map(gil.projectShadowsWrapper)

geeViz.getImagesLib.maskS2clouds(image: Image) → Image[source]¶

Masks clouds and cirrus in a Sentinel-2 image using the QA60 band.

Uses bits 10 (opaque clouds) and 11 (cirrus) of the QA60 band to create a binary cloud mask.

Parameters:: image (ee.Image) – The input Sentinel-2 image containing a QA60 band.
Returns:: The cloud-masked Sentinel-2 image.
Return type:: ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> s2 = ee.ImageCollection("COPERNICUS/S2_HARMONIZED").first()
>>> masked = gil.maskS2clouds(s2)

geeViz.getImagesLib.landsatCloudScore(img: Image) → Image[source]¶

Computes a cloud score for a Landsat image based on spectral indicators.

Evaluates multiple cloud indicators (blue brightness, visible brightness, IR brightness, temperature, and NDSI) and returns the minimum score. Works across sensors as long as the image uses common band names (blue, green, red, nir, swir1, swir2, temp).

Parameters:: img (ee.Image) – The input image with common band names: blue, green, red, nir, swir1, swir2, and temp.
Returns:: A single-band image named "cloudScore" with values 0-100, where higher values indicate greater cloud likelihood.
Return type:: ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CA"]
>>> ls = gil.getLandsat(studyArea, "2023-06-01", "2023-09-01", 152, 244)
>>> scored = ls.map(lambda img: img.addBands(gil.landsatCloudScore(img)))

geeViz.getImagesLib.applyCloudScoreAlgorithm(collection: ImageCollection, cloudScoreFunction: function, cloudScoreThresh: float = 20, cloudScorePctl: float = 10, contractPixels: float = 1.5, dilatePixels: float = 3.5, performCloudScoreOffset: bool = True, preComputedCloudScoreOffset: Image = None) → ImageCollection[source]¶

Applies a cloud score algorithm to an image collection and masks cloudy pixels.

Computes per-pixel cloud scores, optionally subtracts a percentile-based offset to reduce commission errors, then masks pixels exceeding the threshold.

Parameters:

collection (ee.ImageCollection) – The input image collection.
cloudScoreFunction (Callable[[ee.Image], ee.Image]) – A function that takes an image and returns a single-band cloud score image.
cloudScoreThresh (float, optional) – Cloud score threshold for masking. Defaults to 20.
cloudScorePctl (float, optional) – Percentile for computing the cloud score offset. Defaults to 10.
contractPixels (float, optional) – Erosion kernel size in pixels. Defaults to 1.5.
dilatePixels (float, optional) – Dilation kernel size in pixels. Defaults to 3.5.
performCloudScoreOffset (bool, optional) – Whether to subtract a per-pixel offset based on the time series. Defaults to True.
preComputedCloudScoreOffset (ee.Image | None, optional) – A pre-computed cloud score offset image. If None, computed from the collection. Defaults to None.

Returns:

The image collection with cloudy pixels masked out.

Return type:

ee.ImageCollection

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CA"]
>>> ls = gil.getLandsat(studyArea, "2023-06-01", "2023-09-01", 152, 244)
>>> masked = gil.applyCloudScoreAlgorithm(ls, gil.landsatCloudScore)

geeViz.getImagesLib.cFmask(img: Image, fmaskClass: str, bitMaskBandName: str = 'QA_PIXEL') → Image[source]¶

Applies the CFMask algorithm to mask a specific class in a Landsat image.

Supports masking clouds, cloud shadows, snow, and confidence-level cloud classes using the QA_PIXEL bitmask band.

Parameters:

img (ee.Image) – The input Landsat image containing a QA bitmask band.
fmaskClass (str) – The class to mask. Options: "cloud", "shadow", "snow", "high_confidence_cloud", "med_confidence_cloud".
bitMaskBandName (str, optional) – The name of the QA bitmask band. Defaults to "QA_PIXEL".

Returns:

The image with the specified class masked out.

Return type:

ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CA"]
>>> ls = gil.getLandsat(studyArea, "2023-06-01", "2023-09-01", 152, 244)
>>> cloud_masked = ls.map(lambda img: gil.cFmask(img, "cloud"))

geeViz.getImagesLib.applyBitMask(img: Image, bit: int, bitMaskBandName: str = 'QA_PIXEL') → Image[source]¶

Masks pixels where a specific bit is set in a QA bitmask band.

Parameters:

img (ee.Image) – The input image containing a QA bitmask band.
bit (int) – The bit position (0-indexed) to test. Pixels with this bit set to 1 will be masked out.
bitMaskBandName (str, optional) – The name of the QA bitmask band. Defaults to "QA_PIXEL".

Returns:

The image with pixels masked where the specified bit is set.

Return type:

ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> img = ee.Image("LANDSAT/LC08/C02/T1_L2/LC08_044034_20210508")
>>> cloud_masked = gil.applyBitMask(img, 3)  # Bit 3 = cloud in C2

geeViz.getImagesLib.cFmaskCloud(img: Image, landsatCollectionVersion: str, bitMaskBandName: str = 'QA_PIXEL') → Image[source]¶

Applies the CFMask cloud mask to a Landsat image.

Convenience wrapper around applyBitMask that uses the correct cloud bit position for the specified Landsat collection version.

Parameters:

img (ee.Image) – The input Landsat image containing a QA bitmask band.
landsatCollectionVersion (str) – The Landsat collection version ("C1" or "C2").
bitMaskBandName (str, optional) – The name of the QA bitmask band. Defaults to "QA_PIXEL".

Returns:

The image with cloud pixels masked out.

Return type:

ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CA"]
>>> ls = gil.getLandsat(studyArea, "2023-06-01", "2023-09-01", 152, 244)
>>> cloud_free = ls.map(lambda img: gil.cFmaskCloud(img, "C2"))

geeViz.getImagesLib.cFmaskCloudShadow(img: Image, landsatCollectionVersion: str, bitMaskBandName: str = 'QA_PIXEL') → Image[source]¶

Applies the CFMask cloud shadow mask to a Landsat image.

Convenience wrapper around applyBitMask that uses the correct shadow bit position for the specified Landsat collection version.

Parameters:

img (ee.Image) – The input Landsat image containing a QA bitmask band.
landsatCollectionVersion (str) – The Landsat collection version ("C1" or "C2").
bitMaskBandName (str, optional) – The name of the QA bitmask band. Defaults to "QA_PIXEL".

Returns:

The image with cloud shadow pixels masked out.

Return type:

ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CA"]
>>> ls = gil.getLandsat(studyArea, "2023-06-01", "2023-09-01", 152, 244)
>>> shadow_free = ls.map(lambda img: gil.cFmaskCloudShadow(img, "C2"))

geeViz.getImagesLib.simpleTDOM2(collection: ImageCollection, zScoreThresh: float = -1, shadowSumThresh: float = 0.35, contractPixels: float = 1.5, dilatePixels: float = 3.5, shadowSumBands: list = ['nir', 'swir1'], preComputedTDOMIRMean: Image | None = None, preComputedTDOMIRStdDev: Image | None = None) → ImageCollection[source]¶

Applies Temporal Dark Outlier Mask (TDOM) to detect and mask cloud shadows.

Identifies dark outlier pixels by comparing each image to the temporal mean and standard deviation. Pixels that are both statistically dark (z-score below threshold) and absolutely dark (IR sum below threshold) are masked.

Parameters:

collection (ee.ImageCollection) – The input image collection.
zScoreThresh (float, optional) – Z-score threshold for identifying dark outliers. More negative values are more conservative. Defaults to -1.
shadowSumThresh (float, optional) – Absolute threshold for the sum of shadow bands. Defaults to 0.35.
contractPixels (float, optional) – Erosion kernel size in pixels. Defaults to 1.5.
dilatePixels (float, optional) – Dilation kernel size in pixels. Defaults to 3.5.
shadowSumBands (list[str], optional) – Band names used for shadow detection. Defaults to ["nir", "swir1"].
preComputedTDOMIRMean (ee.Image | None, optional) – Pre-computed temporal mean of shadow bands. Computed from collection if None. Defaults to None.
preComputedTDOMIRStdDev (ee.Image | None, optional) – Pre-computed temporal standard deviation. Computed from collection if None. Defaults to None.

Returns:

The collection with dark outlier (shadow) pixels masked out.

Return type:

ee.ImageCollection

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CA"]
>>> ls = gil.getLandsat(studyArea, "2023-01-01", "2023-12-31", 152, 244)
>>> shadow_free = gil.simpleTDOM2(ls)

geeViz.getImagesLib.addIndices(img: Image) → Image[source]¶

Adds a comprehensive set of spectral indices to an image.

Computes all pairwise normalized differences (NDSV) across blue, green, red, nir, swir1, and swir2 bands. Also adds band ratios, EVI, SAVI, and IBI.

Parameters:

img (ee.Image) – Input image with bands named ‘blue’, ‘green’, ‘red’, ‘nir’, ‘swir1’, and ‘swir2’.

Returns:

The input image with additional bands including ND_*: (normalized differences), R_* (ratios), EVI, SAVI, and IBI.

Return type:

ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> img = ee.Image('LANDSAT/LC08/C02/T1_L2/LC08_044034_20200601')
>>> img_with_indices = addIndices(img)
>>> print(img_with_indices.bandNames().getInfo())

geeViz.getImagesLib.addSAVIandEVI(img: Image) → Image[source]¶

Adds SAVI, EVI, and NIRv vegetation indices to an image.

Computes the Enhanced Vegetation Index (EVI), Soil Adjusted Vegetation Index (SAVI with L=0.5), and Near-Infrared Reflectance of Vegetation (NIRv).

Parameters:: img (ee.Image) – Input image with bands named ‘nir’, ‘red’, ‘blue’, and ‘NDVI’. The NDVI band is required for NIRv computation.
Returns:: The input image with added ‘EVI’, ‘SAVI’, and ‘NIRv’ bands.
Return type:: ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> img = simpleAddIndices(ee.Image('LANDSAT/LC08/C02/T1_L2/LC08_044034_20200601'))
>>> img_with_vi = addSAVIandEVI(img)
>>> print(img_with_vi.select(['EVI', 'SAVI', 'NIRv']).bandNames().getInfo())

geeViz.getImagesLib.HoCalcAlgorithm2(image: Image) → Image[source]¶

Applies an algal bloom detection algorithm to an image.

Computes a green/blue ratio (‘bloom2’) and Normalized Difference Green Index (‘NDGI’) based on Matthews (2011), DOI: 10.1080/01431161.2010.512947.

Parameters:

image (ee.Image) – Input image with ‘green’ and ‘blue’ bands.

Returns:

The input image with added ‘bloom2’ (green/blue ratio): and ‘NDGI’ (normalized difference of green and blue) bands.

Return type:

ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> img = ee.Image('LANDSAT/LC08/C02/T1_L2/LC08_044034_20200601')
>>> bloom_img = HoCalcAlgorithm2(img)
>>> print(bloom_img.select(['bloom2', 'NDGI']).bandNames().getInfo())

geeViz.getImagesLib.simpleAddIndices(in_image: Image) → Image[source]¶

Adds common spectral indices (NDVI, NBR, NDMI, NDSI) to an image.

A lightweight alternative to addIndices that computes only the four most commonly used normalized-difference indices.

Parameters:

in_image (ee.Image) – Input image with bands named ‘nir’, ‘red’, ‘swir1’, ‘swir2’, and ‘green’.

Returns:

The input image with added ‘NDVI’, ‘NBR’, ‘NDMI’, and: ’NDSI’ bands.

Return type:

ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> img = ee.Image('LANDSAT/LC08/C02/T1_L2/LC08_044034_20200601')
>>> img = simpleAddIndices(img)
>>> print(img.select(['NDVI', 'NBR', 'NDMI', 'NDSI']).bandNames().getInfo())

geeViz.getImagesLib.addWaterIndices(in_image: Image) → Image[source]¶

Add water detection indices (MNDWI, AWEI_nsh) to an image.

MNDWI (Modified Normalized Difference Water Index; Xu 2006): (green − swir1) / (green + swir1). Better than NDWI for separating water from built-up areas.
AWEI_nsh (Automated Water Extraction Index, no-shadow; Feyisa et al. 2014): 4 × (green − swir1) − (0.25 × nir + 2.75 × swir2). Robust to shadows, dark urban surfaces, and saline water.

Parameters:: in_image (ee.Image) – Input image with bands named green, nir, swir1, swir2. Values should be 0–1 reflectance.
Returns:: The input image with added MNDWI and AWEI_nsh bands.
Return type:: ee.Image

Example

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> img = ee.Image(1).rename(['blue','green','red','nir','swir1','swir2'])
>>> img = gil.addWaterIndices(img)
>>> print(img.select(['MNDWI', 'AWEI_nsh']).bandNames().getInfo())
['MNDWI', 'AWEI_nsh']

geeViz.getImagesLib.addSoilIndices(img: Image) → Image[source]¶

Adds soil-related spectral indices to an image.

Computes NDCI (Normalized Difference Chlorophyll Index), NDII (Normalized Difference Infrared Index), NDFI (Normalized Difference Fraction Index), BSI (Bare Soil Index), and HI (SWIR1/SWIR2 ratio).

Parameters:

img (ee.Image) – Input image with bands named ‘blue’, ‘red’, ‘green’, ‘nir’, ‘swir1’, and ‘swir2’.

Returns:

The input image with added ‘NDCI’, ‘NDII’, ‘NDFI’, ‘BSI’,: and ‘HI’ bands.

Return type:

ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> img = ee.Image('LANDSAT/LC08/C02/T1_L2/LC08_044034_20200601')
>>> img = addSoilIndices(img)
>>> print(img.select(['BSI', 'HI']).bandNames().getInfo())

geeViz.getImagesLib.getTasseledCap(image: Image) → Image[source]¶

Computes the Tasseled Cap transformation using Crist 1985 coefficients.

Applies the 6-component Tasseled Cap transformation for TOA reflectance data using coefficients from Crist (1985).

Parameters:

image (ee.Image) – Input image with bands named ‘blue’, ‘green’, ‘red’, ‘nir’, ‘swir1’, and ‘swir2’.

Returns:

The input image with added ‘brightness’, ‘greenness’,: ’wetness’, ‘fourth’, ‘fifth’, and ‘sixth’ bands.

Return type:

ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> img = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20200601')
>>> tc = getTasseledCap(img)
>>> print(tc.select(['brightness', 'greenness', 'wetness']).bandNames().getInfo())

geeViz.getImagesLib.simpleGetTasseledCap(image: Image) → Image[source]¶

Computes a simplified Tasseled Cap with brightness, greenness, and wetness only.

Uses Crist 1985 TOA reflectance coefficients but returns only the first three components, omitting the fourth through sixth.

Parameters:

image (ee.Image) – Input image with bands named ‘blue’, ‘green’, ‘red’, ‘nir’, ‘swir1’, and ‘swir2’.

Returns:

The input image with added ‘brightness’, ‘greenness’, and: ’wetness’ bands.

Return type:

ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> img = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20200601')
>>> tc = simpleGetTasseledCap(img)
>>> print(tc.select(['brightness', 'greenness', 'wetness']).bandNames().getInfo())

geeViz.getImagesLib.addTCAngles(image: Image) → Image[source]¶

Adds Tasseled Cap angles and distances to an image.

Computes pairwise angles (atan2) and Euclidean distances (hypot) between the brightness, greenness, and wetness TC components. Angles are divided by pi to normalize to the range [-1, 1].

Parameters:

image (ee.Image) – Input image with ‘brightness’, ‘greenness’, and ‘wetness’ bands (e.g., output of getTasseledCap).

Returns:

The input image with added bands: ‘tcAngleBG’, ‘tcAngleGW’,: ’tcAngleBW’, ‘tcDistBG’, ‘tcDistGW’, ‘tcDistBW’.

Return type:

ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> img = getTasseledCap(ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20200601'))
>>> img = addTCAngles(img)
>>> print(img.select(['tcAngleBG', 'tcDistBG']).bandNames().getInfo())

geeViz.getImagesLib.simpleAddTCAngles(image: Image) → Image[source]¶

Adds the Tasseled Cap brightness-greenness angle as in Powell et al. (2009).

A simplified version of addTCAngles that only computes the tcAngleBG band. See: https://doi.org/10.1016/j.rse.2009.08.016

Parameters:

image (ee.Image) – Input image with ‘brightness’, ‘greenness’, and ‘wetness’ bands (e.g., output of simpleGetTasseledCap).

Returns:

The input image with an added ‘tcAngleBG’ band (angle: normalized by pi).

Return type:

ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> img = simpleGetTasseledCap(ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20200601'))
>>> img = simpleAddTCAngles(img)
>>> print(img.select('tcAngleBG').bandNames().getInfo())

geeViz.getImagesLib.addZenithAzimuth(img: Image, toaOrSR: str, zenithDict: dict = {'SR': 'SOLAR_ZENITH_ANGLE', 'TOA': 'SUN_ELEVATION'}, azimuthDict: dict = {'SR': 'SOLAR_AZIMUTH_ANGLE', 'TOA': 'SUN_AZIMUTH'})[source]¶

Adds solar zenith and azimuth angles in radians as bands to an image.

Reads sun angle metadata properties from the image, converts degrees to radians, and adds them as constant-value ‘zenith’ and ‘azimuth’ bands. For TOA images, zenith is derived from SUN_ELEVATION (90 - elevation); for SR images it is read directly from SOLAR_ZENITH_ANGLE.

Parameters:

img (ee.Image) – Input Landsat image with sun angle metadata properties.
toaOrSR (str) – Either 'TOA' or 'SR', indicating the processing level and which metadata properties to use.
zenithDict (dict, optional) – Mapping from toaOrSR key to the zenith metadata property name. Defaults to {'TOA': 'SUN_ELEVATION', 'SR': 'SOLAR_ZENITH_ANGLE'}.
azimuthDict (dict, optional) – Mapping from toaOrSR key to the azimuth metadata property name. Defaults to {'TOA': 'SUN_AZIMUTH', 'SR': 'SOLAR_AZIMUTH_ANGLE'}.

Returns:

The input image with added ‘zenith’ and ‘azimuth’ bands: in radians.

Return type:

ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> img = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20200601')
>>> img = addZenithAzimuth(img, 'TOA')
>>> print(img.select(['zenith', 'azimuth']).bandNames().getInfo())

geeViz.getImagesLib.medoidMosaicMSD(inCollection: ImageCollection, medoidIncludeBands: List | None = None) → Image[source]¶

Creates a medoid mosaic using the Mean Squared Difference (MSD) method.

Calculates the medoid image from an image collection by minimizing the sum of squared differences (Euclidean distance) between each pixel and the collection median.

Parameters:

inCollection (ee.ImageCollection) – The input collection to create the mosaic from. Must have consistent band names and data types.
medoidIncludeBands (ee.List | None, optional) – Band names to include in the MSD calculation. If None, all bands are used. Defaults to None.

Returns:

The medoid mosaic image, containing all original bands plus: ’year’ and ‘julianDay’ bands.

Return type:

ee.Image

Note

Data are not normalized, so bands should have roughly comparable value ranges. If temperature is included alongside reflectance, it may dominate the variance and bias the medoid selection.

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CO"]
>>> s2s = gil.superSimpleGetS2(studyArea, "2024-01-01", "2024-12-31", 190, 250)
>>> medoid = gil.medoidMosaicMSD(s2s, ["green", "red", "nir", "swir1", "swir2"])

geeViz.getImagesLib.exportToAssetWrapper(imageForExport: Image, assetName: str, assetPath: str, pyramidingPolicyObject: dict | None = None, roi: Geometry | None = None, scale: float | None = None, crs: str | None = None, transform: list | None = None, overwrite: bool = False, start: bool = True)[source]¶

Exports an image to an Earth Engine asset with overwrite handling.

Wraps ee.batch.Export.image.toAsset with logic to check for existing assets or running exports, and optionally overwrite them.

Parameters:

imageForExport (ee.Image) – The image to export.
assetName (str) – Task description / asset name (spaces replaced with ‘-‘).
assetPath (str) – Full Earth Engine asset path (e.g., 'projects/my-project/assets/my_image').
pyramidingPolicyObject (dict | None, optional) – Pyramiding policy, e.g., {'.default': 'mean'}. If a string is provided it is wrapped as {'.default': value}. Defaults to None (uses 'mean').
roi (ee.Geometry | None, optional) – Region of interest. The image is clipped to this geometry before export. Defaults to None.
scale (float | None, optional) – Export resolution in meters. Defaults to None (uses the image’s native scale).
crs (str | None, optional) – Coordinate reference system, e.g., 'EPSG:4326'. Defaults to None.
transform (list | None, optional) – Affine transform as a 6-element list. Defaults to None.
overwrite (bool, optional) – If True, deletes existing asset or cancels a running export before re-exporting. Defaults to False.
start (bool, optional) – If True, starts the export task immediately. If False, creates the task but does not start it and returns the task object. Defaults to True.

Returns:

The export task object if start=False,: otherwise None (task is started as a side effect).

Return type:

ee.batch.Task | None

Examples

>>> import ee
>>> ee.Initialize()
>>> img = ee.Image('USGS/SRTMGL1_003')
>>> roi = ee.Geometry.Rectangle([-105.5, 39.5, -105.0, 40.0])
>>> exportToAssetWrapper(img, 'srtm_export', 'projects/my-project/assets/srtm', roi=roi, scale=30)

geeViz.getImagesLib.exportToDriveWrapper(imageForExport: Image, outputName: str, driveFolderName: str, roi: Geometry, scale: float | None = None, crs: str | None = None, transform: list | None = None, outputNoData: int = -32768, start: bool = True)[source]¶

Exports an image to Google Drive as a GeoTIFF.

Wraps ee.batch.Export.image.toDrive, clipping the image to the provided region of interest and filling masked pixels with outputNoData.

Parameters:

imageForExport (ee.Image) – The image to export.
outputName (str) – File name for the exported GeoTIFF (spaces replaced with ‘-‘).
driveFolderName (str) – Google Drive folder name to export into.
roi (ee.Geometry) – Region of interest; the image is clipped to this geometry.
scale (float | None, optional) – Export resolution in meters. Defaults to None (uses the image’s native scale).
crs (str | None, optional) – Coordinate reference system, e.g., 'EPSG:4326'. Defaults to None.
transform (list | None, optional) – Affine transform as a 6-element list. Defaults to None.
outputNoData (int, optional) – Value used to fill masked pixels. Defaults to -32768.
start (bool, optional) – If True, starts the export task immediately. If False, creates the task but does not start it and returns the task object. Defaults to True.

Returns:

The export task object if start=False,: otherwise None (task is started as a side effect).

Return type:

ee.batch.Task | None

Examples

>>> import ee
>>> ee.Initialize()
>>> img = ee.Image('USGS/SRTMGL1_003')
>>> roi = ee.Geometry.Rectangle([-105.5, 39.5, -105.0, 40.0])
>>> exportToDriveWrapper(img, 'srtm_export', 'EE_Exports', roi, scale=30)

geeViz.getImagesLib.exportToCloudStorageWrapper(imageForExport: Image, outputName: str, bucketName: str, roi: Geometry, scale: float | None = None, crs: str | None = None, transform: list | None = None, outputNoData: int = -32768, fileFormat: str = 'GeoTIFF', formatOptions: dict = {'cloudOptimized': True}, overwrite: bool = False, start: bool = True)[source]¶

Exports an image to Google Cloud Storage with overwrite handling.

Wraps ee.batch.Export.image.toCloudStorage, clipping the image to the region of interest and optionally deleting existing blobs before export.

Parameters:

imageForExport (ee.Image) – The image to export.
outputName (str) – Object name / prefix in the bucket (spaces replaced with ‘-‘).
bucketName (str) – Name of the Google Cloud Storage bucket.
roi (ee.Geometry) – Region of interest; the image is clipped to this geometry.
scale (float | None, optional) – Export resolution in meters. Defaults to None.
crs (str | None, optional) – Coordinate reference system, e.g., 'EPSG:4326'. Defaults to None.
transform (list | None, optional) – Affine transform as a 6-element list. Defaults to None.
outputNoData (int, optional) – Value used to fill masked pixels. Defaults to -32768.
fileFormat (str, optional) – Output format, e.g., 'GeoTIFF' or 'TFRecord'. Defaults to 'GeoTIFF'.
formatOptions (dict, optional) – Additional format options passed to the export. Defaults to {'cloudOptimized': True}.
overwrite (bool, optional) – If True, deletes existing blobs or cancels running exports before re-exporting. Defaults to False.
start (bool, optional) – If True, starts the export task immediately. If False, creates the task but does not start it and returns the task object. Defaults to True.

Returns:

The export task object if start=False,: otherwise None (task is started as a side effect).

Return type:

ee.batch.Task | None

Examples

>>> import ee
>>> ee.Initialize()
>>> img = ee.Image('USGS/SRTMGL1_003')
>>> roi = ee.Geometry.Rectangle([-105.5, 39.5, -105.0, 40.0])
>>> exportToCloudStorageWrapper(img, 'srtm_cog', 'my-bucket', roi, scale=30)

geeViz.getImagesLib.wrapDates(startJulian: int, endJulian: int) → list[source]¶

Computes date-wrapping parameters when startJulian > endJulian.

When the compositing window crosses a year boundary (e.g., Oct-Mar), this function returns the offset and which year contains the majority of days, so that year labels are assigned correctly.

Parameters:

startJulian (int) – Start day of year (1-365).
endJulian (int) – End day of year (1-365).

Returns:

A two-element list [wrapOffset, yearWithMajority].: wrapOffset is 365 if wrapping occurs, else 0. yearWithMajority is 1 if the second calendar year has more days in the window, else 0.

Return type:

list

Examples

>>> wrapDates(250, 100)
[365, 1]
>>> wrapDates(1, 250)
[0, 0]

geeViz.getImagesLib.compositeTimeSeries(ls: ImageCollection, startYear: int, endYear: int, startJulian: int, endJulian: int, timebuffer: int = 0, weights: list = [1], compositingMethod: str | None = None, compositingReducer: Reducer | None = None) → ImageCollection[source]¶

Creates annual composites from an image collection over a year range.

Generates one composite per year between startYear and endYear, filtering by Julian day window. Supports multi-year time buffering with weighted averaging and various compositing methods.

Parameters:

ls (ee.ImageCollection) – Input image collection to composite.
startYear (int) – First year to produce a composite for.
endYear (int) – Last year to produce a composite for (inclusive).
startJulian (int) – Start day of year for the compositing window (1-365).
endJulian (int) – End day of year for the compositing window (1-365). Can be less than startJulian for cross-year windows.
timebuffer (int, optional) – Number of years on each side to include in a weighted moving window. Defaults to 0.
weights (list, optional) – Weights for the moving window years. Length should be 2 * timebuffer + 1. Defaults to [1].
compositingMethod (str | None, optional) – Method name, e.g., 'median' or 'medoid'. Defaults to None.
compositingReducer (ee.Reducer | None, optional) – Custom reducer to use instead of a named method. Defaults to None.

Returns:

Collection of annual composite images, each tagged: with compositing metadata properties.

Return type:

ee.ImageCollection

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> area = ee.Geometry.Point([-105.5, 40.0]).buffer(5000)
>>> composites = compositeTimeSeries(
...     gil.getProcessedLandsatScenes(area, 2020, 2022, 152, 273),
...     2020, 2022, 152, 273)

geeViz.getImagesLib.illuminationCorrection(img, scale, studyArea, bandList=['blue', 'green', 'red', 'nir', 'swir1', 'swir2', 'temp'])[source]¶

Applies SCSc topographic correction to specified bands of an image.

Uses the Sun-Canopy-Sensor + C (SCSc) method to correct for illumination effects caused by terrain slope and aspect. Requires ‘IC’, ‘cosZ’, ‘cosS’, and ‘slope’ bands (from the first illuminationCorrection overload). Based on code by Patrick Burns and Matt Macander.

Parameters:

img (ee.Image) – Input image with ‘IC’, ‘cosZ’, ‘cosS’, ‘slope’, and the bands listed in bandList.
scale (float) – Scale in meters for the linear regression reduction.
studyArea (ee.Geometry) – Region used for the linear fit regression.
bandList (list, optional) – Band names to apply the SCSc correction to. Defaults to ['blue', 'green', 'red', 'nir', 'swir1', 'swir2', 'temp'].

Returns:

The topographically corrected image with original metadata: properties and system:time_start preserved.

Return type:

ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> area = ee.Geometry.Point([-122, 37]).buffer(5000)
>>> img = addZenithAzimuth(ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20200601'), 'TOA')
>>> img_ic = illuminationCorrection(img, 30, area)
>>> corrected = illuminationCorrection(img_ic, 30, area)

geeViz.getImagesLib.maskEmptyPixels(image: Image) → Image[source]¶

Masks pixels that have zero observations in a MODIS-style image.

Checks the ‘num_observations_1km’ band and masks out any pixel where the observation count is zero.

Parameters:: image (ee.Image) – Input image with a ‘num_observations_1km’ band (e.g., a MODIS daily product).
Returns:: The input image with zero-observation pixels masked out.
Return type:: ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> modis = ee.Image('MODIS/006/MOD09GA/2020_06_01')
>>> masked = maskEmptyPixels(modis)

geeViz.getImagesLib.getQABits(image: Image, start: int, end: int, name: str) → Image[source]¶

Extracts a range of bits from a QA band image.

Creates a bitmask for bits start through end, applies it with bitwiseAnd, and right-shifts to get the extracted value.

Parameters:

image (ee.Image) – Single-band QA image (e.g., a MODIS state_1km band).
start (int) – Starting bit position (0-based, inclusive).
end (int) – Ending bit position (inclusive).
name (str) – Name for the output band.

Returns:

Single-band image with the extracted QA bit values, renamed: to name.

Return type:

ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> qa = ee.Image('MODIS/006/MOD09GA/2020_06_01').select('state_1km')
>>> cloud_bits = getQABits(qa, 0, 1, 'cloud_state')

geeViz.getImagesLib.maskCloudsWQA(image)[source]¶

Masks cloudy pixels using the MODIS state_1km QA band.

Extracts bit 10 (internal cloud algorithm flag) from the ‘state_1km’ band and masks pixels flagged as cloud.

Parameters:: image (ee.Image) – A MODIS image with a ‘state_1km’ QA band (e.g., from MOD09GA).
Returns:: The input image with cloudy pixels masked out.
Return type:: ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> modis = ee.Image('MODIS/006/MOD09GA/2020_06_01')
>>> clear = maskCloudsWQA(modis)

geeViz.getImagesLib.modisCloudScore(img)[source]¶

Computes a cloud score (0-100) for a MODIS image.

Combines brightness in visible and infrared bands with a snow index (NDSI) and an optional thermal mask to produce a per-pixel cloud likelihood score. Expects common band names (‘red’, ‘green’, ‘blue’, ‘nir’, ‘swir1’, ‘swir2’, ‘temp’).

Parameters:

img (ee.Image) – Input MODIS image with standard band names.

Returns:

Single-band image named ‘cloudScore’ with values 0-100,: where higher values indicate greater cloud likelihood.

Return type:

ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> modis = ee.Image('MODIS/006/MOD09GA/2020_06_01')
>>> cloud = modisCloudScore(modis)
>>> print(cloud.bandNames().getInfo())

geeViz.getImagesLib.sentinel2CloudScore(img)[source]¶

Computes a cloud score (0-100) for a Sentinel-2 image.

Adapts the Landsat cloudScore algorithm for Sentinel-2 by combining brightness in blue/cirrus, visible, and infrared bands with an NDSI snow filter. Currently in beta and may need tuning per study area.

Parameters:

img (ee.Image) – Input Sentinel-2 image with bands named ‘blue’, ‘cb’, ‘green’, ‘red’, ‘nir’, ‘swir1’, and ‘swir2’.

Returns:

Single-band image named ‘cloudScore’ with values 0-100,: where higher values indicate greater cloud likelihood.

Return type:

ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> s2 = ee.Image('COPERNICUS/S2_SR/20200601T184919_20200601T185630_T10SEG')
>>> cloud = sentinel2CloudScore(s2)
>>> print(cloud.bandNames().getInfo())

geeViz.getImagesLib.sentinel2SnowMask(img, dilatePixels=3.5)[source]¶

Masks snow-covered pixels in a Sentinel-2 image using NDSI thresholds.

Identifies snow in open land (NDSI > 0.4 and NIR > 0.11) and snow in forest (0.1 < NDSI < 0.4), then masks those pixels. Adapted from ESA training materials (Salomonson and Appel, 2004/2006).

Parameters:

img (ee.Image) – Input Sentinel-2 image with ‘green’, ‘swir1’, and ‘nir’ bands.
dilatePixels (float, optional) – Number of pixels to erode the snow mask with focal_min to remove edge effects. Defaults to 3.5.

Returns:

The input image with snow pixels masked out.

Return type:

ee.Image

Examples

>>> import ee
>>> ee.Initialize()
>>> s2 = ee.Image('COPERNICUS/S2_SR/20200101T184919_20200101T185630_T10SEG')
>>> snow_free = sentinel2SnowMask(s2, dilatePixels=3.5)

geeViz.getImagesLib.joinCollections(c1, c2, maskAnyNullValues=True, joinProperty='system:time_start', joinPropertySecondary=None)[source]¶

Joins two image collections by a shared property using an inner join.

Merges bands from matching images in two collections. Images are matched based on an exact match of the specified join property. Optionally masks pixels where any band has a null (zero) value after joining.

Parameters:

c1 (ee.ImageCollection) – The primary image collection.
c2 (ee.ImageCollection) – The secondary image collection to join.
maskAnyNullValues (bool, optional) – If True, masks pixels where any band value is zero after joining. Defaults to True.
joinProperty (str, optional) – The property name to match on in the primary collection. Defaults to “system:time_start”.
joinPropertySecondary (str | None, optional) – The property name to match on in the secondary collection. If None, uses the same value as joinProperty. Defaults to None.

Returns:

A new collection with bands from both input: collections merged together for each matching image pair.

Return type:

ee.ImageCollection

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> c1 = ee.ImageCollection("MODIS/061/MOD09GQ").filterDate("2024-01-01", "2024-01-10")
>>> c2 = ee.ImageCollection("MODIS/061/MOD09GA").filterDate("2024-01-01", "2024-01-10")
>>> joined = gil.joinCollections(c1, c2)
>>> print(joined.first().bandNames().getInfo())

geeViz.getImagesLib.smartJoin(primary, secondary, hourDiff)[source]¶

Joins two image collections by closest timestamp within a time window.

For each image in the primary collection, finds the best-matching image in the secondary collection within the specified time difference and merges their bands together.

Parameters:

primary (ee.ImageCollection) – The primary image collection.
secondary (ee.ImageCollection) – The secondary image collection to match against.
hourDiff (int | float) – Maximum time difference in hours to consider a match between images.

Returns:

The primary collection with bands from the: best-matching secondary image appended to each image.

Return type:

ee.ImageCollection

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> terra = ee.ImageCollection("MODIS/061/MOD09GQ").filterDate("2024-06-01", "2024-06-30")
>>> aqua = ee.ImageCollection("MODIS/061/MYD09GQ").filterDate("2024-06-01", "2024-06-30")
>>> joined = gil.smartJoin(terra, aqua, 24)

geeViz.getImagesLib.spatioTemporalJoin(primary, secondary, hourDiff=24, outKey='secondary')[source]¶

Joins two image collections by spatial intersection and closest timestamp.

For each image in the primary collection, finds the best-matching image in the secondary collection that both intersects spatially and falls within the specified time window. Bands from the secondary image are renamed with a suffix and appended.

Parameters:

primary (ee.ImageCollection) – The primary image collection.
secondary (ee.ImageCollection) – The secondary image collection to match against.
hourDiff (int | float, optional) – Maximum time difference in hours to consider a match. Defaults to 24.
outKey (str, optional) – Suffix appended to secondary band names in the format “bandName_outKey”. Defaults to “secondary”.

Returns:

The primary collection with renamed bands from: the best-matching secondary image appended to each image.

Return type:

ee.ImageCollection

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> modis_terra = ee.ImageCollection("MODIS/061/MOD09GQ").filterDate("2024-01-01", "2024-01-31")
>>> modis_aqua = ee.ImageCollection("MODIS/061/MYD09GQ").filterDate("2024-01-01", "2024-01-31")
>>> joined = gil.spatioTemporalJoin(modis_terra, modis_aqua, hourDiff=12, outKey="aqua")

geeViz.getImagesLib.joinFeatureCollections(primary, secondary, fieldName, fieldNameSecondary=None)[source]¶

Joins two feature collections by matching property values using an inner join.

Matches features from two collections based on an exact match of the specified field. Retains the geometry of the primary feature and copies all properties from the matching secondary feature.

Parameters:

primary (ee.FeatureCollection) – The primary feature collection whose geometry is retained.
secondary (ee.FeatureCollection) – The secondary feature collection whose properties are copied to matching features.
fieldName (str) – The property name to match on in the primary collection.
fieldNameSecondary (str | None, optional) – The property name to match on in the secondary collection. If None, uses the same value as fieldName. Defaults to None.

Returns:

A collection of features with the geometry from: the primary and properties from both collections.

Return type:

ee.FeatureCollection

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> states = ee.FeatureCollection("TIGER/2018/States")
>>> lookup = ee.FeatureCollection([ee.Feature(None, {"STATEFP": "08", "region": "Mountain"})])
>>> joined = gil.joinFeatureCollections(states, lookup, "STATEFP")

geeViz.getImagesLib.despikeCollection(c, absoluteSpike, bandNo)[source]¶

Removes spike artifacts from a time series image collection.

Uses a moving window of three images (left, center, right) to detect and replace spikes. A pixel is considered a spike if it deviates from both its neighbors by more than the absolute threshold. Spikes are replaced with the mean of the left and right neighbors.

Parameters:

c (ee.ImageCollection) – The input image collection to despike. Should be temporally ordered.
absoluteSpike (float) – The absolute threshold for spike detection. A pixel is flagged as a spike if its difference from both neighbors exceeds this value.
bandNo (int) – The band index used to detect spikes.

Returns:

The despiked image collection with spike values: replaced by the mean of neighboring images.

Return type:

ee.ImageCollection

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> ndvi = ee.ImageCollection("MODIS/061/MOD13A1").filterDate("2024-01-01", "2024-12-31").select("NDVI")
>>> despiked = gil.despikeCollection(ndvi, 1000, 0)
>>> print(despiked.size().getInfo())

geeViz.getImagesLib.getModisData(startYear: int, endYear: int, startJulian: int, endJulian: int, daily: bool = False, maskWQA: bool = False, zenithThresh: int = 90, useTempInCloudMask: bool = True, addLookAngleBands: bool = False, resampleMethod: str = 'near')[source]¶

Retrieves MODIS imagery from Earth Engine for a specified period. Handles joining all MODIS collections for Terra and Aqua and aligning band names

Parameters:

startYear (int) – The starting year for the data collection.
endYear (int) – The ending year for the data collection.
startJulian (int) – The starting Julian day of year for the data collection (1-366).
endJulian (int) – The ending Julian day of year for the data collection (1-366).
daily (bool, optional) – Determines whether to retrieve daily or 8-day composite data. Defaults to False (8-day composite).
maskWQA (bool, optional) – Controls whether to mask pixels based on the Quality Assurance (QA) band. Only applicable for daily data (daily=True). Defaults to False.
zenithThresh (float, optional) – Sets the threshold for solar zenith angle in degrees. Pixels with zenith angle exceeding this threshold will be masked out. Defaults to 90.
useTempInCloudMask (bool, optional) – Determines whether to use the thermal band for cloud masking. Defaults to True.
addLookAngleBands (bool, optional) – Controls whether to include view angle bands in the output. Defaults to False.
resampleMethod (str, optional) – Specifies the resampling method to apply to the imagery. Valid options include “near”, “bilinear”, and “bicubic”. Defaults to “near” (nearest neighbor).

Returns:

A collection of MODIS imagery for the specified criteria.

Return type:

ee.ImageCollection

>>> import geeViz.getImagesLib as gil
>>> Map = gil.Map
>>> ee = gil.ee
>>> crs = gil.common_projections["NLCD_CONUS"]["crs"]
>>> transform = gil.common_projections["NLCD_CONUS"]["transform"]
>>> scale = 240
>>> transform[0] = scale
>>> transform[4] = -scale
>>> composite = gil.getModisData(2024, 2024, 190, 250, resampleMethod="bicubic").median().reproject(crs, transform)
>>> Map.addLayer(composite, gil.vizParamsFalse, "MODIS Composite")
>>> Map.setCenter(-111, 41, 7)
>>> Map.turnOnInspector()
>>> Map.view()

geeViz.getImagesLib.getProcessedModis(startYear: int, endYear: int, startJulian: int, endJulian: int, zenithThresh: float = 90, addLookAngleBands: bool = True, applyCloudScore: bool = True, applyTDOM: bool = True, useTempInCloudMask: bool = True, cloudScoreThresh: int = 20, performCloudScoreOffset: bool = True, cloudScorePctl: int = 10, zScoreThresh: float = -1, shadowSumThresh: float = 0.35, contractPixels: int = 0, dilatePixels: float = 2.5, shadowSumBands: list[str] = ['nir', 'swir2'], resampleMethod: str = 'bicubic', preComputedCloudScoreOffset: Image | None = None, preComputedTDOMIRMean: Image | None = None, preComputedTDOMIRStdDev: Image | None = None, addToMap: bool = False, crs: str = 'EPSG:4326', scale: int | None = 250, transform: list[int] | None = None)[source]¶

Retrieves, processes, and filters MODIS imagery for a specified period.

This function retrieves daily MODIS imagery from Earth Engine, applies various cloud and cloud shadow masking techniques, and returns a collection of processed images.

Parameters:

startYear (int) – The starting year for the data collection.
endYear (int) – The ending year for the data collection.
startJulian (int) – The starting Julian day of year for the data collection (1-366).
endJulian (int) – The ending Julian day of year for the data collection (1-366).
zenithThresh (float, optional) – Sets the threshold for solar zenith angle in degrees. Pixels with zenith angle exceeding this threshold will be masked out. Defaults to 90.
addLookAngleBands (bool, optional) – Controls whether to include view angle bands in the output. Defaults to True.
applyCloudScore (bool, optional) – Determines whether to apply cloud masking based on the CloudScore simple algorithm adapted to MODIS. Defaults to True.
applyTDOM (bool, optional) – Determines whether to apply the TDOM (Temporal Dark Outlier Mask)
True. (technique for cloud shadow masking. Defaults to)
useTempInCloudMask (bool, optional) – Determines whether to use the thermal band for cloud masking during MODIS data retrieval. Defaults to True.
cloudScoreThresh (int, optional) – Threshold for the CloudScore simple algorithm to classify a pixel as cloudy. Lower number masks out more. Defaults to 20.
performCloudScoreOffset (bool, optional) – Controls whether to perform an offset correction on the Cloud Score data over bright surfaces. Only use this if bright areas are being masked as clouds. Do not use this in persistently cloud areas. Defaults to True.
cloudScorePctl (int, optional) – Percentile of the Cloud Score product to use for the offset correction. Defaults to 10.
zScoreThresh (float, optional) – Threshold for the z-score used in TDOM cloud shadow masking. Pixels with z-scores below this threshold are masked. Defaults to -1.
shadowSumThresh (float, optional) – Threshold for the sum of reflectance in shadow bands used in TDOM cloud shadow masking. Pixels below this threshold and the zScoreThresh are masked as dark outliers (likely cloud shadows). Defaults to 0.35.
contractPixels (int, optional) – Number of pixels to contract cloud and shadow masks by. Defaults to 0.
dilatePixels (float, optional) – Number of pixels to dilate cloud and shadow masks by. Defaults to 2.5.
shadowSumBands (list[str], optional) – List of band names to use for calculating the sum of reflectance in TDOM cloud shadow masking. Defaults to [“nir”, “swir2”].
resampleMethod (str, optional) – Specifies the resampling method to apply to the imagery. Valid options include “near”, “bilinear”, and “bicubic”. Defaults to “bicubic”.
preComputedCloudScoreOffset (float | None, optional) – Pre-computed Cloud Score offset value to avoid redundant calculations. Defaults to None (automatic calculation).
preComputedTDOMIRMean (float | None, optional) – Pre-computed mean of the IR band used in TDOM cloud shadow masking to avoid redundant calculations. Defaults to None (automatic calculation).
preComputedTDOMIRStdDev (float | None, optional) – Pre-computed standard deviation of the IR band used in TDOM cloud shadow masking to avoid redundant calculations. Defaults to None (automatic calculation).
addToMap (bool, optional) – Controls whether to add intermediate processing steps (masked medians) to the Earth Engine map for visualization purposes. Defaults to False.
crs (str, optional) – Only used if addToMap is True. Coordinate Reference System (CRS) for the output imagery. Defaults to “EPSG:4326”.
scale (int | None, optional) – Only used if addToMap is True. Scale (resolution) of the output imagery in meters. Defaults to 250.
transform (list | None, optional) – Only used if addToMap is True. Optional transformation matrix to apply to the output imagery. Defaults to None.

Returns:

Cloud and shadow masked MODIS imagery with: spectral indices added. The collection has processing parameters stored as properties.

Return type:

ee.ImageCollection

Examples

>>> import geeViz.getImagesLib as gil

>>> Map = gil.Map
>>> ee = gil.ee
>>> crs = gil.common_projections["NLCD_CONUS"]["crs"]
>>> transform = gil.common_projections["NLCD_CONUS"]["transform"]
>>> scale = 240
>>> transform[0] = scale
>>> transform[4] = -scale
>>> composite = gil.getProcessedModis(2024, 2024, 190, 250).median().reproject(crs, transform)
>>> Map.addLayer(composite, gil.vizParamsFalse, "MODIS Composite")
>>> Map.setCenter(-111, 41, 7)
>>> Map.turnOnInspector()
>>> Map.view()

geeViz.getImagesLib.nDayComposites(images, startYear, endYear, startJulian, endJulian, compositePeriod)[source]¶

Creates median composites at regular n-day intervals from an image collection.

Divides the specified date range into equal periods of n days and computes the median composite for each period and year.

Parameters:

images (ee.ImageCollection) – The input image collection to composite.
startYear (int) – The first year to create composites for.
endYear (int) – The last year to create composites for.
startJulian (int) – The starting Julian day of year (1-366).
endJulian (int) – The ending Julian day of year (1-366).
compositePeriod (int) – The number of days per composite period.

Returns:

A collection of median composites, each with: ”system:time_start” and “system:index” (formatted as “yyyy-MM-dd”) properties set.

Return type:

ee.ImageCollection

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> modis = ee.ImageCollection("MODIS/061/MOD09GQ").select(["sur_refl_b01", "sur_refl_b02"])
>>> composites = gil.nDayComposites(modis, 2024, 2024, 1, 365, 16)
>>> print(composites.size().getInfo())

geeViz.getImagesLib.exportCollection(exportPathRoot, outputName, studyArea, crs, transform, scale, collection, startYear, endYear, startJulian, endJulian, compositingReducer, timebuffer, exportBands, overwrite=False, exportToAssets=False, exportToCloud=False, bucket=None, start: bool = True)[source]¶

Exports yearly composites from an image collection to EE assets or Cloud Storage.

Iterates through each year (adjusted by timebuffer), extracts the first image for that year, clips it to the study area, and exports it.

Parameters:

exportPathRoot (str) – Root path for exports.
outputName (str) – Base name for exported files.
studyArea (ee.Geometry | ee.FeatureCollection) – Region to clip to.
crs (str) – Coordinate reference system (e.g., “EPSG:5070”).
transform (list[float] | None) – Affine transform for the output.
scale (int | None) – Output resolution in meters.
collection (ee.ImageCollection) – Image collection to export from.
startYear (int) – First year of the collection.
endYear (int) – Last year of the collection.
startJulian (int) – Starting Julian day used in naming.
endJulian (int) – Ending Julian day used in naming.
compositingReducer (str) – Compositing method label for metadata.
timebuffer (int) – Years to buffer. Exports from startYear + timebuffer to endYear - timebuffer.
exportBands (list[str]) – Band names to select for export.
overwrite (bool, optional) – Overwrite existing assets. Defaults to False.
exportToAssets (bool, optional) – Export to EE assets. Defaults to False.
exportToCloud (bool, optional) – Export to Cloud Storage. Defaults to False.
bucket (str | None, optional) – Cloud Storage bucket name. Defaults to None.
start (bool, optional) – If True, starts export tasks immediately. If False, creates the tasks but does not start them and returns a list of task objects. Defaults to True.

Returns:

A list of task objects if start=False,: otherwise None (tasks are started as a side effect).

Return type:

list[ee.batch.Task] | None

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> studyArea = ee.Geometry.Rectangle([-110, 40, -109, 41])
>>> collection = ee.ImageCollection("LANDSAT/LC08/C02/T1_L2").filterDate("2023-06-01", "2023-09-01")
>>> gil.exportCollection("projects/my-project/assets/out", "L8", studyArea, "EPSG:5070", None, 30, collection, 2023, 2023, 152, 244, "median", 0, ["SR_B4", "SR_B5"], exportToAssets=True)

geeViz.getImagesLib.exportCompositeCollection(collection, exportPathRoot, outputName, origin, studyArea, crs, transform, scale, startYear, endYear, startJulian, endJulian, compositingMethod, timebuffer, toaOrSR, nonDivideBands, exportBands, additionalPropertyDict=None, overwrite=False, start: bool = True)[source]¶

Exports yearly composites to Earth Engine assets with scaled integer values.

Iterates through each year (adjusted by timebuffer), scales reflectance bands by 10000, converts to int16, attaches metadata, and exports each yearly composite to an Earth Engine asset. Non-divide bands (e.g., indices or categorical bands) are kept unscaled.

Parameters:

collection (ee.ImageCollection) – The composite image collection.
exportPathRoot (str) – The root asset path for exports.
outputName (str) – Base name for the exported assets.
origin (str) – The data origin label (e.g., “Landsat”, “MODIS”).
studyArea (ee.Geometry | ee.FeatureCollection) – The export region.
crs (str) – The coordinate reference system (e.g., “EPSG:5070”).
transform (list[float] | None) – The affine transform for the output.
scale (int | None) – The output resolution in meters.
startYear (int) – The first year of the collection.
endYear (int) – The last year of the collection.
startJulian (int) – The starting Julian day used in naming.
endJulian (int) – The ending Julian day used in naming.
compositingMethod (str) – The compositing method (e.g., “medoid”, “median”) used in naming and metadata.
timebuffer (int) – Number of years before/after to buffer the year range.
toaOrSR (str) – Reflectance type label (“TOA” or “SR”) used in naming.
nonDivideBands (list[str] | None) – Band names that should not be multiplied by 10000. If None, all bands are scaled.
exportBands (list[str]) – Band names to select for export.
additionalPropertyDict (dict | None, optional) – Extra properties to attach to each exported image. Defaults to None.
overwrite (bool, optional) – If True, overwrites existing assets. Defaults to False.
start (bool, optional) – If True, starts export tasks immediately. If False, creates the tasks but does not start them and returns a list of task objects. Defaults to True.

Returns:

A list of task objects if start=False,: otherwise None (tasks are started as a side effect).

Return type:

list[ee.batch.Task] | None

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> studyArea = ee.Geometry.Rectangle([-110, 40, -109, 41])
>>> result = gil.getLandsatWrapper(studyArea, 2023, 2023, 152, 273)
>>> composites = result["processedComposites"]
>>> gil.exportCompositeCollection(composites, "projects/my-project/assets/composites", "L8_Composite", "Landsat", studyArea, "EPSG:5070", None, 30, 2023, 2023, 152, 273, "medoid", 0, "SR", ["NDVI", "NBR"], ["blue", "green", "red", "nir", "swir1", "swir2", "NDVI"])

geeViz.getImagesLib.getLandsatWrapper(studyArea, startYear, endYear, startJulian, endJulian, timebuffer=0, weights=[1], compositingMethod='medoid', toaOrSR='SR', includeSLCOffL7=False, defringeL5=False, applyCloudScore=False, applyFmaskCloudMask=True, applyTDOM=False, applyFmaskCloudShadowMask=True, applyFmaskSnowMask=False, cloudScoreThresh=10, performCloudScoreOffset=True, cloudScorePctl=10, zScoreThresh=-1, shadowSumThresh=0.35, contractPixels=1.5, dilatePixels=3.5, correctIllumination=False, correctScale=250, exportComposites=False, outputName='Landsat-Composite', exportPathRoot='users/username/test', crs='EPSG:5070', transform=[30, 0, -2361915.0, 0, -30, 3177735.0], scale=None, resampleMethod='near', preComputedCloudScoreOffset=None, preComputedTDOMIRMean=None, preComputedTDOMIRStdDev=None, compositingReducer=None, harmonizeOLI=False, landsatCollectionVersion='C2', overwrite=False, verbose=False)[source]¶

Retrieve cloud-masked Landsat annual composites for a study area and date range.

This is the main high-level wrapper for Landsat imagery. It retrieves and cloud-masks Landsat scenes via getProcessedLandsatScenes, composites them into annual images, and optionally exports the composites to an Earth Engine asset.

Parameters:

studyArea (ee.Geometry | ee.Feature | ee.FeatureCollection) – The geographic area of interest.
startYear (int) – The starting year for the data collection.
endYear (int) – The ending year for the data collection.
startJulian (int) – The starting Julian day of year (1-365). If startJulian > endJulian, dates wrap across the new year.
endJulian (int) – The ending Julian day of year (1-365).
timebuffer (int, optional) – Number of years to buffer composites on each side. Defaults to 0.
weights (list[int], optional) – Weights for years in the composite (length must equal 2 * timebuffer + 1). Defaults to [1].
compositingMethod (str, optional) – Compositing method, e.g. "medoid" or "median". Defaults to "medoid".
toaOrSR (str, optional) – "TOA" for Top of Atmosphere or "SR" for Surface Reflectance. Defaults to "SR".
includeSLCOffL7 (bool, optional) – Whether to include Landsat 7 SLC-off scenes. Defaults to False.
defringeL5 (bool, optional) – Whether to defringe Landsat 5 scenes. Defaults to False.
applyCloudScore (bool, optional) – Whether to apply the CloudScore simple cloud mask. Defaults to False.
applyFmaskCloudMask (bool, optional) – Whether to apply the Fmask cloud mask. Defaults to True.
applyTDOM (bool, optional) – Whether to apply TDOM cloud shadow masking. Defaults to False.
applyFmaskCloudShadowMask (bool, optional) – Whether to apply Fmask cloud shadow mask. Defaults to True.
applyFmaskSnowMask (bool, optional) – Whether to apply Fmask snow mask. Defaults to False.
cloudScoreThresh (int, optional) – Cloud score threshold; lower masks more. Defaults to 10.
performCloudScoreOffset (bool, optional) – Whether to offset cloud score over bright surfaces. Defaults to True.
cloudScorePctl (int, optional) – Percentile for cloud score offset correction. Defaults to 10.
zScoreThresh (float, optional) – Z-score threshold for TDOM shadow masking. Defaults to -1.
shadowSumThresh (float, optional) – Sum-of-reflectance threshold for TDOM. Defaults to 0.35.
contractPixels (float, optional) – Pixels to contract cloud/shadow masks. Defaults to 1.5.
dilatePixels (float, optional) – Pixels to dilate cloud/shadow masks. Defaults to 3.5.
correctIllumination (bool, optional) – Whether to apply terrain illumination correction. Defaults to False.
correctScale (int, optional) – Scale in meters for illumination correction. Defaults to 250.
exportComposites (bool, optional) – Whether to export composites to an Earth Engine asset. Defaults to False.
outputName (str, optional) – Base name for exported assets. Defaults to "Landsat-Composite".
exportPathRoot (str, optional) – Asset folder path for exports. Defaults to "users/username/test".
crs (str, optional) – Coordinate reference system for exports. Defaults to "EPSG:5070".
transform (list[float] | None, optional) – Affine transform for exports. Defaults to [30, 0, -2361915.0, 0, -30, 3177735.0].
scale (float | None, optional) – Scale in meters for exports. Overrides transform if provided. Defaults to None.
resampleMethod (str, optional) – Resampling method ("near", "bilinear", "bicubic"). Defaults to "near".
preComputedCloudScoreOffset (ee.Image | None, optional) – Pre-computed cloud score offset image. Defaults to None.
preComputedTDOMIRMean (ee.Image | None, optional) – Pre-computed TDOM IR mean image. Defaults to None.
preComputedTDOMIRStdDev (ee.Image | None, optional) – Pre-computed TDOM IR standard deviation image. Defaults to None.
compositingReducer (ee.Reducer | None, optional) – Custom reducer for compositing. Overrides compositingMethod if provided. Defaults to None.
harmonizeOLI (bool, optional) – Whether to harmonize OLI to TM/ETM+ spectral response. Defaults to False.
landsatCollectionVersion (str, optional) – Landsat collection version ("C1" or "C2"). Defaults to "C2".
overwrite (bool, optional) – Whether to overwrite existing exported assets. Defaults to False.
verbose (bool, optional) – Whether to print processing details. Defaults to False.

Returns:

A dictionary containing all input arguments plus two additional keys:

'processedScenes' (ee.ImageCollection): The cloud-masked individual Landsat scenes.

'processedComposites' (ee.ImageCollection): The annual composite time series.

Return type:

dict

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CO"]
>>> result = gil.getLandsatWrapper(studyArea, 2020, 2023, 190, 250)
>>> composites = result['processedComposites']
>>> Map = gil.Map
>>> Map.addLayer(composites, gil.vizParamsFalse, "Landsat Composites", True)
>>> Map.centerObject(studyArea)
>>> Map.turnOnInspector()
>>> Map.view()

geeViz.getImagesLib.getProcessedLandsatScenes(studyArea: Geometry | Feature | FeatureCollection, startYear: int, endYear: int, startJulian: int, endJulian: int, toaOrSR: str = 'SR', includeSLCOffL7: bool = False, defringeL5: bool = False, applyCloudScore: bool = False, applyFmaskCloudMask: bool = True, applyTDOM: bool = False, applyFmaskCloudShadowMask: bool = True, applyFmaskSnowMask: bool = False, cloudScoreThresh: int = 10, performCloudScoreOffset: bool = True, cloudScorePctl: int = 10, zScoreThresh: float = -1, shadowSumThresh: float = 0.35, contractPixels: float = 1.5, dilatePixels: float = 3.5, shadowSumBands: list[str] = ['nir', 'swir1'], resampleMethod: str = 'near', harmonizeOLI: bool = False, preComputedCloudScoreOffset: Image | None = None, preComputedTDOMIRMean: Image | None = None, preComputedTDOMIRStdDev: Image | None = None, landsatCollectionVersion: str = 'C2', verbose: bool = False) → ImageCollection[source]¶

Retrieves, processes, and filters Landsat scenes for a specified area and time period.

This function retrieves Landsat scenes from Earth Engine, applies various cloud, cloud shadow, and snow masking techniques, calculates common indices, and returns a collection of processed images.

Parameters:

studyArea (ee.Geometry) – The geographic area of interest (study area) as an Earth Engine geometry, Feature, or FeatureCollection object.
startYear (int) – The starting year for the data collection.
endYear (int) – The ending year for the data collection.
startJulian (int) – The starting Julian day of year for the data collection (1-365).
endJulian (int) – The ending Julian day of year for the data collection (1-365).
toaOrSR (str, optional) – Flag indicating desired reflectance type: “TOA” (Top Of Atmosphere) or “SR” (Surface Reflectance). Defaults to “SR”.
includeSLCOffL7 (bool, optional) – Determines whether to include Landsat 7 SLC-off scenes. Defaults to False.
defringeL5 (bool, optional) – Determines whether to defringe Landsat 5 scenes. Defaults to False.
applyCloudScore (bool, optional) – Determines whether to apply cloud masking based on the CloudScore simple algorithm. Defaults to False.
applyFmaskCloudMask (bool, optional) – Determines whether to apply the Fmask cloud mask. Defaults to True.
applyTDOM (bool, optional) – Determines whether to apply the TDOM (Temporal Dark Outlier Mask) technique for cloud shadow masking. Defaults to False.
applyFmaskCloudShadowMask (bool, optional) – Determines whether to apply the Fmask cloud shadow mask. Defaults to True.
applyFmaskSnowMask (bool, optional) – Determines whether to apply the Fmask snow mask. Defaults to False.
cloudScoreThresh (int, optional) – Threshold for the CloudScore simple algorithm to classify a pixel as cloudy. Lower number masks out more. Defaults to 10.
performCloudScoreOffset (bool, optional) – Controls whether to perform an offset correction on the Cloud Score data over bright surfaces. Only use this if bright areas are being masked as clouds. Do not use this in persistently cloud areas. Defaults to True.
cloudScorePctl (int, optional) – Percentile of the Cloud Score product to use for the offset correction. Defaults to 10.
zScoreThresh (float, optional) – Threshold for the z-score used in TDOM cloud shadow masking. Pixels with z-scores below this threshold are masked. Defaults to -1.
shadowSumThresh (float, optional) – Threshold for the sum of reflectance in shadow bands used in TDOM cloud shadow masking. Pixels below this threshold and the zScoreThresh are masked as dark outliers (likely cloud shadows). Defaults to 0.35.
contractPixels (float, optional) – Number of pixels to contract cloud and shadow masks by. Defaults to 1.5.
dilatePixels (float, optional) – Number of pixels to dilate cloud and shadow masks by. Defaults to 3.5.
shadowSumBands (list[str], optional) – List of band names to use for calculating the sum of reflectance in TDOM cloud shadow masking. Defaults to [“nir”, “swir1”].
resampleMethod (str, optional) – Specifies the resampling method to apply to the imagery. Valid options include “near”, “bilinear”, and “bicubic”. Defaults to “near”.
harmonizeOLI (bool, optional) – Determines whether to harmonize OLI data to match TM/ETM+ spectral response. Defaults to False.
preComputedCloudScoreOffset (float | None, optional) – Pre-computed Cloud Score offset value to avoid redundant calculations. Defaults to None (automatic calculation).
preComputedTDOMIRMean (float | None, optional) – Pre-computed mean of the IR band used in TDOM cloud shadow masking to avoid redundant calculations. Defaults to None (automatic calculation).
preComputedTDOMIRStdDev (float | None, optional) – Pre-computed standard deviation of the IR band used in TDOM cloud shadow masking to avoid redundant calculations. Defaults to None (automatic calculation).
landsatCollectionVersion (str, optional) – Specifies the Landsat collection version to use (e.g., “C1”, “C2”). Defaults to “C2”.
verbose (bool, optional) – Controls whether to print additional information during processing. Defaults to False.

Returns:

A collection of analysis ready, cloud and cloud shadow asked Landsat scenes with common band names.

Return type:

ee.ImageCollection

>>> import geeViz.getImagesLib as gil
>>> Map = gil.Map
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CO"]
>>> composite = gil.getProcessedLandsatScenes(studyArea, 2023, 2023, 190, 250).median()
>>> Map.addLayer(composite, gil.vizParamsFalse, "Landsat Composite")
>>> Map.addLayer(studyArea, {"canQuery": False}, "Study Area")
>>> Map.centerObject(studyArea)
>>> Map.turnOnInspector()
>>> Map.view()

geeViz.getImagesLib.getProcessedSentinel2Scenes(studyArea, startYear, endYear, startJulian, endJulian, applyQABand=False, applyCloudScore=False, applyShadowShift=False, applyTDOM=False, cloudScoreThresh=20, performCloudScoreOffset=True, cloudScorePctl=10, cloudHeights=<ee.ee_list.List object>, zScoreThresh=-1, shadowSumThresh=0.35, contractPixels=1.5, dilatePixels=3.5, shadowSumBands=['nir', 'swir1'], resampleMethod='aggregate', toaOrSR='TOA', convertToDailyMosaics=True, applyCloudProbability=False, preComputedCloudScoreOffset=None, preComputedTDOMIRMean=None, preComputedTDOMIRStdDev=None, cloudProbThresh=40, verbose=False, applyCloudScorePlus=True, cloudScorePlusThresh=0.6, cloudScorePlusScore='cs')[source]¶

Get cloud/shadow-masked Sentinel-2 scenes for a date range.

Retrieves Sentinel-2 imagery, applies selected cloud and shadow masking methods (QA band, cloud score, TDOM, Cloud Score+, cloud probability), and returns the processed scene collection. This is the scene-level counterpart to getSentinel2Wrapper, which also composites.

Parameters:

studyArea (ee.Geometry | ee.FeatureCollection) – Area of interest.
startYear (int) – First year to include.
endYear (int) – Last year to include.
startJulian (int) – Start day of year (1-365).
endJulian (int) – End day of year (1-365). If < startJulian, the date range wraps across the year boundary.
applyQABand (bool) – Apply the Sentinel-2 QA60 cloud bitmask. Defaults to False.
applyCloudScore (bool) – Apply simple cloud scoring. Defaults to False.
applyShadowShift (bool) – Apply shadow-shift cloud shadow detection. Defaults to False.
applyTDOM (bool) – Apply Temporal Dark Outlier Mask for shadows. Defaults to False.
cloudScoreThresh (int) – Cloud score threshold (0-100). Defaults to 20.
performCloudScoreOffset (bool) – Compute per-scene cloud score offset. Defaults to True.
cloudScorePctl (int) – Percentile for cloud score offset. Defaults to 10.
cloudHeights (ee.List) – Cloud heights in meters for shadow projection. Defaults to ee.List.sequence(500, 10000, 500).
zScoreThresh (float) – TDOM z-score threshold. Defaults to -1.
shadowSumThresh (float) – TDOM shadow sum threshold. Defaults to 0.35.
contractPixels (float) – Pixels to contract cloud/shadow mask. Defaults to 1.5.
dilatePixels (float) – Pixels to dilate cloud/shadow mask. Defaults to 3.5.
shadowSumBands (list[str]) – Bands for shadow detection. Defaults to ["nir", "swir1"].
resampleMethod (str) – Resampling method — "aggregate", "near", "bilinear", or "bicubic". Defaults to "aggregate".
toaOrSR (str) – "TOA" or "SR". Defaults to "TOA".
convertToDailyMosaics (bool) – Mosaic same-day images. Defaults to True.
applyCloudProbability (bool) – Apply the S2 cloud probability band. Defaults to False.
preComputedCloudScoreOffset (ee.Image | None) – Pre-computed cloud score offset image. Defaults to None.
preComputedTDOMIRMean (ee.Image | None) – Pre-computed TDOM IR mean. Defaults to None.
preComputedTDOMIRStdDev (ee.Image | None) – Pre-computed TDOM IR standard deviation. Defaults to None.
cloudProbThresh (int) – Cloud probability threshold (0-100). Defaults to 40.
verbose (bool) – Print all processing parameters. Defaults to False.
applyCloudScorePlus (bool) – Apply Cloud Score+ masking. Defaults to True.
cloudScorePlusThresh (float) – Cloud Score+ threshold (0-1). Defaults to 0.6.
cloudScorePlusScore (str) – Cloud Score+ band — "cs" or "cs_cdf". Defaults to "cs".

Returns:

Cloud/shadow-masked Sentinel-2 scenes with standardized band names.

Return type:

ee.ImageCollection

Example

>>> import geeViz.getImagesLib as gil
>>> study = ee.Geometry.Point([-122.3, 37.5]).buffer(5000)
>>> scenes = gil.getProcessedSentinel2Scenes(
...     study, 2023, 2023, 152, 273
... )
>>> print(scenes.first().bandNames().getInfo()[:3])
['cb', 'blue', 'green']

geeViz.getImagesLib.superSimpleGetS2(studyArea: Geometry | Feature | FeatureCollection | None, startDate: Date | datetime | str, endDate: Date | datetime | str, startJulian: int = 1, endJulian: int = 365, toaOrSR: str = 'TOA', applyCloudScorePlus: bool = True, cloudScorePlusThresh: float = 0.6, cloudScorePlusScore: str = 'cs') → ImageCollection[source]¶

Retrieve cloud-masked Sentinel-2 imagery — preferred S2 function.

This is the recommended way to get Sentinel-2 data. It uses the Cloud Score Plus product for cloud/shadow masking and returns an ee.ImageCollection of individual scenes (not annual composites). Use .median() or .mosaic() to composite as needed.

For annual composites with medoid compositing, see getSentinel2Wrapper() (legacy, more complex).

Parameters:

studyArea (ee.Geometry, ee.Feature, ee.FeatureCollection, or None, optional) – An Earth Engine geometry object representing the area of interest. If set to None, startJulian and endJulian cannot be used. Doing so will cause the image to never render.
startDate (ee.Date, datetime.datetime, or str) – The start date for the image collection in YYYY-MM-DD format.
endDate (ee.Date, datetime.datetime, or str) – The end date for the image collection in YYYY-MM-DD format.
startJulian (int, optional) – The start Julian day of the desired data. Defaults to 1.
endJulian (int, optional) – The end Julian day of the desired data. Defaults to 365.
toaOrSR (str, optional) – Specifies whether to retrieve data in Top-Of-Atmosphere (TOA) reflectance or Surface Reflectance (SR). Defaults to “TOA”.
applyCloudScorePlus (bool, optional) – Determines whether to apply cloud filtering based on the Cloud Score Plus product. Defaults to True.
cloudScorePlusThresh (float, optional) – Sets the threshold for cloud cover percentage based on Cloud Score Plus. Images with cloud cover exceeding this threshold will be masked out if applyCloudScorePlus is True. A higher value will mask out more pixels (call them cloud/cloud-shadow). Defaults to 0.6.
cloudScorePlusScore (str, optional) – One of “cs” - Tends to mask out more. Commits ephemeral water, but doesn’t omit cloud shadows as much or “cs_cdf” - Tends to mask out less, notably fewer water bodies and shadows. This can result in omitting cloud shadows, but not committing ephemeral water as a cloud shadow. Specifies the band name within the Cloud Score Plus product containing the cloud cover information. Defaults to “cs”.

Returns:

A collection of cloud and cloud-shadow-free Sentinel-2 satellite images filtered by the specified criteria.

Return type:

ee.ImageCollection

Note

The spectral values range 0-10000.

>>> import geeViz.getImagesLib as gil
>>> Map = gil.Map
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CA"]
>>> composite = gil.superSimpleGetS2(studyArea, "2024-01-01", "2024-12-31", 190, 250).median()
>>> Map.addLayer(composite, gil.vizParamsFalse10k, "Sentinel-2 Composite")
>>> Map.addLayer(studyArea, {"canQuery": False}, "Study Area")
>>> Map.centerObject(studyArea)
>>> Map.turnOnInspector()
>>> Map.view()

geeViz.getImagesLib.getSentinel2Wrapper(studyArea, startYear, endYear, startJulian, endJulian, timebuffer=0, weights=[1], compositingMethod='medoid', applyQABand=False, applyCloudScore=False, applyShadowShift=False, applyTDOM=False, cloudScoreThresh=20, performCloudScoreOffset=True, cloudScorePctl=10, cloudHeights=<ee.ee_list.List object>, zScoreThresh=-1, shadowSumThresh=0.35, contractPixels=1.5, dilatePixels=3.5, shadowSumBands=['nir', 'swir1'], correctIllumination=False, correctScale=250, exportComposites=False, outputName='Sentinel2-Composite', exportPathRoot='users/username/test', crs='EPSG:5070', transform=[10, 0, -2361915.0, 0, -10, 3177735.0], scale=None, resampleMethod='aggregate', toaOrSR='TOA', convertToDailyMosaics=True, applyCloudProbability=False, preComputedCloudScoreOffset=None, preComputedTDOMIRMean=None, preComputedTDOMIRStdDev=None, cloudProbThresh=40, overwrite=False, verbose=False, applyCloudScorePlus=True, cloudScorePlusThresh=0.6, cloudScorePlusScore='cs')[source]¶

Get annual Sentinel-2 composites with cloud/shadow masking.

Deprecated since version Use: superSimpleGetS2() instead for most use cases. It is simpler (fewer parameters), uses the newer Cloud Score Plus product, and returns individual scenes that you composite as needed (including medoid via compositeTimeSeries). This function is retained for workflows that need the all-in-one annual compositing pipeline with temporal buffering, TDOM, or asset export built in.

Wraps getProcessedSentinel2Scenes to retrieve cloud-masked scenes, then composites them into annual (or multi-year buffered) images using compositeTimeSeries. Optionally exports composites to an EE asset.

Parameters:

studyArea (ee.Geometry | ee.FeatureCollection) – Area of interest.
startYear (int) – First year to include.
endYear (int) – Last year to include.
startJulian (int) – Start day of year (1-365).
endJulian (int) – End day of year (1-365). If < startJulian, the date range wraps across the year boundary.
timebuffer (int) – Years to buffer each composite (e.g. 1 means +/- 1 year). Defaults to 0.
weights (list[int]) – Temporal weights for buffered compositing. Defaults to [1].
compositingMethod (str) – "medoid" or "median". Defaults to "medoid".
applyQABand (bool) – Apply the QA60 cloud bitmask. Defaults to False.
applyCloudScore (bool) – Apply simple cloud scoring. Defaults to False.
applyShadowShift (bool) – Apply shadow-shift detection. Defaults to False.
applyTDOM (bool) – Apply Temporal Dark Outlier Mask. Defaults to False.
cloudScoreThresh (int) – Cloud score threshold (0-100). Defaults to 20.
performCloudScoreOffset (bool) – Per-scene cloud score offset. Defaults to True.
cloudScorePctl (int) – Percentile for cloud score offset. Defaults to 10.
cloudHeights (ee.List) – Cloud heights in meters. Defaults to ee.List.sequence(500, 10000, 500).
zScoreThresh (float) – TDOM z-score threshold. Defaults to -1.
shadowSumThresh (float) – TDOM shadow sum threshold. Defaults to 0.35.
contractPixels (float) – Pixels to contract mask. Defaults to 1.5.
dilatePixels (float) – Pixels to dilate mask. Defaults to 3.5.
shadowSumBands (list[str]) – Bands for shadow detection. Defaults to ["nir", "swir1"].
correctIllumination (bool) – Reserved for future illumination correction. Defaults to False.
correctScale (int) – Scale for illumination correction. Defaults to 250.
exportComposites (bool) – Export composites to EE asset. Defaults to False.
outputName (str) – Asset name prefix. Defaults to "Sentinel2-Composite".
exportPathRoot (str) – Asset folder path. Defaults to "users/username/test".
crs (str) – Output CRS. Defaults to "EPSG:5070".
transform (list) – Affine transform. Defaults to [10, 0, -2361915.0, 0, -10, 3177735.0].
scale (int | None) – Output scale in meters (overrides transform if set). Defaults to None.
resampleMethod (str) – Resampling method. Defaults to "aggregate".
toaOrSR (str) – "TOA" or "SR". Defaults to "TOA".
convertToDailyMosaics (bool) – Mosaic same-day images. Defaults to True.
applyCloudProbability (bool) – Apply cloud probability band. Defaults to False.
preComputedCloudScoreOffset (ee.Image | None) – Pre-computed offset. Defaults to None.
preComputedTDOMIRMean (ee.Image | None) – Pre-computed TDOM mean. Defaults to None.
preComputedTDOMIRStdDev (ee.Image | None) – Pre-computed TDOM std dev. Defaults to None.
cloudProbThresh (int) – Cloud probability threshold (0-100). Defaults to 40.
overwrite (bool) – Overwrite existing exports. Defaults to False.
verbose (bool) – Print all parameters. Defaults to False.
applyCloudScorePlus (bool) – Apply Cloud Score+ masking. Defaults to True.
cloudScorePlusThresh (float) – Cloud Score+ threshold (0-1). Defaults to 0.6.
cloudScorePlusScore (str) – "cs" or "cs_cdf". Defaults to "cs".

Returns:

Dictionary with all input args plus:

"processedScenes": ee.ImageCollection of masked scenes
"processedComposites": ee.ImageCollection of annual composites

Return type:

dict

Example

>>> import geeViz.getImagesLib as gil
>>> study = ee.Geometry.Point([-122.3, 37.5]).buffer(5000)
>>> result = gil.getSentinel2Wrapper(
...     study, 2023, 2023, 152, 273
... )
>>> composites = result['processedComposites']
>>> print(composites.size().getInfo())
1

geeViz.getImagesLib.getProcessedLandsatAndSentinel2Scenes(studyArea, startYear, endYear, startJulian, endJulian, toaOrSR='TOA', includeSLCOffL7=False, defringeL5=False, applyQABand=False, applyCloudProbability=False, applyShadowShift=False, applyCloudScoreLandsat=False, applyCloudScoreSentinel2=False, applyTDOMLandsat=True, applyTDOMSentinel2=False, applyFmaskCloudMask=True, applyFmaskCloudShadowMask=True, applyFmaskSnowMask=False, cloudHeights=<ee.ee_list.List object>, cloudScoreThresh=20, performCloudScoreOffset=True, cloudScorePctl=10, zScoreThresh=-1, shadowSumThresh=0.35, contractPixels=1.5, dilatePixels=3.5, shadowSumBands=['nir', 'swir1'], landsatResampleMethod='near', sentinel2ResampleMethod='aggregate', convertToDailyMosaics=True, runChastainHarmonization=True, correctIllumination=False, correctScale=250, preComputedLandsatCloudScoreOffset=None, preComputedLandsatTDOMIRMean=None, preComputedLandsatTDOMIRStdDev=None, preComputedSentinel2CloudScoreOffset=None, preComputedSentinel2TDOMIRMean=None, preComputedSentinel2TDOMIRStdDev=None, cloudProbThresh=40, landsatCollectionVersion='C2', verbose=False, applyCloudScorePlus=True, cloudScorePlusThresh=0.6, cloudScorePlusScore='cs')[source]¶

Get cloud/shadow-masked Landsat + Sentinel-2 scenes merged together.

Retrieves and masks both Landsat and Sentinel-2 imagery for the same date range, optionally applies Chastain harmonization to align the two sensor families, and returns the merged scene collection. This is the scene-level counterpart to getLandsatAndSentinel2HybridWrapper.

Parameters:

studyArea (ee.Geometry | ee.FeatureCollection) – Area of interest.
startYear (int) – First year to include.
endYear (int) – Last year to include.
startJulian (int) – Start day of year (1-365).
endJulian (int) – End day of year (1-365).
toaOrSR (str) – "TOA" or "SR". Defaults to "TOA".
includeSLCOffL7 (bool) – Include Landsat 7 SLC-off imagery. Defaults to False.
defringeL5 (bool) – Defringe Landsat 5 scenes. Defaults to False.
applyQABand (bool) – Apply QA band cloud mask. Defaults to False.
applyCloudProbability (bool) – Apply S2 cloud probability. Defaults to False.
applyShadowShift (bool) – Apply shadow-shift detection. Defaults to False.
applyCloudScoreLandsat (bool) – Apply cloud score to Landsat. Defaults to False.
applyCloudScoreSentinel2 (bool) – Apply cloud score to Sentinel-2. Defaults to False.
applyTDOMLandsat (bool) – Apply TDOM to Landsat. Defaults to True.
applyTDOMSentinel2 (bool) – Apply TDOM to Sentinel-2. Defaults to False.
applyFmaskCloudMask (bool) – Apply Fmask cloud mask to Landsat. Defaults to True.
applyFmaskCloudShadowMask (bool) – Apply Fmask shadow mask. Defaults to True.
applyFmaskSnowMask (bool) – Apply Fmask snow mask. Defaults to False.
cloudHeights (ee.List) – Cloud heights for shadow projection. Defaults to ee.List.sequence(500, 10000, 500).
cloudScoreThresh (int) – Cloud score threshold. Defaults to 20.
performCloudScoreOffset (bool) – Per-scene cloud score offset. Defaults to True.
cloudScorePctl (int) – Percentile for offset. Defaults to 10.
zScoreThresh (float) – TDOM z-score threshold. Defaults to -1.
shadowSumThresh (float) – TDOM shadow sum threshold. Defaults to 0.35.
contractPixels (float) – Pixels to contract mask. Defaults to 1.5.
dilatePixels (float) – Pixels to dilate mask. Defaults to 3.5.
shadowSumBands (list[str]) – Bands for shadow detection. Defaults to ["nir", "swir1"].
landsatResampleMethod (str) – Landsat resampling. Defaults to "near".
sentinel2ResampleMethod (str) – S2 resampling. Defaults to "aggregate".
convertToDailyMosaics (bool) – Mosaic same-day images. Defaults to True.
runChastainHarmonization (bool) – Apply Chastain et al. harmonization between Landsat and S2. Forced to False when toaOrSR="SR". Defaults to True.
correctIllumination (bool) – Reserved. Defaults to False.
correctScale (int) – Scale for illumination correction. Defaults to 250.
preComputedLandsatCloudScoreOffset (ee.Image | None) – Pre-computed Landsat cloud score offset. Defaults to None.
preComputedLandsatTDOMIRMean (ee.Image | None) – Pre-computed Landsat TDOM mean. Defaults to None.
preComputedLandsatTDOMIRStdDev (ee.Image | None) – Pre-computed Landsat TDOM std dev. Defaults to None.
preComputedSentinel2CloudScoreOffset (ee.Image | None) – Pre-computed S2 cloud score offset. Defaults to None.
preComputedSentinel2TDOMIRMean (ee.Image | None) – Pre-computed S2 TDOM mean. Defaults to None.
preComputedSentinel2TDOMIRStdDev (ee.Image | None) – Pre-computed S2 TDOM std dev. Defaults to None.
cloudProbThresh (int) – Cloud probability threshold. Defaults to 40.
landsatCollectionVersion (str) – "C2" for Collection 2. Defaults to "C2".
verbose (bool) – Print all parameters. Defaults to False.
applyCloudScorePlus (bool) – Apply Cloud Score+ to S2. Defaults to True.
cloudScorePlusThresh (float) – Cloud Score+ threshold (0-1). Defaults to 0.6.
cloudScorePlusScore (str) – "cs" or "cs_cdf". Defaults to "cs".

Returns:

Merged, cloud/shadow-masked Landsat and Sentinel-2 scenes with standardized band names (blue, green, red, nir, swir1, swir2).

Return type:

ee.ImageCollection

Example

>>> import geeViz.getImagesLib as gil
>>> study = ee.Geometry.Point([-105.0, 40.0]).buffer(5000)
>>> scenes = gil.getProcessedLandsatAndSentinel2Scenes(
...     study, 2023, 2023, 152, 273
... )
>>> print(scenes.size().getInfo() > 0)
True

geeViz.getImagesLib.coRegisterCollection(images, referenceBands=['nir'])[source]¶

Co-register all images in a collection to the first image.

Uses ee.Image.displacement and ee.Image.displace to align every image to the first image in the collection based on the specified reference bands.

Parameters:

images (ee.ImageCollection) – Collection of images to co-register.
referenceBands (list[str]) – Band names used for displacement matching. Defaults to ["nir"].

Returns:

Co-registered image collection where the first image is unchanged and all subsequent images are displaced to align with it.

Return type:

ee.ImageCollection

Example

>>> import geeViz.getImagesLib as gil
>>> import ee
>>> imgs = ee.ImageCollection('COPERNICUS/S2_SR_HARMONIZED') \
...     .filterBounds(ee.Geometry.Point([-122.0, 37.0])) \
...     .limit(3)
>>> registered = gil.coRegisterCollection(imgs)

geeViz.getImagesLib.coRegisterGroups(imgs, fieldName='SENSING_ORBIT_NUMBER', fieldIsNumeric=True)[source]¶

Co-register images within groups defined by a metadata field.

Splits the collection by unique values of fieldName, co-registers each group independently using coRegisterCollection, and merges the results back into a single collection.

Parameters:

imgs (ee.ImageCollection) – Collection of images to co-register.
fieldName (str) – Metadata property to group by. Defaults to "SENSING_ORBIT_NUMBER".
fieldIsNumeric (bool) – Whether the field values are numeric (parsed with ee.Number.parse). Defaults to True.

Returns:

Co-registered image collection with images aligned within each group.

Return type:

ee.ImageCollection

Example

>>> import geeViz.getImagesLib as gil
>>> import ee
>>> s2 = ee.ImageCollection('COPERNICUS/S2_SR_HARMONIZED') \
...     .filterBounds(ee.Geometry.Point([-122.0, 37.0])) \
...     .filterDate('2023-06-01', '2023-06-30')
>>> registered = gil.coRegisterGroups(s2)

geeViz.getImagesLib.getLandsatAndSentinel2HybridWrapper(studyArea, startYear, endYear, startJulian, endJulian, timebuffer=0, weights=[1], compositingMethod='medoid', toaOrSR='TOA', includeSLCOffL7=False, defringeL5=False, applyQABand=False, applyCloudProbability=False, applyShadowShift=False, applyCloudScoreLandsat=False, applyCloudScoreSentinel2=False, applyTDOMLandsat=True, applyTDOMSentinel2=False, applyFmaskCloudMask=True, applyFmaskCloudShadowMask=True, applyFmaskSnowMask=False, cloudHeights=<ee.ee_list.List object>, cloudScoreThresh=20, performCloudScoreOffset=True, cloudScorePctl=10, zScoreThresh=-1, shadowSumThresh=0.35, contractPixels=1.5, dilatePixels=3.5, shadowSumBands=['nir', 'swir1'], landsatResampleMethod='near', sentinel2ResampleMethod='aggregate', convertToDailyMosaics=True, runChastainHarmonization=True, correctIllumination=False, correctScale=250, exportComposites=False, outputName='Landsat-Sentinel2-Hybrid', exportPathRoot=None, crs='EPSG:5070', transform=[30, 0, -2361915.0, 0, -30, 3177735.0], scale=None, preComputedLandsatCloudScoreOffset=None, preComputedLandsatTDOMIRMean=None, preComputedLandsatTDOMIRStdDev=None, preComputedSentinel2CloudScoreOffset=None, preComputedSentinel2TDOMIRMean=None, preComputedSentinel2TDOMIRStdDev=None, cloudProbThresh=40, landsatCollectionVersion='C2', overwrite=False, verbose=False, applyCloudScorePlusSentinel2=True, cloudScorePlusThresh=0.6, cloudScorePlusScore='cs')[source]¶

Get annual Landsat + Sentinel-2 hybrid composites.

Wraps getProcessedLandsatAndSentinel2Scenes to retrieve merged, cloud-masked Landsat and Sentinel-2 scenes, then composites them into annual images. Optionally exports composites to an EE asset.

Parameters:

studyArea (ee.Geometry | ee.FeatureCollection) – Area of interest.
startYear (int) – First year to include.
endYear (int) – Last year to include.
startJulian (int) – Start day of year (1-365).
endJulian (int) – End day of year (1-365).
timebuffer (int) – Years to buffer each composite. Defaults to 0.
weights (list[int]) – Temporal weights. Defaults to [1].
compositingMethod (str) – "medoid" or "median". Defaults to "medoid".
toaOrSR (str) – "TOA" or "SR". Defaults to "TOA".
includeSLCOffL7 (bool) – Include Landsat 7 SLC-off. Defaults to False.
defringeL5 (bool) – Defringe Landsat 5. Defaults to False.
applyQABand (bool) – Apply QA band mask. Defaults to False.
applyCloudProbability (bool) – Apply S2 cloud probability. Defaults to False.
applyShadowShift (bool) – Apply shadow-shift. Defaults to False.
applyCloudScoreLandsat (bool) – Cloud score for Landsat. Defaults to False.
applyCloudScoreSentinel2 (bool) – Cloud score for S2. Defaults to False.
applyTDOMLandsat (bool) – TDOM for Landsat. Defaults to True.
applyTDOMSentinel2 (bool) – TDOM for S2. Defaults to False.
applyFmaskCloudMask (bool) – Fmask clouds for Landsat. Defaults to True.
applyFmaskCloudShadowMask (bool) – Fmask shadows. Defaults to True.
applyFmaskSnowMask (bool) – Fmask snow. Defaults to False.
cloudHeights (ee.List) – Cloud heights for shadow projection. Defaults to ee.List.sequence(500, 10000, 500).
cloudScoreThresh (int) – Cloud score threshold. Defaults to 20.
performCloudScoreOffset (bool) – Per-scene offset. Defaults to True.
cloudScorePctl (int) – Offset percentile. Defaults to 10.
zScoreThresh (float) – TDOM z-score threshold. Defaults to -1.
shadowSumThresh (float) – TDOM shadow sum threshold. Defaults to 0.35.
contractPixels (float) – Contract mask pixels. Defaults to 1.5.
dilatePixels (float) – Dilate mask pixels. Defaults to 3.5.
shadowSumBands (list[str]) – Shadow detection bands. Defaults to ["nir", "swir1"].
landsatResampleMethod (str) – Landsat resampling. Defaults to "near".
sentinel2ResampleMethod (str) – S2 resampling. Defaults to "aggregate".
convertToDailyMosaics (bool) – Mosaic same-day images. Defaults to True.
runChastainHarmonization (bool) – Harmonize Landsat/S2. Defaults to True.
correctIllumination (bool) – Reserved. Defaults to False.
correctScale (int) – Illumination correction scale. Defaults to 250.
exportComposites (bool) – Export to EE asset. Defaults to False.
outputName (str) – Asset name prefix. Defaults to "Landsat-Sentinel2-Hybrid".
exportPathRoot (str | None) – Asset folder path. Defaults to None.
crs (str) – Output CRS. Defaults to "EPSG:5070".
transform (list) – Affine transform. Defaults to [30, 0, -2361915.0, 0, -30, 3177735.0].
scale (int | None) – Output scale (overrides transform). Defaults to None.
preComputedLandsatCloudScoreOffset (ee.Image | None) – Defaults to None.
preComputedLandsatTDOMIRMean (ee.Image | None) – Defaults to None.
preComputedLandsatTDOMIRStdDev (ee.Image | None) – Defaults to None.
preComputedSentinel2CloudScoreOffset (ee.Image | None) – Defaults to None.
preComputedSentinel2TDOMIRMean (ee.Image | None) – Defaults to None.
preComputedSentinel2TDOMIRStdDev (ee.Image | None) – Defaults to None.
cloudProbThresh (int) – Cloud probability threshold. Defaults to 40.
landsatCollectionVersion (str) – Defaults to "C2".
overwrite (bool) – Overwrite existing exports. Defaults to False.
verbose (bool) – Print all parameters. Defaults to False.
applyCloudScorePlusSentinel2 (bool) – Cloud Score+ for S2. Defaults to True.
cloudScorePlusThresh (float) – Cloud Score+ threshold (0-1). Defaults to 0.6.
cloudScorePlusScore (str) – "cs" or "cs_cdf". Defaults to "cs".

Returns:

Dictionary with all input args plus:

"processedScenes": ee.ImageCollection of merged scenes
"processedComposites": ee.ImageCollection of annual composites

Return type:

dict

Example

>>> import geeViz.getImagesLib as gil
>>> study = ee.Geometry.Point([-105.0, 40.0]).buffer(5000)
>>> result = gil.getLandsatAndSentinel2HybridWrapper(
...     study, 2023, 2023, 152, 273
... )
>>> composites = result['processedComposites']
>>> print(composites.size().getInfo())
1

geeViz.getImagesLib.getHarmonicList(yearDateImg, transformBandName, harmonicList)[source]¶

Compute sin and cos harmonic predictor bands for a year-fraction image.

Takes a year.dd date image and a list of harmonic frequencies, and appends sin and cos bands for each harmonic to the input image.

Parameters:

yearDateImg (ee.Image) – Image containing a band with year-fraction values (e.g., 2020.5 for mid-year 2020).
transformBandName (str) – Name of the band in yearDateImg that holds the year-fraction values (e.g., "year").
harmonicList (list[int]) – List of harmonic numbers to generate predictors for (e.g., [1, 2, 3]). Each value h produces sin(h * pi * t) and cos(h * pi * t) bands.

Returns:

The input image with additional sin and cos bands appended.: Band names follow the pattern sin_<h*100>_<transformBandName> and cos_<h*100>_<transformBandName>.

Return type:

ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> dateImg = ee.Image(2020.5).rename('year')
>>> result = gil.getHarmonicList(dateImg, 'year', [2])
>>> print(result.bandNames().getInfo())
['year', 'sin_200_year', 'cos_200_year']

geeViz.getImagesLib.getHarmonics2(collection, transformBandName, harmonicList, detrend=False)[source]¶

Prepare an ImageCollection with harmonic predictor bands for regression.

Adds sin and cos harmonic predictor bands to each image in the collection, and stores metadata about dependent and independent band names/numbers on the returned collection for use by newRobustMultipleLinear2.

Parameters:

collection (ee.ImageCollection) – Input collection where each image has a year-fraction band (named transformBandName) and one or more dependent variable bands.
transformBandName (str) – Name of the band containing year-fraction values (e.g., "year").
harmonicList (list[int]) – List of harmonic numbers (e.g., [2] for annual, [2, 4] for annual + semi-annual).
detrend (bool, optional) – If True, retains the "year" band as an additional linear trend predictor. Defaults to False.

Returns:

Collection with harmonic bands appended to each image: and metadata properties indBandNames, depBandNames, indBandNumbers, and depBandNumbers set on the collection.

Return type:

ee.ImageCollection

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> composites = ee.ImageCollection('projects/my-project/assets/composites')
>>> withHarmonics = gil.getHarmonics2(composites, 'year', [2])
>>> print(withHarmonics.get('indBandNames').getInfo())

geeViz.getImagesLib.newRobustMultipleLinear2(dependentsIndependents)[source]¶

Fit a linear regression model across an ImageCollection with labeled bands.

Applies ee.Reducer.linearRegression to a collection that has been prepared by getHarmonics2, returning an image of regression coefficients for each dependent variable.

Parameters:

dependentsIndependents (ee.ImageCollection) – Collection with metadata properties depBandNames, depBandNumbers, indBandNames, and indBandNumbers set (as produced by getHarmonics2).

Returns:

Image of regression coefficients with bands named: <dependent>_intercept, <dependent>_<independent>, etc. Has metadata properties noDependents and modelLength.

Return type:

ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> composites = ee.ImageCollection("projects/my-project/assets/composites")
>>> withHarmonics = gil.getHarmonics2(composites, "year", [2])
>>> coeffs = gil.newRobustMultipleLinear2(withHarmonics)
>>> print(coeffs.bandNames().getInfo())

geeViz.getImagesLib.getPeakDate(coeffs, peakDirection=1)[source]¶

Compute the Julian day, month, and day-of-month of peak vegetation vigor.

Finds the date within an annual cycle where the first harmonic (sin/cos) reaches its maximum, accounting for the sign of the peak direction. Uses module-level lookup tables to convert Julian day to month and day of month.

Parameters:

coeffs (ee.Image) – Two-band image where band 0 is the sin coefficient and band 1 is the cos coefficient from a harmonic regression.
peakDirection (int, optional) – Set to 1 for bands positively correlated with vegetation vigor, or -1 for negatively correlated bands. Defaults to 1.

Returns:

Three-band image with bands peakJulianDay (1–365),: peakMonth (1–12), and peakDayOfMonth (1–31).

Return type:

ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> coeffs = ee.Image([0.1, -0.2])
>>> peakInfo = gil.getPeakDate(coeffs, peakDirection=1)
>>> print(peakInfo.bandNames().getInfo())
['peakJulianDay', 'peakMonth', 'peakDayOfMonth']

geeViz.getImagesLib.getAreaUnderCurve(harmCoeffs, t0=0, t1=1)[source]¶

Compute the definite integral (area under curve) of a single-harmonic model.

Analytically integrates the harmonic function amplitude + sin_coeff * sin(2*pi*t) + cos_coeff * cos(2*pi*t) between t0 and t1, normalizing so the minimum of the curve is zero.

Parameters:

harmCoeffs (ee.Image) – Two-band image where band 0 is the sin coefficient and band 1 is the cos coefficient from a harmonic regression.
t0 (float, optional) – Start of the integration interval as a fraction of the year (0 = Jan 1). Defaults to 0.
t1 (float, optional) – End of the integration interval as a fraction of the year (1 = Dec 31). Defaults to 1.

Returns:

Single-band image named AUC with the area under the curve.

Return type:

ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> harmCoeffs = ee.Image([0.05, -0.1])
>>> auc = gil.getAreaUnderCurve(harmCoeffs, t0=0, t1=1)
>>> print(auc.bandNames().getInfo())
['AUC']

geeViz.getImagesLib.getPhaseAmplitudePeak(coeffs, t0=0, t1=1)[source]¶

Extract phase, amplitude, peak date, and AUC from harmonic regression coefficients.

Parses multi-band harmonic regression coefficients (from newRobustMultipleLinear2) and computes per-dependent-variable amplitude, phase (0–1 scaled), peak date (Julian day, month, day of month), and area under the curve.

Parameters:

coeffs (ee.Image) – Harmonic regression coefficient image as returned by newRobustMultipleLinear2, with metadata noDependents and modelLength.
t0 (float, optional) – Start of integration interval for AUC calculation (fraction of year). Defaults to 0.
t1 (float, optional) – End of integration interval for AUC calculation (fraction of year). Defaults to 1.

Returns:

Multi-band image with bands named: <dep>_amplitude, <dep>_phase, <dep>_peakJulianDay, <dep>_peakMonth, <dep>_peakDayOfMonth, and <dep>_AUC for each dependent variable.

Return type:

ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CO"]
>>> result = gil.getLandsatWrapper(studyArea, 2018, 2023, 1, 365)
>>> composites = result["processedComposites"]
>>> coeffs, predicted = gil.getHarmonicCoefficientsAndFit(
...     composites, ["NDVI"], whichHarmonics=[2])
>>> pap = gil.getPhaseAmplitudePeak(coeffs)
>>> print(pap.bandNames().getInfo())

geeViz.getImagesLib.newPredict(coeffs, harmonics)[source]¶

Apply harmonic regression coefficients to predict values for each image.

Uses the coefficient image from newRobustMultipleLinear2 and the harmonic predictor collection from getHarmonics2 to generate predicted values for each dependent variable at each time step.

Parameters:

coeffs (ee.Image) – Harmonic regression coefficient image as returned by newRobustMultipleLinear2, with metadata noDependents and modelLength.
harmonics (ee.ImageCollection) – Collection with harmonic predictor bands as returned by getHarmonics2, with metadata indBandNames, depBandNames, indBandNumbers, and depBandNumbers.

Returns:

Collection where each image contains the original: dependent bands plus <dep>_predicted bands for each dependent variable.

Return type:

ee.ImageCollection

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> composites = ee.ImageCollection("projects/my-project/assets/composites")
>>> withHarmonics = gil.getHarmonics2(composites, "year", [2])
>>> coeffs = gil.newRobustMultipleLinear2(withHarmonics)
>>> predicted = gil.newPredict(coeffs, withHarmonics)
>>> print(ee.Image(predicted.first()).bandNames().getInfo())

geeViz.getImagesLib.getDateStack(startYear, endYear, startJulian, endJulian, frequency)[source]¶

Generate a synthetic date image stack for predicting harmonic time series.

Creates an ImageCollection of dummy images at regular intervals, each tagged with system:time_start and containing a year band with year-fraction values, plus constant bands for each index in the module-level indexNames list.

Parameters:

startYear (int) – First year to include.
endYear (int) – Last year to include.
startJulian (int) – Starting Julian day within each year.
endJulian (int) – Ending Julian day within each year.
frequency (int) – Step size in days between successive images.

Returns:

Collection of images with year (year.dd) and: constant index bands, each with system:time_start and system:time_end properties set.

Return type:

ee.ImageCollection

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> dateStack = gil.getDateStack(2020, 2023, 1, 365, 32)
>>> print(dateStack.size().getInfo())

geeViz.getImagesLib.getHarmonicCoefficientsAndFit(allImages, indexNames, whichHarmonics=[2], detrend=False)[source]¶

Fit harmonic regression to an ImageCollection and return coefficients and fitted values.

Convenience wrapper that chains getHarmonics2, newRobustMultipleLinear2, and newPredict to fit a harmonic model to selected bands and return both the coefficient image and the predicted time series.

Parameters:

allImages (ee.ImageCollection) – Input image collection containing the bands to model.
indexNames (list[str]) – List of band names to fit harmonics to (e.g., ["NDVI", "NBR"]).
whichHarmonics (list[int], optional) – Harmonic numbers to include (e.g., [2] for annual, [2, 4] for annual + semi-annual). Defaults to [2].
detrend (bool, optional) – If True, includes a linear year trend term in the regression. Defaults to False.

Returns:

Two-element list [coeffs, predicted] where:

coeffs (ee.Image): Regression coefficients image.
predicted (ee.ImageCollection): Collection with actual and predicted bands.

Return type:

list

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CO"]
>>> result = gil.getLandsatWrapper(studyArea, 2018, 2023, 1, 365)
>>> composites = result["processedComposites"]
>>> coeffs, predicted = gil.getHarmonicCoefficientsAndFit(
...     composites, ["NDVI"], whichHarmonics=[2])

geeViz.getImagesLib.synthImage(coeffs, dateImage, indexNames, harmonics, detrend)[source]¶

Predict band values at a single date using harmonic regression coefficients.

Builds a predictor image from a date value (year.dd format) and the specified harmonics, then multiplies by the regression coefficients to produce a synthetic image for each band.

Parameters:

coeffs (ee.Image) – Harmonic regression coefficient image as returned by getHarmonicCoefficientsAndFit (first element of the returned list).
dateImage (ee.Image) – Single-band image with year-fraction values (e.g., ee.Image(2021.5)).
indexNames (list[str]) – List of band names that were modeled (e.g., ["NDVI", "NBR"]).
harmonics (list[int]) – Harmonic numbers used when fitting the model (e.g., [2] or [2, 4]).
detrend (bool) – Whether a linear trend term was included in the model.

Returns:

Predicted image with one band per index name.

Return type:

ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CO"]
>>> result = gil.getLandsatWrapper(studyArea, 2018, 2023, 1, 365)
>>> composites = result["processedComposites"]
>>> coeffs, _ = gil.getHarmonicCoefficientsAndFit(
...     composites, ["NDVI", "NBR"], whichHarmonics=[2])
>>> synth = gil.synthImage(coeffs, ee.Image(2022.5), ["NDVI", "NBR"], [2], False)
>>> print(synth.bandNames().getInfo())
['NDVI', 'NBR']

geeViz.getImagesLib.getClimateWrapper(collectionName: str, studyArea: Geometry | Feature | FeatureCollection, startYear: int, endYear: int, startJulian: int, endJulian: int, timebuffer: int = 0, weights: List | list | None = None, compositingReducer: Reducer | None = None, exportComposites: bool = False, exportPathRoot: str | None = None, crs: str | None = None, transform: list[int] | None = None, scale: int | None = None, exportBands: List | list | None = None, exportNamePrefix: str = '', exportToAssets: bool = False, exportToCloud: bool = False, bucket: str = '') → ImageCollection[source]¶

Wrapper function to retrieve and process climate data from various Earth Engine collections.

This function supports retrieving climate data from collections like NASA/ORNL/DAYMET_V3, NASA/ORNL/DAYMET_V4, UCSB-CHG/CHIRPS/DAILY (precipitation only), and potentially others. It allows filtering by date, study area, and Julian day, specifying a compositing reducer, and optionally exporting the resulting time series.

Parameters:

collectionName (str) – Name of the Earth Engine collection containing climate data.
studyArea (ee.Geometry | ee.Feature | ee.FeatureCollection) – The geographic area of interest (study area) as an Earth Engine geometry object.
startYear (int) – The starting year for the data collection.
endYear (int) – The ending year for the data collection.
startJulian (int) – The starting Julian day of year for the data collection (1-365).
endJulian (int) – The ending Julian day of year for the data collection (1-365).
timebuffer (int, optional) – Number of years to buffer around each year. Defaults to 0.
weights (ee.List | list| None, optional) – List of weights for weighted compositing (if applicable to the chosen collection). Defaults to None (equal weights).
compositingReducer (ee.Reducer | None, optional) – Earth Engine reducer used for compositing daily data into the desired temporal resolution. Defaults to None (may require a reducer depending on the collection).
exportComposites (bool, optional) – Flag indicating whether to export the resulting time series. Defaults to False.
exportPathRoot (str | None, optional) – Root path for exporting the composites (if exportComposites is True). Defaults to None (no export).
crs (str | None, optional) – Earth Engine projection object for the exported composites (if exportComposites is True). Defaults to None (uses the source collection’s projection).
transform (list[int] | None, optional) – Earth Engine transform object for the exported composites (if exportComposites is True). Defaults to None (uses the source collection’s transform).
scale (int | None, optional) – Scale in meters for the exported composites (if exportComposites is True). Defaults to None (uses the source collection’s scale).
exportBands (ee.List | list | None, optional) – List of band names to export from the composites (if exportComposites is True). Defaults to None (all bands from the first image in the collection).
exportNamePrefix (str, optional) – Name to place before default name of exported image. Defaults to ‘’.
exportToAssets (bool, optional) – Set to True to export images to earth engine assets. Defaults to False.
exportToCloud (bool, optional) – Set to True to export images to Google Cloud Storage. Defaults to False.
bucket (str, optional) – If exportToCloud is True, images are exported to this Google Cloud storage bucket. Defaults to ‘’, but will need to be provided if exportToCloud is True.

Returns:

The time series collection of processed climate data.

Return type:

ee.ImageCollection

>>> import geeViz.getImagesLib as gil
>>> Map = gil.Map
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CO"]
>>> startJulian = 274
>>> endJulian = 273
>>> startYear = 2016
>>> endYear = 2023
>>> timebuffer = 0
>>> weights = [1]
>>> compositingReducer = ee.Reducer.mean()
>>> collectionName = "NASA/ORNL/DAYMET_V4"
>>> exportComposites = False
>>> exportPathRoot = "users/username/someCollection"
>>> exportBands = ["prcp.*", "tmax.*", "tmin.*"]
>>> exportNamePrefix = 'Colorado_Test_Area_'
>>> crs = "EPSG:5070"
>>> transform = [1000, 0, -2361915.0, 0, -1000, 3177735.0]
>>> scale = None
>>> climateComposites = gil.getClimateWrapper(collectionName, studyArea, startYear, endYear, startJulian, endJulian, timebuffer, weights, compositingReducer, exportComposites, exportPathRoot, crs, transform, scale, exportBands, exportNamePrefix,exportToAssets,exportToCloud,bucket)
>>> Map.addTimeLapse(climateComposites.select(exportBands), {}, "Climate Composite Time Lapse")
>>> Map.addLayer(studyArea, {"strokeColor": "0000FF", "canQuery": False}, "Study Area", True)
>>> Map.centerObject(studyArea)
>>> Map.turnOnInspector()
>>> Map.view()

geeViz.getImagesLib.addAbsDiff(inCollection, qualityBand, percentile, sign)[source]¶

Add a band with the absolute difference from a percentile-based quality target.

Computes the specified percentile of a quality band across the collection, then adds a delta band to each image representing the absolute difference from that percentile value, multiplied by the given sign.

Parameters:

inCollection (ee.ImageCollection) – Input image collection.
qualityBand (str) – Name of the band to compute the percentile on.
percentile (int | float) – Percentile value (0–100) to use as the target quality.
sign (int) – Multiplier for the delta band, typically -1 to invert for use with qualityMosaic (which selects the max).

Returns:

Collection with an added delta band on each image.

Return type:

ee.ImageCollection

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> collection = ee.ImageCollection("LANDSAT/LC09/C02/T1_L2").limit(10)
>>> withDelta = gil.addAbsDiff(collection, "SR_B4", 50, -1)
>>> print(ee.Image(withDelta.first()).bandNames().getInfo())

geeViz.getImagesLib.customQualityMosaic(inCollection, qualityBand, percentile)[source]¶

Create a quality mosaic using a specified percentile rather than the max.

Wraps addAbsDiff and ee.ImageCollection.qualityMosaic to select pixels closest to the given percentile of a quality band, rather than always selecting the maximum.

Parameters:

inCollection (ee.ImageCollection) – Input image collection to mosaic.
qualityBand (str) – Name of the band to use for quality ranking.
percentile (int | float) – Target percentile (0–100). The pixel closest to this percentile value of qualityBand is selected.

Returns:

Mosaic image where each pixel is chosen from the image whose: quality band value is closest to the specified percentile.

Return type:

ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> collection = ee.ImageCollection("LANDSAT/LC09/C02/T1_L2").limit(20)
>>> mosaic = gil.customQualityMosaic(collection, "SR_B4", 50)
>>> print(mosaic.bandNames().getInfo())

geeViz.getImagesLib.simpleWaterMask(img: Image, contractPixels: int = 0, slope_thresh: float = 10, elevationImagePath: str | Image | ImageCollection = 'USGS/3DEP/10m', elevationFocalMeanRadius: float = 5.5) → Image[source]¶

Performs a basic on-the-fly water masking for TOA reflectance imagery.

This function creates a water mask based on thresholds applied to Tasseled Cap angles, brightness, and slope. It’s designed for time-sensitive analysis and works well when wet snow is absent. However, wet snow in flat areas can lead to false positives. SR data might cause false negatives (omissions).

Parameters:

img (ee.Image) – The input Earth Engine image (TOA reflectance data recommended) with Tasseled Cap transformation bands added. You may need to run getTasseledCap to add these bands.
contractPixels (int, optional) – Number of pixels to contract the water mask by for morphological closing. Defaults to 0 (no contraction).
slope_thresh (float, optional) – Threshold for slope (degrees) to identify flat areas suitable for water masking. Defaults to 10.
elevationImagePath (str or ee.Image or ee.ImageCollection, optional) – Path to the Earth Engine image or Earth Engine image or imageCollection object containing elevation data. Defaults to “USGS/3DEP/10m” (10m DEM from USGS 3D Elevation Program).
elevationFocalMeanRadius (float, optional) – Radius (in pixels) for the focal mean filter applied to the elevation data before calculating slope. Defaults to 5.5.

Returns:

The water mask image with a single band named “waterMask”.

Return type:

ee.Image

>>> import geeViz.getImagesLib as gil
>>> Map = gil.Map
>>> ee = gil.ee
>>> studyArea = gil.testAreas["CO"]
>>> s2s = gil.superSimpleGetS2(studyArea, "2024-01-01", "2024-12-31", 190, 250).map(lambda img: gil.getTasseledCap(img.resample("bicubic").divide(10000)))
>>> median_composite = s2s.median()
>>> water = gil.simpleWaterMask(median_composite).rename("Water")
>>> water = water.selfMask().set({"Water_class_values": [1], "Water_class_names": ["Water"], "Water_class_palette": ["0000DD"]})
>>> Map.addLayer(median_composite.reproject("EPSG:32613", None, 10), gil.vizParamsFalse, "Sentinel-2 Median Composite")
>>> Map.addLayer(water.reproject("EPSG:32613", None, 10), {"autoViz": True}, "Water Mask")
>>> Map.addLayer(studyArea, {"canQuery": False}, "Study Area")
>>> Map.centerObject(studyArea, 12)
>>> Map.turnOnInspector()
>>> Map.view()

geeViz.getImagesLib.simpleMask(image: Image, mask_type: str = 'vegetation', threshold: float = None, invert: bool = False, **kwargs) → Image[source]¶

Create a simple spectral mask from standard optical bands.

Applies well-established spectral index thresholds to produce binary masks for common land cover types. Input must have bands named blue, green, red, nir, swir1, swir2 with reflectance values scaled 0–1. Landsat processed through geeViz wrappers (getProcessedLandsatScenes) is already 0–1. Sentinel-2 from superSimpleGetS2 is 0–10000 — divide by 10000 first.

The returned image has class properties set so it works directly with autoViz, area charting, and thumbnails.

Mask types and their default rules (all on 0–1 reflectance):

"water" — detects water using one of three methods (pass method="tc"|"mndwi"|"awei" via **kwargs):
- "tc" (default) — TC angles + brightness + slope via simpleWaterMask(). Good for general use.
- "mndwi" — MNDWI > 0 + slope < threshold (Xu 2006). Better for saline/shallow water bodies.
- "awei" — MNDWI > 0 AND AWEI_nsh > 0 + slope < threshold (Feyisa et al. 2014). Most robust — handles shadows, dark surfaces, and saline water (Aral Sea, Great Salt Lake).
Also accepts slope_thresh (default 5), contractPixels, elevationImagePath, etc. via **kwargs.
"vegetation" — NDVI > 0.4 (Tucker 1979). Override with threshold=0.2 for sparse vegetation.
"snow" — NDSI > 0.4 AND NIR > 0.11 (Hall et al. 1995, MODIS snow product basis). threshold overrides the NDSI value.
"bare" — NDVI < 0.2 AND NDSI < 0.4 AND not water. Identifies exposed soil/rock. threshold overrides NDVI ceiling.
"urban" — NDBI > 0 AND NDVI < 0.2 (Zha et al. 2003). NDBI is (SWIR1 − NIR) / (SWIR1 + NIR). threshold overrides NDBI.
"cloud" — blue > 0.3 AND TC brightness > 0.35 (simple heuristic; for production use CFmask/s2cloudless instead). threshold overrides blue reflectance.
"shadow" — NIR < 0.1 AND TC brightness < 0.1 (simple heuristic; for production use CFmask geometry-based shadows). threshold overrides NIR value.

Parameters:

image (ee.Image) – Input image with bands blue, green, red, nir, swir1, swir2 scaled 0–1.
mask_type (str) – One of "water", "vegetation", "snow", "bare", "urban", "cloud", "shadow".
threshold (float, optional) – Override the primary threshold for the chosen mask type. When None, uses literature defaults.
invert (bool) – If True, returns pixels that do NOT match (e.g. non-vegetation). Default False.
**kwargs –
Extra arguments forwarded to the water mask method when mask_type="water":
- method (str): "tc" (default), "mndwi", or "awei". See mask type docs above.
- slope_thresh (float): Max slope in degrees for flat areas (default 5 for mndwi/awei, 10 for tc).
- contractPixels (int): Morphological closing pixels (default 0). Only for method="tc".
- elevationImagePath: DEM source (default "USGS/3DEP/10m"). Only for method="tc".

Returns:

Single-band binary mask (1 = matches, 0 = doesn’t) named by mask_type (e.g. "vegetation"). Class properties are set for autoViz rendering.

Return type:

ee.Image

Examples

Vegetation mask from Landsat (already 0–1):

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> area = ee.Geometry.Point([-111.9, 40.7]).buffer(10000)
>>> scenes = gil.getProcessedLandsatScenes(area, 2023, 2023, 152, 273)
>>> composite = scenes['processedScenes'].median()
>>> veg = gil.simpleMask(composite, "vegetation")

Snow mask from S2 (divide by 10000 first):

>>> s2 = gil.superSimpleGetS2(area, "2023-01-01", "2023-03-31").median()
>>> snow = gil.simpleMask(s2.divide(10000), "snow")

Water mask (default TC method):

>>> water = gil.simpleMask(composite, "water")

Water mask for saline/shallow water (AWEI method):

>>> water = gil.simpleMask(composite, "water", method="awei")

geeViz.getImagesLib.HoCalcGreenness(img)[source]¶

Compute the hue component for algal bloom greenness detection.

Implements a hue calculation from RGB bands to help distinguish algal bloom pixels from suspended sediment. Pixels with hue below 1.6 are more likely to be algal blooms. Based on the Jeff Ho method for water quality analysis.

Parameters:: img (ee.Image) – Input image with red, green, and blue bands.
Returns:: Single-band image named H containing the hue values.
Return type:: ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> img = ee.Image("LANDSAT/LC09/C02/T1_TOA/LC09_017031_20220601")
>>> hue = gil.HoCalcGreenness(img.select(["B4", "B3", "B2"], ["red", "green", "blue"]))
>>> print(hue.bandNames().getInfo())
['H']

geeViz.getImagesLib.HoCalcAlgorithm1(image)[source]¶

Apply the Ho et al. algal bloom detection algorithm to a satellite image.

Implements Algorithm 1 from Wang & Shi (2007) for detecting algal blooms in water bodies using NIR-SWIR atmospheric correction. Adds a hue-based greenness filter to distinguish blooms from suspended sediment.

Reference:: Wang, M., & Shi, W. (2007). The NIR-SWIR combined atmospheric correction approach for MODIS ocean color data processing. Optics Express, 15(24), 15722-15733.

Parameters:

image (ee.Image) – Input image with red, green, blue, nir, and swir1 bands.

Returns:

The input image with additional bands: H (hue from: HoCalcGreenness), bloom1 (bloom intensity), and bloom1_mask (binary bloom classification).

Return type:

ee.Image

Examples

>>> import geeViz.getImagesLib as gil
>>> ee = gil.ee
>>> img = ee.Image("LANDSAT/LC09/C02/T1_TOA/LC09_017031_20220601")
>>> bands = img.select(["B4", "B3", "B2", "B5", "B6"], ["red", "green", "blue", "nir", "swir1"])
>>> result = gil.HoCalcAlgorithm1(bands)
>>> print(result.bandNames().getInfo())