Processing

ImageDev contains different types of algorithms:

• Algorithms working on images and providing output images (processing filters).
• Algorithms providing numerical results (analysis algorithms).
• Algorithms working on vector data that represent segments of object edges (polygonal approximation).
• Algorithms working only on 2D images.
• Algorithms working only on 3D images.
• Algorithms working on both 2D and 3D images.

Class and Function programming modes

ImageDev provides two modes for invoking an image processing algorithm: a class and a function programming mode.
Each algorithm documentation exposes two code snippets illustrating the use of both modes.

Function mode

In Function programming mode, the algorithm is directly launched when calling the function.
The result can be obtained either as a returned value, or as the last parameter(s) of the function prototype. This mode is simpler to use for algorithms with few parameters and, in some ways, in languages where parameters can be omitted, like in Python. This mode saves memory by reusing already allocated data which can be, for eligible algorithms, the input data (in situ processing).

With function mode, outputs are returned by the function. When an algorithm generates several outputs:

• A specific structure is returned in C++ and C#.
• A tuple is returned in Python.

Image outputs also can be returned as parameters of the function. This option is particularly useful for reusing the allocated memory of a temporary image or working in situ when the algorithm is eligible.

Class mode

In Class programming mode, the algorithm is instantiated as a class object and is launched when calling its execute() method.
This mode is simpler to use for algorithms with many parameters, when most of parameters have to keep their default value.
With class mode, a parameter can be:

• Written in C++ as argument of a method named with the set prefix in front of the parameter name
• Written in C# and Python by assigning it to a property named with the parameter name (no set prefix)
• Read as returned value of a method or property named with the parameter name (no get prefix)

To save memory, it is possible to set already allocated data as output which can be, for eligible algorithms, the input data (in situ processing). If the output data is not set, new data is allocated.

API change policy

ImageDev aims to be binary compatible between its successive versions. However, in some very specific cases, compatibility breaks can occur.
The API compatibility is fully ensured between two versions when using the class mode in all languages.
With the function mode, the API compatibility is fully ensured in C++.
In C# and Python, some API break can rarely occur when a parameter is added to or removed from an algorithm.
When an API change occurs, the old behavior is maintained during two versions and is then definitely removed. A warning is sent to inform the user which feature must be used instead and when the legacy behavior will disappear.
The release notes detail all the deletions made in the current release and list the features that will be removed in future releases. If you feel that a deletion puts your project at risk, please contact the ImageDev technical support.

Algorithm deprecation

When an algorithm is deprecated, a warning is generated to inform the user when it will be removed. The substitute solution is indicated in the warning message.
In C++ and C#, the warning message is displayed at the build step if a deprecated feature is used in the project. In Python, the warning message is displayed at the execution.

Parameter deprecation

When an algorithm parameter is deprecated:

• In class mode, a warning is displayed. It indicates when the parameter will be removed, and the recommendations related to this suppression.
• In C++ function mode, a warning message is displayed. It indicates when the parameter will be permanently deleted and the new prototype of the function.
• In C# and Python function modes, the signature using the legacy parameter no longer compiles or runs.

Note: Generally, no parameter is really removed from the ImageDev API. The purpose of parameter deprecation is mostly for renaming a parameter that is incorrectly named.

Parameter addition

• In class mode, nothing happens.
• In C++ function mode, a warning message is displayed. It indicates when the parameter must be filled in and the new prototype of the function.
• In C# and Python function modes, the signature not using the new parameter no longer compiles or runs.

Naming conventions

Capitalization Rules

For a given type of identifier, ImageDev uses the recommended case in each language. $$ \begin{array}{|l|l|l|l|} \hline \textbf{Type of Identifier} & \textbf{C++ Case} & \textbf{Python Case} & \textbf{C# Case}\\ \hline \textbf{Class} & \mbox{PascalCase} & \mbox{PascalCase} & \mbox{PascalCase}\\ \hline \textbf{Function} & \mbox{camelCase} & \mbox{snake_case} & \mbox{PascalCase}\\ \hline \textbf{Class method} & \mbox{camelCase} & \mbox{snake_case} & \mbox{PascalCase}\\ \hline \textbf{Argument} & \mbox{camelCase} & \mbox{snake_case} & \mbox{camelCase}\\ \hline \textbf{Enumerate Type} & \mbox{PascalCase} & \mbox{PascalCase} & \mbox{PascalCase}\\ \hline \textbf{Enumerate Value} & \mbox{SCREAMING_SNAKE_CASE} & \mbox{SCREAMING_SNAKE_CASE} & \mbox{SCREAMING_SNAKE_CASE}\\ \hline \end{array} $$

Dimensional compatibility

ImageDev algorithm names may end with 2d or 3d:

• 2d indicates that an algorithm is dedicated to deal with 2D images.
• 3d indicates that an algorithm is dedicated to deal with 3D images.
• If this information is omitted, the algorithm works on both types of images.

Parameter naming

Input and output data

An algorithm parameter (a function argument or a class member) can be:

• An input data object (generally an image)
• An output data object
• A computation setting

By convention:

• A parameter name beginning with input represents an input data object.
• A parameter name beginning with output represents an output data object.
• A parameter name beginning neither with input , nor output represents a computation setting.
• Exception: the outputDataType parameter, available in several ImageDev algorithms, is an enumerated value that represents the type to assign to the output data.

A parameter name beginning with input or output represents data. A key-word specifies the type of data:

• A parameter name containing Image represents an image (an ImageView object).
• A parameter name containing Analysis represents a result of analysis; that is, a list of measurements for a set of objects(AnalysisMeasurement object).
• A parameter name containing Segment represents a chain of segments; that is, a list of vertices obtained from a polygonal approximation of objects edges.
• A parameter named outputMeasurement represents a result object specific to the algorithm. It generally represents the measurement results of a global analysis of an image (for example, Area2d::outputMeasurement ).

Kernel size parameters

In many ImageDev processing filters, a parameter represents the size of a moving window applied on the input image to compute the output image. Generally, this window is a square in 2D and a cube in 3D which must have an odd side length in pixels, but, in some cases, it also can be a disk or a ball.
By convention:

• A parameter name beginning with kernelSize represents a full size of a window side length. Some algorithms may raise an exception when this parameter is set to an even value (for example, BilateralFilter2d::kernelSizeX ).
• A parameter name beginning with kernelRadius represents a half size of a window side length or a radius for disk and ball kernels (for example, MedianFilter2d::kernelRadius ).

Disk processing

ImageDev disk processing features allow the application of computational algorithms on data stored on disk.
To access an image stored on disk without loading the whole data set into memory, the "ioformat::openView" function should be used rather than the "ioformat::readImage" function.
To create temporary images on disk, the "iolink::ImageViewFactory::allocateOnDisk" function should be used. The associated file is automatically deleted when the image is no longer used.
The following example illustrates the use of disk images.

Example