Class ApertureFilterOperator

java.lang.Object
net.algart.math.functions.ApertureFilterOperator
All Implemented Interfaces:
Operator

public final class ApertureFilterOperator extends 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.

Author:
Daniel Alievsky
See Also:
  • Method Details

    • 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:
      NullPointerException - if one of the arguments of the method is null.
      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

      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:
      NullPointerException - if one of the arguments of the method is null.
      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:
      NullPointerException - if one of the arguments of the method is null.
      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:
      NullPointerException - if one of the arguments of the method is null.
      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:
      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 String toString()
      Returns a brief string description of this object.
      Overrides:
      toString in class Object
      Returns:
      a brief string description of this object.