ImageCollection class

class inter.ImageCollection

ImageCollection class is the interface to the selection and filtering operations inside JEODPP interactive library. It can be used to select an image dataset and perform filtering of its content based on geographic location and on any metadata attribute of the collection. An instance of ImageCollection has to be created giving as argument the name of the collection. To list all the available collection names the following call should be executed:

inter.listImageCollections()

To work with Sentinel2 data the following ImageCollection can be created:

coll = inter.ImageCollection("S2")

After the ImageCollection is created, one or more filtering criteria can be added. To add a filtering on geographic location the method ImageCollection.filterOnLocation() can be used, while to add a filter on a metadata attribute the method ImageCollection.filterOn() can be used. Filters on acquisition date can be added using the ImageCollection.filterOnDate() method. When all the filtering criteria have been added, usually a ImageCollection.sort() clause is added to sort the images satisfying all the criteria on one of the metadata attributes. A ImageCollection.limit() clause can also be added to limit the number of images returned before passing them to the map to be displayed.

Examples:

The following example selects all the Sentinel 2 images acquired in 2015 or 2016 over the city of Munich:

coll = inter.ImageCollection("S2")
cityName="Munchen"
enlargeByDegree= 0
countryCode="DE"
coll = coll.filterOnGeoName(cityName, enlargeByDegree, countryCode)
coll = coll.filterOnDate(2015,1,1, 2016,12,31)

To filter on a metadata attribute (like the cloud cover percentage of the images) and narrow the results to only the 4 less cloudy images, the following clauses can be executed:

coll = coll.sort("cloudcoverpercentage")
coll.limit(4)
Notes:

The calls to ImageCollection methods can be chained together using the . syntax. When more than one method is called in a single instruction, it is always a good practice to assign the result of the calls to a variable (or to the same collection object) like in:

coll = coll.filterOnDate(2015,1,1, 2016,12,31).sort("cloudcoverpercentage").limit(4)

General methods

ImageCollection.getDebug()

Queries the current state of the Debug flag

Returns:
True if Debug state is active, False otherwise.
ImageCollection.setDebug(flag)

Sets the Debug flag. When the Debug flag is set the ImageCollection class prints queries sent to database to the output of the ipython notebook. It can be useful to debug possible problems encountered in selecting complex image databases.

Args:
  • flag (bool): True if the Debug state has to be activated, False if it has to be deactivated.
ImageCollection.copyTo(collection)

Copies the content of an ImageCollection instance to another instance.

Args:
  • collection (ImageCollection): Destination instance of ImageCollection copyTo operation
Example:

The following code shows a typical usage of copyTo method to obtain a copy of an existing ImageCollection istance and modify it:

# Select all 2016 images over Munchen (DE)
coll = inter.ImageCollection("S2")
coll = coll.filterOnGeoName("Munchen", 0, "DE")
coll = coll.filterOnDate(2016,1,1, 2016,12,31)

# Create a copy of the collection
coll2 = inter.ImageCollection("")
coll.copyTo(coll2)

# Modify the second collection to filter only images having small cloud cover
coll2.filterOn("cloudcoverpercentage","<=",5)

# print number of images in the original and the copied ImageCollection
print coll.count()
print coll2.count()
ImageCollection.printNamedColors(format=1)

Prints the list of named colors managed by the interactive visualization library. Colors can be selected using WEB format (#RRGGBB) or using names of colors in this list.

Args:

  • format (integer): format to use for the R,G,B component of the named colors (optional, default = 1):

    • 0: components are written in CSV (i.e. 255,0,128).
    • 1: components are written in WEB format (i.e. #FF05AA).
    • 2: components are written in HEX format (i.e. FF05AA).
Returns:
The number of named colors printed.
ImageCollection.printColorSchemes()

Prints the list of of all available color schemes. Colors schemes can be used to customize the appearance of layers in the map by using the method ImageProcess.colorScheme().

Returns:
The number of color schemes printed.
ImageCollection.printGeoNames(Name, Country='', MaxRows=10, FeatureClass='A', FeatureCode='')

Queries the GeoNames service for geocoding: prints geonames found. This method can be used to better understand what will be selected with a call to ImageCollection.filterOnLocation()

Args:
  • Name (string): named place to search for.
  • Country (string): two digit country code of the country (optional, default value = “”).
  • MaxRows (integer): maximum number of rows to be returned from GeoNames call (optional, default value = 10).
  • FeatureClass (string): feature class to search inside GeoNames database (optional, default = “A”, i.e. “Country, state, region, …”).
  • FeatureCode (string): feature code to search (optional, default = “”).
Returns:
The number of geonames printed.

Information methods

ImageCollection.count()

Counts the number of images currently selected.

Returns:
The number of selected images.
ImageCollection.printImages(AttributeName='id')

Prints the values of the metadata attribute whose name is passed as argument for all the selected images of the collection. To have a list of all the available metadata attributes for a specific ImageCollection, the method ImageCollection.printAttributes() can be called.

Args:
  • AttributeName (string): The name of the metadata attribute whose values have to be printed (optional, defaut = “id”)
Returns:
The numer of selected images.
ImageCollection.listImages(AttributeName='id')

Given in input a name of a metadata attribute, the listImages method returns a python list containing the values of the attribute for all the selected images of the ImageCollection instance. To have a list of all the available metadata attributes for a specific ImageCollection, the method ImageCollection.printAttributes() can be called.

Args:
  • AttributeName (string): The name of the metadata attribute whose values have to be returned (optional, defaut = “id”)
Returns:
A python list.
ImageCollection.printAttributes()

Prints the list of all available metadata attributes for the ImageCollection.

Returns:
The number of attributes printed.
ImageCollection.distinct(*args)

Given in input a name of a metadata attribute, the distinct method returns a python list containing the distinct values of the attribute for all the selected images of the ImageCollection instance. To have a list of all the available metadata attributes for a specific ImageCollection, the method ImageCollection.printAttributes() can be called.

Args:
  • AttributeName (string): The name of the metadata attribute whose values have to be returned (optional, defaut = “id”)
Returns:
A python list.
ImageCollection.printBandNames()

Prints the list of all available band names for the ImageCollection.

Returns:
The number of band names printed.
ImageCollection.getAcquisitionDays()

Returns the ordered list of all acquisition days of the selected images inside the collection.

Returns:
A python list of strings in “YYYY-MM-DD” format.
ImageCollection.process(BandName=None)

Creates an instance of ImageProcess from the collection. The created object can be used to perform processing operations (like mask, combine, filter, etc.) and then visualize it adding a new layer to the Map.

Args:
  • BandName (string): name of the band (optional).
Returns:
An instance of an ImageProcess class that contains the images selected by the ImageCollection object
ImageCollection.processMulti(*args)

Creates a multi-band instance of ImageProcess from the collection. The created object can be used to perform processing operations (like mask, combine, filter, etc.) and then visualize it adding a new layer to the Map.

Args:
  • BandList (python List of strings): list containing the names of the bands to select from the collection to create the multi-band ImageProcess.
Returns:
An instance of a multi-band ImageProcess class that contains the images selected by the ImageCollection object
Example:

The following code shows a typical usage of processMulti for a Sentinel-2 image collection.

Select Sentinel-2 images covering Lombardia region:

coll = inter.ImageCollection("S2")
coll = coll.filterOnGeoName("Lombardia", 0, "IT")
coll = coll.filterOnDate(2018,1,1, 2018,4,30)
coll = coll.filterOn("cloudcover", "<=", 5)
coll = coll.filterOn("jrc_filepath", "<>", "")
coll = coll.filterOn("mgrs","like","32TNR")
coll.removeOverlap()
coll.sort("cloudcover",True)
coll.limit(10)

Create a 4-bands ImageProcess:

S2bands=["B02","B03","B04","B08"]

p = coll.processMulti(S2bands)

Selection methods

ImageCollection.limit(value)

Limits the number of results that the ImageCollection has to return.

Args:
  • value (integer): The maximum number of records to be returned
Returns:
A reference to the modified instance of ImageCollection (so that this method can be chained with other methods using the . syntax).
ImageCollection.sort(AttributeName, SortAscending=True)

Defines how to sort images that are currently selected inside the image collection. Any of the metadata attributes listed by the ImageCollection.printAttributes() can be used to sort the images.

Args:
  • AttributeName (string): The name of the metadata attribute on which the selected images have to be sorted.
  • SortAscending (boolean): True if the sort has to be done in ascending mode, False if in descending mode (optional, default = True)
Returns:
A reference to the modified instance of ImageCollection (so that this method can be chained with other methods using the . syntax).
ImageCollection.expandToScenes(flag=True)

Sets or resets the flag that controls the expansion of selection to the entire scene. For collections that have the concept of scene/tile (or product/granule) when the flag is set to True and an image is selected, the entire scene is automatically selected.

Args:
  • flag (boolean): True if the selection has to be expanded to scenes, False otherwise (optional, default = True)
Returns:
A reference to the modified instance of ImageCollection (so that this method can be chained with other methods using the . syntax).
Notes:
Only few ImageCollections implement the flag. For instance, Sentinel 2 products delivered before 2017 could have many granules inside: in this case the expandToScene method can be used.
ImageCollection.removeOverlap(flag=True)

Sets or resets the flag that controls if the visualization system should try to remove images that overlap and that would not be visible because other images are displayed on top of them. The method is implemented only by Sentinel 2 ImageCollection and is based on the MGRS code. Selected images are displayed in the inverse order defined by sort: the images that appear fisrt in the selection are displayed as last so that they “cover” other images on the selection. If other images on the list have the same MGRS code they are not displayed to gain a better performance.

Args:
  • flag (boolean): True if the remove overlap has to be activated, False otherwise (optional, default = True)
Returns:
A reference to the modified instance of ImageCollection (so that this method can be chained with other methods using the . syntax).
Notes:
Use with care: if an image is sorted first in the selection but covers only partially the MGRS tile, then an empty area will be visible.
ImageCollection.filterOnPoint(Longitude, Latitude, BufferDistance=0.0)

Filters the ImageCollection on the base of a geographic location. All the images that contain the point (within the specified buffer distance) are selected.

Args:
  • Longitude (float): Longitude of the point in degrees
  • Latitude (float): Latitude of the point in degrees
  • BufferDistance (float): Amount in degrees to enlarge. If the BufferDistance is greater then 0.0, a square is built having the point at its center and as side two times the buffer distance: the containment test is done using ImageCollection.FilterOnRect() (optional, default = 0.0).
Returns:
A reference to the modified instance of ImageCollection (so that this method can be chained with other methods using the . syntax).
ImageCollection.filterOnRect(minLongitude, minLatitude, maxLongitude, maxLatitude)

Filters the ImageCollection on the base of a geographic rectangle. All the images that have intersection with the rectangle are selected. Rectangle coordinates have to be written in degrees.

Args:
  • minLongitude (float): minimum longitude of the rectangle in degrees.
  • minLatitude (float): minimum latitude of the rectangle in degrees.
  • maxLongitude (float): maximum longitude of the rectangle in degrees.
  • maxLatitude (float): maximum latitude of the rectangle in degrees.
Returns:
A reference to the modified instance of ImageCollection (so that this method can be chained with other methods using the . syntax).
ImageCollection.filterOnDate(*args)

Filters the ImageCollection on the base of date range. All the images that have been acquired inside the date range are selected.

Args:

Dates that define the range can be specified using three integers for year, month, day or using a string format like “YYYY-MM-DD”.

  • Dates defined using integers:

    • minYear (integer): year of the minimum date of the range.
    • minMonth (integer): month of the minimum date of the range.
    • minDay (integer): day of the minimum date of the range.
    • maxYear (integer): year of the maximum date of the range.
    • maxMonth (integer): month of the maximum date of the range.
    • maxDay (integer): day of the maximum date of the range.

  • Dates defined using strings:

    • minDate (string): minimum date of the range in format “YYYY-MM-DD”.
    • maxDate (string): maximum date of the range in format “YYYY-MM-DD”.
Returns:
A reference to the modified instance of ImageCollection (so that this method can be chained with other methods using the . syntax).
Examples:

Defining a date range using integers:

coll = inter.ImageCollection("S2")
coll = coll.filterOnDate(2015,1,1, 2016,12,31)

Defining a date range using strings:

coll = inter.ImageCollection("S2")
coll = coll.filterOnDate("2015-01-01", "2016-12-31")
ImageCollection.filterOnDay(*args)

Filters the ImageCollection on the base of specific date. All the images that have been acquired on that day are selected.

Args:

Date can be specified using three integers for year, month, day or using a string format like “YYYY-MM-DD”

  • Day defined using integers:

    • Year (integer): year of acquisition
    • Month (integer): month of acquisition
    • Day (integer): day of acquisition

  • Day defined using a string:

    • Date (string): acquisition day in format “YYYY-MM-DD”
Returns:
A reference to the modified instance of ImageCollection (so that this method can be chained with other methods using the . syntax).
Examples:

Defining a day using integers:

coll = inter.ImageCollection("S2")
coll = coll.filterOnDay(2016,4,30)

Defining a day using a string:

coll = inter.ImageCollection("S2")
coll = coll.filterOnDay("2016-04-30")
ImageCollection.filterOn(AttributeName, Operator, Value)

Filters the ImageCollection on the values of a metadata attribute. All the images that satisfy the selection clause are selected. To have a list of all the available metadata attributes for a specific ImageCollection, the method ImageCollection.printAttributes() can be called.

Args:
  • AttributeName (string): The name of the metadata attribute to use for selection
  • Operator (string): Comparison operator, can be “=”, “<”, “<=”, “>”, “>=”, “LIKE” etc.
  • Value (string, integer or float depending on the attribute data type): Value to use in the selection clause
Returns:
A reference to the modified instance of ImageCollection (so that this method can be chained with other methods using the . syntax).
Example:

Selecting all images with a cloud cover less than 5 percent:

coll = inter.ImageCollection("S2")
coll = coll.filterOn("cloudcoverpercentage", "<=", 5)
ImageCollection.filterOnGeoName(Name, BufferDistance=0.0, Country='')

Filters the ImageCollection on the intersection with the extents of a named location (as returned by the online service GeoNames). All the images that intersect the named location area are selected.

Args:
  • Name (string): The name of the location to search for.
  • BufferDistance (float): Amount in degrees to enlarge from the extents returned by GeoNames online service (optional, default = 0.0).
  • Country (string): International two letters country code to use in case of names present in different countries (optional, default = “”).
Returns:
A reference to the modified instance of ImageCollection (so that this method can be chained with other methods using the . syntax).
Example:

Selecting all images on the area of Munich (DE):

coll = inter.ImageCollection("S2")
coll = coll.filterOnGeoName("Munchen", 0, "DE")

Custom collection management

ImageCollection.getCustom()

Returns the JSON representation of the ImageCollection instance that can be used to create a custom collection using ImageCollection.setCustom() method.

Returns:

A string containing the JSON representation of the ImageCollection instance.

Sample result: {“size”: 7, “values: “PHYS” | “CAT”, “0”: {“path”: ……, “bnames”:[“B01”,”B02”,”B03”,”B04”,”B05”,”B06”,”B07”,”B08”,”B8A”,”B09”,”B10”,”B11”,”B12”], “ext”:”tif”, “nbands”:13, “type”: “SB”|”MB”, “bands”: {“B01”: {“mean”: 5946.72, “stddev”: 1781.67}, “B02”: {“mean”: 5803.18, “stddev”: 1748.18}, … }, “epsg”: 4326, “nodata”: 0.0, “xmin”: …, “ymin”: …, “xmax”: …, “ymax”: …, “over”: “YES” | “NO” }, “1”: … }

  • PHYS means Physical values (statistics on bands have to be calculated)
  • CAT means Categorical values
  • SB means SingleBand files (e.g. Sentinel2)
  • MB means MultipleBand files (e.g. Single tiff with more bands inside the same file)
ImageCollection.setCustom(strJSON)

Changes the ImageCollection to become a ‘’CUSTOM’’ ImageCollection by setting all the internal members to the information read from the JSON string passed as argument. The string can be constructed manually by the user or obtained from a call to ImageCollection.getCustom() method.

Args:
  • strJSON (string): The JSON representation of the custom collection
Returns:
True if the interpretation of the string was successful, False otherwise.
Note:

A typical JSON representation of an ImageCollection object follows:

Sample result: {“size”: 7, “values: “PHYS” | “CAT”, “0”: {“path”: ……, “bnames”:[“B01”,”B02”,”B03”,”B04”,”B05”,”B06”,”B07”,”B08”,”B8A”,”B09”,”B10”,”B11”,”B12”], “ext”:”tif”, “nbands”:13, “type”: “SB”|”MB”, “bands”: {“B01”: {“mean”: 5946.72, “stddev”: 1781.67}, “B02”: {“mean”: 5803.18, “stddev”: 1748.18}, … }, “epsg”: 4326, “nodata”: 0.0, “xmin”: …, “ymin”: …, “xmax”: …, “ymax”: …, “over”: “YES” | “NO” }, “1”: … }

  • PHYS means Physical values (statistics on bands have to be calculated)
  • CAT means Categorical values
  • SB means SingleBand files (e.g. Sentinel2)
  • MB means MultipleBand files (e.g. Single tiff with more bands inside the same file)
Example:

A custom collection can be built by creating a string containing a JSON representation of the collection, like in the following code:

jstr = '{"size": 1, "values": "CAT", "0": {"epsg": 4326, "path":"/eos/jeodpp/data/base/Soil/GLOBAL/HWSD/VER1-2/Data/GeoTIFF/hwsd.tif"} }'
cust = inter.ImageCollection("CUSTOM")
cust.setCustom(jstr)

or by getting the JSON string from another instance of ImageCollection (and possibly modyfing it)