public interface ApertureProcessor<K>
Abstract aperture matrix processor: an algorithm, processing a group of
ndimensional 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
M_{i}, 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 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 nonnull resulting matrices M'_{j}, passed to the method in dest
argument, must be updatable, i.e. their builtin arrays
must implement UpdatableArray
interface.
The dimensions of all source and nonnull 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 M_{i} this aperture processor defines
the corresponding dependence aperture A_{i}: a rectangular set of
integer points, represented by IRectangularArea
class and returned by
dependenceAperture(i)
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 M_{i}.
There should be a guarantee, that every element of any resulting ndimensional matrix
M'_{j} with coordinates
x+a = x_{0}+a_{0}, x_{1}+a_{1}, ..., x_{n−1}+a_{n−1},
where
dependenceAperture(i)
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 nonnull 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 M_{i}
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.
Modifier and Type  Method and Description 

IRectangularArea 
dependenceAperture(K srcMatrixKey)
Returns the dependence aperture A_{i}
for the source matrix M_{i} with the given index
i=srcMatrixKey.

void 
process(java.util.Map<K,Matrix<?>> dest,
java.util.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.

void process(java.util.Map<K,Matrix<?>> dest, java.util.Map<K,Matrix<?>> src)
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 builtin 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 builtin arrays
implement UpdatableArray
.)
Note 8: unlike this, all nonnull 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 nonnull 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.
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 M_{i} is the value
src.get(i) of this map.java.lang.NullPointerException
 if dest or src argument is null,
or if one of values in src map is null.java.lang.IllegalArgumentException
 if some values in dest map are not null
and, at the same time, their builtin 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 nonnull resulting matrices
(values of dest map), passed while calling this
method, have different dimensions. It is a typical runtime
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.IRectangularArea dependenceAperture(K srcMatrixKey)
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.
srcMatrixKey
 the index (key) of the source matrix.