001/*******************************************************************************
002 * This software is provided as a supplement to the authors' textbooks on digital
003 * image processing published by Springer-Verlag in various languages and editions.
004 * Permission to use and distribute this software is granted under the BSD 2-Clause
005 * "Simplified" License (see http://opensource.org/licenses/BSD-2-Clause).
006 * Copyright (c) 2006-2023 Wilhelm Burger, Mark J. Burge. All rights reserved.
007 * Visit https://imagingbook.com for additional details.
008 ******************************************************************************/
009package imagingbook.spectral.dft;
010
011/**
012 * <p>
013 * Interface to be implemented by all one-dimensional DFT/FFT implementations.
014 * See Ch. 18 of [1] for additional details.
015 * </p>
016 * <p>
017 * [1] W. Burger, M.J. Burge, <em>Digital Image Processing &ndash; An Algorithmic Introduction</em>,
018 * 3rd ed, Springer (2022).
019 * </p>
020 * @see Dft1dDirect
021 * @see Dft1dFast
022 */
023public interface Dft1d {
024        
025        /**
026         * Returns the size of this DFT (length of data vectors).
027         * @return the size of this DFT
028         */
029        public int getSize();
030        
031        /**
032         * Returns the scaling mode of this DFT (see {@link ScalingMode}).
033         * @return the scaling mode of this DFT.
034         */
035        public ScalingMode getScalingMode();
036        
037        // ---------------------------------------------------------------------------------
038        
039        /**
040         * Sub-interface for 1D DFT implementations operating on {@code float} data.
041         */
042        public interface Float extends Dft1d {
043                
044                /**
045                 * Performs an "in-place" DFT forward transformation on the supplied 1D {@code float} data.
046                 * The input signal is replaced by the associated DFT spectrum.
047                 * @param gRe real part of the signal (modified)
048                 * @param gIm imaginary part of the signal (modified)
049                 */
050                public void forward(float[] gRe, float[] gIm);
051                
052                /**
053                 * Performs an "in-place" DFT inverse transformation on the supplied 1D {@code float} spectrum.
054                 * The input spectrum is replaced by the associated signal.
055                 * @param GRe real part of the spectrum (modified)
056                 * @param GIm imaginary part of the spectrum (modified)
057                 */
058                public void inverse(float[] GRe, float[] GIm);
059                
060                /**
061                 * Transforms the given 1D arrays 'in-place'. Separate arrays of identical size
062                 * must be supplied for the real and imaginary parts of the signal (forward) 
063                 * or spectrum (inverse), neither of which may be {@code null}.
064                 * 
065                 * @param inRe real part of the input signal or spectrum (modified)
066                 * @param inIm imaginary part of the input signal or spectrum (modified)
067                 * @param forward forward transformation if {@code true}, inverse transformation if {@code false}
068                 */
069                public void transform(float[] inRe, float[] inIm, boolean forward);
070                
071                default void checkSize(float[] re, float[] im) {
072                        if (re.length != this.getSize())
073                                throw new IllegalArgumentException(
074                                        String.format("re: wrong 1D array size %d (expected %d)", re.length, this.getSize()));
075                        
076                        if (im.length != this.getSize())
077                                throw new IllegalArgumentException(
078                                        String.format("im: wrong 1D array size %d (expected %d)", im.length, this.getSize()));
079                }
080                
081        }
082        
083        // -------------------------------------------------------------------
084        
085        /**
086         * Sub-interface for 1D DFT implementations operating on {@code double} data.
087         */
088        public interface Double extends Dft1d {
089                
090                /**
091                 * Performs an "in-place" 1D DFT forward transformation on the supplied {@code double} data.
092                 * The input signal is replaced by the associated DFT spectrum.
093                 * 
094                 * @param gRe real part of the signal (modified)
095                 * @param gIm imaginary part of the signal (modified)
096                 */
097                public void forward(double[] gRe, double[] gIm);
098                
099                /**
100                 * Performs an "in-place" 1D DFT inverse transformation on the supplied {@code double} spectrum.
101                 * The input spectrum is replaced by the associated signal.
102                 * 
103                 * @param GRe real part of the spectrum (modified)
104                 * @param GIm imaginary part of the spectrum (modified)
105                 */
106                public void inverse(double[] GRe, double[] GIm);
107                
108                /**
109                 * Transforms the given 1D arrays 'in-place'. Separate arrays of identical size
110                 * must be supplied for the real and imaginary parts of the signal (forward) 
111                 * or spectrum (inverse), neither of which may be {@code null}.
112                 * 
113                 * @param inRe real part of the input signal or spectrum (modified)
114                 * @param inIm imaginary part of the input signal or spectrum (modified)
115                 * @param forward forward transformation if {@code true}, inverse transformation if {@code false}
116                 */
117                public void transform(double[] inRe, double[] inIm, boolean forward);
118                
119                default void checkSize(double[] re, double[] im) {
120                        if (re.length != this.getSize())
121                                throw new IllegalArgumentException(
122                                        String.format("re: wrong 1D array size %d (expected %d)", re.length, this.getSize()));
123                        
124                        if (im.length != this.getSize())
125                                throw new IllegalArgumentException(
126                                        String.format("im: wrong 1D array size %d (expected %d)", im.length, this.getSize()));
127                }
128                
129        }
130        
131}