CImage:Math Operators

The CImage class supports numerous math operations between images and numbers. This is an object oriented feature, similar to operator overloading in other modern computer languages.

Class operators make it possible for a script to contain expressions like the following:

     ImResult = 0.08 / -(Im ^ 0.5)

     ImResult = 1.0024 * ((Im - ImBias - ImDark) - 100) / ImFlat

All operators have class method counterparts. For example, the alternative to using the operator + would be the method Add. A primary difference between the operators and corresponding methods is that many of the operators create the result as a new CImage object, whereas the method operates on the object it is called from. The operators do not modify the original image, although the class methods do modify the CImage the method is called from. These differences are described in the table below.

Methods that perform a math operation, such as Add or Pow create the result image with a floating point pixel type. If you do not want to create a new image or do not want the operation to use a "real" pixel format, use the class method instead.

NOTE: Since expressions are evaluated left to right, the order of objects is important. When a table or value is to be used by the CImage object in an expression, the CImage object must precede the table or value so that CImage operator methods are called to apply the table or value. For example, Im3=Im2+25.2 is valid, but Im3=25.2+Im2 causes a script error because a raw number like 25.2 has no methods.

Operators

 

Im1 + Im2

Adds the values of two images and creates a new CImage for the result. This operation is similar to the Add method. For example,

Im3 = Im1 + Im2

is equivalent to the following:

Im3 = new_image( Im1 )

Im3:Add( Im2 )

Im1 + num

Adds a number to the image values and creates a new CImage for the result. This operation is similar to the Add method. For example,

Im2 = Im1 + 0.5

is equivalent to the following:

Im2 = new_image( Im1 )

Im2:Add( 0.5 )

Im1 - Im2

Subtracts the values of Im2 from Im1 and creates a new CImage for the result. This operation is similar to the Sub method. For example,

Im3 = Im1 - Im2

is equivalent to the following:

Im3 = new_image( Im1 )

Im3:Sub( Im2 )

Im1 - num

Subtracts a number from the image values and creates a new CImage for the result. This operation is similar to the Sub method. For example,

Im2 = Im1 - 0.5

is equivalent to the following:

Im2 = new_image( Im1 )

Im2:Sub( 0.5 )

Im1 * Im2

Multiplies the values of two images and creates a new CImage for the result. This operation is similar to the Mul method. For example,

Im3 = Im1 * Im2

is equivalent to the following:

Im3 = new_image( Im1 )

Im3:Mul( Im2 )

Im1 * num

Multiplies the values of an image by a number and creates a new CImage for the result. This operation is similar to the Mul method. For example,

Im2 = Im1 * 0.5 is equivalent to the following:

Im2 = new_image( Im1 )

Im2:Mul( 0.5 )

Im1 / Im2

Divides the values of Im1 by those of Im2 and creates a new CImage for the result. This operation is similar to the Div method. For example,

Im3 = Im1 / Im2

is equivalent to the following:

Im3 = new_image( Im1 )

Im3:Div( Im2 )

Im1 / num

Divides the image values by a number and creates a new CImage for the result. This operation is similar to the Div method. For example,

Im2 = Im1 / 0.5 is equivalent to the following:

Im2 = new_image( Im1 )

Im2:Div( 0.5 )

Im1 ^ Im2

Raises the values of Im1 to the power of Im2, pixel by pixel, and creates a new CImage for the result. This operation is similar to the Pow method. For example,

Im3 = Im1 ^ Im2

is equivalent to the following:

Im3 = new_image( Im1 )

Im3:Pow( Im2 )

Im1 ^ num

Raises the image values to a numeric power and creates a new CImage for the result. This operation is similar to the Pow method. For example,

Im2 = Im1 ^ 0.5

is equivalent to the following:

Im2 = new_image( Im1 )

Im2:Pow( 0.5 )

Im1 % Im2

Computes the modulus (or remainder) of Im1 divided by Im2 and creates a new CImage for the result. This operation is similar to the Mod method. For example,

Im3 = Im1 % Im2 is equivalent to the following:

Im3 = new_image( Im1 )

Im3:Mod( Im2 )

Im1 % num

Computes the modulus (or remainder) of image values divided by a number and creates a new CImage for the result. This operation is similar to the Mod method. For example,

Im2 = Im1 % 0.5

is equivalent to the following:

Im2 = new_image( Im1 )

Im2:Mod( 0.5 )

-Im

Computes the unary minus of the image by negating its pixel values, creating a new CImage for the result. This operation is similar to the Chs method. For example,

Im2 = -Im1

is equivalent to the following:

Im2 = new_image( Im1 )

Im2:Chs()

==

Compares two images on a pixel by pixel basis. Returns true if every pixel value in Im1 is equal to the corresponding pixel in Im2. For example,

if Im2 == Im1 then MyFunc() end

<=

Compares two images on a pixel by pixel basis. Returns true if every pixel value in Im1 is less than or equal to the corresponding pixel in Im2. For example,

if Im2 <= Im1 then MyFunc() end

<

Compares two images on a pixel by pixel basis. Returns true if every pixel value in Im1 is less than the corresponding pixel in Im2. For example,

if Im2 < Im1 then MyFunc() end

Comparison between Operators and Methods

The introduction above gives an example of a complex expression using math operators. Let's compare an operator-based expression with its method-based equivalent script. Here is the expression using operators:

     ImResult = 1.0024 * ((Im - ImBias - ImDark) - 100) / ImFlat

To realize the same result using class methods, we have the following script:

     Im:SetPixelType( "float" )

     Im:Sub( ImBias )

     Im:Sub( ImDark )

     Im:Sub( 100 )

     Im:Div( ImFlat )

     Im:Mul( 1.0024 )

The advantages of using operators are reduced script complexity and expressions that are more intelligible. However, one drawback to the operator based expression is that it creates a number of intermediate images and none of them has its memory released before the objects in the expression are "garbage collected" after going "out of scope", which may be the end of the script or the end of the local function where they are used.

For example, in evaluating the operator-based expression, Im - ImBias creates a CImage result, then result - ImDark creates another result. Then 100 is subtracted from that result to make yet another result, and so on. In fact, the expression creates 5 new CImage's that are "hidden" and you can not manually delete. There is no way to avoid this. By comparison, the alternative script works by repeatedly changing the CImage Im and and does not even need to create a new image to hold the result. However, Im is altered by the method based script whereas the operators leave Im intact. If you want the method-based script to leave Im intact, simply construct a new copy of Im at the beginning, as in Im2 = new_image( Im ), and then call the methods from Im2. There is no work-around to these differences in behavior; so goes object-oriented programming. If you do not care that intermediate images are created, then using the expression can make your scripts far easier to understand.

Related Topics

CImage class


Mira Pro x64 Script User's Guide, Copyright Ⓒ 2023 Mirametrics, Inc. All Rights Reserved.