CImage Operators

The CImage class supports numerous "operators" as a shorthand for several common operations between images and numbers. This is an object oriented feature, and is akin to" operator overloading" in the C++ language. Operators make it possible for a script to contain expressions like the following:

     ImResult = -(Im^0.5) / 0.08

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

In these expressions, Im, ..., and ImResult all refer to instances of CImage objects. When using operators, it is not necessary to use direct methods such as new, Copy, or Create to first create the result of the expression. In the examples above, Im, ImBias, and ImFlat must exist before the expression is used, but ImResult is created automatically as a new CImage.

All operators have class method counterparts. For example, the alternative to using the + operator is the Add method. A primary difference between the operators and their 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.

Class methods that perform a math operation, such as Add or Pow, automatically create the result image with a floating point data type to maintain numeric precision. 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: Usually in a sequence of operations, all the images must have identical dimensions. If the operations involved have this requirement, then processing will normally stop at the point where the incompatible image is reached in the expression and return the calculation in effect at that point.

Another requirement is that the expression must have a CImage, rather than a number or string, as the first operand to the right of the = sign. This is required so that the expression can be properly understood by the interpreter.

Math 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

Im3 = CImage:new( 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

Im2 = CImage:new( 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

Im3 = CImage:new( 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

Im2 = CImage:new( 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

Im3 = CImage:new( 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

Im2 = CImage:new( 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

Im3 = CImage:new( 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

Im2 = CImage:new( 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

Im3 = CImage:new( 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

Im2 = CImage:new( 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

Im3 = CImage:new( 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

  Im2 = CImage:new( Im1 )

  Im2:Mod( 0.5 )

—Im

Computes the unary minus (or negative) of the image and creates a new CImage for the result. This operation is similar to the Chs method. For example,

  Im2 = -Im1

is equivalent to

Im2 = CImage:new( 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. This operation is similar to the CompareEQ method. For example,

  if Im2 == Im1 then Func() end

is equivalent to

  if Im2:CompareEQ( Im1 ) == true then Func() 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. This operation is similar to the CompareLE method. For example,

  if Im2 <= Im1 then Func() end

is equivalent to

  if Im2:CompareLE( Im1 ) == true then Func() 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. This operation is similar to the CompareLT method. For example,

  if Im2 < Im1 then Func() end

is equivalent to

  if Im2:CompareLT( Im1 ) == true then Func() end

Choosing to use Operators or 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 = ((Im - ImBias - ImDark) - 100) / ImFlat

To do the same calculation using class methods, we have the following script:

     Im:SetDatatype( "float" )

     Im:Sub( ImBias )

     Im:Sub( ImDark )

     Im:Sub( 100 )

     Im:Div( ImFlat )

     ImResult = Im:Mul( 1.0024 )

 

The advantages of using operators include

    reduced script complexity;

    mathematical expressions may be more readable.

One side effect of operators is that intermediate objects (here, CImage objects) are temporarily created and their memory is not released until the script processor decides they are to be "garbage collected". In the operator example, above, several intermediate images are created when processing the expression (more on this below). Garbage collection may occur at the end of the script, at the end of the local function where the intermediate objects are used, or somewhere else. Using methods instead of operators, the number of intermediate images can be controlled. If you have plenty of memory compared with the amount required by the CImage's involved, then this side effect usually is not important.

For example, in evaluating the operator-based expression above, Im — ImBias creates a CImage result, then result — ImDark creates another result. Then 100 is subtracted from that result to make yet another result. In fact, the expression creates 5 new CImage's that are temporary. By comparison, the alternative script works by repeatedly changing the CImage Im and and does not, technically, even need to create ImResult since Im contains all the changes. Conversely, notice that Im is altered by each step of the method-based script whereas the operators leave Im intact. If you want the method-based script to leave Im intact, simply construct a copy of Im before it is altered, as in Im2 = CImage:new( Im ).

Related Topics

CImage class