topomask - Computes topography-dependent surface temperatures and optional cloud mask, using IR channel and geopotential profiles

SYNOPSIS

topomask  [ parameter=value ]  [ inputfile outputfile ]

Parameters are:   TBB_variable, climatology, mask_clouds, topo_set, topo_var, delta_temp, min_sea_temp, temprof_set, geoprof_set, surface_set, temprof_var, geoprof_var, pressprof_var, surface_var.
 

DESCRIPTION

topomask  allows for the estimation of expected land surface temperatures by extrapolating geopotential temperature profiles to local surface elevations for every pixel in a geo-locatable input image background defined by variable TBB_variable. topomask creates an output dataset with a variable surface_temp containing estimated surface temperatures for the date specified with the TBB_variable input data, as well as  an optional cloud mask cloud, which is calculated for the same input brightness temperature IR channel image in TBB_variable.

The topomask output product variable surface_temp provides a useful reference dataset for cloud-masking purposes over land. Over oceans, prevailing sea-surface  temperatures must be expected to differ  substantially from extrapolations of geopotential profiles to sea-level;  however in all instances, variations of  surface-temperature are related to extrapolated (to surface elevation) atmospheric  temperature profile variations, so that the output product variable surface_temp remains useful as an aid in estimating an expected range of temperature variations, such as temperature standard deviations, for many land and ocean instances.

Required inputs include a master background dataset which provides a temperature variable TBB_variable and  an earth-transform for geolocation, a topography dataset topo_set the default for which is provided by TeraScan  in $REFDATA/bathy/etop05, and geopotential height/temperature profiles such as a climatology or forecast model output profiles, the default being the climatology provided by TeraScan in $REFDATA/climate/geopclim.tdf, tempclim.tdf.
 

PARAMETERS

TBB_variable

Name of input TBB brightness temperature variable.  No default.
 

climatology

Parameter to enable using climatology profiles for elevation dependent temperature assignments. The default climatology dataset (provided by TeraScan in $REFDATA/climate/geopclim.tdf, tempclim.tdf) contains 12 months of monthly averaged profiles, derived from the NCEP/NCAR Reanalysis.  Setting climatology="no" permits specifying (an)other  model profile dataset(s), temprof_set, geoprof_set, surface_set, etc..., in lieu of the default climatology.  The default is climatology="yes".
 

mask_clouds

Parameter to enable/disable cloud mask calculations for the output variable cloud.  The cloud mask is calculated by comparing input TBB image values with the calculated expected surface temperature mask surface_temp; values lower than the expected surface temperature in surface_temp minus delta_temp are categorized as cloudy. Setting mask_clouds="yes" creates the output variable cloud, which is a byte variable containing 1 for cloudy pixels, 0 for clear pixels, and GP_BAD_BYTE for undefined/bad pixels.  The default is mask_clouds="no".
 

topo_set

Parameter for specifying the name of the TeraScan dataset containing applicable topography data. The dataset must have a geolocated variable topo_var containing elevation data for the geolocation of interest. The default is topo_set="$REFDATA/bathy/etop05".
 

topo_var

Parameter for specifying the name of the variable in the TeraScan dataset topo_set containing applicable topography data. The units should be the same as the height units associated with the climatology or other geopotential height/temperature profiles, preferably meters. The default is topo_var="elevation".  (See $REFDATA/bathy/etop05)
 

temprof_set

Relevent only if climatology="no" (default) was specified. Parameter for specifying the name of the dataset containing model temperature profiles. The default is temprof_set="".
 

geoprof_set

Relevent only if climatology="no" (default) was specified. Parameter for specifying the name of the dataset containing model geopotential height profiles. The default is geoprof_set="".
 

surface_set

Relevent only if climatology="no" (default) was specified.   Parameter for specifying the name of the dataset containing model surface temperature data. The default is surface_set="".
 

temprof_var

Relevent only if climatology="no" (default) was specified.   Parameter for specifying the name of the temperature variable in model temperature profiles.  The default is temprof_var="".
 

geoprof_var

Relevent only if climatology="no" (default) was specified.   Parameter for specifying the name of the geopotential height variable in model geopotential profiles.   The default is geoprof_var="".
 

pressprof_var

Relevent only if climatology="no" (default) was specified.   Parameter for specifying the name of the pressure level variable in model profiles.  The default is geoprof_var="".
 

surface_var

Relevent only if climatology="no" (default) was specified.   Parameter for specifying the name of the surface temperature variable in profile datasets, especially surface_set.   The default is surface_var="".
 

seasurf_var

Relevent only if climatology="no" (default) was specified.   Parameter for specifying the name of the sea surface temperature variable in profile datasets, especially surface_set.   The default is seasurf_var="".
 

delta_temp

Specifies an error tolerance, in celsius, between calculated and observed surface-temperatures, defining a relative threshold for temperature-based cloud-detection. Image data pixels colder than the estimated/calculated TBB minus the delta_temp value are unconditionally classified cloudy in the associated output cloud mask cloud.  delta_temp is relevent only if mask_clouds="yes".   The default is delta_temp=10 deg. C.
 

min_sea_temp

Specifies a minimum expected sea-surface temperature, in celsius, for unconditionally distinguishing clouds over ocean, for the associated output cloud mask cloud. min_sea_temp is relevent only if mask_clouds="yes".    The default is dmin_sea_temp="-2" deg. C.

EXAMPLES

In this example, an AVHRR image dataset input is processed to generate the surface_temp and cloud output products.
 

% topomask

in/out files   : char(255) ? testdata0  testdata0.topomask

TBB_variable   : char(255) ? avhrr_ch4

climatology    : char(  3) ? [no] y

mask_clouds    : char(  3) ? [no] y

topo_set       : char(255) ? [/opt/terascan/refdata/bathy/etop05]

topo_var       : char(255) ? [elevation]

delta_temp     : int       ? [10] 5

min_sea_temp   : int       ? [-2]

Generating temperature mask for ../testdata0

 processing line  0 ...

 processing line  50 ...

 processing line  100 ...

 processing line  150 ...

 processing line  200 ...

 processing line  250 ...

 processing line  300 ...

 processing line  350 ...

 processing line  400 ...

 processing line  450 ...

./testdata0.topomask: Completed

% contents testdata0.topomask

printout       : char(  3) ? [no]

Contents of File: testdata0.topomask    Page 1

Dimension         Size    Coord         Scale      Offset    Variable

 line               500    y                1           0

 sample             800    x                1           0

Attribute       Type            Units           Value

 projection      long                            2

 et_affine       double                          -0.125 0 0 0.125 250.5 400.5

 satellite       string12                        noaa-14

 sensor          long            std_sensor      avhrr

 pass_date       long            std_date        1998/10/19

 start_time      double          std_time        21:50:13.14

 time_adjust     double          std_time        00:00:00

 attitude        double          radians         0 0 0

 sensor_tilt     double          radians         0

 scan_samples    long                            2048

 scan_rates      double                          6 40000 37.6991

 miss_algn_mat   double                          1 0 0 0 1 0 0 0 1

 use_orbele      long            boolean         1

 orb_elements    double                          0.839306 0.828365 0.00018 0.0009653 0.0175866 0.621812 0.275158

 sensorient      double          radians         0 0.785398 0 0.965167 -0.965167

 orb_elem_date   long            std_date        1998/10/16

 orb_elem_time   double          std_time        00:00:00

 interp_points   long                            4

 scan_time       double          seconds         -600 1800 4200 6600

 sensor_tilt_arr double          radians         0 0 0 0

 sensor_twist    double          radians         0 0 0 0

 satellite_roll  double          radians         0 0 0 0

 satellite_pitch double          radians         0 0 0 0

 satellite_yaw   double          radians         0 0 0 0

 nutation_mat    double                          1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1

 center_lat      double          std_latitude    35  0.00 N

 center_lon      double          std_longitude   130  0.00 W

 map_angle       double          radians         0

 proj_param      double          std_latitude     0  0.00 N

 equator_radius  double          km              6378.14

 flattening      double                          0.00335281

 projection_name string16                        rectangular

 history         byte

Variable        Type            Units

 cloud           byte            -

 surface_temp    double          celsius

Variable        Dimension       Size

 cloud           line             500

 cloud           sample           800

 surface_temp    line             500

 surface_temp    sample           800

Variable            BadValue    ValidMin    ValidMax       Scale      Offset

 cloud                   255           0         255           1           0

 surface_temp    -3.4028e+38 -1.7977e+308 1.7977e+308          1           0

SEE ALSO

avcloud, cloudmask_script, cloudprod

REFERENCES

Last Update: $Date: 2000/12/12 01:10:28 $