Syntax_Extract
Specify extraction of optical calibration data for file database_mN.cal

back to Help


 
1 - NO NEED for field data, nor for atmospheric correction
2 - this is demonstrated in this website, using a variety of hyper/multi spectral data
 
Requirements are
1 - homogeneous water body and atmosphere
2 - some coverage of optically deep water
3 - some coverage of dry land
 
Problems are
1 - the precision on estimated depth is found wanting, because the noise-equivalent change in radiance  of accessible data is too high for shallow water column correction work 
2 - radiance data should be preprocessed by the provider at level 1 in order to improve S/N ratio
3 - exponential decay: the deeper/darker the bottom, the poorer the performances
 
So
I keep digging
until suitable data
become available
 


Syntax_Extract
HowTo Extract BPL
HowTo Extract Soil Line

  • -Extract/v/rawBDH/FullBDH/MapBPL/NIRband3/NIRmax255/mBPL3/mask_3
  • -Extract  (without any argument) is the default:
    • all specifications are taken from the default file 4sm.def
  • V(v)
    •  default is silent mode
  • RawBDH
    • default is RawBDH
    • RawBDH .........shall collect raw            marine data for the  bidimensional histograms
    • rawBDH ..........shall collect deglinted    marine data for the  bidimensional histograms
  • FullBDH     for bidimensional histograms
    • FullBDH is the default to collect land and marine pixels
    • fullBDH to collect only marine pixels
  • M(m)apBPL to map BPL pixels for each pair in three U8 channels
  • NIRband_3 default=bands, as usually there  is only one NIR band in multispectral images
    • NIRband=23 usefull when several NIR bands are available in hyperspectral images, as NIR bands with wavelength >850 nm exhibit poor glint correlation
  • NIRmax5.0   default is dLsNirBPL=5 DNs over Lswnir              
    • shall collect BPL pixels which exhibit Lsnir>=Lswnir+NIRmax
    • pixels with Lsnir>Lswnir+ 5 shall not be considered for making up the Brightest_Pixels_Line:
      • this prevents heavily glinted very shallow pixels from showing up in the BPL.
    • this threshold can be set to any desired value:
      • for example, by specifying NIRmax255, then all shallow pixels shall be considered for BPL.
  • mBPL5   default is mBPL=2 to collect BPL pixels which are mapped over the 2-20 range in special effect mask mSE, i.e. pixels with mSE==1 shall be skipped
    • mBPL_5 shall collect BPL pixels which are mapped over the 5-20 range in special effect mask mSE
      • i.e. pixels  which are mapped over the 1-4 range in the mSE mask shall not be considered for making up the Brightest_Pixels_Line.
      • all pixels with 5<=mSE<=20 shall be considered.
      • this way of segmenting shallow areas allows to avoid some unwanted areas.
  • mSOIL21   default is mSOIL=21
    • Soil pixels_masked_at_mSOIL=21 shall be read to make up a Soil Line.
    • Note that 4SM shall also prepare two other soil lines
  • mask_3    default is that no mask is used
NOTE: if the  -deglint.... argument is not available,
  • deglinting of shallow calibration data cannot occur
  • this tends to blurr the exponential decay: best is to allow deglinting of calibration data!
  • NO DEGLINTING is applied to pixels selected for the BPL based on the NIR band
-Extract shall iterate on all [bi][bj] combinations of bands
  • Three Soil Lines: extracts three different Soil Lines:
    • AvmSOIL[c][dn].......SL by mSOIL....an average of land pixels masked under mSE=mSOIL
    • AvSoilDPL[c][dn].....SL by DPL........an average DPL
    • AvSoilNIR[c][dn]......SL by NIR........an average inside a cone of +/-CSL for the Red/Nir pair
  • Writes a calibration data textfile
    • either.....named  image_m0.cal  if no Mask was specified
    • or..........named  image_mN.cal  if Mask_N was specified



How to Extract BPL and DPL
Syntax_Extract

HowTo Extract BL
HowTo Extract Soil Line
  • The -deglint argument is disabled by default: no deglinting upon extraction of calibration data
    • except in the AutoCAL process if a glint.shp shapefile is available
  • The Smooth and Smart options are used as/if enabled. Smoothing is advised, but be wise.
  • Some shallow areas may need to be avoided as follows:
    • mSE and mBPL : this may be achieved through the mBPL parameters in the -Extract argument.
      • Any pixel with a value of mSE<mBPL is skipped upon the extraction of BPL data
      • Any pixel with a value of mSE>=mBPL and mBPL<mSOIL is considered in the extraction of BPL data.
      • for example, if you set BPL at 2, and mSOIL at 21 all pixels with mSE>=2 and mSE<=20 are considered, and all pixel with mSE<2 or mSE>=21 are bypassed
    • Mask : alternatively, by enabling the Mask_N option in in the -Extract... argument, all pixels with mSE in the range N-21 are considered for BPL, while all others are bypassed
      • for example, with Mask_3: only pixels with mSE==3 through to mSE=20 are considered, all others are bypasseded.
BPL   Brightest Pixels Line

For each pair of bands, the BPL is made of all pixels that are brightest in band i for each DN in band j
  • The BPL may be seen as the outer envelope of the shallow pixels exponential bulge
  • It intends to sample the brightest type of bottom substrate that is present across the whole range of bottom detection. tmnov_how_nice_x12
  • LsNirMaxBPL : in order to prevent selecting heavily glinted pixels in pairs which do not involve the NIR band, a NIR threshold is applied through the LsNirMaxBPL  parameter   of the -Extract argument
  • A value of LsNirMaxBPL=5 above Lsw niris usually recommended
    • this is to ensure that pixels which are badly damaged by glint  effect are discarded
DPL   Darkest Pixels Line

For each pair of bands, the DPL is made of all pixels that are darkest in band i for each DN in band j
  • For an image with dryland exposure, most Darkest Pixels are at near null depth, from bright to dark
  • The DPL is extremely usefull for the determination of spectral La
  • For an image without any dryland exposure like an atoll submerged at high tide, the DPL, from bright to dark, is likely to represent pixels at a certain depth:
  • The DPL is also averaged into SL_DPL: see tarawa-subset-m0cal

Extraction window
  • A rectangular extraction window may be specified if desired at the end of the -Extract argument , so that the extraction of calibration data shall be limited to pixels inside that window extraction is strictly limited to shallow pixels with mSE=Mask
  • -extract/v/NIRband4/NIRmax5/mBPL_2/mSOIL_21/Mask_4 (this overrides the value specified for mBPL)
  • Mask_2:     ==> 4SM writes and shall read text file negril85.m2.cal
  • Mask_3:     ==> 4SM writes and shall read text file negril85.m3.cal
  • Mask_N:    ==> 4SM writes and shall read text file negril85.mN.cal
Upon calibration : don't get mixed up

if Mask_N is specified (1>=N<mSOIL)

4SM shall read negril85.mN.cal

else

4SM  shall read negril85.m0.cal


See How to read calibration data textfile

 

Look at the location of BPL pixels
in the tarawa-subset image
They are mapped in channels 15, 16 and 17 by the Extraction process

see tarawa-subset

pair 12 in channel 15
 

pair 13 in channel 16

 

pair 23 in channel 17

 


Here is a color composite of these three pairs of BPL

 


  


How to Extract Soil Line

The Soil Line is the radiometric model for bare land pixels (~= null depth)
It helps to settle for spectral atmospheric path radiance La
caicostm Soil Line                             tmnov how nice x12
  • SL_SOIL : pixels under the mSE code equal to mSOIL are used for the computation of an average spectral Soil Line
  • SL_DPL : by default, 4SM also prepares an alternate spectral Soil Line using all DPL pixels for all pairs
  • SL_NIR : by default, 4SM also prepares an alternate spectral Soil Line using LsM and La as follows:
    • in the Red-Nir pair, the variables LsM redand LsM nirfor a very bright beach, La redand La nirfor a black body on the beach make up the theoretical Soil Line for that pair, with a certain SLOPE
    • this is fairly straightforward, as La=Lsw for those wavebands
    • all pixels with a slope of less than SLOPE*CSL and more than SLOPE/CSL may be assumed to be non-vegetated and at null depth
    • a value of CSL=1.18 is recommendedthe average spectral properties of this selection of pixels in other pairs of bands may be used to prepare the spectrale Soil Line