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     *     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    */
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      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