;+
; NAME:
;	SMEI_IMAGE_INFO
;
;
; PURPOSE:
;	Get various information from a SMEI_IMAGE
;
;
; CATEGORY:
;	CLI
;
;
; CALLING SEQUENCE:
;	smei_image_info, source, info, <selector keyword>, [, index=index]
;
;
; INPUTS:
;	source	objref	Either a SMEI_IMAGE object or a SMEI_SEQUENCE
;                       object 
;
;
; KEYWORD PARAMETERS:
;	index	int	If source is a sequence, then this keyword
;			MUST be set to specify which image is to be
;			queried.
;	/planes		If set, then return the number of planes in
;			the raw image
;	/scale		If set, then return the image scale
;	/size		If set, then return the image size
;	/summary	If set, then return a 1-line summary of the
;			image.
;	/time		If set, then return the time range of the image.
;	/unit		If set, then return the unit of the image.
;	/file		If set, then return the original fits file
;			name of the image
;	/projection	If set, then return the image projection.
;	/start & /stop	Qualify the /time keyword to only return the
;			start or stop time.
;	/convert	If set and /time and one of /start or /stop is
;			set, then return the DOY format.
;	/x & /y		Qualify the /scale and /size keywords to only
;			return the X or Y components.
;	/string		Qualify the projection key to return the name
;			of the projection
;	/astrom_code	Qualify the projection key to return the code
;			needed by wcsxy2sph and WCSSPH2XY
;
; OUTPUTS:
; 	info	various	A named variable to hold the returned information
;
; RESTRICTIONS:
;	Exactly one primary selector key must be given. If the source
;	is a sequence, then the index key must be given. Inappropriate
;	secondary selectors are ignored.
;
;
; MODIFICATION HISTORY:
;	Original: 20/1/04; SJT
;	Add handling for projections: 13/2/04; SJT
;-

pro smei_image_info, source, info, index = index, planes = planes, $
                     scale = scale, size = size, summary = summary, $
                     time = time, unit = unit, start = start, stop = $
                     stop, convert = convert, x = x, y = y, file = $
                     file, help = help

if keyword_set(help) then begin
    self_help
    return
endif

if not arg_present(info) then begin
    smei_msg, /warn, ['SMEI_IMAGE_INFO 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_INFO 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_INFO must ', $
                      'be a SMEI_IMAGE or a SMEI_SEQUENCE']
    return
endelse

nkey = keyword_set(planes) + keyword_set(scale) + keyword_set(size) + $
       keyword_set(summary) + keyword_set(time) + keyword_set(unit) + $
       keyword_set(file)

if nkey ne 1 then begin
    smei_msg, /warn, ['You must specify exactly one of the', $
                      'selector keys: /planes, /scale, /size,', $
                      '/summary, /time, /file or /unit']
    return
endif

if keyword_set(planes) then info = img -> get_planes() $
else $
  if keyword_set(scale) then info = img -> get_scale(x = x, $
                                                     y = y) $
  else $
  if keyword_set(size) then info = img -> get_size(x = x, y = $
                                                   y) $
  else $
  if keyword_set(summary) then info = img -> get_summary() $
  else $
  if keyword_set(time) then info = img -> get_time(start = start, stop $
                                                   = stop, convert = $
                                                   convert) $
  else $
  if keyword_set(unit) then info = img -> get_unit() $
  else $
  if keyword_set(file) then info = img -> get_file()

end