;+
; NAME:
;	smei_frm_read
; PURPOSE:
;	Read SMEI frame
; CATEGORY:
;	camera/idl/misc
; CALLING SEQUENCE:
	FUNCTION smei_frm_read, ff	, $
		source		= source	, $
		head_room	= head_room	, $
		hdr			= hdr		, $
		silent		= silent	, $
		error		= error		, $
		nodata		= nodata	, $
		ramdisk		= ramdisk	, $
		raw			= raw		, $
		allow_bad	= allow_bad	, $
		ls_corrupt	= ls_corrupt, $
		rm_corrupt	= rm_corrupt
; INPUTS:
;	ff				scalar; type: string
;						file name of SMEI frame
;						If no file type is specified then .fts.gz is assumed
;						If no directory is specified then the main
;						SMEI data base on smeidb is used.
; OPTIONAL INPUT PARAMETERS:
;	source=source	scalar; type: string
;						source directory of SMEI frames
;	/nodata 		if set, only read the frame header
;					(return value of img will be -1).
; OUTPUTS:
;	img				array[n,m]; type: integer
;						SMEI frame data
; OPTIONAL OUTPUT PARAMETERS:
;	hdr=hdr			array[1]; type: structure
;						frame header
;	error=error		scalar; type: string
;						error string. Will be the null string if
;						file was read successfully.
; INCLUDE:
	@compile_opt.pro		; On error, return to caller
	@smei_roi_mask.pro		; ROI mask common block
; CALLS:
;	SetFileSpec, GetFileSpec, timeposn, TimeUnit, TimeGet
;	InitVar, bin_read, smei_frm_cvhdr, smei_filepath, TimeOp
;	smei_property, IsType, readfits, headfits
; SEE ALSO:
; SIDE EFFECTS:
; RESTRICTIONS:
;	Andy renames .nic files to .raw to look at them in Adobe Photoshop.
;	For now we assume that all .raw files are indeed .nic files in disguise.
; PROCEDURE:
; MODIFICATION HISTORY:
;	MAY-2003, Paul Hick (UCSD/CASS)
;	JUN-2003, Paul Hick (UCSD/CASS)
;		Added check for missing file extension.
;	JUL-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
;		Added /ramdisk keyword
;-

InitVar, nodata , /key
InitVar, raw	, /key
InitVar, silent , 0

InitVar, ls_corrupt, /key
InitVar, rm_corrupt, /key

type = GetFileSpec(ff, part='type')

CASE GetFileSpec(upto='directory') EQ '' OF
0: img_file = ff
1: BEGIN
	CASE 1 OF
	IsType(source,/undefined): tmp = smei_filepath(GetFileSpec(ff, part='name'))
	source EQ 'SMEIDB?'	 : tmp = smei_filepath(GetFileSpec(ff, part='name'),source=source)
	source EQ 'SMEIDC?'	 : tmp = smei_filepath(GetFileSpec(ff, part='name'),source=source)
	ELSE	 : tmp = source
	ENDCASE
	img_file = filepath(root=tmp,ff)
END
ENDCASE

IF type EQ '' THEN BEGIN
	type = '.fts.gz'
	img_file += type
ENDIF

; Andy renames .nic files to .raw to look at them in Adobe Photoshop.
; For now we assume that all .raw files are indeed .nic files in disguise.

is_nic = strpos(img_file,'.nic') NE -1 OR strpos(img_file,'.raw') NE -1

CASE is_nic OF
0: BEGIN
	CASE nodata OF
	0: BEGIN
		img = readfits(img_file, fits_hdr, silent=silent)
		error = (['','read error'])[n_elements(img) EQ 1]
	END
	1: BEGIN
		img = -1
		error = ''
		fits_hdr = headfits(img_file, silent=silent, errmsg=error)
	END
	ENDCASE
END
1: BEGIN
	status = bin_read(img_file, img, trailer=byte_hdr, error=error, silent=silent, ramdisk=ramdisk)
	IF nodata THEN img = -1
END
ENDCASE

CASE error EQ '' OF
0: BEGIN
	;if silent le 1 then message, /info, img_file+', '+error
	IF silent LE 1 THEN message, /info, error+', '+hide_env(img_file)
	img = -1
END
1: BEGIN

	CASE is_nic OF
	0: hdr = smei_frm_cvhdr(from_fits=fits_hdr, /to_hdr, allow_bad=allow_bad)
	1: hdr = smei_frm_cvhdr(from_byte=byte_hdr[3:*] , /to_hdr)
	ENDCASE

	CASE IsType(hdr,/structure) OF

	0: img = -1

	1: BEGIN

		ut = smei_property(hdr,/time)

		; Sanity checks

		; Make sure the file name agrees with the header
		; If not the file is corrupt.

		usec = TimeUnit(/sec)
		IF TimeOp(/subtract, ut, timeposn(ff,/extract,part='name'), usec) NE 0 THEN BEGIN
			tmp = 'bad time, '+hide_env(ff)+' '+TimeGet(ut,/_ydoy,upto=usec)
			CASE 1 OF
			ls_corrupt: message, /info, tmp
			rm_corrupt: BEGIN
				message, /info, tmp
				tmp = do_file(/delete, ff)
			END
			ELSE: message, 'bad time: '+ff+' '+TimeGet(ut,/_ydoy,upto=usec)
			ENDCASE
		ENDIF

		IF NOT nodata AND NOT raw THEN BEGIN
			head_room = 1d0

			IF smei_property(hdr, /onboard_ff_enabled) THEN BEGIN

				head_room = 0.75d0	;50000d0/65535d0

				; Fix the 0.75 head room

				img = round(img/head_room)

				; In the onboard small-scale flatfield the partially covered pixels
				; are set to zero. For m=0 (no rebinning) this results in two
				; columns of zeros. For m=1,2 the rebinning is done AFTER the
				; flatfield is applied, so 1st and last column inside the FOV
				; (corresponding to *roi_bad[m]) underestimate the intensity by a
				; factor 2^m/(2^m-1), i.e. a factor 2 in mode 1 and a factor 4/3
				; in mode 2 (mode 1: 2 of 4 pixels averaged are zero; mode 2; 4 of
				; 16 pixels are zero).

				m = smei_property(hdr,/mode)

				IF m NE 0 THEN BEGIN
					tmp = 2^m
					tmp = tmp/(tmp-1d0)
					img[*roi_bad[m]] = round(tmp*img[*roi_bad[m]])
				ENDIF
			ENDIF
		ENDIF

	END
	ENDCASE

END
ENDCASE

RETURN, img  &  END