getOC

Bulk download Ocean Color images from ESA and NASA platforms.

getOC is a python utility simplifying bulk download of Ocean Color images from NASA Ocean Data and ESA COPERNICUS Dataspace APIs. getOC takes as input a csv file with the list of positions and dates of interest (ex: test.csv) and it downloads images for the selected instrument, processing level, and product type. Depending on the options selected an EARTHDATA or a COPERNICUS dataspace account is required. A strong internet connection is recommended.

Synthax for ESA satellite collections can be found here (example for Sentinel-3 collection)

DEPRECATED: Previous getOC versions used the Creodias API but the Creodias v2 API required 2 step authentications preventing automatic downloads. ESA satellites (+Landsat over europe) are now downloaded using the new Copernicus API

If you only need to download images in a given time frame without specifying a position, the File Search utility from NASA might be a better tool. The NASA utility also provides a few wget examples on this Ocean Color Forum Post.

Supported instrument

| Instrument Name | Instrument Acronym | Temporal Coverage | Spatial Coverage | Level | L2 Product | | --- | --- | --- | --- | --- | --- | | Coastal Zone Color Scanner (CZCZ) | CZCZ | 1978-1986 | global@1km | L1A, L2, L3m | OC | | Ocean Color Temperature Sensor (OCTS) | OCTS | 1996-1997 | global@700m | L1A, L2 | OC | | Sea Viewing Wide Field Scanner (SeaWiFS) | SeaWiFS | 1997-2010@daily | global@1.1km | L1A, L2, L3m | OC | | Moderate Resolution Imaging Spectroradiometer (MODIS, Terra) | MODIS-Terra | 1999-now@daily | global@0.25,0.5,1km | L1A, L2, L3m | OC | | Moderate Resolution Imaging Spectroradiometer (MODIS, Aqua) | MODIS-Aqua | 2002-now@daily | global@0.25,0.5,1km | L1A, L2, L3m | OC, SST | | MEdium Resolution Imaging Spectrometer (MERIS, Full/Reduced Resolution) | MERIS-FR, MERIS-FR | 2002-2012@daily | global@300m-1km | L1, L2 | OC | | Geostationary Ocean Color Imager (GOCI) | GOCI | 2010-now@hourly | 36ºN 130ºE@500m | L1B, L2 | OC | | Visible Infrared Imaging Radiometer Suite (VIIRS, Suomi NPP) | VIIRSN | 2011-now@daily | global@1km | L1A, L2, L3m | OC, SST | | Visible Infrared Imaging Radiometer Suite (VIIRS, JPSS-1) | VIIRSJ1 | 2017-now@daily | global@1km | L1A, L2, L3m | OC | | MultiSpectral Instrument (MSI, Sentinel-2A/B) | MSI | 2015-now@5days | coastal@10,20,60m | L1C, L2A | OC | | Ocean and Land Colour Instrument (OLCI, Sentinel-3A/B) | OLCI | 2016-now@daily | global@300m-1km | L1-EFR, L1-ERR, L2-WFR, L2-WRR, L2-LFR, L2-LRR | OC | | Sea and Land Surface Temperature Radiometer (SLSTR, Sentinel-3A/B) | SLSTR | 2016-now@daily | global@1km | L1-RBT, L2-WST, L2-LST, L2-AOD, L2-FRP | SST | | OLCI/SLSTR Synergy products (SYN, Sentinel-3A/B) | SYN | 2016-now@daily | global@1km | L2-SYN, L2-V10, L2-VG1, L2-VGP, L2-AOD | OC, SST | | SAR Radar Altimeter (SRAL, Sentinel-3A/B) | SRAL | 2016-now@daily | global@300m | L1-SRA, L1-SRA-A, L1-SRA-BS, L2-WAT, L2-LAN, L2-LAN-HY, L2-LAN-LY, L2-WAT-SI | OTHER (Altimeter) | | Synthetic Aperture Radar (SAR, Sentinel-1A/B) | SAR | 2014-now@12days | global@5m | L0-RAW, L1-GRD, L1-GRD-COG, L1-SLC, L2-OCN, L2-CARD-BS, L2-CARD-COH12 | OTHER (ice, fishing, and oil spill monitoring) | | Thematic Mapper (TM, Landsat-5) | L5-TM | 1984-2013@16days | Europe@30m-OC 120m-SST | L1G, L1T | OC, SST | | Enhenced Thematic Mapper Plus (ETM+, Landsat-7) | L7-ETM | 1999-2011@16days | Europe@30m-OC 120m-SST | L1G, L1GT, L1T, TC-1P | OC, SST | | Operational Land Imager (OLI) & Thermal Infrared Sensor (TIRS) (Landsat-8) | L8-OLI-TIRS | 2013-now@16days | Europe@30m-OC 100m-SST | L1, L1GT, L1T, L1TP, L2, L2SP| OC, SST |

Resolutions are indicative for Level 1 and 2 data, Level 3 is only available at 4 or 9 km for NASA satellites.

Command Line Usage

Typical call from bash:

python getOC.py -i VIIRSJ1 -l L2 <csv_filename> -u <earthdata-username> -w --box 60

Argument description:

• -i INSTRUMENT, --instrument=INSTRUMENT: specify instrument, available options are:
  • SeaWiFS
  • MODIS-Aqua
  • MODIS-Terra
  • OCTS
  • CZCS
  • MERIS
  • VIIRSN
  • VIIRSJ1
  • HICO
  • OLCI
  • SLSTR
  • SYN
  • SRAL
  • MSI
  • GOCI
  • L5-TM
  • L7-ETM
  • L8-OLI-TIRS
• -l LEVEL, --level=LEVEL: specify processing level, available options are listed below (c.f. table above for level compatible with the instrument selected).
  • MODIS-Aqua MODIS-Terra VIIRSN VIIRSJ1 SeaWiFS OCTS CZCS:
    
    • L1A
    • L2
    • L3b
    • L3m
  • OLCI:
    
    • L1-EFR full resolution or L1_ERR reduced resolution
      
    • L2-WFR full resolution or L2_WRR reduced resolution [Water]
      
    • L2-LFR full resolution or L2_LRR reduced resolution [Land]
      
  • SLSTR:
    
    • L1-RBT
    • L2_WST [Water temperature]
      
    • L2_LST [Land temprature]
      
    • L2_AOD [Aerosol optical depth]
      
    • L2_FRP [Fire radiative power]
      
  • SRAL:
    
    • L1-SRA
    • L1-SRA-A
    • L1-SRA-BS
    • L2-WAT [Water altimetry]
      
    • L2-LAN [Land altimetry]
      
    • L2-LAN-HY
    • L2-LAN-LY
    • L2-LAN-SI
  • SYN:
    
    • L2-SYN [Reflectance and aerosol parameter over land]
      
    • L2-V10 [Vegetation-Like product (~VGT-S10), 10 day synthesis surface reflectance and NDVI]
      
    • L2-VG1 [Vegetation-Like product (~VGT-S1), 1 day synthesis surface reflectance and NDVI]
      
    • L2-VGP [Vegetation-Like product (~VGT-P), TOA reflectance]
      
    • L2-AOD [Aerosol optical depth over land and water 4.5x4.5 km resolution]
      
  • MERIS:
    
    • L1
    • L2
    • L3b
    • L3m
  • SAR:
    
    • L0-RAW
    • L1-GRD
    • L1-GRD-COG
    • L1-SLC
    • L2-OCN
    • L2-CARD-BS
    • L2-CARD-COH12
  • GOCI:
    • L1B
    • L2
  • MSI:
    
    • L1C
    • L2A
• -u USERNAME, --username=USERNAME: specify username to login to Copernicus (for OLCI, SLSTR, SLAR, SAR, MSI, L5-TM, L7-ETM and L8-OLI-TIRS instruments) or EarthData (for any other sensor). Password will be prompted when the script is executed. (TO DO: add option to use a credential file credentials.ini)
  • Earthdata login for NASA satellites
    
  • Copernicus dataspace login for ESA satellites
• -w, --write-image-name: getOC first query an api to retrieve the list of images to download. The output of that query can be written to a csv file. getOC can then be restarted directly from that file saving that query time.
• -r, --read-image-list: getOC loads the list previously queried and printed, to avoid querying twice the same list

• -q, --quiet: Quiet please ! getOC does not output any information relative to the download and querying of the points of interest.

• -p product
  Specify the product type to download:

  • OC [default]
    
  • IOP
  • SST

Options specific to a level:

• Level 1 & 2:
  • --box=BOUNDING_BOX_SIZE, --bounding-box-size=BOUNDING_BOX_SIZE: Define the size of the bounding box around the point of interest in nautical miles. getOC downloads all images that intersect with this box (must be > 0).
• Level 2 & 3:
  • -p PRODUCT, --product=PRODUCT: Specify the product type to download (only for NASA satellites) (c.f. table above for level compatible with the instrument selected):
    • Level 2 (NASA):
      • OC (default)
      • IOP (deprecated)
      • SST
    • Level 3 (NASA):
      • CHL
      • POC
      • not tested: GSM, IOP, KD, LAND, PAR, PIC, QAA, RRS, and ZLEE
• Level 3: at this level the world's ocean is downloaded, getOC ignores the latitude and longitudes in the input csv file.
  • -b BINNING_PERIOD, --binning-period=BINNING_PERIOD: specify binning period (only for L3), available options are:
    • DAY (default)
    • 8D
    • MO
    • YR
  • --res=SRESOL, --spatial-resolution=SRESOL: specify spatial resolution (only for L3), available options are:
    • 4km (default)
    • 9km

Options specific to a downloading platform:

• ESA Copernicus downloads only:

  • -c CLOUD_COVER_INTERVAL, --cloud-cover=CLOUD_COVER_INTERVAL: Cloud cover interval to download (in %):
    • -c [0 100]: download all images [default]
    • -c [0 80]: download all images with less than 80% cloud cover
    • -c [0 20]: download all images with less than 20% cloud cover
    • ...

• NASA Ocean Color Level 1&2 Browser:

  • -d QUERY_DELAY, --delay=QUERY_DELAY: Delay between queries only needed to query L1L2_browser. (default=1 second)

Instruments specificity:

• VIIRS: GEO files required to process L1A files from that sensor are downloaded automatically when the level L1A is selected for this instrument.
• Level synthax for ESA satellites are specific to sensors providing different options: Use L1-EFR for OLCI full resolution data and L1-ERR for low resolution (cf table and level paragraph)

Examples:

Level 1:

python getOC.py -i MODIS-Aqua -l L1A test.csv -u <earthdata-username> -w --box 60
python getOC.py -i GOCI -l L1B test.csv -u <copernicus-username> -w --box 60 
python getOC.py -i VIIRSN -l L1A test.csv -u <earthdata-username> -w --box 60
python getOC.py -i VIIRSJ1 -l L1A test.csv -u <earthdata-username> -w --box 60
python getOC.py -i MSI -l L1C test.csv -u <copernicus-username> -w --box 60
python getOC.py -i OLCI -l L1-EFR test.csv -u <copernicus-username> -w --box 60
python getOC.py -i SLSTR -l L1-WST test.csv -u <copernicus-username> -w --box 60
python getOC.py -i SRAL -l L1-RBT test.csv -u <copernicus-username> -w --box 60
python getOC.py -i L5-TM -l L1T test.csv -u <copernicus-username> -w --box 60

Level 2:

python getOC.py -i MODIS-Aqua -l L2 test.csv -u <earthdata-username> -p OC -w --box 60
python getOC.py -i GOCI -l L2 test.csv -u <copernicus-username> -w --box 60
python getOC.py -i VIIRSN -l L2 test.csv -u <earthdata-username> -p OC -w --box 60
python getOC.py -i VIIRSJ1 -l L2 test.csv -u <earthdata-username> -p OC -w --box 60
python getOC.py -i MSI -l L2A test.csv -u <copernicus-username> -w --box 60 
python getOC.py -i OLCI -l L2-WRR test.csv -u <copernicus-username> -w --box 60
python getOC.py -i SLSTR -l L2-WST test.csv -u <copernicus-username> -w --box 60
python getOC.py -i SYN -l L2-AOD test.csv -u <copernicus-username> -w --box 60
python getOC.py -i L8-OLI-TIRS -l L2 test.csv -u <copernicus-username> -w --box 60

Level 3:

python getOC.py -i MODIS-Aqua -l L3b test.csv <earthdata-username> -p CHL -b 8D --res 4km -w
python getOC.py -i MODIS-Aqua -l L3m test.csv <earthdata-username> -p CHL -b YR --res 9km -w