HALCON Reference Manual 10.0.2
Table of Contents / Filters / Arithmetic ClassesClassesClasses | | | Operators

sub_imagesub_imagesub_imageSubImageSubImage (Operator)

Name

sub_imagesub_imagesub_imageSubImageSubImage — Subtract two images.

Signature

sub_image(ImageMinuend, ImageSubtrahend : ImageSub : Mult, Add : )

Herror sub_image(const Hobject ImageMinuend, const Hobject ImageSubtrahend, Hobject* ImageSub, double Mult, double Add)

Herror T_sub_image(const Hobject ImageMinuend, const Hobject ImageSubtrahend, Hobject* ImageSub, const Htuple Mult, const Htuple Add)

Herror sub_image(Hobject ImageMinuend, Hobject ImageSubtrahend, Hobject* ImageSub, const HTuple& Mult, const HTuple& Add)

HImage HImage::SubImage(const HImage& ImageSubtrahend, const HTuple& Mult, const HTuple& Add) const

HImageArray HImageArray::SubImage(const HImageArray& ImageSubtrahend, const HTuple& Mult, const HTuple& Add) const

void HOperatorSetX.SubImage(
[in] IHUntypedObjectX* ImageMinuend, [in] IHUntypedObjectX* ImageSubtrahend, [out] IHUntypedObjectX** ImageSub, [in] VARIANT Mult, [in] VARIANT Add)

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

static void HOperatorSet.SubImage(HObject imageMinuend, HObject imageSubtrahend, out HObject imageSub, HTuple mult, HTuple add)

HImage HImage.SubImage(HImage imageSubtrahend, HTuple mult, HTuple add)

HImage HImage.SubImage(HImage imageSubtrahend, double mult, double add)

Description

The operator sub_imagesub_imagesub_imageSubImageSubImage subtracts two images. The gray values (g1,g2)

                g' := (g1 - g2) * Mult + Add

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

Several images can be processed in one call. In this case both input parameters contain the same number of images which are then processed in pairs. An output image is generated for every pair.

Please note that the runtime of the operator varies with different control parameters. For frequently used combinations special optimizations are used. Additionally, for byte, int2, and uint2 images special optimizations are implemented that use SIMD technology. The actual application of these special optimizations is controlled by the system parameter 'mmx_enable'"mmx_enable""mmx_enable""mmx_enable""mmx_enable" (see set_systemset_systemset_systemSetSystemSetSystem). If 'mmx_enable'"mmx_enable""mmx_enable""mmx_enable""mmx_enable" is set to 'true'"true""true""true""true" (and the SIMD instruction set is available), the internal calculations are performed using SIMD technology.

sub_imagesub_imagesub_imageSubImageSubImage 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 sub_imagesub_imagesub_imageSubImageSubImage 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")set_system("mmx_enable","false")SetSystem("mmx_enable","false")SetSystem("mmx_enable","false").

Parallelization

Parameters

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

Minuend(s).

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

Subtrahend(s).

ImageSubImageSubImageSubImageSubimageSub (output_object)  (multichannel-)image(-array) → objectHImageHImageHImageXHobject * (byte / int1 / int2 / uint2 / int4 / int8 / real / direction / cyclic / complex)

Result image(s) by the subtraction.

MultMultMultMultmult (input_control)  number → HTupleHTupleVARIANTHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong) (double / Hlong)

Correction factor.

Default value: 1.0

Suggested values: 0.0, 1.0, 2.0, 3.0, 4.0

Typical range of values: -255.0 ≤ Mult Mult Mult Mult mult ≤ 255.0

Minimum increment: 0.001

Recommended increment: 0.1

AddAddAddAddadd (input_control)  number → HTupleHTupleVARIANTHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong) (double / Hlong)

Correction value.

Default value: 128.0

Suggested values: 0.0, 128.0, 256.0

Typical range of values: -512.0 ≤ Add Add Add Add add ≤ 512.0

Minimum increment: 0.01

Recommended increment: 1.0

Example (HDevelop)

read_image(Image0,'fabrik')
disp_image(Image0,WindowHandle)
read_image(Image1,'monkey')
disp_image(Image1,WindowHandle)
sub_image(Image0,Image1,Result,2.0,10.0)
disp_image(Result,WindowHandle)

Example (C)

read_image(&Image0,"fabrik");
disp_image(Image0,WindowHandle);
read_image(&Image1,"monkey");
disp_image(Image1,WindowHandle);
sub_image(Image0,Image1,&Result,2.0,10.0);
disp_image(Result,WindowHandle);

Example (HDevelop)

read_image(Image0,'fabrik')
disp_image(Image0,WindowHandle)
read_image(Image1,'monkey')
disp_image(Image1,WindowHandle)
sub_image(Image0,Image1,Result,2.0,10.0)
disp_image(Result,WindowHandle)

Example (HDevelop)

read_image(Image0,'fabrik')
disp_image(Image0,WindowHandle)
read_image(Image1,'monkey')
disp_image(Image1,WindowHandle)
sub_image(Image0,Image1,Result,2.0,10.0)
disp_image(Result,WindowHandle)

Example (HDevelop)

read_image(Image0,'fabrik')
disp_image(Image0,WindowHandle)
read_image(Image1,'monkey')
disp_image(Image1,WindowHandle)
sub_image(Image0,Image1,Result,2.0,10.0)
disp_image(Result,WindowHandle)

Result

The operator sub_imagesub_imagesub_imageSubImageSubImage 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>)set_system("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>) If necessary an exception is raised.

Possible Successors

dual_thresholddual_thresholddual_thresholdDualThresholdDualThreshold

Alternatives

mult_imagemult_imagemult_imageMultImageMultImage, add_imageadd_imageadd_imageAddImageAddImage

See also

add_imageadd_imageadd_imageAddImageAddImage, mult_imagemult_imagemult_imageMultImageMultImage, dyn_thresholddyn_thresholddyn_thresholdDynThresholdDynThreshold, check_differencecheck_differencecheck_differenceCheckDifferenceCheckDifference

Module

Foundation

Table of Contents / Filters / Arithmetic ClassesClassesClasses | | | Operators
HALCON Reference Manual 10.0.2 Copyright © 1996-2011 MVTec Software GmbH