PRO calculate_interpolation_coeffs_1dvec, vdata, poles, tol, coeffs, status, danidl_cppcode
; Description: This module calculates the vector of interpolation coefficients "coeffs" for an input
; vector of data "vdata" and an 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 module 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 ~55 times faster than the
; IDL code in this case.
;
; Input Parameters:
;
; vdata - FLOAT/DOUBLE VECTOR - A one-dimensional data vector for which the interpolation coefficients
; are to be calculated. Note that this data vector should not contain
; bad data values, and therefore such values should have been previously
; interpolated over in "vdata".
; poles - FLOAT/DOUBLE VECTOR - A one-dimensional vector of values for the poles required for the
; recursive filter. The elements of this vector must be non-zero. 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 is calculated from a subset of data
; values, while achieving the acceptable relative error "tol". By setting this
; parameter to any other value, including "0.0", the initial value of the causal
; coefficient is calculated exactly from all the data values in the data vector.
; danidl_cppcode - 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.
;
; Output Parameters:
;
; coeffs - DOUBLE VECTOR - A one-dimensional vector of the same length as "vdata" that represents the
; interpolation coefficients for the interpolation scheme with filter poles
; "poles".
; status - INTEGER - If the vector of interpolation coefficients "coeffs" was calculated successfully,
; then "status" is returned with a value of "1", otherwise it is returned with a
; value of "0".
;
; N.B: In DanIDL, I adopt a pixel coordinate system such that the origin of the coordinate system is
; at the left hand side of the left hand pixel in a vector. Therefore, the centre of the left
; hand pixel in a vector has an x coordinate of 0.5 in this coordinate system. For each full pixel
; moved to the right in the vector, the x pixel coordinate increments by 1.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 15/08/2010 - Module created (dmb).
;Set the default output parameter values
;Check that "vdata" is a one-dimensional vector of the correct number type
;Check that "poles" is a one-dimensional vector of the correct number type, and that it has no zero
;values
;Check that "tol" is a number of the correct type
;Set up the output vector of interpolation coefficients "coeffs"
;If there is only one input data point, then return "coeffs" without any filtering
;Determine if the shared library of DanIDL C++ routines is installed
;If the shared library of DanIDL C++ routines is installed, then use the C++ code to speed up the
;calculation of the interpolation coefficients
;Calculate the interpolation coefficients
;If the shared library of DanIDL C++ routines is not installed, then use the default IDL code
;Compute the overall gain, and apply this gain to the interpolation coefficients
;If "tol" is greater than "0.0" but less than "1.0", then calculate the lengths of the required
;truncated sums
;For each pole
;Extract the value of the current pole and the length of the corresponding truncated sum
;If the length of the truncated sum is less than the length of "vdata"
;Calculate the initial value of the causal coefficient with a truncated sum
;If the length of the truncated sum is greater than or equal to the length of "vdata"
;Calculate the initial value of the causal coefficient with a full sum
;Store the initial value of the causal coefficient
;Execute the causal recursion on the interpolation coefficients
;Calculate the initial value of the anti-causal coefficient
;Execute the anti-causal recursion on the interpolation coefficients
;Set "status" to "1"