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 (
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
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,
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
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
Some of the resulting matrices M'j (but not the source arguments),
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
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
(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
either is empty or contains only null matrices,
process method usually does nothing.
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 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+a = x0+a0, x1+a1, ..., xn−1+an−1,
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),
process method still works and the results are correct,
but excessively large aperture sizes can slow down the calculations.
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
method of the same instance of the processor.
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
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.
|Modifier and Type||Method and Description|
Returns the dependence aperture Ai for the source matrix Mi with the given index i=srcMatrixKey.
Main method of the aperture processor, that performs processing the source matrices src with saving results in the resulting matrices dest.
comments to ApertureProcessorfor 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
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
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
work only with a fixed number of dimensions, equal to
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
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 Mi 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
built-in arraysare 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.
IRectangularArea dependenceAperture(K srcMatrixKey)
comments to ApertureProcessorfor 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.