;+
; NAME:
;    IDLSNAP
;
; PURPOSE:
;    Grab one grayscale image from a a video file or from a 
;    frame grabber using the IDLvideo interface
;
; CATEGORY:
;    Image acquisition, Image processing.
;
; CALLING SEQUENCE:
;    a = idlsnap([filename], channel = channel, geometry = geometry)
;
; OPTIONAL INPUTS:
;    filename: Name of a video file
;
; KEYWORD PARAMETERS:
;    channel: camera number.  Default: 0
;
;    geometry: Dimensions of image [xsize, ysize]
;        Default: the natural dimensions for the video source.
;
; KEYWORD FLAGS:
;    stabilize: keep taking pictures until no pixel varies by more
;        than this value.
;
;    quiet: If set, do not provide diagnostic messages.
;
; OUTPUTS:
;    a: [xsize,ysize] byte array of pixels.
;       Returns -1 if image acquisition failed.
;
; PROCEDURE:
;    Calls routines from the IDLvideo library.
;
; EXAMPLE:
;    IDL> a = idlsnap()
;
; MODIFICATION HISTORY:
; 04/30/2003: David G. Grier, The University of Chicago, created.
; 09/29/2004: DGG New York University:
;                  replaced KEYWORD_SET with N_PARAMS.
;                  implemented STABILIZE keyword.
; Version 1.1 DGG, New York University.
;       Updated for IDL 6.1.
;       Try again if library call fails, rather than returning junk.
;
; Version 2.0 DGG: Updated for OpenCV interface
; 06/04/2010 DGG major overhaul
; 06/10/2010 DGG Return -1 on failure.  Add COMPILE_OPT.
; 12/29/2010 DGG use default geometry for cameras.
;
; Copyright (c) 2003-2010 David G. Grier
;
; UPDATES:
;    The most recent version of this program may be obtained from
;    http://physics.nyu.edu/grierlab/software.html
; 
; LICENSE:
;    This program is free software; you can redistribute it and/or
;    modify it under the terms of the GNU General Public License as
;    published by the Free Software Foundation; either version 2 of the
;    License, or (at your option) any later version.
;
;    This program is distributed in the hope that it will be useful,
;    but WITHOUT ANY WARRANTY; without even the implied warranty of
;    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
;    General Public License for more details.
;
;    You should have received a copy of the GNU General Public License
;    along with this program; if not, write to the Free Software
;    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
;    02111-1307 USA
;
;    If the Internet and WWW are still functional when you are using
;    this, you should be able to access the GPL here: 
;    http://www.gnu.org/copyleft/gpl.html
;-

function idlsnap, filename, $
                  channel = channel, $
                  geometry = geometry, $
                  stabilize = stabilize, $
                  quiet = quiet

COMPILE_OPT IDL2

report = ~keyword_set(quiet)

if n_params() eq 1 then $
   s = open_videofile(filename, geometry = geometry, /gray) $
else begin
   if ~arg_present(channel) then $
      channel = 0
   s = open_videocamera(channel, geometry = geometry, /gray)
endelse

if ~is_videostream(s) then begin
   if report then $
      message, "Could not acquire video frame", /inf
   return, -1
endif

image = read_videoframe(s)

if keyword_set(stabilize) then begin
   npix = 1
   maxpix = 60                  ; more than 2 seconds
   image2 = image
   repeat begin
      image = read_videoframe(s)
      delta = max(abs(fix(image)-fix(image2)))
      image = image2
      npix++
   endrep until (delta lt stabilize) or (npix ge maxpix)
   if npix ge maxpix and report then $
      message, "Image not stabilized", /inf
endif

close_video, s

return, image
end