Jamoma API  0.6.0.a19
TTInterpolate.h
Go to the documentation of this file.
1 /** @file TTInterpolate.h
2  *
3  * @ingroup foundationLibrary
4  *
5  * @brief Interpolation Utilities
6 
7  * @details Defines several functions for <a href="http://en.wikipedia.org/wiki/Interpolation">interpolating</a> between discrete data points such as those found in an array or matrix. These methods are commonly used in digital audio whenever we alter the rate at which a signal is read.
8  * These functions require known discrete values to be passed by reference along with a double between 0 and 1 representing the fractional location desired. They return the interpolated value.
9  *
10  * @author Timothy Place
11  *
12  * @copyright Copyright © 2012, Timothy Place @n
13  * This code is licensed under the terms of the "New BSD License" @n
14  * http://creativecommons.org/licenses/BSD/
15  */
16 
17 #ifndef __TT_INTERPOLATE_H__
18 #define __TT_INTERPOLATE_H__
19 
20 #include "TTBase.h"
21 
22 /** Isolate the fractional part from a double.
23  Essentially wraps the <a href="http://www.cplusplus.com/reference/clibrary/cmath/modf/">modf()</a> function, but protects Jamoma in case it ever prooves uneven in implementation. NW: FAILS TO BUILD but Xcode can't find error.
24  @param aa Double whose fractional part you would like.
25  @return The fractional portion of aa.
26 
27 double TTSplitFractional(double& aa)
28 {
29  double discard;
30  return modf(aa,&discard);
31 }
32 */
33 
34 
35 /** Linear interpolation.
36  @param x0 Sample value at prior integer index
37  @param x1 Sample value at next integer index
38  @param delta Linear interpolation between x0 (delta=0) and x1 (delta=1)
39  @return The interpolated value.
40 
41  @seealso TTInterpolateCosine
42  @seealso TTInterpolateCubic
43  @seealso TTInterpolateSpline
44  @seealso TTInterpolateHermite
45 */
46 template<class T>
47 T TTInterpolateLinear(const T& x0, const T& x1, const double& delta)
48 {
49  return x0 + delta * (x1-x0);
50 }
51 
52 
53 /** Cosine interpolation
54  @param x Sample value at prior integer index
55  @param y Sample value at next integer index
56  @param a Fractional location between x (0) and y (1)
57  @return The interpolated value.
58 
59  @seealso TTInterpolateLinear
60  @seealso TTInterpolateHermite
61  @seealso TTInterpolateCubic
62  @seealso TTInterpolateSpline
63  */
64 template<class T>
65 T TTInterpolateCosine(const T& x, const T& y, const double& a)
66 {
67  T a2 = 0.5 * (1.0 - cos(a * kTTPi));
68  return x + a2 * (y-x);
69 }
70 
71 
72 /** Cubic interpolation
73 
74  @details This interpolation algorithms calculate the coefficients a, b, c, d
75  of the 3rd order polynomial
76 
77  f(delta) = a*aDelta^3 + b*aDelta^2 + c*aDelta + d
78  = ( (a*aDelta + b )*aDelta + c)*aDelta + d)
79 
80 so that the function fulfill the following four conditions:
81 
82  -# f(0) = x1 @n
83  -# f(1) = x2 @n
84  -# f'(0) = (x2-x0)/2 @n
85  -# f'(1) = (x3-x1)/2
86 
87  The two last conditions use a symetric estimate of the difference at the end points
88  of the region to interpolate over: 0 ≤ aDelta ≤ 1
89 
90  These asumptions ensure that the resulting interpolated function, when moving over several
91  subsequent sections, is:
92 
93  -# Continuous (no sudden jump)
94  -# Has a continuous derivative (no break pints with hard edges)
95 
96  However, the 2nd order derivate will generally be discontinuous on the points connecting two sections.
97 
98 
99 
100  @param x0 Sample value at integer index prior to x0
101  @param x1 Sample value at prior integer index
102  @param x2 Sample value at next integer index
103  @param x3 Sample value at integer index after x2
104  @param aDelta Fractional location where we want to do the interpolation. @n
105  aDelta = 0 => interpolatedeValue = x1 @n
106  aDelta = 1 => interpolatedeValue = x2
107  @return The interpolated value.
108 
109  @seealso TTInterpolateLinear
110  @seealso TTInterpolateCosine
111  @seealso TTInterpolateHermite
112  @seealso TTInterpolateSpline
113 */
114 template<class T>
115 T TTInterpolateCubic(const T& x0, const T& x1, const T& x2, const T& x3, const double& aDelta)
116 {
117  T a = (-x0 + 3.*x1 - 3*x2 + x3)*0.5;
118  T b = x0 - 2.5*x1 + 2.*x2 - 0.5*x3;
119  T c = (x2-x0)*0.5;
120 
121  //T a = x3 - x2 - x0 + x1;
122  //T b = x0 - x1 - f0;
123  //T c = x2 - x0;
124  // T d = x1;
125  return ( (a*aDelta + b)*aDelta + c)*aDelta + x1;
126 }
127 
128 
129 /** Spline interpolation based on the Breeuwsma catmull-rom spline
130  @param w Sample value at integer index prior to x
131  @param x Sample value at prior integer index
132  @param y Sample value at next integer index
133  @param z Sample value at integer index after y
134  @param a Fractional location between x (0) and y (1)
135  @return The interpolated value.
136 
137  @seealso TTInterpolateLinear
138  @seealso TTInterpolateCosine
139  @seealso TTInterpolateCubic
140  @seealso TTInterpolateHermite
141 */
142 template<class T>
143 T TTInterpolateSpline(const T& w, const T& x, const T& y, const T& z, const double& a)
144 {
145  T a2 = a*a;
146  T f0 = -0.5*w + 1.5*x - 1.5*y + 0.5*z;
147  T f1 = w - 2.5*x + 2.0*y - 0.5*z;
148  T f2 = -0.5*w + 0.5*y;
149  return f0*a*a2 + f1*a2 + f2*a + x;
150 }
151 
152 
153 /** Hermite interpolation
154  @param w Sample value at integer index prior to x
155  @param x Sample value at prior integer index
156  @param y Sample value at next integer index
157  @param z Sample value at integer index after y
158  @param a Fractional location between x (0) and y (1)
159  @return The interpolated value.
160 
161  @seealso TTInterpolateLinear
162  @seealso TTInterpolateCosine
163  @seealso TTInterpolateCubic
164  @seealso TTInterpolateSpline
165 */
166 template<class T>
167 T TTInterpolateHermite(const T& w, const T& x, const T& y, const T& z, const double& a, const double& bias, const double& tension)
168 {
169  T aa = a*a;
170  T aaa = a*aa;
171  T bp = 1+bias;
172  T bm = 1-bias;
173  T mt = (1-tension)*0.5;
174  T m0 = ((x-w)*bp + (y-x)*bm) * mt;
175  T m1 = ((y-x)*bp + (z-y)*bm) * mt;
176  T a0 = 2*aaa - 3*aa + 1;
177  T a1 = aaa - 2*aa + a;
178  T a2 = aaa - aa;
179  T a3 = -2*aaa + 3*aa;
180  return a0*x + a1*m0 + a2*m1 + a3*y;
181 }
182 
183 
184 #endif // __TT_INTERPOLATE_H__
185 
T TTInterpolateLinear(const T &x0, const T &x1, const double &delta)
Isolate the fractional part from a double.
Definition: TTInterpolate.h:47
Jamoma's lowest-level base class and related infrastructure.
T TTInterpolateSpline(const T &w, const T &x, const T &y, const T &z, const double &a)
Spline interpolation based on the Breeuwsma catmull-rom spline.
T TTInterpolateHermite(const T &w, const T &x, const T &y, const T &z, const double &a, const double &bias, const double &tension)
Hermite interpolation.
T TTInterpolateCubic(const T &x0, const T &x1, const T &x2, const T &x3, const double &aDelta)
Cubic interpolation.
T TTInterpolateCosine(const T &x, const T &y, const double &a)
Cosine interpolation.
Definition: TTInterpolate.h:65
TTFOUNDATION_EXPORT const TTFloat64 kTTPi
[doxygenAppendixC_constExample]
Definition: TTBase.cpp:23