threshHLS
Top  Previous  Next

threshHLS ( integer Input, integer Output, integer Mode, integer& Phases, integer& Multi,
integer&MinH1, integer&MaxH1, integer&MinL1, integer&MaxL1, integer&MinS1, integer&MaxS1
[,integer&MinH2, integer&MaxH2, integer&MinL2, integer&MaxL2, integer&MinS2, integer&MaxS2]
… )

Use this function to separate objects of interest from the background and segment them into different phases based on the ranges of HLS components that represent pixel colors. The output image is typically created as a multiphase one with a selected number of phases. Input pixels whose values fall within the color ranges specified for a certain phase are converted into the output pixels with values equal to the corresponding phase number, while the pixels whose values are outside the intensity ranges specified for any of the phases are assigned the zero level.

The function can be called in the automatic or interactive modes. In the interactive modes, the user can adjust the range of intensities for the foreground pixels interactively and preview the segmented areas in real time, as the color overlays highlight the objects of interest in the input image.

Parameters
 
Input  
 
An integer between 0 and 116 specifying the input image frame number. A value of 0 represents the DMA memory buffer of the video device. Values in the range of 100-116 correspond to hidden frames. If the function is called in the interactive mode (M_DIALOG or M_MOUSE), only visible frames (1-99) can be used.  
 
Output  
 
An integer between 1 and 116 specifying the output image frame number. Values in the range of 100-116 correspond to hidden frames.  
 
Mode  
 
An enumerated integer that describes the mode to use. Must be one of the following values:  
 
M_PRESET=0 – immediately applies the function to the input image using the values specified by the Min and Max parameters.  
M_DIALOG=1 – opens the HLS Threshold dialog that lets the user adjust the threshold ranges for each color component manually by moving a related pair of sliders on the dialog or picking up foreground levels with the Sampling tool. As the sliders are moved, the color overlay on the input image corresponding to the active phase expands or contracts.  
M_MOUSE=2 – activates the mouse mode that lets the user interactively select the threshold ranges for the selected component and phase with a mouse. Moving the mouse upward and downward widens or narrows the threshold range respectively. Moving the mouse rightward or leftward raises or lowers the threshold range respectively. Pressing H, L, S keys switches between the Hue, Luminance and Saturation components respectively. Pressing INSERT adds a new phase, pressing 1, 2,…,9 switches to a specific phase, pressing DELETE removes the last added phase. To apply the changes and exit the function, press the left mouse button. To exit the function without applying the changes to the image, press the right mouse button.  
 
Phases  
 
An integer between 1 and 16 specifying the amount of phases into which the input image will be segmented. Depending on a value of Phases, the function will expect a corresponding number of Min/Max triple pairs following this argument. If the function is called in the interactive mode (M_DIALOG or M_MOUSE), the variable will return a selected number of phases.  
 
Multi  
 
A boolean integer that defines the type of the output image. Must be one of the following values:  
 
FALSE=0 – the output image will be of the same type as the input one. The foreground pixels will be transferred into the output image unchanged, while the pixels with values outside the specified color ranges will be assigned the black level.  
TRUE=1 – the output image will be created as a multiphase one. The input pixels whose values fall within the color ranges specified for a certain phase are converted into the output pixels with values equal to the corresponding phase number, while the pixels whose values are outside the color ranges specified for any of the phases are assigned the zero level.  
Default value: TRUE  
 
MinH1, MaxH1, MinL1, MaxL1, MinS1, MaxS1,  
MinH2, MaxH2, MinL2, MaxL2, MinS2, MaxS2….  
 
Floating arguments specifying the minimum and maximum levels of the thresholding range for the red, green and blue components of each phase. A value of Max must be greater than a corresponding value of Min, and all the levels must be in the range of pixel values allowable for the input image type. The number of Min/Max triple pairs submitted to the function must be equal to the amount of phases specified by the Phases argument. If the function is called in the interactive mode (M_DIALOG or M_MOUSE), the variables will return interactively selected levels.  
 
Error flags

ERR_OK  
 
The flag set if successful.  
 
ERR_FAILED  
 
The flag set if failed.  
 
ERR_CANCEL=-2  
 
The flag set if the function cancelled in the interactive mode.  

Example

This set of statements performs HLS thresholding of a sample image in the automatic mode. The image is segmented into two phases:  
 
setCurDir("samples")  
loadIm (1,"sample8.iwd")  
threshHLS(1,2,M_DIALOG,TRUE,2, 81,173, 184,215, 94,182,  
   100,255, 215,234, 151,215)  
 
Example

For more information on the HLS Threshold dialog box, refer to ImageWarp User's Guide.