Scale Gray Range to 8 Bit

Use this tool to scale a grayscale image to an 8-bit image based on a predefined gray value range. You may use images with arbitrary pixel types as input, e.g., 16-bit images.

Most of the provided MERLIC tools require an 8-bit image as input. Therefore, it is recommended to convert images with any other pixel type to ensure that the images can be processed in subsequent tools. If you are using images that are no 8-bit images, e.g., images acquired from a 3D sensor, you should use this tool to convert the images prior to any processing tasks in MERLIC. Thus, this tool enables you to prepare all kinds of grayscale images, especially 3D height images, for the processing in MERLIC. The scaled image can then be used for further processing tasks in subsequent tools.

For the conversion of the image a specific range of gray values is scaled to the range of an 8-bit image. This means that the gray values of the resulting image range from 0 to 255. The minimum and maximum value of the gray value range can be determined from different sources: from a training image, from the processing images, or from predefined gray values. Thus, in contrast to the tool Convert Pixel Type, this tool enables you to scale only a specific range of gray values to an 8-bit image instead of the whole gray range.

This tool provides a training mode but the training mode is only required if the gray value range is determined from a training image. If you want to determine the gray value range from the processing images or from predefined minimum and maximum gray values, the training image has no effect. See the topic Working with the Training Mode to learn more about how to work with tools that require a training.

Beside the conversion to 8-bit images, it might be necessary to perform some additional preprocessing steps if your images are acquired from a 3D sensor. The provided MERLIC tools of the category 3D Height Image are especially designed for this preprocessing tasks. For more detailed information about the recommended order of the preprocessing steps, please see the topic 3D Height Image.

Defining the Gray Value Range

You can choose between different sources for the conversion of the image. The selected source at the parameter "Gray Range Source" specifies how the gray value range to be scaled is determined and from which image.

Determining the Gray Value Range From a Training Image

In this mode the lower and upper limits of the gray value range are determined automatically from the selected training image.

1. Select the source "Training Image (Training ROI)" at the parameter "Gray Range Source".
2. Select the training image you want to use for the determination of the gray value range.
3. Optionally, define a specific area in which the gray value range is determined:
   1. Switch to the selected training image.
   2. Draw an ROI into the training image. The minimum and maximum gray value will then be determined only from the gray values within the defined ROI area. If an ROI is connected to the parameter "ROI for Gray Range", it will have no effect because the ROI must be defined manually in the training image. If no ROI is used, the gray value range is determined from the whole training image.
4. Optionally, adjust the value of the parameter "Range Expansion" to extend the determined gray value range by a predefined factor.

The resulting gray value range will be used for the conversion of all processing images. The lower and upper limits of the gray value range are used for the scaling of the image that is returned in the tool results "Minimum Gray Value Used" and "Maximum Gray Value Used".

The parameters "Predefined Minimum Gray Value" and "Predefined Maximum Gray Value" have no effect in this mode because the gray value range will be determined automatically from the training image.

Defining the Gray Value Range From the Processing Images

If this mode is selected, the lower and upper limits of the gray value range are determined from the processing images.

1. Select the source "Processing Image (Region/ROI for Gray Range)" at the parameter "Gray Range Source".
2. Optionally, define a specific area for determining the gray value range by drawing an ROI into the processing image. The minimum and maximum gray values will then be determined from the corresponding image part in the processing images.
3. Optionally, adjust the value in the parameter "Range Expansion" to extend the determined gray value range by a predefined factor.

The resulting gray value range that has been determined will only be applied for the conversion of the current processing image. For each processing image, the gray value range will be determined anew. Thus, for each image, an individual value range is used. The tool results "Minimum Gray Value Used" and "Maximum Gray Value Used" return the final minimum and maximum value of the gray value range that is used for the scaling of the image in the current processing image.

The parameters "Predefined Minimum Gray Value" and "Predefined Maximum Gray Value" have no effect in this mode because the gray value range will be determined automatically from the processing image.

Defining the Gray Value Range Via Predefined Values

This mode enables you to define the lower and upper limits of the gray value range manually at the respective parameters.

1. Select the source "Predefined Minimum/Maximum Gray Values" at the parameter "Gray Range Source".
2. Set the desired minimum value of the gray value range at the respective parameter "Predefined Minimum Gray Value".
3. Set the desired maximum value of the gray value range at the respective parameter "Predefined Maximum Gray Value".

The defined gray value range will be used for the conversion of all processing images.

Since the gray value range is defined manually, possibly defined regions of interest (ROIs) have no effect on the upper and lower limits.

Parameters

Basic Parameters

Image:

This parameter represents the grayscale image to be converted. You may use images with the following pixel types:

Pixel Type	Description	Value Range
int1	1 byte per pixel with sign	−128 ... 127
uint2	2 bytes per pixel, unsigned	0 ... 65535 (216 −1)
int2	2 bytes per pixel with sign	−32768 (−215) ... 32767 (215 - 1)
int4	4 bytes per pixel with sign	−2147483648 (−231) ... 2147483647 (231 - 1)
int8	8 bytes per pixel with sign	-9223372036854775808 (−263) ... 9223372036854775807 (263 - 1)
real	4 bytes per pixel, floating point Precision: 6 significant decimal digits	−3.4e38 to 3.4e38

Gray Range Source:

This parameter defines how and from which image the gray value range, that is scaled to the 8-bit range, is determined. As a default, this value is set to "Training Image (Training ROI)". You may choose from the following sources:

Value	Description
Training Image (Training ROI)	The minimum and maximum gray values are determined automatically from a training image. The resulting gray value range can be further adjusted via the parameter "Range Expansion". You also have the possibility to restrict the area from which the values are determined by drawing an ROI. The final gray value range will be applied for the conversion of all processing images.
Processing Image (Region/ROI for Gray Range)	The minimum and maximum gray values are determined automatically from the processing images. The resulting gray value range can be further adjusted via the parameter "Range Expansion". You also have the possibility to restrict the area from which the values are determined by drawing an ROI or by using the ROI or region of a previous tool for the parameter "ROI for Gray Range" or "Region for Gray Range", respectively. If this gray range source is selected, an individual gray value range is determined anew for each processing image.
Predefined Minimum/Maximum Gray Values	This mode enables you to define the minimum and maximum gray values manually at the parameters "Predefined Minimum Gray Value" and "Predefined Maximum Gray Value". If this gray range source is selected, the gray value range is only defined by the values that have been set in these parameters.

See also the section Defining the Gray Value Range for a detailed description of how to work with each conversion method.

If the gray value range has been determined from an image part defined by an ROI, it might be the case that the gray value range does not cover all gray values of a processing image. In this case, these gray values will be clipped to the determined minimum and maximum gray values for the conversion of the image.

In case of possible invalid gray value data, e.g., if the 3D sensor used for the image acquisition did not provide correct gray value data for some pixel, you can use the tool Remove Outlier Pixels beforehand to correct these data.

Additional Parameters

Alignment Data:

This parameter represents the alignment data that are used to align the ROI. By default no alignment data are connected and thus no effect is visible. If you want to use specific alignment data, you have to connect the parameter to an appropriate result of a previous tool such as Determine Alignment with Matching, Determine Alignment with Straight Border, Align Image, or Rotate Image.

In the tool "Scale Gray Range to 8 Bit" the alignment data is used to align the ROI for Gray Range but only if the gray range source "Processing Image (Region/ROI for Gray Range)" is selected at the parameter "Gray Range Source".

Predefined Minimum Gray Value:

This parameter defines the minimum value of the gray value range that is scaled to the range of an 8-bit image. This parameter is only applied if the parameter "Gray Range Source" is set to "Predefined Minimum/Maximum Gray Values".

The parameter is set to "undefined" by default. However, as soon as "Predefined Minimum/Maximum Gray Values" has been selected as gray range source, the minimum value is automatically determined from the pixel type of the image and set accordingly. You can also adjust the value manually to the desired gray value.

The following table shows the value range of the respective pixel type of an image:

Pixel type	Value range
byte	[0, 255]
int1	[-127, 127]
int2	[-32768, 32767]
uint2	[0, 65535]
all other pixel types	[-100000.0, 100000.0]

Predefined Maximum Gray Value:

This parameter defines the maximum value of the gray value range that is scaled to the range of an 8-bit image. This parameter is only applied if the parameter "Gray Range Source" is set to "Predefined Minimum/Maximum Gray Values".

The parameter is set to "undefined" by default. However, as soon as "Predefined Minimum/Maximum Gray Values" has been selected as gray range source, the maximum value is automatically determined from the pixel type of the image and set accordingly. You can also adjust the value manually to the desired gray value. The respective value range also depends on the pixel type of the images. See the table in the description of the parameter "Predefined Minimum Gray Value" for an overview of the different value ranges.

Range Expansion:

This parameter defines the factor for the expansion of the defined gray value range. The range expansion is defined as a percentage value and set to 0 by default. It refers to the gray range within the image from which the gray range for the scaling is determined. First, the corresponding expansion value is calculated from the respective gray range. Then, the lower and upper limits of the gray range, that has been determined for the scaling, are each expanded by half of the calculated expansion value.

The gray range that is used to calculate the actual expansion value depends on the selected gray range source and the use of an ROI or a region: 

In case "Predefined Minimum/Maximum Gray Values" is selected as gray range source, the expansion value is calculated from the gray range that has been defined at the parameters "Predefined Minimum Gray Value" and "Predefined Maximum Gray Value".

In case "Training Image (Training ROI)" is selected as gray range source, the expansion value is calculated from the gray range of the training image. If an ROI is used in the training image, only the gray range within the respective ROI is used to calculate the range expansion value. If no ROI is used in the training image, the gray range of the whole training image is used.

In case "Processing Image (Region/ROI for Gray Range)" is selected as gray range, the expansion value is calculated from the gray range of the current processing images. If an ROI or a region is used in the processing image, only the gray range within the respective ROI and region area is used to calculate the range expansion value. If neither an ROI nor a region is used, the gray range of the whole processing image is used.

We recommend to set the range expansion to a value larger than 0 in case there are variations in the gray range of the acquired images.

Region for Gray Range:

This parameter defines the region in which gray values for the scaling are determined. In combination with the ROI, it defines the area in which the gray value range is determined because the value range is determined from the union of the region defined in this parameter and the ROI. In case both of them are empty, the gray value range is determined from the whole image.

By default the "Region for Gray Range" is defined as empty region. To specify a "Region for Gray Range", you have to connect the parameter to an appropriate region result of a previous tool to make sure that a region is transmitted to this tool.

The region defined in this parameter is only applied if the gray range source "Processing Image (Region/ROI for Gray Range)" is selected at the parameter "Gray Range Source". For all other gray range sources, this parameter has no effect.

Results

Basic Results

Scaled Image:

This result represents the 8-bit image that has been scaled to a gray value range of 0 to 255.

Minimum Gray Value Used:

This result returns the minimum value of the gray value range that has been scaled to the range of an 8-bit image. It represents the minimum gray value that has been determined from the selected gray range source and then been expanded by the factor defined in the parameter "Range Expansion". Therefore, this result gives information about the final gray value range that has been used for the current processing image.

Maximum Gray Value Used:

This result returns the maximum value of the gray value range that has been scaled to the range of an 8-bit image. It represents the maximum gray value that has been determined from the selected gray range source and then been expanded by the factor defined in the parameter "Range Expansion". Therefore, this results gives information about the final gray value range that has been used for the current processing image.

Scaling Factor:

This result returns the multiplication factor that has been used in the internal transformation of the image. If desired, it can be used to calculate the original gray values of the image with the formula described for the result "Scaling Offset".

Scaling Offset:

This result returns the offset value that has been used in the internal transformation of the image. If desired it can be used to calculate the original gray values of the image with the following formula:

Tool State:

"Tool State" returns information about the state of the tool and thus can be used for error handling. Please see the topic Tool State Result for more information about the different tool state results.

Additional Results

Processing Time:

This result returns the duration of the most recent execution of the tool in milliseconds. The result is provided as additional result. Therefore, it is hidden by default but it can be displayed via the button beside the tool results. For more information see the section Processing Time in the tool reference overview.

Application Examples

This tool is used in the following MERLIC Vision App examples:

• check_correct_filling_on_3d_height_images.mvapp
• read_text_in_3d_height_image.mvapp