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"