8.1.5. segment

class hs_process.segment(spyfile)[source]

Bases: object

Class for aiding in the segmentation and/or masking of image data to filter out pixels that are of least interest.

Methods Summary

band_math_derivative([wl1, wl2, wl3, b1, …])

Calculates a derivative-type spectral index from two input bands and/or wavelengths.

band_math_mcari2([wl1, wl2, wl3, b1, b2, …])

Calculates the MCARI2 (Modified Chlorophyll Absorption Ratio Index Improved; Haboudane et al., 2004) spectral index from three input bands and/or wavelengths.

band_math_ndi([wl1, wl2, b1, b2, spyfile, …])

Calculates a normalized difference spectral index from two input bands and/or wavelengths.

band_math_ratio([wl1, wl2, b1, b2, spyfile, …])

Calculates a simple ratio spectral index from two input band and/or wavelengths.

composite_band([wl1, b1, spyfile, …])

Calculates a composite band from a range of bands or wavelengths.

load_spyfile(spyfile)

Loads a SpyFile (Spectral Python object) for data access and/or manipulation by the hstools class.

Methods Documentation

band_math_derivative(wl1=None, wl2=None, wl3=None, b1=None, b2=None, b3=None, spyfile=None, list_range=True, print_out=True)[source]

Calculates a derivative-type spectral index from two input bands and/or wavelengths. Bands/wavelengths can be input as two individual bands, two sets of bands (i.e., list of bands), or range of bands (i.e., list of two bands indicating the lower and upper range).

Definition:

array_der = (wl1 - wl2) / (wl2 - wl3)

Parameters
  • wl1 (int, float, or list) – the wavelength (or set of wavelengths) to be used as the first parameter of the derivative index; if list, then consolidates all bands between two wavelength values by calculating the mean pixel value across all bands in that range (default: None).

  • wl2 (int, float, or list) – the wavelength (or set of wavelengths) to be used as the second parameter of the derivative index; if list, then consolidates all bands between two wavelength values by calculating the mean pixel value across all bands in that range (default: None).

  • wl3 (int, float, or list) – the wavelength (or set of wavelengths) to be used as the third parameter of the derivative index; if list, then consolidates all bands between two wavelength values by calculating the mean pixel value across all bands in that range (default: None).

  • b1 (int, float, or list) – the band (or set of bands) to be used as the first parameter of the derivative index; if list, then consolidates all bands between two band values by calculating the mean pixel value across all bands in that range (default: None).

  • b2 (int, float, or list) – the band (or set of bands) to be used as the second parameter of the derivative index; if list, then consolidates all bands between two band values by calculating the mean pixel value across all bands in that range (default: None).

  • b3 (int, float, or list) – the band (or set of bands) to be used as the third parameter of the derivative index; if list, then consolidates all bands between two band values by calculating the mean pixel value across all bands in that range (default: None).

  • spyfile (SpyFile object or numpy.ndarray) – The datacube to process; if numpy.ndarray or None, loads band information from self.spyfile (default: None).

  • list_range (bool) – Whether bands/wavelengths passed as a list is interpreted as a range of bands (True) or for each individual band in the list (False). If list_range is True, b1/wl1 and b2/wl2 should be lists with two items, and all bands/wavelegths between the two values will be used (default: True).

  • print_out (bool) – Whether to print out the actual bands and wavelengths being used in the NDI calculation (default: True).

Returns

2-element tuple containing

  • array_der (numpy.ndarray): Derivative band math array.

  • metadata (dict): Modified metadata describing the derivative array (array_der).

Example

Load hsio and segment modules

>>> import numpy as np
>>> import os
>>> from hs_process import hsio
>>> from hs_process import segment
>>> data_dir = r'F:\nigo0024\Documents\hs_process_demo'
>>> fname_in = os.path.join(data_dir, 'Wells_rep2_20180628_16h56m_pika_gige_7-Radiance Conversion-Georectify Airborne Datacube-Convert Radiance Cube to Reflectance from Measured Reference Spectrum.bip.hdr')
>>> io = hsio(fname_in)
>>> my_segment = segment(io.spyfile)

Calculate the MERIS Terrestrial Chlorophyll Index (MTCI; Dash and Curran, 2004) via segment.band_math_derivative

>>> array_mtci, metadata = my_segment.band_math_derivative(wl1=754, wl2=709, wl3=681, spyfile=io.spyfile)
Band 1: [176]  Band 2: [154]  Band 3: [141]
Wavelength 1: [753.84]  Wavelength 2: [708.6784]  Wavelength 3: [681.992]
>>> array_mtci.shape
(617, 1300)
>>> np.nanmean(array_mtci)
9.401104

Show MTCI image via hsio.show_img

>>> io.show_img(array_mtci, vmin=-2, vmax=15)
api/img/segment/mtci.png
band_math_mcari2(wl1=None, wl2=None, wl3=None, b1=None, b2=None, b3=None, spyfile=None, list_range=True, print_out=True)[source]

Calculates the MCARI2 (Modified Chlorophyll Absorption Ratio Index Improved; Haboudane et al., 2004) spectral index from three input bands and/or wavelengths. Bands/wavelengths can be input as two individual bands, two sets of bands (i.e., list of bands), or range of bands (i.e., list of two bands indicating the lower and upper range).

Definition:

array_mcari2 = ((1.5 * (2.5 * (wl1 - wl2) - 1.3 * (wl1 - wl3))) / np.sqrt((2 * wl1 + 1)**2 - (6 * wl1 - 5 * np.sqrt(wl2)) - 0.5))

Parameters
  • wl1 (int, float, or list) – the wavelength (or set of wavelengths) to be used as the first parameter of the MCARI2 index; if list, then consolidates all bands between two wavelength values by calculating the mean pixel value across all bands in that range (default: None).

  • wl2 (int, float, or list) – the wavelength (or set of wavelengths) to be used as the second parameter of the MCARI2 index; if list, then consolidates all bands between two wavelength values by calculating the mean pixel value across all bands in that range (default: None).

  • wl3 (int, float, or list) – the wavelength (or set of wavelengths) to be used as the third parameter of the MCARI2 index; if list, then consolidates all bands between two wavelength values by calculating the mean pixel value across all bands in that range (default: None).

  • b1 (int, float, or list) – the band (or set of bands) to be used as the first parameter of the MCARI2 index; if list, then consolidates all bands between two band values by calculating the mean pixel value across all bands in that range (default: None).

  • b2 (int, float, or list) – the band (or set of bands) to be used as the second parameter of the MCARI2 index; if list, then consolidates all bands between two band values by calculating the mean pixel value across all bands in that range (default: None).

  • b3 (int, float, or list) – the band (or set of bands) to be used as the third parameter of the MCARI2 index; if list, then consolidates all bands between two band values by calculating the mean pixel value across all bands in that range (default: None).

  • spyfile (SpyFile object or numpy.ndarray) – The datacube to process; if numpy.ndarray or None, loads band information from self.spyfile (default: None).

  • list_range (bool) – Whether bands/wavelengths passed as a list is interpreted as a range of bands (True) or for each individual band in the list (False). If list_range is True, b1/wl1 and b2/wl2 should be lists with two items, and all bands/wavelegths between the two values will be used (default: True).

  • print_out (bool) – Whether to print out the actual bands and wavelengths being used in the NDI calculation (default: True).

Returns

2-element tuple containing

  • array_mcari2 (numpy.ndarray): MCARI2 spectral index band math array.

  • metadata (dict): Modified metadata describing the MCARI2 index array (array_mcari2).

Example

Load hsio and segment modules

>>> import numpy as np
>>> import os
>>> from hs_process import hsio
>>> from hs_process import segment
>>> data_dir = r'F:\nigo0024\Documents\hs_process_demo'
>>> fname_in = os.path.join(data_dir, 'Wells_rep2_20180628_16h56m_pika_gige_7-Radiance Conversion-Georectify Airborne Datacube-Convert Radiance Cube to Reflectance from Measured Reference Spectrum.bip.hdr')
>>> io = hsio(fname_in)
>>> my_segment = segment(io.spyfile)

Calculate the MCARI2 spectral index (Haboudane et al., 2004) via segment.band_math_mcari2

>>> array_mcari2, metadata = my_segment.band_math_mcari2(wl1=800, wl2=670, wl3=550, spyfile=io.spyfile)
Band 1: [198]  Band 2: [135]  Band 3: [77]
Wavelength 1: [799.0016]  Wavelength 2: [669.6752]  Wavelength 3: [550.6128]
>>> np.nanmean(array_mcari2)
0.57376945

Show MCARI2 image via hsio.show_img

>>> io.show_img(array_mcari2)
api/img/segment/mcari2.png
band_math_ndi(wl1=None, wl2=None, b1=None, b2=None, spyfile=None, list_range=True, print_out=True)[source]

Calculates a normalized difference spectral index from two input bands and/or wavelengths. Bands/wavelengths can be input as two individual bands, two sets of bands (i.e., list of bands), or range of bands (i.e., list of two bands indicating the lower and upper range).

Definition:

array_ndi = (wl1 - wl2) / (wl1 + wl2)

Parameters
  • wl1 (int, float, or list) – the wavelength (or set of wavelengths) to be used as the first parameter of the normalized difference index; if list, then consolidates all bands between two wavelength values by calculating the mean pixel value across all bands in that range (default: None).

  • wl2 (int, float, or list) – the wavelength (or set of wavelengths) to be used as the second parameter of the normalized difference index; if list, then consolidates all bands between two wavelength values by calculating the mean pixel value across all bands in that range (default: None).

  • b1 (int, float, or list) – the band (or set of bands) to be used as the first parameter of the normalized difference index; if list, then consolidates all bands between two band values by calculating the mean pixel value across all bands in that range (default: None).

  • b2 (int, float, or list) – the band (or set of bands) to be used as the second parameter of the normalized difference index; if list, then consolidates all bands between two band values by calculating the mean pixel value across all bands in that range (default: None).

  • spyfile (SpyFile object or numpy.ndarray) – The datacube to process; if numpy.ndarray or None, loads band information from self.spyfile (default: None).

  • list_range (bool) – Whether bands/wavelengths passed as a list is interpreted as a range of bands (True) or for each individual band in the list (False). If list_range is True, b1/wl1 and b2/wl2 should be lists with two items, and all bands/wavelegths between the two values will be used (default: True).

  • print_out (bool) – Whether to print out the actual bands and wavelengths being used in the NDI calculation (default: True).

Returns

2-element tuple containing

  • array_ndi (numpy.ndarray): Normalized difference band math array.

  • metadata (dict): Modified metadata describing the normalized difference array (array_ndi).

Example

Load hsio and segment modules

>>> import numpy as np
>>> import os
>>> from hs_process import hsio
>>> from hs_process import segment
>>> data_dir = r'F:\nigo0024\Documents\hs_process_demo'
>>> fname_in = os.path.join(data_dir, 'Wells_rep2_20180628_16h56m_pika_gige_7-Radiance Conversion-Georectify Airborne Datacube-Convert Radiance Cube to Reflectance from Measured Reference Spectrum.bip.hdr')
>>> io = hsio(fname_in)
>>> my_segment = segment(io.spyfile)

Calculate the Normalized difference vegetation index using 10 nm bands centered at 800 nm and 680 nm via segment.band_math_ndi

>>> array_ndvi, metadata = my_segment.band_math_ndi(wl1=[795, 805], wl2=[675, 685], spyfile=io.spyfile)
Effective NDI: (800 - 680) / 800 + 680)
>>> np.nanmean(array_ndvi)
0.8184888

Show NDVI image via hsio.show_img

>>> io.show_img(array_ndvi)
api/img/segment/ndvi.png
band_math_ratio(wl1=None, wl2=None, b1=None, b2=None, spyfile=None, list_range=True, print_out=True)[source]

Calculates a simple ratio spectral index from two input band and/or wavelengths. Bands/wavelengths can be input as two individual bands, two sets of bands (i.e., list of bands), or a range of bands (i.e., list of two bands indicating the lower and upper range).

Definition:

array_ratio = (wl1/wl2)

Parameters
  • wl1 (int, float, or list) – the wavelength (or set of wavelengths) to be used as the first parameter of the ratio index; if list, then consolidates all bands between two wavelength values by calculating the mean pixel value across all bands in that range (default: None).

  • wl2 (int, float, or list) – the wavelength (or set of wavelengths) to be used as the second parameter of the ratio index; if list, then consolidates all bands between two wavelength values by calculating the mean pixel value across all bands in that range (default: None).

  • b1 (int, float, or list) – the band (or set of bands) to be used as the first parameter (numerator) of the ratio index; if list, then consolidates all bands between two band values by calculating the mean pixel value across all bands in that range (default: None).

  • b2 (int, float, or list) – the bands (or set of bands) to be used as the second parameter (denominator) of the ratio index; if list, then consolidates all bands between two bands values by calculating the mean pixel value across all bands in that range (default: None).

  • spyfile (SpyFile object or numpy.ndarray) – The datacube to process; if numpy.ndarray or None, loads band information from self.spyfile (default: None).

  • list_range (bool) – Whether a band passed as a list is interpreted as a range of bands (True) or for each individual band in the list (False). If list_range is True, b1/wl1 and b2/wl2 should be lists with two items, and all bands/wavelegths between the two values will be used (default: True).

  • print_out (bool) – Whether to print out the actual bands and wavelengths being used in the NDI calculation (default: True).

Returns

2-element tuple containing

  • array_ratio (numpy.ndarray): Ratio band math array.

  • metadata (dict): Modified metadata describing the ratio array (array_ratio).

Example

Load hsio and segment modules

>>> import numpy as np
>>> import os
>>> from hs_process import hsio
>>> from hs_process import segment
>>> data_dir = r'F:\nigo0024\Documents\hs_process_demo'
>>> fname_in = os.path.join(data_dir, 'Wells_rep2_20180628_16h56m_pika_gige_7-Radiance Conversion-Georectify Airborne Datacube-Convert Radiance Cube to Reflectance from Measured Reference Spectrum.bip.hdr')
>>> io = hsio(fname_in)
>>> my_segment = segment(io.spyfile)

Calculate a red/near-infrared band ratio using a range of bands (i.e., mimicking a broadband sensor) via segment.band_math_ratio

>>> array_ratio, metadata = my_segment.band_math_ratio(wl1=[630, 690], wl2=[800, 860], list_range=True)
Effective band ratio: (659/830)
>>> np.nanmean(array_ratio)
0.10981177

Notice that 29 spectral bands were consolidated (i.e., averaged) to mimic a single broad band. We can take the mean of two bands by changing list_range to False, and this slightly changes the result.

>>> array_ratio, metadata = my_segment.band_math_ratio(wl1=[630, 690], wl2=[800, 860], list_range=False)
Effective band ratio: (660/830)
>>> np.nanmean(array_ratio)
0.113607444

Show the red/near-infrared ratio image via hsio.show_img

>>> io.show_img(array_ratio, vmax=0.3)
api/img/segment/ratio_r_nir.png
composite_band(wl1=None, b1=None, spyfile=None, list_range=True, print_out=True)[source]

Calculates a composite band from a range of bands or wavelengths. Bands/wavelengths can be input as individual bands, a set of bands (i.e., list of bands), or a range of bands (i.e., list of two bands indicating the lower and upper range).

Parameters
  • wl1 (int, float, or list) – the wavelength (or set of wavelengths) to consolidate; if list, then all wavelengths between two wavelength values are consolidated by calculating the mean pixel value across all wavelengths in that range (default: None).

  • b1 (int, float, or list) – the band (or set of bands) to consolidate; if list, then all bands between two band values are consolidated by calculating the mean pixel value across all bands in that range (default: None).

  • spyfile (SpyFile object or numpy.ndarray) – The datacube to process; if numpy.ndarray or None, loads band information from self.spyfile (default: None).

  • list_range (bool) – Whether a band passed as a list is interpreted as a range of bands (True) or for each individual band in the list (False). If list_range is True, b1/wl1 and b2/wl2 should be lists with two items, and all bands/wavelegths between the two values will be used (default: True).

  • print_out (bool) – Whether to print out the actual bands and wavelengths being used in the NDI calculation (default: True).

Returns

2-element tuple containing

  • array_b1 (numpy.ndarray): Consolidated array.

  • metadata (dict): Modified metadata describing the consolidated array (array_b1).

load_spyfile(spyfile)[source]

Loads a SpyFile (Spectral Python object) for data access and/or manipulation by the hstools class.

Parameters

spyfile (SpyFile object) – The datacube being accessed and/or manipulated.

Example

Load hsio and segment modules

>>> from hs_process import hsio
>>> from hs_process import segment
>>> fname_in = r'F:\nigo0024\Documents\hs_process_demo\Wells_rep2_20180628_16h56m_pika_gige_7-Convert Radiance Cube to Reflectance from Measured Reference Spectrum.bip.hdr'
>>> io = hsio(fname_in)
>>> my_segment = segment(io.spyfile)

Load datacube via segment.load_spyfile

>>> my_segment.load_spyfile(io.spyfile)
>>> my_segment.spyfile
Data Source:   'F:\nigo0024\Documents\hs_process_demo\Wells_rep2_20180628_16h56m_pika_gige_7-Convert Radiance Cube to Reflectance from Measured Reference Spectrum.bip'
    # Rows:            617
    # Samples:        1300
    # Bands:           240
    Interleave:        BIP
    Quantization:  32 bits
    Data format:   float32