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
  • if a Mask_N.shp is available, and a Mask_N is specified in the -Extract/... argument, then extraction shall occur only for pixels with mSE=N,
    • N is limited to the range 3-20
  • and calibration shall read image_mN.cal for calibration data textfile

• 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

• 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

• 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.

• 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

• 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:
  • this helps to decide on spectral La, like in the case of   DaviesReef       DaviesReefCalibration   
• The DPL is also averaged into SL_DPL: see tarawa-subset-m0cal

• 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

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

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