1 /* ----------------------------------------------------------------------
2  * Project:      CMSIS DSP Library
3  * Title:        arm_bilinear_interp_f32.c
4  * Description:  Floating-point bilinear interpolation
5  *
6  * $Date:        23 April 2021
7  * $Revision:    V1.9.0
8  *
9  * Target Processor: Cortex-M and Cortex-A cores
10  * -------------------------------------------------------------------- */
11 /*
12  * Copyright (C) 2010-2021 ARM Limited or its affiliates. All rights reserved.
13  *
14  * SPDX-License-Identifier: Apache-2.0
15  *
16  * Licensed under the Apache License, Version 2.0 (the License); you may
17  * not use this file except in compliance with the License.
18  * You may obtain a copy of the License at
19  *
20  * www.apache.org/licenses/LICENSE-2.0
21  *
22  * Unless required by applicable law or agreed to in writing, software
23  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
24  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
25  * See the License for the specific language governing permissions and
26  * limitations under the License.
27  */
28 
29 #include "dsp/interpolation_functions.h"
30 
31 /**
32   @ingroup groupInterpolation
33  */
34 
35 /**
36    * @defgroup BilinearInterpolate Bilinear Interpolation
37    *
38    * Bilinear interpolation is an extension of linear interpolation applied to a two dimensional grid.
39    * The underlying function <code>f(x, y)</code> is sampled on a regular grid and the interpolation process
40    * determines values between the grid points.
41    * Bilinear interpolation is equivalent to two step linear interpolation, first in the x-dimension and then in the y-dimension.
42    * Bilinear interpolation is often used in image processing to rescale images.
43    * The CMSIS DSP library provides bilinear interpolation functions for Q7, Q15, Q31, and floating-point data types.
44    *
45    * <b>Algorithm</b>
46    * \par
47    * The instance structure used by the bilinear interpolation functions describes a two dimensional data table.
48    * For floating-point, the instance structure is defined as:
49    * <pre>
50    *   typedef struct
51    *   {
52    *     uint16_t numRows;
53    *     uint16_t numCols;
54    *     const float32_t *pData;
55    * } arm_bilinear_interp_instance_f32;
56    * </pre>
57    *
58    * \par
59    * where <code>numRows</code> specifies the number of rows in the table;
60    * <code>numCols</code> specifies the number of columns in the table;
61    * and <code>pData</code> points to an array of size <code>numRows*numCols</code> values.
62    * The data table <code>pTable</code> is organized in row order and the supplied data values fall on integer indexes.
63    * That is, table element (x,y) is located at <code>pTable[x + y*numCols]</code> where x and y are integers.
64    *
65    * \par
66    * Let <code>(x, y)</code> specify the desired interpolation point.  Then define:
67    * <pre>
68    *     XF = floor(x)
69    *     YF = floor(y)
70    * </pre>
71    * \par
72    * The interpolated output point is computed as:
73    * <pre>
74    *  f(x, y) = f(XF, YF) * (1-(x-XF)) * (1-(y-YF))
75    *           + f(XF+1, YF) * (x-XF)*(1-(y-YF))
76    *           + f(XF, YF+1) * (1-(x-XF))*(y-YF)
77    *           + f(XF+1, YF+1) * (x-XF)*(y-YF)
78    * </pre>
79    * Note that the coordinates (x, y) contain integer and fractional components.
80    * The integer components specify which portion of the table to use while the
81    * fractional components control the interpolation processor.
82    *
83    * \par
84    * if (x,y) are outside of the table boundary, Bilinear interpolation returns zero output.
85    */
86 
87 
88   /**
89    * @addtogroup BilinearInterpolate
90    * @{
91    */
92 
93 
94   /**
95   * @brief  Floating-point bilinear interpolation.
96   * @param[in,out] S  points to an instance of the interpolation structure.
97   * @param[in]     X  interpolation coordinate.
98   * @param[in]     Y  interpolation coordinate.
99   * @return out interpolated value.
100   */
arm_bilinear_interp_f32(const arm_bilinear_interp_instance_f32 * S,float32_t X,float32_t Y)101   float32_t arm_bilinear_interp_f32(
102   const arm_bilinear_interp_instance_f32 * S,
103   float32_t X,
104   float32_t Y)
105   {
106     float32_t out;
107     float32_t f00, f01, f10, f11;
108     const float32_t *pData = S->pData;
109     int32_t xIndex, yIndex, index;
110     float32_t xdiff, ydiff;
111     float32_t b1, b2, b3, b4;
112 
113     xIndex = (int32_t) X;
114     yIndex = (int32_t) Y;
115 
116     /* Care taken for table outside boundary */
117     /* Returns zero output when values are outside table boundary */
118     if (xIndex < 0 || xIndex > (S->numCols - 2) || yIndex < 0 || yIndex > (S->numRows - 2))
119     {
120       return (0);
121     }
122 
123     /* Calculation of index for two nearest points in X-direction */
124     index = (xIndex ) + (yIndex ) * S->numCols;
125 
126 
127     /* Read two nearest points in X-direction */
128     f00 = pData[index];
129     f01 = pData[index + 1];
130 
131     /* Calculation of index for two nearest points in Y-direction */
132     index = (xIndex ) + (yIndex+1) * S->numCols;
133 
134 
135     /* Read two nearest points in Y-direction */
136     f10 = pData[index];
137     f11 = pData[index + 1];
138 
139     /* Calculation of intermediate values */
140     b1 = f00;
141     b2 = f01 - f00;
142     b3 = f10 - f00;
143     b4 = f00 - f01 - f10 + f11;
144 
145     /* Calculation of fractional part in X */
146     xdiff = X - xIndex;
147 
148     /* Calculation of fractional part in Y */
149     ydiff = Y - yIndex;
150 
151     /* Calculation of bi-linear interpolated output */
152     out = b1 + b2 * xdiff + b3 * ydiff + b4 * xdiff * ydiff;
153 
154     /* return to application */
155     return (out);
156   }
157 
158   /**
159    * @} end of BilinearInterpolate group
160    */
161 
162