## Edge Detection and Image SegmentatiON (EDISON) System Command Prompt Specification

### Table of Contents

- Overview
- Syntax
- Commands
- Parameters
- Data Types and Enumerations
- Input Types
- Output Types
- Supported Image/File Formats
- Other Image Formats
- Example: Confidence Based Edge Detection
- Example: Mean Shift Based Segmentation
- Example: Synergistic Segmentation
- Example: Mean Shift Based Image Filtering and Region Fusion

### Overview

The command prompt version of the Edge Detection and Image SegmentatiON (EDISON) System provides a versatile environment for performing confidence based edge detection and synergistic image segmentation through the definition of user defined scripts. In an EDISON script one specifies the system parameters, input, output, and operations. The system functionality is facilitated through a simple set of commands and parameters described in the following sections.

Once compiled and installed, the system may be invoked from the command prompt by typing,
>> edison myscript.eds
where 'myscript.eds' is a user defined EDISON script file.

The source code and makefile for the command prompt version of the EDISON system is available from the Robust Image Understanding Laboratory web site. The system was tested under both UNIX and Windows operating system environments.

### Syntax

The C-like syntax of the EDISON system is extraordinarily simple. In short, the EDISON script language is case sensitive, each statement must end in a semicolon, and assignments must be performed using the equals sign. Line comments and block comments are facilitated through the use of ' // ' and ' /* ... */ ' respectively. The language is limited to a small set of pre-defined parameters and commands whose usage is outlined in the following sections.

### Commands

The EDISON language contains three basic classes of commands. These classes as well as the commands that constitute them are listed below.

Input/Output

| Command: | Save
| Description: | Outputs system results. System results may be saved as images and MATLAB ASCII data files for analysis and further processing. If the requested result is not available a run-time error will be flagged by the system and the system execution will be halted.
| Syntax: | Save('filename', filetype, outputtype);
| Arguments
| filename | A character string containing the name of the file to which the result will be saved. The file extension must be included in the filename, EDISON will not place one automatically.
| filetype | An enumeration that specifies the image/data format, the only data format available being a MATLAB ASCII file. The File Type enumeration is detailed below.
| outputtype | An enumeration that specifies which result is to be saved. The Output Type enumeration is detailed below.
| Command: | Load
| Description: | Loads system input. There are two types of system input: (1) the images which are processed by the EDISON system, and (2) data maps used by the synergistic image segmentation algorithm to segment an image using specialized (possible higher-level) information. If the specified file to be loaded does not exist or read permission is denied, a run-time error is flagged and the system execution is halted.
| Syntax: | Load('filename', inputtype);
| Arguments
| filename | A character string containing the name of the input file.
| inputtype | An enumeration specifying the type of input IMAGE or MAP. The input type is outlined below.
| Command: | Use Result
| Description: | Routes the filtering or segmentation result from the previous operation to the current input of the system. When UseResult is invoked, the original image is replaced by the system output and any current output is deleted. In order to reinstate the input image Load must be called once again. If system output does not exists in the form of a filtered or segmented image a run-time error is generated and the system is halted.
| Syntax: | UseResult(outputtype);
| Arguments
| outputtype | An enumeration that specifies which result is to be stored as input to the system. Unlike Save the outputtype to argument to UseResult may only have one of two values: SEGM_IMAGE or FILT_IMAGE. The Output Type enumeration is detailed below.

Operations

EDISON operations do not take any arguments when invoked. The arguments to these operations are specified by the parameter assignments which must be made prior to invoking an operation. If a parameter remains un-specified or system input is needed to perform the desired operation, a run-time error will be flagged and the system execution halted.

| Command: | Edge Detect
| Description: | Performs confidence based edge detection.
| Syntax: | EdgeDetect;
| Command: | Filter
| Description: | Performs mean shift filtering.
| Syntax: | Filter;
| Command: | Fuse
| Description: | Performs transitive closure on the input image, fusing its regions based on a set of similarity criterion. See the paper for details. The Fuse operation will use the filtered image output as input if available, otherwise the input image regions will be fused.
| Syntax: | Fuse;
| Command: | Segment
| Description: | Performs traditional mean shift based and synergistic image segmentation.
| Syntax: | Segment;

Flags

EDISON flags define the system state. They have a value of either ON or OFF The EDISON system keeps track of three system flags which are set using the following commands. If a flag is not specified its default value is OFF. The flag type enumeration is also mentioned below.

| Command: | Synergistic
| Description: | The system performs synergistic segmentation when this flag has the value ON and mean shift based segmentation when it has the value OFF.
| Syntax: | Synergistic FLAG;
| Command: | Display Progress
| Description: | When turned ON this flag instructs the system to output its progress to stdout . When OFF no output is generated.
| Syntax: | DisplayProgress FLAG;
| Command: | Use Custom Weight Map
| Description: | The user specified custom weight map is used during synergistic segmentation when this flag is set to ON. When OFF the derived weight map is used.
| Syntax: | UseCustomWeightMap FLAG;

### Parameters

All necessary parameters must be specified prior to invoking an operation. The system takes no default values because of the strong dependence between parameter values and the input image. The parameters are categorized according to operation and are outlined below. Although each parameter is briefly described, for a more detailed description please consult the papers available from the RIUL web site.

Mean Shift Based Segmentation

| Parameter: | SpatialBandwidth
| Description: | Specifies a spatial search window of size (2r+1)x (2r+1) during the mean shift computation, where r is the spatial bandwidth.
| Type: | Integer
| Range: | Greater than zero.
| Parameter: | RangeBandwidth
| Description: | Specifies the bandwidth of the search window in the range subspace during the computation of mean shift.
| Type: | Floating point.
| Range: | Greater than zero.
| Parameter: | MinimumRegionArea
| Description: | Specifies the minimum allowable region area (in pixels) contained in the segmented image.
| Type: | Integer
| Range: | Greater than zero.
| Parameter: | Speedup
| Description: | Determines the speedup level used when computing mean shift.
| Type: | Enumeration

Synergistic Image Segmentation

In addition to the parameters specified for mean shift based segmentation three supplemental parameters are needed to perform synergistic segmentation.

| Parameter: | GradientWindowRadius
| Description: | Used to compute the gradient and confidence maps employed in the algorithm.
| Type: | Integer
| Range: | Greater than zero.
| Parameter: | MixtureParameter
| Description: | Specifies the relative importance between gradient and confidence in the definition of the edge weight map. More specifically the mixture parameter is the parameter aij described in the paper.
| Type: | Floating point.
| Range: | Between zero and one.
| Parameter: | EdgeStrengthThreshold
| Description: | During transitive closure (i.e. region fusion) regions having an average edge strength large than this threshold are not fused.
| Type: | Floating point.
| Range: | Between zero and one.

Confidence Based Edge Detection

| Parameter: | GradientWindowRadius
| Description: | Used to compute the gradient and confidence maps employed in the algorithm.
| Type: | Integer
| Range: | Greater than zero.
| Parameter: | MinimumLength
| Description: | Removes edges whose length is less than this threshold.
| Type: | Integer.
| Range: | Greater than zero.
| Parameter: | NmxRank
| Description: | Specifies the x-intercept of the non-maximum suppression curve.
| Type: | Floating point.
| Range: | Between zero and one.
| Parameter: | NmxConf
| Description: | Specifies the y-intercept of the non-maximum suppression curve.
| Type: | Floating point.
| Range: | Between zero and one.
| Parameter: | NmxType
| Description: | Specifies the curve type of the non-maximum suppression curve. Unlike, the other two curves the non-maximum suppression curve may not be of a CUSTOM type.
| Type: | Enumeration.
| Parameter: | HysterisisHighRank
| Description: | Specifies the x-intercept of the high hysterisis threshold curve.
| Type: | Floating point.
| Range: | Between zero and one.
| Parameter: | HysterisisHighConf
| Description: | Specifies the y-intercept of the high hysterisis threshold curve.
| Type: | Floating point.
| Range: | Between zero and one.
| Parameter: | HysterisisHighType
| Description: | Specifies the curve type of the high hysterisis threshold curve.
| Type: | Enumeration.
| Parameter: | CustomCurveHystHigh
| Description: | Specifies the vertices of the high hysterisis threshold custom curve.
| Type: | Vertex List.
| Parameter: | HysterisisLowRank
| Description: | Specifies the x-intercept of the low hysterisis threshold curve.
| Type: | Floating point.
| Range: | Between zero and one.
| Parameter: | HysterisisLowConf
| Description: | Specifies the y-intercept of the low hysterisis threshold curve.
| Type: | Floating point.
| Range: | Between zero and one.
| Parameter: | HysterisisLowType
| Description: | Specifies the curve type of the low hysterisis threshold curve.
| Type: | Enumeration.
| Parameter: | CustomCurveHystLow
| Description: | Specifies the vertices of the low hysterisis threshold custom curve.
| Type: | Vertex List.

### Data Types and Enumerations

The EDISON system parameters are either of integer or floating point type, or they are an enumeration. Each enumeration as well as the Vertex List data structure are outlined below.

Flag

The flag enumeration is used to specify the system state. Flags have a value of either ON or OFF and are set using flag commands.

Possible Values

- ON
- OFF

Speedup Level

The speedup level of the mean shift algorithm is determined through the use of this enumeration. There are three speedup levels outlined below: (1) NONE indicating that no speedup is to be used, (2) MEDIUM employs the speedup technique described in the paper, and (3) HIGH is an extension of the MEDIUM speedup to result in an even faster execution of the mean shift algorithm.

Possible Values

- NONE
- MEDIUM
- HIGH

Curve Type

The curve type enumeration is used to specify the shape of the curves used during the non-maximum and hysterisis thresholding steps of the confidence based edge detection algorithm. The possible curve types are listed below.

NOTE:The non-maxima suppression curve may not be of type CUSTOM.

Possible Values

- ARC
- HORIZONTAL_LINE
- VERTICAL_LINE
- LINE
- BOX
- CUSTOM

Vertex List

The vertex list is a list of 2-dimensional vertices that are placed in the row-eta diagram to form a custom curve. The custom curve has the syntax outlined below.

Syntax:

Parameter = {(x1, y1), (x2, y2), ..., (xn, yn)};

where xi and yi are real valued numbers.

NOTE: Empty vertex lists (i.e. using '{};') are not permitted.

### Input Types

There are two types of input used by the EDISON system.

1. Image Input

   The images analyzed using the EDISON system are specified as input by passing IMAGE as an argument to the Load command. A list of supported and extendible file formats are provided below.

2. Map Input

   A custom weight map may be specified as input to the synergistic image segmentation algorithm by passing MAP as an argument to the Load command. Currently custom weight maps may only be specified using MATLAB ASCII data files.

### Output Types

The nine different output types are grouped below according to operation. All output types may be output using any supported or extendible file formats.

Edge Detection

| Output Type: | EDGES
| Description: | Output the edge map.

Image Segmentation

| Output Type: | SEGM_BOUNDARIES
| Description: | Output the region boundaries of a segmented or filtered image.
| Output Type: | SEGM_IMAGE
| Description: | Output the segmented image.
| Output Type: | SEGM_IMAGE_BOUNDARIES
| Description: | Output the segmented image with the region boundary points overlaid onto the image.
| Output Type: | FILT_IMAGE
| Description: | Output the filtered image.
| Output Type: | FILT_IMAGE_BOUNDARIES
| Description: | Output the filtered image with region boundary points overlayed onto the image.
| Output Type: | WEIGHT_MAP
| Description: | Output the weight map

Edge Detection and Image Segmentation

| Output Type: | GRADIENT_MAP
| Description: | Output the gradient map.
| Output Type: | CONFIDENCE_MAP
| Description: | Output the confidence map.

### Supported Image/File Formats

The supported file formats include: (1) Images: Portable Pixel-map (Grey-scale [pgm] and Color [ppm]) and Portable Any-map (pnm), (2) Data: MATLAB ASCII data files. These file formats are specified via the file format enumeration whose possible values are listed below.

File Type Enumeration

- PPM - Portable Pixel-map Color Images
- PGM - Portable Pixel-map Grey-scale Images
- PNM - Portable Any-map Images
- MAT-LAB_ASCII - MATLAB ASCII data files

  One may extend the EDISON system to support additional image/file formats as needed.

  ### Other Image Formats

  One may extend the EDISON system to support additional image/file formats by altering the code in the following files, and then alter the makefile and recompile the system with the additional source files containing the function definitions necessary for reading/writing.

  - defs.h
  - globalFnc.h

  In 'defs.h' the constant FILETYPE_NUM must be changed to indicate the number of available file formats. An enumeration must then be added to the file type enumeration list, and a corresponding entry must be placed in the FILETYPE_LIST to indicate how this file format will be represented in the EDISON script. Finally, a corresponding entry must also be entered into the FILETYPE_HEADER_LIST specifying the file header that identifies the file format. Completing the above will define the new file type(s) in the EDISON system.

  Next, in 'globalFnc.cpp' an entry must be entered for each new file type in the case statements located in the functions CmCReadImage() and CmCWriteImage(), that will read/write a file using the specified file format. Once complete, the enumeration of the new file type(s) must be entered into the SUPPORTED_FILETYPE_LIST, which indicates to the system that the file types are supported.

  As seen from the code in 'defs.h' the file types for jpeg, pcx, and png are already defined in the EDISON system. These image formats are not currently supported by the system, however. Using them in an EDISON script without adding the appropriate functionality and recompiling the code will result in a version incompatibility error, which is flagged prior to running the script.

  ### Example: Confidence Based Edge Detection

  /*
  Performs confidence based edge detection.
  */

  //Specify the edge detection parameters
  GradientWindowRadius = 2;
  MinimumLength = 5;
  NmxRank = 0.5;
  NmxConf = 0.5;
  NmxType = ARC;
  HysterisisHighRank = 0.9;
  HysterisisHighConf = 0.9;
  HysterisisHighType = BOX;
  HysterisisLowRank = 0.8;
  HysterisisLowConf = 0.8;
  HysyerisisLowType = CUSTOM;
  CustomCurveHystLow = {(0.4,0.7), (0.6,0.3)};

  //Display progress
  DisplayProgress ON;

  //Load an image to perform edge detection
  Load('image.ppm', IMAGE);

  //Perform edge detection
  EdgeDetect;

  //Save the resulting edge map
  Save('edgemap.pgm', PGM, EDGES);

  //done.

  ### Example: Mean Shift Based Segmentation

  /*
  Performs mean shift based segmentation.
  */

  //Specify mean shift parameters
  SpatialBandwidth = 7;
  RangeBandwidth = 6.5;
  MinimumRegionArea = 20;
  Speedup = MEDIUM;

  //Display progress
  DisplayProgress ON;

  //Load an image to be segmented
  Load('image.pnm', IMAGE);

  //Segment the image
  Segment;

  //Save the result:

  //The segmented image...
  Save('segmimage.pnm', PNM, SEGM_IMAGE);

  //The filtered image...
  Save('filtimage.ppm', PPM, FILT_IMAGE);

  //The boundary image...
  Save('bndyimage.pgm', PGM, SEGM_BOUNDARIES);

  //done.

  ### Example: Synergistic Segmentation

  /*
  Performs synergistic image segmentation.
  */

  //Specify the necessary parameters...
  SpatialBandwidth = 7;
  RangeBandwidth = 6.5;
  MinimumRegionArea = 20;
  Speedup = MEDIUM;
  GradientWindowRadius = 2;
  MixtureParameter = 0.3;
  EdgeStrengthThreshold = 0.55;

  //Load an image
  Load('image.pnm', IMAGE);

  //Load a custom weight map
  Load('map.dat', MAP);

  //Use synergistic segmentation
  Synergistic ON;

  //Use a custom weight map
  UseCustomWeightMap ON;

  //Do not display progress
  DisplayProgress OFF;

  //Segment the image
  Segment;

  //Save the resulting segmented image with the region boundaries
  //overlayed.
  Save('syngimage.pnm', PNM, SEGM_IMAGE_BOUNDARIES);

  //done.

  ### Example: Mean Shift Based Image Filtering and Region Fusion

  /*
  Performs mean shift based filtering and region fusion.
  */

  //Specify the mean shift parameters for (fine) filtering...
  SpatialBandwidth = 4;
  RangeBandwidth = 4;
  Speedup = MEDIUM;

  //Load an image
  Load('image.pnm', IMAGE);

  //Display progress
  DisplayProgress ON;

  //Filter the image
  Filter;

  //Save the filtered image
  Save('filtimage.pnm', PNM, FILT_IMAGE);

  //Segment the image using a large resolution in both subspaces...
  SpatialBandwidth = 7;
  RangeBandwidth = 6.5;
  MinimumRegionArea = 20;

  //Fuse the filtered image regions
  Fuse;

  //Save the result
  Save('fuseimage.pnm', PNM, SEGM_IMAGE);

  //Further fuse the regions using a larger minimum area
  MinimumRegionArea = 50;
  UseResult(SEGM_IMAGE);
  Fuse;

  //Save the result
  Save('newimage.ppm', PPM, SEGM_IMAGE);

  //done.

  Robust Image Understanding Laboratory, (freeware) 2002.