ClassesClassesClassesClasses | | | | Operators

scale_imagescale_imageScaleImagescale_imageScaleImageScaleImage (Operator)

Name

scale_imagescale_imageScaleImagescale_imageScaleImageScaleImage — Scale the gray values of an image.

Signature

scale_image(Image : ImageScaled : Mult, Add : )

Herror scale_image(const Hobject Image, Hobject* ImageScaled, double Mult, double Add)

Herror T_scale_image(const Hobject Image, Hobject* ImageScaled, const Htuple Mult, const Htuple Add)

Herror scale_image(Hobject Image, Hobject* ImageScaled, const HTuple& Mult, const HTuple& Add)

HImage HImage::ScaleImage(const HTuple& Mult, const HTuple& Add) const

HImageArray HImageArray::ScaleImage(const HTuple& Mult, const HTuple& Add) const

void ScaleImage(const HObject& Image, HObject* ImageScaled, const HTuple& Mult, const HTuple& Add)

HImage HImage::ScaleImage(const HTuple& Mult, const HTuple& Add) const

HImage HImage::ScaleImage(double Mult, double Add) const

void HOperatorSetX.ScaleImage(
[in] IHUntypedObjectX* Image, [out] IHUntypedObjectX*ImageScaled, [in] VARIANT Mult, [in] VARIANT Add)

IHImageX* HImageX.ScaleImage(
[in] VARIANT Mult, [in] VARIANT Add)

static void HOperatorSet.ScaleImage(HObject image, out HObject imageScaled, HTuple mult, HTuple add)

HImage HImage.ScaleImage(HTuple mult, HTuple add)

HImage HImage.ScaleImage(double mult, double add)

Description

The operator scale_imagescale_imageScaleImagescale_imageScaleImageScaleImage scales the input images (ImageImageImageImageImageimage) by the following transformation:

                     g' := g * Mult + Add

If an overflow or an underflow occurs the values are clipped. Note that this is not the case with cyclic and direction images.

This operator can be applied, e.g., to map the gray values of an image, i.e., the interval [GMin,GMax], to the maximum range [0:255]. For this, the parameters are chosen as follows:


      MultMultMultMultMultmult = 255 / (GMax-GMin)         AddAddAddAddAddadd  = - MultMultMultMultMultmult*GMin

The values for GMin and GMax can be determined, e.g., with the operator min_max_graymin_max_grayMinMaxGraymin_max_grayMinMaxGrayMinMaxGray.

Please note that the runtime of the operator varies with different control parameters. For frequently used combinations special optimizations are used. Additionally, special optimizations are implemented that use fixed point arithmetic (for int2 and uint2 images), and further optimizations that use SIMD technology (for byte, int2, and uint2 images). The actual application of these special optimizations is controlled by the system parameters 'int_zooming'"int_zooming""int_zooming""int_zooming""int_zooming""int_zooming" and 'mmx_enable'"mmx_enable""mmx_enable""mmx_enable""mmx_enable""mmx_enable" (see set_systemset_systemSetSystemset_systemSetSystemSetSystem). If 'int_zooming'"int_zooming""int_zooming""int_zooming""int_zooming""int_zooming" is set to 'true'"true""true""true""true""true", the internal calculation is performed using fixed point arithmetic, leading to much shorter execution times. However, the accuracy of the transformed gray values is slightly lower in this mode. The difference to the more accurate calculation (using 'int_zooming'"int_zooming""int_zooming""int_zooming""int_zooming""int_zooming" = 'false'"false""false""false""false""false") is typically less than two gray levels. If 'mmx_enable'"mmx_enable""mmx_enable""mmx_enable""mmx_enable""mmx_enable" is set to 'true'"true""true""true""true""true"(and the SIMD instruction set is available), the internal calculations are performed using fixed point arithmetic and SIMD technology. In this case the setting of 'int_zooming'"int_zooming""int_zooming""int_zooming""int_zooming""int_zooming" is ignored.

scale_imagescale_imageScaleImagescale_imageScaleImageScaleImage can be executed on an OpenCL device for byte, int1, int2, uint2, int4, real, direction, cyclic, and complex images. However, since for OpenCL 1.0 only single precision floating point is supported for all devices, and not all rounding modes are supported, the OpenCL implementation can produce slightly different results from the scalar or SIMD implementations.

Attention

Note that the acceleration gained by SIMD technology is highest on large, compact input regions. However, in rare cases, the execution of scale_imagescale_imageScaleImagescale_imageScaleImageScaleImage might take significantly longer with SIMD technology than without, depending on the input region and the capabilities of the hardware. In these cases, the use of SIMD technology can be avoided by set_system(::'mmx_enable','false':)set_system("mmx_enable","false")SetSystem("mmx_enable","false")set_system("mmx_enable","false")SetSystem("mmx_enable","false")SetSystem("mmx_enable","false").

Parallelization

Parameters

ImageImageImageImageImageimage (input_object)  (multichannel-)image(-array) objectHImageHImageHImageHImageXHobject (byte* / int1* / int2* / uint2* / int4* / int8 / real* / direction* / cyclic* / complex*) *allowed for compute devices

Image(s) whose gray values are to be scaled.

ImageScaledImageScaledImageScaledImageScaledImageScaledimageScaled (output_object)  (multichannel-)image(-array) objectHImageHImageHImageHImageXHobject * (byte* / int1* / int2* / uint2* / int4* / int8 / real* / direction* / cyclic* / complex*) *allowed for compute devices

Result image(s) by the scale.

MultMultMultMultMultmult (input_control)  number HTupleHTupleHTupleVARIANTHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong) (double / Hlong) (double / Hlong)

Scale factor.

Default value: 0.01

Suggested values: 0.001, 0.003, 0.005, 0.008, 0.01, 0.02, 0.03, 0.05, 0.08, 0.1, 0.5, 1.0

Minimum increment: 0.001

Recommended increment: 0.1

AddAddAddAddAddadd (input_control)  number HTupleHTupleHTupleVARIANTHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong) (double / Hlong) (double / Hlong)

Offset.

Default value: 0

Suggested values: 0, 10, 50, 100, 200, 500

Minimum increment: 0.01

Recommended increment: 1.0

Example (HDevelop)

* Complement of the gray values:
scale_image(Image,Invert,-1.0,255.0)

Example (C)

/* simulation of invert for type 'byte' */
byte_invert(Hobject In, Hobject *out)
{
  scale_image(In,Out,-1.0,255.0);
}

Example (HDevelop)

* Complement of the gray values:
scale_image(Image,Invert,-1.0,255.0)

Example (HDevelop)

* Complement of the gray values:
scale_image(Image,Invert,-1.0,255.0)

Example (HDevelop)

* Complement of the gray values:
scale_image(Image,Invert,-1.0,255.0)

Example (HDevelop)

* Complement of the gray values:
scale_image(Image,Invert,-1.0,255.0)

Result

The operator scale_imagescale_imageScaleImagescale_imageScaleImageScaleImage returns the value 2 (H_MSG_TRUE) if the parameters are correct. The behavior in case of empty input (no input images available) is set via the operator set_system(::'no_object_result',<Result>:)set_system("no_object_result",<Result>)SetSystem("no_object_result",<Result>)set_system("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>) Otherwise an exception treatment is carried out.

Possible Predecessors

min_max_graymin_max_grayMinMaxGraymin_max_grayMinMaxGrayMinMaxGray

Alternatives

mult_imagemult_imageMultImagemult_imageMultImageMultImage, add_imageadd_imageAddImageadd_imageAddImageAddImage, sub_imagesub_imageSubImagesub_imageSubImageSubImage

See also

min_max_graymin_max_grayMinMaxGraymin_max_grayMinMaxGrayMinMaxGray

Module

Foundation


ClassesClassesClassesClasses | | | | Operators