C+
C NAME:
C	smei_cal_c3mask
C PURPOSE:
C	Reads bad pixel mask for camera 3
C CATEGORY:
C	gen/for/lib/frm
C CALLING SEQUENCE:
	logical function smei_cal_c3mask(ipatt,tframe,flat_enabled,mask,tmask)
C INPUTS:
C	ipatt		integer		0/1, passed to smei_frm_c3mask_active
C	tframe		character	SMEI frame time in format YYYY_DOY_hhmmss
C	flat_enabled	integer		nint(hdr(SMEI__HDR_FLAT_ENABLED)) or -1
C					"flatfield-enabled" flag from SMEI frame header
C OUTPUTS:
C	smei_cal_c3mask	logical		.TRUE. : bad pixel mask in use for specified time
C						and flatfield flag (if not -1)
C					.FALSE.: no bad pixel mask in use for specified time
C						and flatfield flag (if not -1)
C	mask(*)		real		bad pixel mask
C					Mask has full resolution of 1272x256 and
C					contains values 0 and 1.
C					If no bad pixel mask is in effect than all values
C					in the mask are set to 1.
C	tmask		character*(SMEI__UT_FORMAT_LEN)
C					smei_cal_c3mask=.TRUE. : name of C3 "bad-pixel" mask
C					smei_cal_c3mask=.FALSE.: blank string
C CALLS:
C	iFilePath, bOpenFile, ArrR4Constant, Str2Str, Int2Str, itrim, Say
C	cInt2Str, iFreeLun
C INCLUDE:
	include		'filparts.h'
	include		'dirspec.h'
	include		'openfile.h'
	include		'smei_frm_layout.h'
C PROCEDURE:
C	The test for whether or not a "bad pixel" needs to be read is
C	done by smei_frm_c3mask_active.
C
C	A mask is applied only for camera 3 in mode 1 (2x2 binned). The mask is
C	multiplied with the readout onboard, EXCEPT THAT the mask is NOT APPLIED
C	when a whole 2x2 group of mask elements is zero. In this case the
C	the usual 2x2 average is returned.
C
C	Therefore, if a 2x2 group of elements in the mask read from file is set
C	to zero (flagged as "bad") then the 4 pixels in this group are set back
C	to one (set to "good").
C MODIFICATION HISTORY:
C	FEB-2007, Paul Hick (UCSD/CASS)
C	JUN-2011, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
C	    Added new argument, tmask, to return name of C3 "bad-pixel" mask.
C-
	    integer		ipatt
	    character*(*)	tframe
	    integer		flat_enabled
	    real		mask(SMEI__FRM_NX,SMEI__FRM_NY)
	    character		tmask*(SMEI__UT_FORMAT_LEN)

	character	cSay*15	/'smei_cal_c3mask'/

	character	cfile*(FIL__LENGTH)
	character	cfmt *10

	integer		smei_frm_c3mask_active
	logical		bOpenFile
	integer		Str2Str
	character	cInt2Str*14

	smei_cal_c3mask = smei_frm_c3mask_active(ipatt,tframe,flat_enabled,tmask,fudge) .eq. 1

	if (smei_cal_c3mask) then		! "Bad pixel" mask i is in effect

	    i = iFilePath(cEnvi(:iEnvi)//'SMEIDB',1,'c3mask','ff_mask_'//tmask//'.txt',cfile)

	    i = 0
	    smei_cal_c3mask = bOpenFile(OPN__REOPEN+OPN__TEXT,iu,cfile,i)

	    if (smei_cal_c3mask) then		! Mask file opened successfully

		i = 0
		i = i+Str2Str('('	  , cfmt(i+1:))
		i = i+Int2Str(SMEI__FRM_NX, cfmt(i+1:))
		i = i+Str2Str('F1.0)'	  , cfmt(i+1:))

		do j=1,SMEI__FRM_NY				!  256 rows
		    read (iu,cfmt) (mask(i,j),i=1,SMEI__FRM_NX)	! 1272 columns
		end do

		iu = iFreeLun(iu)

		! Check 2x2 groups of pixels where mask is set to bad (zero)
		! These are set back to good (one) because on-board these
		! pixels are NOT stamped out!!

		n = 0
		do j=1,SMEI__FRM_NY,2
		    do i=1,SMEI__FRM_NX,2
			if (mask(i,j)+mask(i+1,j)+mask(i,j+1)+mask(i+1,j+1) .eq. 0.0) then
			    n = n+1
			    mask(i  ,j  ) = 1.0
			    mask(i+1,j  ) = 1.0
			    mask(i  ,j+1) = 1.0
			    mask(i+1,j+1) = 1.0
			end if
		    end do
		end do

		call Say(cSay,'I','#'//cfile,'"bad-pixel" mask')
		call Say(cSay,'I',cInt2Str(n),'2x2 "bad-pixel" groups set to "good"')

	    end if

	end if

	! Safety belt: return value 1.0 in the mask everywhere
	! If the mask is used then it is usually multiplied with another array.
	! Setting values to 1.0 means that no damage will be done.
	
	if (.not. smei_cal_c3mask) call ArrR4Constant(SMEI__FRM_NPIX,1.0,mask)

	return
	end