Package net.algart.math.functions

Class ContrastingFunc

java.lang.Object
net.algart.math.functions.ContrastingFunc
All Implemented Interfaces:
Func
public abstract class ContrastingFunc extends Object implements Func

Contrasting function: by default, f(x0, x1, x2, x3) = M * (x0/x1) * (x−x2) / max(x3−x2,threshold), where x = (x1<x2 ? x2 : x1>x3 ? x3 : x1) is x1, truncated to x2..x3 range, M and threshold are constants. In addition, in a case of 3 arguments this function always returns f(x0, x1, x2) = f(x0, x0, x1, x2). Note that f(x0, x1, x2, x3) = (x0/x1) * f(x1, x2, x3).

If x0=x1=b is a brightness of some image pixel, x2..x3 represents some brightness range, and threshold is a positive value ≤x3−x2, this function performs contrasting of x2..x3 range to 0..M range: all values b≤x2 are transformed to 0, all values b≥x3 are transformed to M, and values between x2 and x3 are proportionally transformed to values between 0 and M. However, if x3−x2 is too small, i.e. <threshold, this value is used instead of x3−x2: b=x3 and greater values are transformed not to M, but only to M*(x3−x2)/threshold. It allows avoiding to perform very "strong" contrasting when x3−x2 is very small and, in particular, avoiding 0/0 when x3=x2. Usually x2 and x3 are the minimal (or almost minimal) and the maximal (or almost maximal) brightnesses of the image or of some image area.

If x0≠x1, this functions performs contrasting of x1 to the contrasted value y = f(x1, x1, x2, x3), as described above, and returns proportionally changed x0, i.e. y*(x0/x1). It can be useful for contrasting color images: we can pass the average intensity (brightness) as x1 argument and a concrete color component (red, green, blue) as x0, then the image will be contrasted with preserving colors.

The described implementation is default and used when you create an instance by getInstance(M,threshold) call. But you can create your own implementation of this abstract class, for example, with another logic of threshold processing. It is supposed that any implementation of this class in a case of 3 arguments performs some "contrasting" of the brightness, specified by the 1st argument, accordingly the brightness range, specified by 2nd and 3rd argument, and that in a case of 4 arguments f(x0, x1, x2, x3) = (x0/x1) * f(x1, x2, x3).

The get(double...) method of the instances of this class requires at least 3 arguments and throws IndexOutOfBoundsException if the number of arguments is 0, 1 or 2.

All implementations of this class are immutable and thread-safe: there are no ways to modify settings of the created instance.

Author:
Daniel Alievsky

  • Constructor Details

    • ContrastingFunc

      protected ContrastingFunc()
      Creates an instance of this class.

  • Method Details

    • getInstance

      public static ContrastingFunc getInstance(double m, double threshold)
      Returns an instance of this class, providing the default behaviour described in the comments to this class.
      Parameters:
      m - the M constant: maximal value returned by this function.
      threshold - the threshold constant.
      Returns:
      the contrasting function with the given parameters.

    • get

      public double get(double... x)
      This method is fully implemented in this class: it returns get(x[0],x[1],x[2],x[3]), if x.length>=4, returns get(x[0],x[1],x[2]), if x.length==3, and throws IndexOutOfBoundsException, if x.length<3.
      Specified by:
      get in interface Func
      Parameters:
      x - the function arguments.
      Returns:
      the function result.
      Throws:
      IndexOutOfBoundsException - if the number of passed arguments is 0, 1 or 2.

    • get

      public final double get()
      Description copied from interface: Func
      Equivalent to get(new double[0]). Provides better performance because it does not require Java array creation.
      Specified by:
      get in interface Func
      Returns:
      the function result.

    • get

      public final double get(double x0)
      Description copied from interface: Func
      Equivalent to get(new double[] {x0}). Provides better performance because it does not require Java array creation.
      Specified by:
      get in interface Func
      Parameters:
      x0 - the function argument.
      Returns:
      the function result.

    • get

      public final double get(double x0, double x1)
      Description copied from interface: Func
      Equivalent to get(new double[] {x0, x1}). Provides better performance because it does not require Java array creation.
      Specified by:
      get in interface Func
      Parameters:
      x0 - the first function argument.
      x1 - the second function argument.
      Returns:
      the function result.

    • get

      public abstract double get(double x0, double x1, double x2)
      Description copied from interface: Func
      Equivalent to get(new double[] {x0, x1, x2}). Provides better performance because it does not require Java array creation.
      Specified by:
      get in interface Func
      Parameters:
      x0 - the first function argument.
      x1 - the second function argument.
      x2 - the third function argument.
      Returns:
      the function result.

    • get

      public double get(double x0, double x1, double x2, double x3)
      This method is fully implemented in this class: it returns x0/x1*get(x1,x2,x3). You can override it toe provide better performance or precision.
      Specified by:
      get in interface Func
      Parameters:
      x0 - the first function argument.
      x1 - the second function argument.
      x2 - the third function argument.
      x3 - the fourth function argument.
      Returns:
      the function result.