# NAME: take_shutter_frames.cl
#
# VERSION: 20121111
# PACKAGES: icex

# An IRAF-ICE procedure for taking the images need to build a
# shutter correction data frame
#
# Reference: Stetson, P.B. 1989, in `Highlights in Astronomy' Vol.8, 635.
#
# The exposure times and filter have been set for instrument DIAFI and the
# HJST 150 W flat field bulb on the back of the secondary mirror.
#
# Assuming you have IRAF environment variable 'home' set in your login.cl file,
# and that your scripts are in directory 'scripts' within your IRAF home
# directory, then you can load script take_shutter_frames with:
#
# task take_shutter_frames = home$scripts/take_shutter_frames.cl
#
# A pair of shutter correction images consists of:
#   1x 30 sec and 30x 1.00 sec
# After the pair(s), a 1x 30 sec frame is taken to monitor the light level
# Four pairs of correction images (9 images) takes ?? min
# Six pairs of correction images (13 images) takes ?? min
#
# It is possible to stop the script during the short exposures
# by creating a file "stop" in the current directory.
# Abort works at the end of each frame.
#
# To derive the delta image from these images:
#   -Fix bad pixels, subtract bias pedestal, trim, subtract master bias
#   -Either:
#      make the master delta frame with the script make_shutter_frame
#   -Or:
#      *Make one combined image from the 1x 30 s frames,   (shutter-long)
#      *Make one combined image from the 30x 1.00 s frames (shutter-shorts)
#      *Derive the quotient frame:  R = shutter-shorts/shutter-long
#      *Derive the delta frame:     I_delta = 30(1-R) / (R-30)
#
# The delta frame is the time difference between the
# set exposure time and the actual exposure time:
# exptime(actual) = exptime(set) + delta
#
# I_delta=(n*t_s - t_l*R)/(R-n), where
# t_l=long integration time, t_s=short integration time, n=number of short ints.
#
# I_c=I_o*t_o/(t_o+I_delta)
# I_c=corrected image, I_o=observed image, t_o=observed image integration time

procedure take_shutter_frames(number_of_pairs)

int  number_of_pairs {5,prompt="Enter the required number of pairs of images"}
char filter_name     {"Halpha_z0_1nm",prompt="Enter the filter name"}
#real short_int_time  {1.0, prompt="Enter the short integration time"}
#real long_int_time   {30.0,prompt="Enter the long integration time"}

begin
int n_pairs
char n_pointsave

n_pairs=number_of_pairs

# Load the filter
instrument(instrfi="@"//filter_name)

# Set the detector parameters
cache("detpars")
detpars.firstc=1
detpars.lastc=2048
detpars.firstr=1
detpars.lastr=2048
detpars.colbin=2
detpars.rowbin=2
detpars.integrator=3

# start n_pairs pairs of shutter correction frames

for(j=1; j<=n_pairs; j+=1){

  # Take a long exposure frame (1x30sec)
  printf("\nTaking the long-integration frame for pair %d of %d:\n\n",j,n_pairs)
  observe(obj="Shutter-long",image="flat",exposure=30,setfilter-,setfocus-)

  if (qpars.aborted || access("stop")) break

  # Take a short exposures frame (30x1.00sec)
  printf("\nTaking the frame of short-integrations for pair %d of %d:\n\n",
    j,n_pairs)
  observe(obj="Shutter-shorts",image="focus",nfexpo=30,shtype="detector",
    focmode="auto",fstart="+0",fdelta="+0",nrvrows=0,exposure=1.00,setfilter-)

  if (qpars.aborted || access("stop")) break
} #for

if (!qpars.aborted && !access("stop")) {
  # End with a long exposure to bracket the short exposures frames
  printf("\nTaking the final long-integration frame:\n\n")
  observe(obj="Shutter-long",image="flat",exposure=30,setfilter-)
} #if

end