Package net.algart.matrices

Interface ApertureProcessor<K>

public interface ApertureProcessor<K>

Abstract aperture matrix processor: an algorithm, processing a group of n-dimensional matrices and returning a group of resulting matrices, where the value of every element of every resulting matrix depends only on the elements of the source matrices in some aperture "around" the same position. This aperture should be a subset of some rectangular area (IRectangularArea); this area (possibly different for different source matrices) is called a dependence aperture of the aperture processor. All matrices must have same dimensions. This interface is used, for example, together with TiledApertureProcessorFactory class.

Below is more precise formal definition of the aperture matrix processors. All classes, implementing this interface, should comply this definition.

The main method of this interface, process, works with some group of AlgART matrices Mi, i∈Q, called the arguments or source matrices, and a group of another AlgART matrices M'j, j∈R, called the results or resulting matrices. Here the indexes i and j (elements of the index sets Q and R) can be objects of any nature and should be represented by Java objects of the generic type K — the generic argument of this interface (for example, Integer or String). The indexes of arguments and results are also called their keys. The group of the source arguments and the group of results are represented by java.util.Map, more precisely, by a generic type java.util.Map<K, Matrix<?>>:

     process(java.util.Map<K, Matrix<?>> dest, java.util.Map<K, Matrix<?>> src)

The group destof resulting matrices M'j can be passed to process method, or can be formed by this method dynamically (an empty map dest can be passed in this case), or it is possible that a part of resulting matrices is passed in dest while calling the method and other resulting matrices are added to dest map by the method itself.

In all comments, the designations M'j and R means the group (dest) and the index set (dest.keySet()) of resulting matrices after the call of process method.

Some of the resulting matrices M'j (but not the source arguments), passed to process method, may be null — it means that process method must create them itself. (And it also may create some additional matrices M'j, not contained in dest while calling this method.) All non-null resulting matrices M'j, passed to the method in dest argument, must be updatable, i.e. their built-in arrays must implement UpdatableArray interface. The dimensions of all source and non-null resulting matrices must be the same: Matrix.dimEquals(Matrix) method must return true for any pair of them. The sets of indexes of arguments Q and results R, as well as the dimensions of matrices, may vary for different calls of process method. (Even the number of dimensions n may vary, but it is a rarer situation.) Degenerated cases Q=∅ (no arguments) and R=∅ (no results) are allowed. If Q=∅ (no matrices are passed in src map) and the dest map, passed to process method, either is empty or contains only null matrices, then process method usually does nothing. See comments to that method for additional details.

For each source argument Mi this aperture processor defines the corresponding dependence aperture Ai: a rectangular set of integer points, represented by IRectangularArea class and returned by dependenceAperture(i) method. This aperture can depend only on the argument index i and cannot vary for different calls of dependenceAperture method for the same processor.

The goal of the main process method is to fill elements of the resulting matrices M'j (usually all elements of all M'j, j∈R) on the base of the elements of the source matrices Mi. There should be a guarantee, that every element of any resulting n-dimensional matrix M'j with coordinates x = (x0, x1, ..., xn−1) can depend only on elements of each source matrix Mi with coordinates

x+a = x0+a0, x1+a1, ..., xn−1+an−1,

where a = (a0, a1, ..., an−1) is one of points belonging to the corresponding dependence aperture Ai=dependenceAperture(i). Please draw attention that we use plus sing + in this definition, instead of more traditional minus sign − (used, for example, in specifications of StreamingApertureProcessor or RankMorphology). In many cases, it is convenient to use DependenceApertureBuilder class to create dependence apertures for an aperture processor.

If this rule is violated, for example, if the aperture, returned by dependenceAperture method, is too little (the results depend on elements outside this aperture), then process method still works, but the results of processing can be incorrect. If the aperture, returned by dependenceAperture method, is too large (the results do not depend on most of elements in the aperture), then process method still works and the results are correct, but excessively large aperture sizes can slow down the calculations.

The process method fills all resulting matrices. But if some of the resulting matrices M'j, passed via dest map while calling this method, is null, then it must be automatically created. Moreover, if some of the resulting matrices M'j was not null while calling this method, the method still may create new matrix for this key (index) j and store it in dest map instead of the original matrix. In addition, this method may create (and store in dest map) some new resulting matrices with new keys (indexes), which were not contained in dest while calling the method. But here must be the following guarantee: the set of indexes j of the resulting matrix M'j, created and stored in dest map by this method in addition to existing key/value pairs in dest map, cannot vary for different calls of process method of the same instance of the processor.

If process method allocates some resulting matrix, then all these matrices must be created with the same dimensions as all the source and non-null resulting matrices, passed to the method. The type of elements of the newly created matrix is selected by some rules, depending on the implementation. Typical example — it is selected to be equal to the element type of some source matrices. But here must be the following guarantee: the element type of the resulting matrix M'j with the given index j cannot vary for different calls of process method of the same processor, if the element types of all source matrices Mi do not vary while these calls. In other words, a concrete instance of the processor may select the element type of newly created matrices only on the base of the element types of the arguments, but not, for example, on the base of the matrix dimensions.

Author:
Daniel Alievsky

  • Method Summary

    Modifier and Type
    Method
    Description
    IRectangularArea
    dependenceAperture(K srcMatrixKey)
    Returns the dependence aperture Ai for the source matrix Mi with the given index i=srcMatrixKey.
    void
    process(Map<K,Matrix<?>> dest, Map<K,Matrix<?>> src)
    Main method of the aperture processor, that performs processing the source matrices src with saving results in the resulting matrices dest.

  • Method Details

    • process

      void process(Map<K,Matrix<?>> dest, Map<K,Matrix<?>> src)
      Main method of the aperture processor, that performs processing the source matrices src with saving results in the resulting matrices dest. The source matrices Mi, i∈Q are passed in src map: Mi=src.get(i). The resulting matrices M'j, j∈R, are passed or, maybe, dynamically created and stored in dest map: M'j=dest.get(j). So, the sets of indexes Q and R are the Java sets src.keySet() and dest.keySet() (after the call of this method). See comments to ApertureProcessor for more details.

      Note 1: some of the source matrices may be references to the same object (src.get(i)==src.get(j)) — such situations must be processed correctly by this method.

      Note 2: this method must not modify src map and the source matrices, contained in this map.

      Note 3: this method must not remove key/value pairs from dest map (but may add new resulting matrices).

      Note 4: if some resulting matrix M'j, passed in dest map as dest.get(j), is null while calling this method, it must be automatically created and stored back in dest map for the same key (index) j. (Besides this, this method may create and store in dest another additional resulting matrices with another indexes.)

      Note 5: if this method creates some resulting matrices itself, then dest map should be mutable. The created resulting matrices are saved in this map by dest.put(K,...) call.

      Note 6: if this method stores some resulting matrices it dest map, they must have the same dimensions as all matrices, passed in src and dest maps while calling the method. This method must not store null values in dest map.

      Note 7: resulting matrices, created by this method instead of null values in dest map or in addition to the existing matrices in dest map, may be not updatable, i.e. it is possible that their built-in arrays will not implement UpdatableArray interface. The simplest example: the algorithm may return, as a result (saved in dest), some lazy view of one of the source matrices src.get(i) or even just a reference to a source matrix src.get(i). (But if this object is a tiled processors, returned by TiledApertureProcessorFactory.tile(ApertureProcessor) method, then it is impossible: in this case, all resulting matrices, created by this method and stored in dest map, are always updatable, and their built-in arrays implement UpdatableArray.)

      Note 8: unlike this, all non-null values, present in dest map while calling this method, must be updatable — because this method may need to store results in them. It is true even if this method does not use the old non-null values M'j and replace them with newly created matrices — even in this case the method may check, that they are not updatable, and throw an exception if so.

      Note 9: the sets of indexes of arguments Q and results R, as well as the dimensions of matrices, may vary for different calls of this method. (Even the number of dimensions may vary in some implementations, but it is a rarer situation. The tiled processors, returned by TiledApertureProcessorFactory.tile(ApertureProcessor) method, work only with a fixed number of dimensions, equal to TiledApertureProcessorFactory.dimCount().)

      Note 10: degenerated cases Q=∅ (src.isEmpty(): no arguments) and R=∅ (dest.isEmpty(): no results) are allowed. If Q=R=∅, as well as if Q=∅ and the dest map, passed to this method, either is empty or contains only null matrices, then this method usually does nothing — it is really true for the tiled processors, returned by TiledApertureProcessorFactory.tile(ApertureProcessor) method, but it is not a strict requirement for other implementations.

      Parameters:
      dest - the resulting matrices: the result M'j will be the value dest.get(j) of this map after calling this method.
      src - the source arguments: the argument Mi is the value src.get(i) of this map.
      Throws:
      NullPointerException - if dest or src argument is null, or if one of values in src map is null.
      IllegalArgumentException - if some values in dest map are not null and, at the same time, their built-in arrays are not updatable; ClassCastException can be also thrown in this case instead of this exception.
      SizeMismatchException - if some matrices among the source arguments (values of src map) or non-null resulting matrices (values of dest map), passed while calling this method, have different dimensions. It is a typical run-time exception in this case, and it is really thrown by the tiled processors, created by TiledApertureProcessorFactory.tile(ApertureProcessor) method; but other implementations are permitted to throw another exceptions in this case.

    • dependenceAperture

      IRectangularArea dependenceAperture(K srcMatrixKey)
      Returns the dependence aperture Ai for the source matrix Mi with the given index i=srcMatrixKey. See comments to ApertureProcessor for more details.

      This method must return correct result for any key, which can appear and can be processed in process method as a key in its src map. If srcMatrixKey argument has some "impossible" value, the result is not specified.

      This method should work quickly and must never throw exceptions.

      Parameters:
      srcMatrixKey - the index (key) of the source matrix.
      Returns:
      the dependence aperture of the processing algorithm for this source matrix.