FUNCTION interp_coeffs_2d, imdata, poles, tol, DanIDL_C_code
; Description: This function calculates the array of interpolation coefficients for input image data
; "imdata" and a given interpolation scheme with filter poles "poles". The calculation
; of the initial value of the causal coefficient can be speeded up by setting the value
; of "tol" to a positive value greater than "0.0" but less than "1.0", which represents
; the maximum acceptable relative error during the filtering process.
; This function will use C++ code if possible to achieve a much faster execution than
; the default IDL code. The C++ code is an astounding factor of ~22 times faster than
; the IDL code in this case. Note that the default IDL code does not call the function
; "interp_coeffs_1d", but instead does the repeated calculation of this function within
; this code in order to minimise the overheads.
;
; Input Parameters:
;
; imdata - FLOAT/DOUBLE ARRAY - An image array for which the interpolation coefficients are to be
; calculated. Note that this image array should not contain bad
; pixels, so such pixels should have been previously interpolated over
; in "imdata".
; poles - FLOAT/DOUBLE VECTOR - A one-dimensional vector of values for the poles required for the
; recursive filter. A list of the pole values required for each interpolation
; scheme are reported here for convenience:
;
; Interpolation Scheme: No. Poles: First Pole: Second Pole:
;
; Quadratic B-splines 1 sqrt(8)-3
; Cubic B-Splines 1 sqrt(3)-2
; Quartic B-Splines 2 sqrt(664-sqrt(438976))+sqrt(304)-19 sqrt(664+sqrt(438976))-sqrt(304)-19
; Quintic B-Splines 2 (sqrt(270-sqrt(70980))+sqrt(105)-13)/2 (sqrt(270+sqrt(70980))-sqrt(105)-13)/2
; Cubic O-MOMS 1 (sqrt(105)-13)/8
;
; tol - FLOAT/DOUBLE - The maximum acceptable relative error during the filtering process. By setting
; this parameter to a positive value greater than "0.0" but less than "1.0", the
; initial value of the causal coefficient for each row and column is calculated
; from a subset of pixel values, while achieving the acceptable relative error
; "tol". By setting this parameter to any other value, the initial value of the
; causal coefficient is calculated exactly from all pixel values in the current
; row or column.
; DanIDL_C_code - STRING - The full directory path indicating where the DanIDL C++ code is installed.
; The shared library of DanIDL C++ routines should exist as
; "/dist/libDanIDL.so" within the installation.
;
; Return Value:
;
; The return value is an array of DOUBLES of the same dimensions as "imdata" that represents the
; interpolation coefficients for the given interpolation scheme with filter poles "poles". If this
; module fails for any reason, then the return value is 0.0D.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 15/08/2008 - Module created (dmb)
;Check that "imdata" is an image of the correct number type
;Check that "poles" is a one-dimensional vector of the correct number type
;Check that "tol" is a number of the correct type
;Determine if the shared library of DanIDL C++ routines is installed
;Set up the output array of interpolation coefficients
;If the shared library of DanIDL C++ routines is installed, then use the C++ code
;to speed up the calculation of the interpolation coefficients
;If there are at least two elements in an image row
;Filter the image rows
;If there are at least two elements in an image column
;Filter the image columns
;If the shared library of DanIDL C++ routines is not installed, then use the default IDL code
;Compute the overall gain
;If "tol" is greater than "0.0" but less than "1.0", then calculate the lengths of the
;required truncated sums
;If there are at least two elements in an image row
;Filter the image rows
;Extract the current image row, applying the overall gain
;For each pole
;If the length of the truncated sum is less than the length of an image row, then calculate
;the initial value of the causal coefficient with a truncated sum
;If the length of the truncated sum is the same as or greater than the length of an image row,
;then calculate the initial value of the causal coefficient with a full sum
;Execute the causal recursion on the current image row
;Calculate the initial value of the anti-causal coefficient
;Execute the anti-causal recursion on the current image row
;Save the filtered current image row
;If "tol" is greater than "0.0" but less than "1.0", then calculate the lengths of the
;required truncated sums
;If there are at least two elements in an image row
;Filter the image columns
;Extract the current image column, applying the overall gain
;For each pole
;If the length of the truncated sum is less than the length of an image column, then calculate
;the initial value of the causal coefficient with a truncated sum
;If the length of the truncated sum is the same as or greater than the length of an image column,
;then calculate the initial value of the causal coefficient with a full sum
;Execute the causal recursion on the current image column
;Calculate the initial value of the anti-causal coefficient
;Execute the anti-causal recursion on the current image column
;Save the filtered current image column
;Return the output array of interpolation coefficients