FUNCTION smei_frm_flatfield, frm, camera=camera, ssff=ssff, lsff=lsff, clsff=clsff, $
	mode=mode, raw=raw, silent=silent
;+
; NAME:
;	smei_frm_flatfield
; PURPOSE:
;	Get small or large-scale flatfield for the SMEI cameras.
; CATEGORY:
;	camera/idl/field
; CALLING SEQUENCE:
;	ff = smei_frm_flatfield(camera=camera [, /lsff)
; INPUTS:
; OPTIONAL INPUT PARAMETERS:
;	camera=camera		scalar; type: integer; default: 1
;							camera number (1,2, or 3)
;	/lsff				get large scale flatfield instead of
;						small scale flatfield.
; OUTPUTS:
;	ff					array[1272,256]; type: double
;							flatfield value; the flatfield is applied
;							by multiplying the uncorrected value by ff.
; INCLUDE:
	@compile_opt.pro		; On error, return to caller
	@smei_roi_mask.pro		; ROI definition
; CALLS:
;	InitVar, who_am_i
; PROCEDURE:
;	SMALL SCALE (ON BOARD) FLAT FIELDS:
;
;	c1_ssff.fts.gz, c2_ssff.fts.gz, c3_ssff.fts.gz
;
;	For the small-scale flatfields, if the uncorrected CCD-readout is N ADUs,
;	then the flat field corrected read-out M follows by adding one to the
;	flatfield values and multiplying, i.e. with ff the array read from the
;	FTS file:
;
;	M = (1+ff)*N
;
;	The addition of 1 is already done in the output array
;	(i.e. 1+ff is returned).
;
;
;	LARGE SCALE FLAT FIELDS:
;
;	c1_lsff.fts.gz, c2_lsff.fts.gz, c3_lsff.fts.gz
;
;	For the large-scale flatfields, if the uncorrected readout is N ADUs, then
;	the flat field corrected readout M follows by dividing by the flat field
;	value, i.e. with ff the array from the FTS file:
;
;	M = N/ff
;
;	The inversion is already done in the output array (i.e. 1/ff is returned).
;
;
;	RAL TO SMEI MAPPING (applies to ssff and lsff files, NOT the lsffc files):
;
;	All FTS files contain float arrays of size 1280x600 ('RAL frame'). The SMEI
;	engineering mode (mode 0) frames have dimensions 1272x256. The pixels in a
;	SMEI frame are a subset of the pixels in a RAL frame. The RAL frame is
;	mapped to the SMEI frame by dropping the first 5 columns, then extracting
;	the next 1272 columns; and dropping the first 65, 59 and 61 rows for
;	cameras 1, 2 and 3, resp., then extracting the next 256.
;
;	Let:
;		n = 5, m = 65	for camera 1
;		n = 5, m = 59	for camera 2
;		n = 5, m = 61	for camera 3
;
;	Then in IDL (with 0-based array indices):
;
;		SMEI = RAL[n:n+1271,m:m+255]
;
;	or pixel-by-pixel:
;
;		SMEI[i,j] = RAL[n+i,m+j]
;
;	In Fortran (1-based array indices):
;
;		for j=1,256
;	    	for i=1,1272
;	    	    SMEI[i,j] = RAL[n+i,m+j]
;	    	end for
;		end for
;
;	NORMALIZED FLAT FIELD CORRECTION (clsff):
;
;	c1_clsff.fts.gz, c2_clsff.fts.gz, c3_clsff.fts.gz
;
;	Contain arrays of size 1280x301 with numbers of order 1. As far as I can
;	tell these are based on the large-scale flat field files with a couple of
;	modifications:
;	- geometrical effects are taken out (cosine effect along long dimension due
;	  to changing effective aperture size, and radial effect along the narrow
;	  dimension
;	- a couple of 'bad pixels' are stamped out
;
;	Even though the arrays suggest they are in engineering mode they are
;	effectively in mode 2 (4x4 binning): numbers are identical in groups of 4x4.
;	To use them with the SMEI an offset needs to be taken into account different
;	from the large-scale flatfield discussed above: the first two columns need
;	to be dropped, and the first 16, 10 and 12 rows for cameras 1,2 and 3,
;	respectively.
;	So let:
;		n = 2, m = 16	for camera 1
;		n = 2, m = 10	for camera 2
;		n = 2, m = 12	for camera 3
;	Then use the same code as above for the large-scale flatfields.
; MODIFICATION HISTORY:
;	JAN-2004, Paul Hick (UCSD/CASS)
;	NOV-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
;		Added the normalized flatfield corrections.
;-

InitVar, raw	, /key
InitVar, silent , 0
InitVar, camera , 1
InitVar, lsff	, /key
InitVar, clsff	, /key

ssff = 1-lsff AND 1-clsff

CASE 1 OF
ssff : postfix = 'ssff'
lsff : postfix = 'lsff'
clsff: postfix = 'clsff'
ENDCASE

dim = *(roi_siz)[0] 			; Mode 0 size is 1272 x 256

tmp = 'c'+strcompress(camera,/rem)+'_'+postfix+'.fts.gz'

ff = ''
root = getenv('SSWDB_SMEI')
IF root NE '' THEN ff = file_search( filepath(root=root, subdir='flatfield', tmp) )
IF ff   EQ '' THEN ff = file_search( filepath(root=who_am_i(/dir), tmp) )
IF ff   EQ '' THEN message, /info, 'flatfield not found: '+tmp

IF silent LT 1 THEN message, /info, ff
ff = readfits(ff)

IF raw THEN RETURN, ff

CASE clsff OF
1: BEGIN
    nn = 2
	mm = ([16,10,12])[camera-1]
END
0: BEGIN
	nn = 5							; # columns to drop from the left
	mm = ([65,59,61])[camera-1]		; # rows to drop from the bottom
END
ENDCASE

ff = ff[nn:nn+dim[0]-1,mm:mm+dim[1]-1]

CASE 1 OF
ssff : ff = 1d0+double(ff)
lsff : ff = 1d0/double(ff)
clsff: ff = 1d0/double(ff)
ENDCASE

CASE 1 OF

IsType(mode, /defined): BEGIN
	mag = 2^mode

	CASE clsff OF
	0: ff = MagnifyArray(ff, mag, /undo)
	1: ff = MagnifyArray(ff, 4/mag)
	ENDCASE
END

IsType(frm , /defined): BEGIN

	dim = size(frm, /dim)
	mag = (*(roi_siz)[0]/dim)[0]

	CASE clsff OF
	0: ff = MagnifyArray(ff, mag, /undo)
	1: ff = MagnifyArray(ff, 4/mag)
	ENDCASE

	nf = n_elements(frm)/(dim[0]*dim[1])

	ff = frm*SuperArray(ff, nf, /trail)	

END

ELSE:

ENDCASE

RETURN, ff  &  end