PRO fit_lintrans_2d, x1, y1, x2, y2, weights, x1t, y1t, param, det, status
; Description: This module fits a linear transformation with six free parameters that maps
; as closely as possible (in a least squares sense) the points with coordinates
; "(x1,y1)" in the coordinate space S1 to the same points with coordinates
; "(x2,y2)" in a different coordinate space S2. The fitted model relating the
; coordinates in S1 to the coordinates in S2 is defined by:
;
; x2 = A*x1 + B*y1 + E
; y2 = C*x1 + D*y1 + F
;
; If required, the fit can be weighted via the parameter "weights". The fitted
; parameters A, B, C, D, E and F are returned via the output parameter "param"
; along with the status of the fit "status". Note that there must be at least
; three points in each coordinate list in order for the module to succeed.
;
; Input Parameters:
;
; x1 - FLOAT/DOUBLE VECTOR - A one-dimensional vector of x coordinates for the points in the
; coordinate space S1.
; y1 - FLOAT/DOUBLE VECTOR - A one-dimensional vector of y coordinates for the points in the
; coordinate space S1. This vector must have the same number of
; elements as "x1".
; x2 - FLOAT/DOUBLE VECTOR - A one-dimensional vector of x coordinates for the points in the
; coordinate space S2. This vector must have the same number of
; elements as "x1".
; y2 - FLOAT/DOUBLE VECTOR - A one-dimensional vector of y coordinates for the points in the
; coordinate space S2. This vector must have the same number of
; elements as "x1".
; weights - FLOAT/DOUBLE VECTOR - A one-dimensional vector with the same number of elements
; as "x1", that contains weights to be used in the calculation
; of the fitted linear transformation. If this vector does not
; have the same number of elements as "x1", then all point
; pairs are weighted equally. Point pairs to be ignored can be
; pre-flagged by setting the corresponding weights in this
; array to zero (or negative values).
;
; Output Parameters:
;
; x1t - DOUBLE VECTOR - A one-dimensional vector of x coordinates in the coordinate space S2
; obtained by transforming the x coordinates of the points in the
; coordinate space S1 using the fitted model transformation.
; y1t - DOUBLE VECTOR - A one-dimensional vector of y coordinates in the coordinate space S2
; obtained by transforming the y coordinates of the points in the
; coordinate space S1 using the fitted model transformation.
; param - DOUBLE VECTOR - A vector of six DOUBLES representing the fitted quantities A, B, C,
; D, E and F in this order.
; det - DOUBLE - The determinant of the linear transformation defined by:
;
; det = (A*D) - (B*C)
;
; status - INTEGER - If the module successfully fit a linear transformation to the coordinate
; data, then "status" is returned with a value of 1, otherwise it is returned
; with a value of 0.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 11/08/2008 - Module created (dmb)
;Check that "x1" is a vector containing number data
;Check that "y1" is a vector containing number data
;If the first coordinate list has less than three points, or the number of x coordinates is not
;equal to the number of y coordinates for this list, then return with a status of "0"
;Check that "x2" is a vector containing number data
;Check that "y2" is a vector containing number data
;If the second coordinate list has less than three points, or the number of x coordinates is not
;equal to the number of y coordinates for this list, then return with a status of "0"
;If the number of points in each coordinate list is not the same, then return with a status of "0"
;If "weights" is not a number vector with the same number of elements as "x1", then weight all point
;pairs equally, otherwise set any negative weights equal to zero.
;Calculate the elements of the matrix to be inverted
;Calculate the first vector on the right
;Calculate the second vector on the right
;Set up the matrix and then invert it
;If the matrix was inverted successfully
;Calculate the fitted parameters of the linear transformation
;Calculate the determinant of the fitted linear transformation
;Calculate the coordinates of the points from the first coordinate list after applying
;the fitted linear transformation
;Set the status to "1"