;+
; NAME:
;	SMEI_PROFILE
;
;
; PURPOSE:
;	Generate a profile from a SMEI sequence
;
;
; CATEGORY:
;	CLI
;
;
; CALLING SEQUENCE:
;	smei_profile, seqref, npa, nel, pmin, pmax, profile[, pa, $
;		elong, date]
;
;
; INPUTS:
;	seqref	objref	The smei_sequence object from which to get the
;			profile 
;	npa	int	The number of bins in the position-angle
;			direction 
;	nel	int	The number of bins in the elongation direction
;	pmin	float	The lower limit of position angle or
;			elongation (circumferential profiles)
;	pmax	float	The upper limit of position angle or
;			elongation (circumferential profiles)
;
;
; KEYWORD PARAMETERS:
;	/circumferential	If set, then make a circumferential
;				rather than a radial profile.
;	/verbose		If set, then show the region being profiled.
;	save	string	input	A filename to which to save the
;				profile and its axes.
;	plane	int	input	The image plane to use (0 for
;				processed, 1-n for raw planes).
;	mask	uint	input	An optional mask pattern for
;				conditions to exclude from the
;				profile.
;	/use_flags		If set, then use the display flags
;				setting as the mask (should not be
;				used together with MASK key --- if it
;                               is then MASK is used).
;	/miss_nan		If set, then a cell with no values is
;				NaN rather than zero.
;
;
; OUTPUTS:
;	profile	float	The profile generated (indices are [pa,
;			elongation, image])
;
; OPTIONAL OUTPUTS:
;	pa	float	The midpoints of the bins in position angle
;	elong	float	The midpoints of the bins in elongation.
;	date	double	The Julian dates of the start and end of each
;			image.
;
; MODIFICATION HISTORY:
;	Original: 15/12/03; SJT
;	Added plane keyword: 13/1/04; SJT
;	Added mask, miss_nan & use_flags keywords: 8/8/09; SJT
;-

pro smei_profile, seqref, npa, nel, pmin, pmax, profile, pa, $
                  elong, date, circumferential = circumferential, $
                  verbose = verbose, save = save, plane = plane, $
                  mask = mask, use_flags = use_flags, miss_nan = $
                  miss_nan, help = help

if keyword_set(help) then begin
    self_help
    return
endif

if n_params() lt 6 then begin
    smei_msg, /alert, ["SMEI_PROFILE needs at least 6 arguments", $
                       "use smei_profile,/help to get full details"]
    return
endif

if not (obj_valid(seqref) && obj_isa(seqref, "SMEI_SEQUENCE")) then $
  begin
    smei_msg, /alert, ["The first argument to SMEI_PROFILE must", $
                       "be a SMEI_SEQUENCE object"]
    stop
    return
endif

if not arg_present(profile) then begin
    smei_msg, /alert, ["The profile argument of SMEI_PROFILE", $
                       "must be a named variable to receive", $
                       "the output values"]
    return
endif

if n_elements(plane) ne 0 then begin
    if plane gt seqref -> get_n_planes() or plane lt 0 then begin
        smei_msg, /alert, ["Requested out of range plane " + $
                           ""+string(plane), $
                           "Range must be 0-"+string(seqref -> $
                                                     get_n_planes())]
        return
    endif
endif

if keyword_set(use_flags) then begin
    if keyword_set(mask) then smei_msg, /warn, $
      'MASK and USE_FLAGS both given, using MASK' $
    else mask = seqref -> get_flags()
endif

profile = seqref -> make_profile(npa, nel, pmin, pmax, pa = $
                                 pa, elong = elong, date = date, $
                                 circumferential = $
                                 keyword_set(circumferential), $
                                 verbose = keyword_set(verbose), plane $
                                 = plane, mask = mask, miss_nan = miss_nan)

if keyword_set(save) then begin
    sz = size(profile, /dimensions)
    if n_elements(sz) eq 1 then sz = [sz, 1, 1]
    if n_elements(sz) eq 2 then sz = [sz, 1]
    openw, ilu, /get, save
    printf, ilu, sz, format = "(3I6)"
    printf, ilu, pa, format = "(12G12.4)"
    printf, ilu, elong, format = "(12G12.4)"
    for j = 0, sz[2]-1 do begin
        printf, ilu, date[*, j], format = "(2F14.5)"
        printf, ilu, profile[*, *, j], format = $
          "(12G12.4)"
    endfor
    free_lun, ilu
endif

end