This procedure has been replaced by the FXSegmentation task.

This procedure automates the Segment Only Feature Extraction workflow, which extract segments without performing rule-based or example-based classification. Based on the segmentation options that you specify, ENVI will compute spatial, spectral, and texture attributes and will generate a segmentation image, attribute image, and shapefile containing the regions from the segmentation image.

Syntax

ENVI_DOIT, 'ENVI_FX_SEGMENTONLY_DOIT' [, A_FID=array] [, A_POS=array] [, ATTRIBUTE_RASTER_FILENAME=string] [, BR_BANDS=array] [, CS_BANDS=array] [, DIMS=array], FID=file ID [, /INVERSE_MASK] [, KERNEL_SIZE=long integer] [, M_FID=file ID][, MERGE_ALGORITHM=string] [ , MERGE_BANDS=array] [, MERGE_LEVEL=floating point] [, POS=array] [, R_FID=variable] [, REPORT_FILENAME=string] [, SCALE_LEVEL=floating point] [, SEGMENT_ALGORITHM=string], SEGMENTATION_RASTER_FILENAME=string [, SEGMENT_BANDS=array] [, VECTOR_FILENAME=string]

Keywords

A_FID (optional)

Set this keyword to an array of file IDs for ancillary data files. Use this keyword in conjunction with the A_POS keyword. The number of elements of A_FID must equal the number of elements of A_POS.

A_POS (optional)

Set this keyword to an array of long integers representing band numbers to process in the ancillary data files. Use this keyword in conjunction with the A_FID keyword. Specify bands starting with zero (Band 1 = 0, Band 2 = 1, etc.)

Each element in the A_POS array corresponds to an element in the A_FID array. For example, suppose you have two ancillary files whose file IDs are 100 and 200. To process Band 1 from file ID 200, and to process Bands 2-5 from file 100, write the code as follows:

  A_FID = [200, 100, 100, 100, 100]
  A_POS = [0, 1, 2, 3, 4]

To process all bands from the same file (100), write the code as follows:

  A_FID = [100, 100, 100, 100, 100]
  A_POS = [0, 1, 2, 3, 4]

ATTRIBUTE_RASTER_FILENAME (optional)

Set this keyword to a string with the name of the output attribute image, which is a multi-layer image in ENVI raster format where each layer represents the values of a specific attribute. All attributes are included.

BR_BANDS (optional)

Set this keyword to a two-element array of long integers that represent band numbers used to compute an optional Normalized Difference index to use in segmentation.

CS_BANDS (optional)

Set this keyword to a three-element array of long integers that represent the red, green, and blue bands from the input image. These will be used to perform an optional RGB to HSI color space transformation that will create Hue, Saturation, and Intensity bands to use in segmentation.

DIMS (optional)

The “dimensions” keyword is a five-element array of long integers that defines the spatial subset (of a file or array) to use for processing. Nearly every time you specify the keyword FID, you must also specify the spatial subset of the corresponding file (even if the entire file, with no spatial subsetting, is to be processed).

  • DIMS[0]: A pointer to an open ROI; use only in cases where ROIs define the spatial subset. Otherwise, set to -1L.
  • DIMS[1]: The starting sample number. The first x pixel is 0.
  • DIMS[2]: The ending sample number
  • DIMS[3]: The starting line number. The first y pixel is 0.
  • DIMS[4]: The ending line number

To process an entire file (with no spatial subsetting), define DIMS as shown in the following code example. This example assumes you have already opened a file using ENVI_SELECT or ENVI_PICKFILE:

  envi_file_query, fid, dims=dims

FID

The file ID (FID) is a long-integer scalar with a value greater than 0. An invalid FID has a value of -1. The FID is provided as a named variable by any routine used to open or select a file. Often, the FID is returned from the keyword R_FID in the ENVIRasterToFID routine. Files are processed by referring to their FIDs. If you work directly with the file in IDL, the FID is not equivalent to a logical unit number (LUN).

INVERSE_MASK (optional)

Set this keyword to invert the mask specified by the M_FID keyword. Inverting the mask means that Feature Extraction will process regions with pixel values of 0 in the mask.

KERNEL_SIZE (optional)

Set this keyword to a long-integer odd number representing the size of the kernel used in texture attribute calculations. The default value is 3.

M_FID (optional)

Set this keyword to the file ID of a raster mask image. If you specify this keyword, Feature Extraction will ignore regions with pixel values of 0 in the mask.

MERGE_ALGORITHM (optional)

Set this keyword to one of the following strings, specifying the method used to perform merging:

  • Full Lambda Schedule: (default). Merges small segments within larger, textured areas such as trees or clouds, where over-segmentation may be a problem.
  • Fast Lambda: Merges adjacent segments with similar colors and border sizes.

See Merge Algorithms Background for more detailed descriptions of each option.

MERGE_BANDS (optional)

Set this keyword to an array of long integers that represent band numbers to use with the merge algorithm and merge level that you specify. Merging will be based on the differences between region colors on all selected bands. By default, all bands of the input image will be used.

If you selected a spectral subset of bands using the POS keyword, then specify band numbers according to the POS array, not the original dataset. For example, suppose that you created a spectral subset of bands 1, 2, 5, and 7 from a 7-band dataset. The POS array for these four bands is [0, 1, 2, 3]. To perform merging on bands 1, 2, and 5 from the original dataset, then use the corresponding POS band numbers as follows: 

MERGE_BANDS=[0, 1, 2]

If you do not select a spectral subset, then you do not have to keep track of the POS band numbering, as in this example. By default, the MERGE_BANDS keyword will use all bands from the input image.

MERGE_LEVEL (optional)

Set this keyword to a floating-point value between 0 and 100.0, specifying the merge level used to combine segments with similar colors (Fast Lambda method) or to merge over-segmented areas (Full Lambda Schedule method). The default value is 0.

POS (optional)

Use this keyword to specify an array of band numbers used to perform segmentation. POS indicates the spectral subset of bands to use in processing. Specify bands starting with zero (Band 1 = 0, Band 2 = 1, etc.)

ENVI creates a single dataset from the combined bands of the input image, ancillary data, normalized difference, hue, saturation, and intensity (if selected). For best results, you should not perform segmentation with a combination of custom bands (normalized difference or HSI color space) and visible/NIR bands. You can perform segmentation on the normalized difference or color space bands by themselves, but not in combination with visible and NIR bands. So in most cases, you will need to select a spectral subset for segmentation instead of using all bands.

Specify band numbers in the following order:

  1. Input image: one or more bands
  2. Ancillary image(s): one or more bands
  3. Normalized difference: one band
  4. Hue: one band
  5. Saturation: one band
  6. Intensity: one band

For example, if the input image has four bands and you want to perform segmentation on these bands only, set POS = [0, 1, 2, 3].

Or, suppose you have a 4-band image and you set the BR_BANDS and CS_BANDS keywords. The band numbers are as follows:

  • Input image: [0, 1, 2, 3]
  • Normalized difference: [4]
  • Hue: [5]
  • Saturation: [6]
  • Intensity: [7]

To perform segmentation on the saturation band only, set POS = [6] in this example.

For hyperspectral imagery, we strongly recommend that you run a principal components analysis or independent components analysis on the dataset before using it in Feature Extraction. Segmentation and merging work best on datasets with only a few bands, plus it helps you keep track of the band numbers when setting the POS keyword.

R_FID (optional)

This keyword is a returned variable containing the file ID of the segmentation image. If processing fails for any reason, then R_FID = -1.

REPORT_FILENAME (optional)

Set this keyword to a string indicating the filename of a text report that lists the segmentation and merge settings used, the input and ancillary files used, a list of attributes that were computed for the segmentation image, and any output files that were created.

SCALE_LEVEL (optional)

Set this keyword to a floating-point value between 0 and 100.0, indicating the scale level used to delineate features of interest in segmentation. Increasing the value reduces the number of segments. The default value is 50.0 for the Edge segmentation method and 0 for the Intensity method.

SEGMENT_ALGORITHM (optional)

Set this keyword to one of the following strings, indicating the segmentation method to use:

  • Edge (default): Best for detecting edges of features where objects of interest have sharp edges. Set the SCALE_LEVEL and MERGE_LEVEL as needed to best delineate features of interest.
  • Intensity: Best for segmenting images with subtle gradients such as digital elevation models (DEMs) or images of electromagnetic fields. When selecting this method, don't perform any merging; set MERGE_LEVEL=0. Merging is used primarily to combine segments with similar spectral information. Elevation and other related attributes are not appropriate for merging.

See Watershed Algorithm Background for more detailed descriptions of each option.

SEGMENTATION_RASTER_FILENAME

Set this keyword to a string indicating the filename of the output segmentation image. This is an image in ENVI raster format that shows the regions defined by segmentation; each region is assigned the mean spectral values of all the pixels that belong to that region.

SEGMENT_BANDS (optional)

Set this keyword to an array of long integers representing the band numbers to use in the segmentation method and scale level that you specify. All bands from the input image are selected by default. The settings will apply to a grayscale image derived from the average of all selected bands. For best segmentation results, select a combination of bands that have similar spectral ranges such as red, green, blue, and near-infrared bands.

If you selected a spectral subset of bands using the POS keyword, then specify band numbers according to the POS array, not the original dataset. For example, suppose that you created a spectral subset of bands 1, 2, 5, and 7 from a 7-band dataset. The POS array for these four bands is [0, 1, 2, 3]. To perform segmentation on bands 1, 2, and 5 from the original dataset, then use the corresponding POS band numbers as follows: 

SEGMENT_BANDS=[0, 1, 2]

If you do not select a spectral subset, then you do not have to keep track of the POS band numbering, as in this example. By default, the SEGMENT_BANDS keyword will use all bands from the input image.

VECTOR_FILENAME (optional)

Set this keyword to a string indicating the filename of a shapefile that contains the polygon regions from the segmentation image. Shapefiles have a maximum filesize of 2 GB. If you do not specify this keyword, then no shapefile will be created.

Example

PRO EXAMPLE_FX_SEGMENTONLY_DOIT
  compile_opt IDL2
  ;
  ; Initialize ENVI and send all errors  
  ; and warnings to the file batch.txt
  ;
  e = ENVI(/HEADLESS)
  e.LOG_FILE = 'batch.txt'
  ;
  ; Open the input file  
  ;
  InputFile = FILEPATH('bhtmref.img', $
     ROOT_DIR=e.ROOT_DIR, $
     SUBDIR = ['classic', 'data'])
  raster = e.OpenRaster(InputFile)
  fid = ENVIRasterToFID(raster)
  ;
  ; Verify FID is valid
  ;
  IF (FID eq -1) THEN BEGIN
    e.Close
    RETURN
  ENDIF
  ;
  ; Set output filenames
  ;
  SegImage = 'segmentation_image.dat'
  Report = 'report.txt'
  VectorImage = 'regions.shp'
  AttImage = 'attributes.dat'
  ;  
  ; Set the keywords.
  dims = [-1L, 0, raster.ncolumns-1, 0, raster.nrows-1]
  pos = lindgen(raster.nbands); process all bands
  ;
  ; Perform the segmentation                
  ;  
  envi_doit, 'envi_fx_segmentonly_doit', $    
     fid=fid, pos=pos, dims=dims, $    
     r_fid=r_fid, $
     attribute_raster_filename=AttImage, $
    merge_level=20.0, $
     report_filename=Report, scale_level=30.0, $
     segmentation_raster_filename=SegImage, $
     vector_filename=VectorImage
  ;  
  ; Exit ENVI  
  e.Close
  ;
  ; Re-open ENVI in interactive mode and display the image
  ;
  e = ENVI()
  oSegImage = e.OpenRaster(SegImage)
  view1 = e.GetView()
  layer1 = view1.CreateLayer(oSegImage)
END