Overview  Package   Class  Tree  Deprecated  Index  Help 
AlgART Home
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

net.algart.math.functions
Class ApertureFilterOperator

java.lang.Object
  extended by net.algart.math.functions.ApertureFilterOperator
All Implemented Interfaces:
Operator
public final class ApertureFilterOperator
extends java.lang.Object
implements Operator

Aperture filtering operator in n-dimensional Euclidean space: g(x) = O f(x) = apertureFunc(f(x+a0), f(x+a1), ..., f(x+am-1)), where x is a point of the n-dimensional space, apertureFunc is some function with m arguments (the aperture function), {ai} is a set of points with (usually) little coordinates (the aperture), f is the source mathematical function and g is the result of applying the operator to f.

The number of space dimensions n is equal to the length of the apertureDim array, passed to all generation methods. However, the new function, returned by this operator (by its apply(Func) method, can be called with any number of arguments N. If the number of arguments N<n, than only first N coordinates of the aperture points ai will be used: in other words, the aperture will be projected to the N-dimensional subspace. If the number of arguments N>n, than only first n coordinates of the source point x will be increased by the corresponding coordinates of aperture points: in other words, all extra coordinates of aperture points will be supposed to be zero. In any case, the original function f will be called with the same number of arguments N, as were passed to the new function g. So, if the function f has some restriction for the possible number of arguments, the new function g will have the same restrictions.

This class is immutable and thread-safe: there are no ways to modify settings of the created instance.

AlgART Laboratory 2007-2013

Since:
JDK 1.5
Version:
1.2
Author:
Daniel Alievsky
See Also:
ApertureFilteredFunc

Field Summary
Modifier and Type Field and Description
 
Fields inherited from interface net.algart.math.functions.Operator
IDENTITY
 
Method Summary
Modifier and Type Method and Description
 long[] apertureDim()
          Returns the dimensions of the aperture of this filter.
 double apertureDim(int coordIndex)
          Equivalent to apertureDim()[coordIndex].
 double[] apertureFrom()
          Returns the start coordinates of the points in the aperture of this filter.
 double apertureFrom(int coordIndex)
          Equivalent to apertureFrom()[coordIndex].
 Func apertureFunc()
          Returns the aperture function, used by this filter.
 double apertureStep(int coordIndex)
          Equivalent to apertureSteps()[coordIndex].
 double[] apertureSteps()
          Returns the steps of changing coordinates of the points in the aperture of this filter.
 double apertureTo(int coordIndex)
          Equivalent to apertureFrom()[coordIndex] + (apertureDim()[coordIndex] - 1) * apertureSteps()[coordIndex].
 Func apply(Func f)
          Returns the result of applying this operator to the given function.
static ApertureFilterOperator getAveragingInstance(long... apertureDim)
          Equivalent to getInstance(averagingFunc, apertureDim), where averagingFunc is the averaging linear function LinearFunc.getAveragingInstance(m), m = apertureDim[0]*apertureDim[1]*....
static ApertureFilterOperator getAveragingInstance(long[] apertureDim, double[] apertureFrom, double[] apertureSteps)
          Equivalent to getInstance(averagingFunc, apertureDim, apertureFrom, apertureSteps), where averagingFunc is the averaging linear function LinearFunc.getAveragingInstance(m), m = apertureDim[0]*apertureDim[1]*....
static ApertureFilterOperator getInstance(Func apertureFunc, long... apertureDim)
          Equivalent to getInstance(apertureFunc, apertureDim, apertureFrom, apertureSteps), where averagingFrom and apertureSteps are chosen automatically to get an aperture 1.0x1.0x... starting from the origin of coordinates (0<=aij<1).
static ApertureFilterOperator getInstance(Func apertureFunc, long[] apertureDim, double[] apertureFrom, double[] apertureSteps)
          Returns an instance of this class, describing the aperture filter with the specified aperture and aperture function apertureFunc.
 boolean isAveraging()
          Returns true if and only if this filter performs averaging, i.e. if the aperture function is a linear function, where the b coefficient is zero and all ai coefficients are equal to 1/m, m=apertureDim[0]*apertureDim[1]*....
 double maxApertureSize()
          Returns the maximal aperture size for all dimensions: the maximal value of apertureTo(k)-apertureFrom(k) for all k=0,1,...,n()-1
 int n()
          Returns the number of dimensions of the aperture of this filter.
static boolean tooLargeAperture(long... apertureDim)
          Returns true if the specified sizes of the aperture are too large for processing by this class.
 java.lang.String toString()
          Returns a brief string description of this object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

getInstance

public static ApertureFilterOperator getInstance(Func apertureFunc,
                                                 long[] apertureDim,
                                                 double[] apertureFrom,
                                                 double[] apertureSteps)
Returns an instance of this class, describing the aperture filter with the specified aperture and aperture function apertureFunc.

The aperture {ai}, i=0,1,...,m-1 is defined by apertureDim, apertureFrom, apertureSteps arguments. Namely, the number of dimensions of the space for the new operator will be equal to apertureDim.length, and the aperture will consist of the following points ai = (ai0, ai1, ..., ai,n-1):

ai0 = apertureFrom[0] + j0 * apertureSteps[0],   j0 = 0,1,...,apertureDim[0],
ai1 = apertureFrom[1] + j1 * apertureSteps[1],   j1 = 0,1,...,apertureDim[1],
. . .
ai,n-1 = apertureFrom[n-1] + jn-1 * apertureSteps[n-1],   jn-1 = 0,1,...,apertureDim[n-1]

In other words, the aperture is a rectangular n-dimensional grid of point, the coordinates of which are started from apertureFrom and increased by the steps apertureSteps. The number of points in the aperture is

m = apertureDim[0] * apertureDim[1] * ... * apertureDim[n-1]

This number must not be greater than Integer.MAX_VALUE.

The passed Java arrays are cloned by this method: no references to them are maintained by the created instance.

Parameters:
apertureFunc - the aperture function.
apertureDim - the dimensions of the aperture.
apertureFrom - the start coordinates of the points in the aperture.
apertureSteps - the steps of changing coordinates of the points in the aperture.
Returns:
the aperture filtering operator with the specified aperture and aperture function.
Throws:
java.lang.NullPointerException - if one of the arguments of the method is null.
java.lang.IllegalArgumentException - if the lengths of apertureDim, apertureFrom and apertureSteps arrays are not equal, or if they are zero ("0-dimensional" space), or if some elements of apertureDim array are zero or negative, or if tooLargeAperture(apertureDim) returns true, or, probably, if it's possible to detect that the number of points in the aperture (m) is insufficient for passing to the apertureFunc function.
See Also:
getInstance(Func, long[]), getAveragingInstance(long[], double[], double[]), getAveragingInstance(long[]), tooLargeAperture(long[])

getInstance

public static ApertureFilterOperator getInstance(Func apertureFunc,
                                                 long... apertureDim)
Equivalent to getInstance(apertureFunc, apertureDim, apertureFrom, apertureSteps), where averagingFrom and apertureSteps are chosen automatically to get an aperture 1.0x1.0x... starting from the origin of coordinates (0<=aij<1). More precisely, the following averagingFrom and apertureSteps are chosen: 
 apertureFrom[k] = 0.0;
 apertureSteps[k] = 1.0 / apertureDim[n];

Parameters:
apertureFunc - the aperture function.
apertureDim - the dimensions of the aperture.
Returns:
the aperture filtering operator with the specified aperture and aperture function.
Throws:
java.lang.NullPointerException - if one of the arguments of the method is null.
java.lang.IllegalArgumentException - if the lengths of apertureDim is zero ("0-dimensional" space), or if some elements of apertureDim array are zero or negative, or if tooLargeAperture(apertureDim) returns true, or, probably, if it's possible to detect that the number of points in the aperture (m) is insufficient for passing to the apertureFunc function.

getAveragingInstance

public static ApertureFilterOperator getAveragingInstance(long[] apertureDim,
                                                          double[] apertureFrom,
                                                          double[] apertureSteps)
Equivalent to getInstance(averagingFunc, apertureDim, apertureFrom, apertureSteps), where averagingFunc is the averaging linear function LinearFunc.getAveragingInstance(m), m = apertureDim[0]*apertureDim[1]*....

Parameters:
apertureDim - the dimensions of the aperture.
apertureFrom - the start coordinates of the points in the aperture.
apertureSteps - the steps of changing coordinates of the points in the aperture.
Returns:
the aperture averaging (smoothing) operator with the specified aperture.
Throws:
java.lang.NullPointerException - if one of the arguments of the method is null.
java.lang.IllegalArgumentException - in the same situations as getInstance(Func, long[], double[], double[]).

getAveragingInstance

public static ApertureFilterOperator getAveragingInstance(long... apertureDim)
Equivalent to getInstance(averagingFunc, apertureDim), where averagingFunc is the averaging linear function LinearFunc.getAveragingInstance(m), m = apertureDim[0]*apertureDim[1]*....

Parameters:
apertureDim - the dimensions of the aperture.
Returns:
the aperture averaging (smoothing) operator with the specified aperture.
Throws:
java.lang.NullPointerException - if one of the arguments of the method is null.
java.lang.IllegalArgumentException - in the same situations as getInstance(Func, long[]).

tooLargeAperture

public static boolean tooLargeAperture(long... apertureDim)
Returns true if the specified sizes of the aperture are too large for processing by this class. Namely, it returns true if and only if the product of all dimensions apertureDim[0]*apertureDim[1]*... is greater than Integer.MAX_VALUE.

If you are not sure that your aperture is small enough, please call this method before instantiating this class.

Parameters:
apertureDim - the dimensions of the aperture.
Returns:
true if the specified dimensions of the aperture are too large (>Integer.MAX_VALUE points).
Throws:
java.lang.IllegalArgumentException - if some elements of apertureDim array are zero or negative.

apply

public Func apply(Func f)
Description copied from interface: Operator
Returns the result of applying this operator to the given function.

Specified by:
apply in interface Operator
Parameters:
f - some function.
Returns:
new transformed function.

n

public int n()
Returns the number of dimensions of the aperture of this filter. The result is equal to the length of apertureDim array, passed to all generation methods.

Returns:
the number of dimensions of the aperture of this filter.

apertureDim

public long[] apertureDim()
Returns the dimensions of the aperture of this filter. The result is equal to apertureDim array, passed to all generation methods.

The returned array is a clone of the internal dimension array stored in this object. The returned array is never empty (its length cannot be zero).

Returns:
the dimensions of the aperture of this filter.

apertureFrom

public double[] apertureFrom()
Returns the start coordinates of the points in the aperture of this filter. The result is equal to apertureFrom array, passed to getInstance(Func, long[], double[], double[]) or getAveragingInstance(long[], double[], double[]) generation methods.

The returned array is a clone of the internal dimension array stored in this object. The returned array is never empty (its length cannot be zero).

Returns:
the start coordinates of the points in the aperture of this filter.

apertureSteps

public double[] apertureSteps()
Returns the steps of changing coordinates of the points in the aperture of this filter. The result is equal to apertureSteps array, passed to getInstance(Func, long[], double[], double[]) or getAveragingInstance(long[], double[], double[]) generation methods.

The returned array is a clone of the internal dimension array stored in this object. The returned array is never empty (its length cannot be zero).

Returns:
the steps of changing coordinates of the points in the aperture of this filter.

apertureDim

public double apertureDim(int coordIndex)
Equivalent to apertureDim()[coordIndex].

Parameters:
coordIndex - the index of dimension.
Returns:
the dimension of the aperture of this filter.

apertureFrom

public double apertureFrom(int coordIndex)
Equivalent to apertureFrom()[coordIndex].

Parameters:
coordIndex - the index of coordinate.
Returns:
the start coordinate of the points in the aperture of this filter.

apertureTo

public double apertureTo(int coordIndex)
Equivalent to apertureFrom()[coordIndex] + (apertureDim()[coordIndex] - 1) * apertureSteps()[coordIndex].

Parameters:
coordIndex - the index of coordinate.
Returns:
the last coordinate of the points in the aperture of this filter.

apertureStep

public double apertureStep(int coordIndex)
Equivalent to apertureSteps()[coordIndex].

Parameters:
coordIndex - the index of coordinate.
Returns:
the steps of changing this coordinate of the points in the aperture of this filter.

maxApertureSize

public double maxApertureSize()
Returns the maximal aperture size for all dimensions: the maximal value of apertureTo(k)-apertureFrom(k) for all k=0,1,...,n()-1

Returns:
the maximal aperture size for all dimensions.

apertureFunc

public Func apertureFunc()
Returns the aperture function, used by this filter.

Returns:
the aperture function, used by this filter.

isAveraging

public boolean isAveraging()
Returns true if and only if this filter performs averaging, i.e. if the aperture function is a linear function, where the b coefficient is zero and all ai coefficients are equal to 1/m, m=apertureDim[0]*apertureDim[1]*.... In particular, this method returns true if this filter was created by getAveragingInstance(long[], double[], double[]) or getAveragingInstance(long[]) method.

Returns:
true if and only if this filter performs averaging (smoothing).

toString

public java.lang.String toString()
Returns a brief string description of this object.

Overrides:
toString in class java.lang.Object
Returns:
a brief string description of this object.
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD