OrsFilterEditable_a53a39ba632311e78d649cb6d012cc4e

Abstract class of the image filter plugin definition.

The purpose of this class is to give uniform behavior for image filter plugins. This behavior is based on the condition of partial computing over a subset of the given inputs and write into specific location of the given outputs. This is done in order to be time and memory efficient.

Each image filter plugin class inheriting this abstract class can support multiple image filters. Once the image filter to use is specified, the specifications of all the inputs and outputs are given, then the method ORSServiceClass.OrsPlugin.orsabstractfilterplugin.OrsAbstractFilterPlugin.apply() is called to perform the actual image filtering computation.

Computation area

Image filters supported by this class consider the data matrix of every input and output as being aligned, using only the matrix indexes as spatial information.

The method ORSServiceClass.OrsPlugin.orsabstractfilterplugin.OrsAbstractFilterPlugin.apply() receives the computation area with the minimal and maximal indexes in X, Y, Z and T. This is the area for which all outputs should be overwritten with the filter results; nothing else should be overwritten in the outputs.

In many situations, the computation of the filter result for a given computation area might require only the data in the neighborhood of this computation area from the inputs. This is the case, for example, for convolution filters like Gaussian, Mean or Median. The methods ORSServiceClass.OrsPlugin.orsabstractfilterplugin.OrsAbstractFilterPlugin.getLengthDependenceX(), ORSServiceClass.OrsPlugin.orsabstractfilterplugin.OrsAbstractFilterPlugin.getLengthDependenceY() and ORSServiceClass.OrsPlugin.orsabstractfilterplugin.OrsAbstractFilterPlugin.getLengthDependenceZ() are called so that the filter can tell what is the size of that requested neighborhood. To avoid using unnecessary memory, inputs may therefore be given to the filter with only that required data to perform the computation over the specified computation area. If the data in the input does not extend to the end of the neighborhood specified, it means that the image border has been reached. The method ORSServiceClass.OrsPlugin.orsabstractfilterplugin.OrsAbstractFilterPlugin.setIndexFirstVoxelInputChannel() is used to tell the filter what is the area of the data subset kept in the memory of each input.

Similarly, the outputs given will have at least a memory allocation required to contain the result of the filter for the computation area. The method ORSServiceClass.OrsPlugin.orsabstractfilterplugin.OrsAbstractFilterPlugin.setIndexFirstVoxelOutputChannel() is used to tell the filter what is the area of the data subset kept in the memory of each output.

When the computation is to be performed, it is the responsibility of the filter to access the data of each input accordingly with the index offsets specified by setIndexFirstVoxelInputChannel, and to write the result in each output accordingly with the index offsets specified by setIndexFirstVoxelOutputChannel.

Computation area: example

This image filter takes one input and computes one output. It requires, for each output pixel, 3 pixels on each side in X (so, 2*3 + 1 = 7 pixels wide) and 5 pixels on each side in Y (so, 2*5 + 1 = 11 pixels high). There is no dependency on Z neither on T. It means that, for each output pixel, an area of 77 pixels is required.

For simplicity, the following analysis considers only X and Y indexes.

OrsPythonPlugins/OrsFilterEditable_a53a39ba632311e78d649cb6d012cc4e/FilterPluginComputationArea.png

The setIndexFirstVoxelInputChannel method is called with these arguments for the input dataset:

  • x: 50

  • y: 100

The setIndexFirstVoxelOutputChannel method is called with these arguments for the output dataset:

  • x: 75

  • y: 200

The apply method is called with these arguments:

  • xMin: 100

  • yMin: 250

  • xMax: 450

  • yMax: 550

It means that the Computation area (red referential) is: [(x=100, y=250), (x=450, y=550)].

To obtain the result of the filter for the pixel located at (x=100, y=250), the pixels located in the area [(x=100-3=97, y=250-5=245), (x=100+3=103, y=250+5=255)] will be required. Similarly, to obtain the result of the filter for the pixel located at (x=450, y=550), the pixels located in the area [(x=450-3=447, y=550-5=545), (x=450+3=453, y=550+5=555)] will be required. Therefore, the input dataset will be given with at least the area [(x=97, y=245), (x=453, y=555)] in memory. Also, the output dataset will be given with at least the area [(x=100, y=250), (x=450, y=550)] in memory. These indexes were all given accordingly to the World (black) referential system of indexes.

To access the data from the input, the first voxel in memory specified for the input dataset needs to be used. The pixel (x=97, y=245) of the World referential corresponds to the pixel (x=97-50=47, y=245-100=145) of the input data matrix (Input memory (blue) referential).

Similarly, the result for the pixel (x=100, y=250) of the World referential needs to be written in the pixel (x=100-75=25, y=250-200=50) of the output data matrix (Output memory (green) referential).

Class Code