;+
; NAME:
;	SMEI_IMAGE_IMAGE
;
;
; PURPOSE:
;	Gets the actual image data from a SMEI_IMAGE
;
;
; CATEGORY:
;	CLI
;
;
; CALLING SEQUENCE:
;	smei_image_image, imref, image[, /raw]
;	or
;	smei_image_image, seqref, image, index=index[, /raw]
;
;
; INPUTS:
;	imref	objref	Object reference to the image object
;
;
; OPTIONAL INPUTS:
;	seqref	objref	Object reference to the SMEI_SEQUENCE
;			containing the image to be extracted.
;
;
; KEYWORD PARAMETERS:
;	index	long	Image index (1-based) used when the first
;			argument is a sequence
;	/raw		If set, then extract the raw image and
;			weights, rather than the normalized image
;			(will fail if the image object is compacted).
;	plane	int	If set, then select the specified 1-based
;			plane of the raw image.
;	flag	int	If set, then extract the image flag data.
;			1: Flags for the current orbit astrometry
;			2: Flags for the next orbit astrometry
;			3: Both flag planes
;	/time		If set, then extract the times from the
;			ancillary data
;	/longitude	If set, then extract the s/c longitude from
;			the ancillary data
;	/latitude	If set, then extract the s/c latitude from the
;			ancillary data
;
; OUTPUTS:
;	image	float	A named variable to receive the image data.
;
;
; RESTRICTIONS:
;	If the source is a sequence, then the index keyword must be
;	used. If it is an image then index is ignored.
;
;
; MODIFICATION HISTORY:
;	Original: 8/1/03; SJT
;	Added missing plane keyword: 20/1/04; SJT
;	Added flag and ancillary data keys: 6/4/10; SJT
;-

pro smei_image_image, source, image, index = index, raw = raw, plane = $
                      plane, flag = flag, time = time, longitude = $
                      longitude, latitude = latitude, help = help

if keyword_set(help) then begin
    self_help
    return
endif

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

if not obj_valid(source) then begin
    smei_msg, /warn, ['The specified source for the image must be', $
                      'a valid object reference']

    return
endif

if obj_isa(source, 'SMEI_SEQUENCE') then begin

    if n_elements(index) eq 0 then begin
        smei_msg, /warn, ['If the source in SMEI_IMAGE_IMAGE is a', $
                          'sequence then the INDEX keyword must be given']
        return
    endif
    if index lt 1 or index gt source -> get_count() then begin
        smei_msg, /warn, 'The image number is out of range'
        return
    endif

    img = source -> get_image(index-1)
endif else if obj_isa(source, 'SMEI_IMAGE') then img = source $
else begin
    smei_msg, /warn, ['The source argument of SMEI_IMAGE_IMAGE must ', $
                      'be a SMEI_IMAGE or a SMEI_SEQUENCE']
    return
endelse

if keyword_set(flag) then case flag of
    3: image = img -> get_flag_data()
    2: image = img -> get_flag_data(/next)
    1: image = img -> get_flag_data(/current)
    else: begin
        smei_msg, /warn, 'Invalid flag selection, using FLAG=1'
        image = img -> get_flag_data(/current)
    end
endcase else if keyword_set(time) then image = img -> get_ancil(/time) $
else if keyword_set(longitude) then image = img -> get_ancil(/longitude)  $
else if keyword_set(latitude) then image = img -> get_ancil(/latitude) $
else if keyword_set(raw) then image = img -> get_raw_image() $
else if keyword_set(plane) then image = img -> get_raw_image(plane = $
                                                             plane) $
else image = img -> get_image()

end