Package noaa.coastwatch.tools

Class cwtccorrect

java.lang.Object
noaa.coastwatch.tools.cwtccorrect
public class cwtccorrect extends Object

The true color correction tool corrects top-of-atmosphere true color reflectance data.

Name

cwtccorrect - corrects top-of-atmosphere true color reflectance data.

Synopsis

cwtccorrect [OPTIONS] input [output]

General options:

-h, --help
-b, --bands=RED/GREEN/BLUE
-e, --esun=RED/GREEN/BLUE
-n, --nameext=TEXT
-p, --props=FILE
-s, --sensor=NAME
--threads=MAX
-v, --verbose
--version

Angle options:

-l, --latitude=VARIABLE
-L, --longitude=VARIABLE
-u, --sunzen=VARIABLE
-U, --sunazi=VARIABLE
-a, --satzen=VARIABLE
-A, --satazi=VARIABLE
-r, --relazi=VARIABLE

Description

The true color correction tool corrects top-of-atmosphere true color reflectance data. The correction accounts for molecular (Rayleigh) scattering and gaseous absorption (water vapor, ozone) but performs no aerosol correction (dust, ash, smoke, sulfate). No real-time input or ancillary data is required. The algorithm used was originally written by Jacques Descloitres for use with the MODIS Rapid Response Project, NASA/GSFC/SSAI.

The input file can be in either level 2 or level 3 projection, and must at a minimum contain:

  • Red, green, and blue color band data. By default these are found by looking for common variable names for a given sensor used in CoastWatch product files, or can be specified directly using the --bands option. Band data can either be in radiance units or reflectance units. If in radiance units, the data is first normalized to reflectance using a known solar irradiance value for the sensor band and solar zenith angle data.
  • Latitude and longitude geolocation data, and zenith and azimuth angles for both sun and satellite. By default the correct variables containing the angle data are detected from a combination of the variable names and the long name (if any) specified in the metadata. Note that if relative azimuth angle data is found, it will be used instead of the individal solar and satellite azimuth angles.

The result of the operation is to write a new set of band reflectance variables into the input file, or into a new output file, by appending '_refl' to the band variable names. The corrected surface reflectance is an approximation only, but is well suited for providing near real time true color imagery.

Parameters

Main parameters:

input
The input data file name.
output
The output data file name. If specified and the file does not already exist, it will be created using metadata from the input file. If it does exist, it will be opened and checked for a compatible earth transform and the new corrected reflectance data will be added to the file. The new variables must not already exist in the output file.

General options:

-h, --help
Prints a brief help message.
-b, --bands=RED/GREEN/BLUE
The names of the band variables to use for each of red, green, and blue wavelengths. By default when the sensor is known, the band names are automatically determined. Use this option to overrride the default band names, or in case the sensor is unknown.
-e, --esun=RED/GREEN/BLUE
Specifies the values of the solar irradiance (the esun constant) for each of the red, green, and blue wavelengths in mW/cm2/um. This is only needed when the data is in radiance units rather than reflectance units. By default when the sensor is known, the solar irradiance values are automatically determined. Use this option to overrride the default solar irradiance values, or in case the sensor is unknown.
-n, --nameext=TEXT
The text to use to extend the band variable names when creating the new corrected reflectance variables. By default '_refl' is used to extend the band variable names.
-p, --props=FILE
The path for a custom properties file giving the names of supported sensors and their bands and solar irradiance values. By default the true_color.properties file in the installation directory data/noaa/coastwatch/tools is used. The format of the properties file is a set of key/value pairs. For example to add the new Zork Visible Spectrum Imager aboard the satellite Frobozz-5 to the list of allowed sensors, you can create a new properties file as follows: 
     sensors = fbz5_zvsi

     fbz5_zvsi.keywords = frobozz-5 fbz-5 zvsi
     fbz5_zvsi.red.band = Band_3
     fbz5_zvsi.green.band = Band_2
     fbz5_zvsi.blue.band = Band_1
     fbz5_zvsi.red.esun = 150.072
     fbz5_zvsi.green.esun = 181.820
     fbz5_zvsi.blue.esun = 195.128
Then supply the new properties file path to the --props option. This helps to reduce the command line parameters needed to correct data for an unsupported sensor. Alternatively, you can also add the content above to the default true_color.properties file and the new sensor will be automatically detecting using the keywords.
-s, --sensor=NAME
The name of the sensor to use. This is normally determined automatically from the metadata, but if the automatic test fails, use this option. The currently supported sensors are 'n20_viirs', 'npp_viirs', 's2a_msi', 's2b_msi', 's3a_olci', and 's3b_olci'. The sensor name is used to determine the solar irradiance values and the band names for known sensors, and is not needed if both the --bands and --esun options are set.
--threads=MAX
Specifies the maximum number of threads for parallel processing. By default the program will automatically detect the maximum number of threads possible. To process data in serial, use a max value of 1.
-v, --verbose
Turns verbose mode on. The current status of data conversion is printed periodically. The default is to run quietly.
--version
Prints the software version.

Angle options:

-l, --latitude=VARIABLE
The latitude angle variable name, by default determined from metadata.
-L, --longitude=VARIABLE
The longitude angle variable name, by default determined from metadata.
-u, --sunzen=VARIABLE
The solar zenith angle variable name, by default determined from metadata.
-U, --sunazi=VARIABLE
The solar azimuth angle variable name, by default determined from metadata.
-a, --satzen=VARIABLE
The satellite zenith angle variable name, by default determined from metadata.
-A, --satazi=VARIABLE
The satellite azimuth angle variable name, by default determined from metadata.
-r, --relazi=VARIABLE
The relative azimuth angle variable name, by default determined from metadata. Note that relative azimuth is only needed if either the satellite azimuth or solar azimuth are not available.

Exit status

0 on success, > 0 on failure. Possible causes of errors:

  • Invalid command line option
  • Invalid input or output file names
  • Unsupported input file format
  • Input / output file dates or earth transforms do not match
  • Sensor not supported
  • Angle data could not be automatically detected

Examples

The following shows the true color correction of level 2 NOAA-20 VIIRS data with verbose mode on:

   phollema$ cwtccorrect -v VRSLCW.C2023001.102322.hdf 
     VRSLCW.C2023001.102322.corr.hdf
   [INFO] Opening input VRSLCW.C2023001.102322.hdf
   [INFO] Creating output VRSLCW.C2023001.102322.corr.hdf
   [INFO] Found supported sensors: [n20_viirs, npp_viirs, s2a_msi, s2b_msi, s3a_olci, s3b_olci]
   [INFO] Detected sensor 'n20_viirs'
   [INFO] Computing reflectance for red band 'EV_BandM5'
   [INFO] Using Earth-Sun distance factor 1.0169916, solar irradiance 151.096 mW/cm^2/um
   [INFO] Using variable 'sun_zenith' in reflectance computation
   [INFO] Total grid size is 768x3200
   [INFO] Using 12 parallel threads for processing
   [INFO] Processing 27 data chunks of size 362x362
   [INFO] Computing reflectance for green band 'EV_BandM4'
   [INFO] Using Earth-Sun distance factor 1.0169916, solar irradiance 182.753 mW/cm^2/um
   [INFO] Total grid size is 768x3200
   [INFO] Using 12 parallel threads for processing
   [INFO] Processing 27 data chunks of size 362x362
   [INFO] Computing reflectance for blue band 'EV_BandM3'
   [INFO] Using Earth-Sun distance factor 1.0169916, solar irradiance 197.808 mW/cm^2/um
   [INFO] Total grid size is 768x3200
   [INFO] Using 12 parallel threads for processing
   [INFO] Processing 27 data chunks of size 362x362
   [INFO] Using variable 'latitude' for latitude angle data
   [INFO] Using variable 'longitude' for longitude angle data
   [INFO] Using variable 'sun_zenith' for solar zenith angle data
   [INFO] Using variable 'sun_azimuth' for solar azimuth angle data
   [INFO] Using variable 'sat_zenith' for satellite zenith angle data
   [INFO] Using variable 'sat_azimuth' for satellite azimuth angle data
   [INFO] Computing atmospheric correction for true color bands
   [INFO] Total grid size is 768x3200
   [INFO] Using 12 parallel threads for processing
   [INFO] Processing 27 data chunks of size 362x362
 
   phollema$ cwinfo VRSLCW.C2023001.102322.corr.hdf
   Contents of VRSLCW.C2023001.102322.corr.hdf

   Global information:
     Satellite:           NOAA-20
     Sensor:              VIIRS
     Date:                2023/01/01 JD 001
     Start time:          10:23:22 UTC
     End time:            10:24:46 UTC
     Projection type:     swath
     Transform ident:     noaa.coastwatch.util.trans.SwathProjection
     Origin:              NOAA/NESDIS/STAR/SOCD
     Format:              CoastWatch HDF version 3.4
     Reader ident:        noaa.coastwatch.io.CWHDFReader
   
   Variable information:
     Variable         Type    Dimensions   Units     Scale   Offset   
     latitude         float   768x3200     degrees   -       -        
     longitude        float   768x3200     degrees   -       -        
     EV_BandM5_refl   float   768x3200     1         -       -        
     EV_BandM4_refl   float   768x3200     1         -       -        
     EV_BandM3_refl   float   768x3200     1         -       -
Since:
3.8.0
Author:
Peter Hollemans

  • Method Details

    • main

      public static void main(String[] argv)
      Performs the main function.
      Parameters:
      argv - the list of command line parameters.