ImageDev

StackRescaleIntensity

Performs a linear scaling of the gray level values of each slice of an image stack.

Access to parameter description

This algorithm performs a linear scaling of the gray level values of each slice of an image stack to a user-specified interval. The linear scaling can be performed either using intensity intervals (scalingMode NORMALIZATION) or an average and a standard deviation (scalingMode STANDARDIZATION).

Scaling mode NORMALIZATION

In Figure 1, the input gray levels of interest are in the user-specified interval [a, b], and the output range is the interval [c, d].

<b> Figure 1.</b> The intensity rescaling transformation by normalization
Figure 1. The intensity rescaling transformation by normalization

The input image is I, and the output image is O. Let [a, b] be the input range and [c, d] the output range, then:
$$ \begin{array}{ll} O(n,m)=c & ~\mbox{if $I(n,m) \leq a$}\\ O(n,m)=\left(\frac{d-c}{b-a}\right)(I(n,m)-a)+c & ~\mbox{if $a < I(n,m) \leq b$}\\ O(n,m)=d & ~\mbox{if $I(n,m) > b$}\end{array} $$

Scaling mode STANDARDIZATION

The aim of intensity rescaling by standardization is to recenter the intensities of an image around a new mean while maintaining a defined standard deviation. In Figure 2, the red curve represents the histogram of an input image, while the blue curve represents the result of scaling with a higher mean and a smaller standard deviation.

<b> Figure 2.</b> Histogram of an image before and after a rescale by standardization
Figure 2. Histogram of an image before and after a rescale by standardization

The formula used to compute the intensity of the output image is:
$$ O(n,m) = \left[\left(\frac{I(n,m)-\mu_I}{\sigma_I}\right)\sigma_O\right]+\mu_O $$ where:

The type of the output image is set by an enumerate as detailed in the Data Type Management section.

See also

Function Syntax

This function returns outputImage. 
// Function prototype
std::shared_ptr< iolink::ImageView >
stackRescaleIntensity( std::shared_ptr< iolink::ImageView > inputImage,
                       StackRescaleIntensity::ScalingMode scalingMode,
                       StackRescaleIntensity::RangeMode inputRangeMode,
                       const iolink::Vector2d& percentageInputRange,
                       const iolink::Vector2d& intensityInputRange,
                       StackRescaleIntensity::ScalingScope scalingScope,
                       StackRescaleIntensity::RangeMode outputRangeMode,
                       const iolink::Vector2d& percentageOutputRange,
                       const iolink::Vector2d& intensityOutputRange,
                       const iolink::Vector2d& intensityOutputStatistics,
                       StackRescaleIntensity::OutputType outputType,
                       std::shared_ptr< iolink::ImageView > outputImage = nullptr );
This function returns outputImage. 
// Function prototype.
stack_rescale_intensity(input_image: idt.ImageType,
                        scaling_mode: StackRescaleIntensity.ScalingMode = StackRescaleIntensity.ScalingMode.STANDARDIZATION,
                        input_range_mode: StackRescaleIntensity.RangeMode = StackRescaleIntensity.RangeMode.MIN_MAX,
                        percentage_input_range: Union[Iterable[int], Iterable[float]] = [2, 98],
                        intensity_input_range: Union[Iterable[int], Iterable[float]] = [0, 255],
                        scaling_scope: StackRescaleIntensity.ScalingScope = StackRescaleIntensity.ScalingScope.GLOBAL,
                        output_range_mode: StackRescaleIntensity.RangeMode = StackRescaleIntensity.RangeMode.MIN_MAX,
                        percentage_output_range: Union[Iterable[int], Iterable[float]] = [2, 98],
                        intensity_output_range: Union[Iterable[int], Iterable[float]] = [0, 255],
                        intensity_output_statistics: Union[Iterable[int], Iterable[float]] = [0, 1],
                        output_type: StackRescaleIntensity.OutputType = StackRescaleIntensity.OutputType.SAME_AS_INPUT,
                        output_image: idt.ImageType = None) -> idt.ImageType
This function returns outputImage. 
// Function prototype.
public static IOLink.ImageView
StackRescaleIntensity( IOLink.ImageView inputImage,
                       StackRescaleIntensity.ScalingMode scalingMode = ImageDev.StackRescaleIntensity.ScalingMode.STANDARDIZATION,
                       StackRescaleIntensity.RangeMode inputRangeMode = ImageDev.StackRescaleIntensity.RangeMode.MIN_MAX,
                       double[] percentageInputRange = null,
                       double[] intensityInputRange = null,
                       StackRescaleIntensity.ScalingScope scalingScope = ImageDev.StackRescaleIntensity.ScalingScope.GLOBAL,
                       StackRescaleIntensity.RangeMode outputRangeMode = ImageDev.StackRescaleIntensity.RangeMode.MIN_MAX,
                       double[] percentageOutputRange = null,
                       double[] intensityOutputRange = null,
                       double[] intensityOutputStatistics = null,
                       StackRescaleIntensity.OutputType outputType = ImageDev.StackRescaleIntensity.OutputType.SAME_AS_INPUT,
                       IOLink.ImageView outputImage = null );

Class Syntax

Parameters

Parameter Name Description Type Supported Values Default Value
input
inputImage
The input image stack to normalize. If the input is a 3D volume, it will be considered as a stack of XY images. Image Grayscale or Multispectral nullptr
input
scalingMode
The type of rescaling to apply on each slice.
STANDARDIZATION The scaling is performed by subtracting the mean and dividing by the standard deviation.
NORMALIZATION The scaling is performed by subtracting the minimum and dividing by data range.
Enumeration STANDARDIZATION
input
inputRangeMode
The way to define the input intensity range, applied on each slice of the stack.
MIN_MAX The input range is the minimum and maximum of each slice.
PERCENTILE The input range is defined by two user-defined percentiles, computed on each slice.
OTHER The input range is between user-defined bounds [a,b].
Enumeration MIN_MAX
input
percentageInputRange
The low and high histogram percentile to use when the input range mode is set to PERCENTILE (in percent). This parameter is ignored with other input range modes. Vector2d [0, 100] {2.f, 98.f}
input
intensityInputRange
The input intensity range [a, b] to use when the input range mode is set to OTHER. This parameter is ignored with other input range modes. Vector2d Any value {0.f, 255.f}
input
scalingScope
The scope for computing the output parameters (mean, standard deviation, percentiles, minimum or maximum).
GLOBAL The output parameters are computed globally on the input stack.
SLICE_AVERAGING The output parameters are computed independently on each slice of the stack, and then averaged.
Enumeration GLOBAL
input
outputRangeMode
The way to define the destination intensity range.
MIN_MAX The destination range is the minimum and maximum, computed on the entire input data.
PERCENTILE The output range is defined by two user-defined percentiles, computed on the entire input data.
OTHER The output range is defined by two user-defined values.
Enumeration MIN_MAX
input
percentageOutputRange
The low and high histogram percentile to use when the output range mode is set to PERCENTILE (in percent). This parameter is ignored with other output range modes. Vector2d [0, 100] {2.f, 98.f}
input
intensityOutputRange
The output minimum and maximum values used in normalization mode. This parameter is disabled in standardization mode and is only enabled if outputRangeMode is set to OTHER. Vector2d Any value {0.f, 255.f}
input
intensityOutputStatistics
The mean and standard deviation values used in standardization mode. This parameter is disabled in normalization mode and is only enabled if outputRangeMode is set to OTHER. Vector2d Any value {0.f, 1.f}
input
outputType
The output image data type.
UNSIGNED_INTEGER_8_BIT The output image data type is 1 byte depth. Its possible intensities are unsigned integer from 0 to 255.
UNSIGNED_INTEGER_16_BIT The output image data type is 2 bytes depth. Its possible intensities are unsigned integer from 0 to 65,535.
UNSIGNED_INTEGER_32_BIT The output image data type is 4 bytes depth. Its possible intensities are signed integer from 0 to 4,294,967,295.
SIGNED_INTEGER_8_BIT The output image data type is 1 byte depth. Its possible intensities are signed integer from -128 to 127.
SIGNED_INTEGER_16_BIT The output image data type is 2 bytes depth. Its possible intensities are signed integer from -32,768 to 32,767.
SIGNED_INTEGER_32_BIT The output image data type is 4 bytes depth. Its possible intensities are signed integer from -2,147,483,648 to 2,147,483,647.
FLOAT_32_BIT The output image data type is 4 bytes depth. Its possible intensities are unsigned floating-point from -3.4E38 to 3.4E38.
FLOAT_64_BIT The output image data type is 8 bytes depth. Its possible intensities are unsigned floating-point from -1.7E308 to 1.7E308.
SAME_AS_INPUT The output image has the same type as the input image.
Enumeration SAME_AS_INPUT
output
outputImage
The output image. Its dimensions are forced to the same values as the input. Its data type is user-defined. Image nullptr
Parameter Name Description Type Supported Values Default Value
input
input_image
The input image stack to normalize. If the input is a 3D volume, it will be considered as a stack of XY images. image Grayscale or Multispectral None
input
scaling_mode
The type of rescaling to apply on each slice.
STANDARDIZATION The scaling is performed by subtracting the mean and dividing by the standard deviation.
NORMALIZATION The scaling is performed by subtracting the minimum and dividing by data range.
enumeration STANDARDIZATION
input
input_range_mode
The way to define the input intensity range, applied on each slice of the stack.
MIN_MAX The input range is the minimum and maximum of each slice.
PERCENTILE The input range is defined by two user-defined percentiles, computed on each slice.
OTHER The input range is between user-defined bounds [a,b].
enumeration MIN_MAX
input
percentage_input_range
The low and high histogram percentile to use when the input range mode is set to PERCENTILE (in percent). This parameter is ignored with other input range modes. vector2d [0, 100] [2, 98]
input
intensity_input_range
The input intensity range [a, b] to use when the input range mode is set to OTHER. This parameter is ignored with other input range modes. vector2d Any value [0, 255]
input
scaling_scope
The scope for computing the output parameters (mean, standard deviation, percentiles, minimum or maximum).
GLOBAL The output parameters are computed globally on the input stack.
SLICE_AVERAGING The output parameters are computed independently on each slice of the stack, and then averaged.
enumeration GLOBAL
input
output_range_mode
The way to define the destination intensity range.
MIN_MAX The destination range is the minimum and maximum, computed on the entire input data.
PERCENTILE The output range is defined by two user-defined percentiles, computed on the entire input data.
OTHER The output range is defined by two user-defined values.
enumeration MIN_MAX
input
percentage_output_range
The low and high histogram percentile to use when the output range mode is set to PERCENTILE (in percent). This parameter is ignored with other output range modes. vector2d [0, 100] [2, 98]
input
intensity_output_range
The output minimum and maximum values used in normalization mode. This parameter is disabled in standardization mode and is only enabled if outputRangeMode is set to OTHER. vector2d Any value [0, 255]
input
intensity_output_statistics
The mean and standard deviation values used in standardization mode. This parameter is disabled in normalization mode and is only enabled if outputRangeMode is set to OTHER. vector2d Any value [0, 1]
input
output_type
The output image data type.
UNSIGNED_INTEGER_8_BIT The output image data type is 1 byte depth. Its possible intensities are unsigned integer from 0 to 255.
UNSIGNED_INTEGER_16_BIT The output image data type is 2 bytes depth. Its possible intensities are unsigned integer from 0 to 65,535.
UNSIGNED_INTEGER_32_BIT The output image data type is 4 bytes depth. Its possible intensities are signed integer from 0 to 4,294,967,295.
SIGNED_INTEGER_8_BIT The output image data type is 1 byte depth. Its possible intensities are signed integer from -128 to 127.
SIGNED_INTEGER_16_BIT The output image data type is 2 bytes depth. Its possible intensities are signed integer from -32,768 to 32,767.
SIGNED_INTEGER_32_BIT The output image data type is 4 bytes depth. Its possible intensities are signed integer from -2,147,483,648 to 2,147,483,647.
FLOAT_32_BIT The output image data type is 4 bytes depth. Its possible intensities are unsigned floating-point from -3.4E38 to 3.4E38.
FLOAT_64_BIT The output image data type is 8 bytes depth. Its possible intensities are unsigned floating-point from -1.7E308 to 1.7E308.
SAME_AS_INPUT The output image has the same type as the input image.
enumeration SAME_AS_INPUT
output
output_image
The output image. Its dimensions are forced to the same values as the input. Its data type is user-defined. image None
Parameter Name Description Type Supported Values Default Value
input
inputImage
The input image stack to normalize. If the input is a 3D volume, it will be considered as a stack of XY images. Image Grayscale or Multispectral null
input
scalingMode
The type of rescaling to apply on each slice.
STANDARDIZATION The scaling is performed by subtracting the mean and dividing by the standard deviation.
NORMALIZATION The scaling is performed by subtracting the minimum and dividing by data range.
Enumeration STANDARDIZATION
input
inputRangeMode
The way to define the input intensity range, applied on each slice of the stack.
MIN_MAX The input range is the minimum and maximum of each slice.
PERCENTILE The input range is defined by two user-defined percentiles, computed on each slice.
OTHER The input range is between user-defined bounds [a,b].
Enumeration MIN_MAX
input
percentageInputRange
The low and high histogram percentile to use when the input range mode is set to PERCENTILE (in percent). This parameter is ignored with other input range modes. Vector2d [0, 100] {2f, 98f}
input
intensityInputRange
The input intensity range [a, b] to use when the input range mode is set to OTHER. This parameter is ignored with other input range modes. Vector2d Any value {0f, 255f}
input
scalingScope
The scope for computing the output parameters (mean, standard deviation, percentiles, minimum or maximum).
GLOBAL The output parameters are computed globally on the input stack.
SLICE_AVERAGING The output parameters are computed independently on each slice of the stack, and then averaged.
Enumeration GLOBAL
input
outputRangeMode
The way to define the destination intensity range.
MIN_MAX The destination range is the minimum and maximum, computed on the entire input data.
PERCENTILE The output range is defined by two user-defined percentiles, computed on the entire input data.
OTHER The output range is defined by two user-defined values.
Enumeration MIN_MAX
input
percentageOutputRange
The low and high histogram percentile to use when the output range mode is set to PERCENTILE (in percent). This parameter is ignored with other output range modes. Vector2d [0, 100] {2f, 98f}
input
intensityOutputRange
The output minimum and maximum values used in normalization mode. This parameter is disabled in standardization mode and is only enabled if outputRangeMode is set to OTHER. Vector2d Any value {0f, 255f}
input
intensityOutputStatistics
The mean and standard deviation values used in standardization mode. This parameter is disabled in normalization mode and is only enabled if outputRangeMode is set to OTHER. Vector2d Any value {0f, 1f}
input
outputType
The output image data type.
UNSIGNED_INTEGER_8_BIT The output image data type is 1 byte depth. Its possible intensities are unsigned integer from 0 to 255.
UNSIGNED_INTEGER_16_BIT The output image data type is 2 bytes depth. Its possible intensities are unsigned integer from 0 to 65,535.
UNSIGNED_INTEGER_32_BIT The output image data type is 4 bytes depth. Its possible intensities are signed integer from 0 to 4,294,967,295.
SIGNED_INTEGER_8_BIT The output image data type is 1 byte depth. Its possible intensities are signed integer from -128 to 127.
SIGNED_INTEGER_16_BIT The output image data type is 2 bytes depth. Its possible intensities are signed integer from -32,768 to 32,767.
SIGNED_INTEGER_32_BIT The output image data type is 4 bytes depth. Its possible intensities are signed integer from -2,147,483,648 to 2,147,483,647.
FLOAT_32_BIT The output image data type is 4 bytes depth. Its possible intensities are unsigned floating-point from -3.4E38 to 3.4E38.
FLOAT_64_BIT The output image data type is 8 bytes depth. Its possible intensities are unsigned floating-point from -1.7E308 to 1.7E308.
SAME_AS_INPUT The output image has the same type as the input image.
Enumeration SAME_AS_INPUT
output
outputImage
The output image. Its dimensions are forced to the same values as the input. Its data type is user-defined. Image null

Object Examples

auto foam = readVipImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "foam.vip" );

StackRescaleIntensity stackRescaleIntensityAlgo;
stackRescaleIntensityAlgo.setInputImage( foam );
stackRescaleIntensityAlgo.setScalingMode( StackRescaleIntensity::ScalingMode::STANDARDIZATION );
stackRescaleIntensityAlgo.setInputRangeMode( StackRescaleIntensity::RangeMode::MIN_MAX );
stackRescaleIntensityAlgo.setPercentageInputRange( {2, 98} );
stackRescaleIntensityAlgo.setIntensityInputRange( {0, 255} );
stackRescaleIntensityAlgo.setScalingScope( StackRescaleIntensity::ScalingScope::GLOBAL );
stackRescaleIntensityAlgo.setOutputRangeMode( StackRescaleIntensity::RangeMode::MIN_MAX );
stackRescaleIntensityAlgo.setPercentageOutputRange( {2, 98} );
stackRescaleIntensityAlgo.setIntensityOutputRange( {0, 255} );
stackRescaleIntensityAlgo.setIntensityOutputStatistics( {0, 1} );
stackRescaleIntensityAlgo.setOutputType( StackRescaleIntensity::OutputType::SAME_AS_INPUT );
stackRescaleIntensityAlgo.execute();

std::cout << "outputImage:" << stackRescaleIntensityAlgo.outputImage()->toString();

foam = imagedev.read_vip_image(imagedev_data.get_image_path("foam.vip"))

stack_rescale_intensity_algo = imagedev.StackRescaleIntensity()
stack_rescale_intensity_algo.input_image = foam
stack_rescale_intensity_algo.scaling_mode = imagedev.StackRescaleIntensity.STANDARDIZATION
stack_rescale_intensity_algo.input_range_mode = imagedev.StackRescaleIntensity.MIN_MAX
stack_rescale_intensity_algo.percentage_input_range = [2, 98]
stack_rescale_intensity_algo.intensity_input_range = [0, 255]
stack_rescale_intensity_algo.scaling_scope = imagedev.StackRescaleIntensity.GLOBAL
stack_rescale_intensity_algo.output_range_mode = imagedev.StackRescaleIntensity.MIN_MAX
stack_rescale_intensity_algo.percentage_output_range = [2, 98]
stack_rescale_intensity_algo.intensity_output_range = [0, 255]
stack_rescale_intensity_algo.intensity_output_statistics = [0, 1]
stack_rescale_intensity_algo.output_type = imagedev.StackRescaleIntensity.SAME_AS_INPUT
stack_rescale_intensity_algo.execute()

print("output_image:", str(stack_rescale_intensity_algo.output_image))

ImageView foam = Data.ReadVipImage( @"Data/images/foam.vip" );

StackRescaleIntensity stackRescaleIntensityAlgo = new StackRescaleIntensity
{
    inputImage = foam,
    scalingMode = StackRescaleIntensity.ScalingMode.STANDARDIZATION,
    inputRangeMode = StackRescaleIntensity.RangeMode.MIN_MAX,
    percentageInputRange = new double[]{2, 98},
    intensityInputRange = new double[]{0, 255},
    scalingScope = StackRescaleIntensity.ScalingScope.GLOBAL,
    outputRangeMode = StackRescaleIntensity.RangeMode.MIN_MAX,
    percentageOutputRange = new double[]{2, 98},
    intensityOutputRange = new double[]{0, 255},
    intensityOutputStatistics = new double[]{0, 1},
    outputType = StackRescaleIntensity.OutputType.SAME_AS_INPUT
};
stackRescaleIntensityAlgo.Execute();

Console.WriteLine( "outputImage:" + stackRescaleIntensityAlgo.outputImage.ToString() );

Function Examples

auto foam = readVipImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "foam.vip" );

auto result = stackRescaleIntensity( foam, StackRescaleIntensity::ScalingMode::STANDARDIZATION, StackRescaleIntensity::RangeMode::MIN_MAX, {2, 98}, {0, 255}, StackRescaleIntensity::ScalingScope::GLOBAL, StackRescaleIntensity::RangeMode::MIN_MAX, {2, 98}, {0, 255}, {0, 1}, StackRescaleIntensity::OutputType::SAME_AS_INPUT );

std::cout << "outputImage:" << result->toString();

foam = imagedev.read_vip_image(imagedev_data.get_image_path("foam.vip"))

result = imagedev.stack_rescale_intensity(foam, imagedev.StackRescaleIntensity.STANDARDIZATION, imagedev.StackRescaleIntensity.MIN_MAX, [2, 98], [0, 255], imagedev.StackRescaleIntensity.GLOBAL, imagedev.StackRescaleIntensity.MIN_MAX, [2, 98], [0, 255], [0, 1], imagedev.StackRescaleIntensity.SAME_AS_INPUT)

print("output_image:", str(result))

ImageView foam = Data.ReadVipImage( @"Data/images/foam.vip" );

IOLink.ImageView result = Processing.StackRescaleIntensity( foam, StackRescaleIntensity.ScalingMode.STANDARDIZATION, StackRescaleIntensity.RangeMode.MIN_MAX, new double[]{2, 98}, new double[]{0, 255}, StackRescaleIntensity.ScalingScope.GLOBAL, StackRescaleIntensity.RangeMode.MIN_MAX, new double[]{2, 98}, new double[]{0, 255}, new double[]{0, 1}, StackRescaleIntensity.OutputType.SAME_AS_INPUT );

Console.WriteLine( "outputImage:" + result.ToString() );





© 2025 Thermo Fisher Scientific Inc. All rights reserved.