;+
; NAME:
;	SMEI_IMAGE
;
;
; PURPOSE:
;	Extract a SMEI image object from a sequence
;
;
; CATEGORY:
;	CLI
;
;
; CALLING SEQUENCE:
;	smei_image, seq, index, image
;
;
; INPUTS:
;	seq	objref	Object reference of the sequence.
;	index	long	The image number to get (1-based).
;
;
; OUTPUTS:
;	image	objref	A named variable to contain the reference to
;			the image. (If the image is not found then the
;			contents are unchanged).
;
;
; RESTRICTIONS:
;	DO NOT DESTROY the returned image, doing so will break the
;	sequence. 
;
;
; MODIFICATION HISTORY:
;	Original: 8/1/03; SJT
;-

pro smei_image, seq, index, image, help = help

if keyword_set(help) then begin
    self_help
    return
endif

if not arg_present(image) then begin
    smei_msg, /warn, ['SMEI_IMAGE must have 3 arguments,', $
                      'the third must be writable']
    return
endif

if not obj_valid(seq) then begin
    smei_msg, /warn, ['The specified sequence must be a valid', $
                      'object reference']

    return
endif

if not obj_isa(seq, 'SMEI_SEQUENCE') then begin
    smei_msg, /warn, ['The first argument of SMEI_IMAGE must', $
                      'be a reference to a SMEI_SEQUENCE']
    return
endif

if index lt 1 or index gt seq -> get_count() then begin
    smei_msg, /warn, 'The image number is out of range'
    return
endif

image = seq -> get_image(index-1)

end