; docformat = 'rst'
;+
; This function loads the tle data file and then sends the file data to the
;  tle structure parser function.
; A TLE is a NORAD Two Line Element file that contains spacecraft geolocation data.
;
; :Author:
;    Chris Jeppesen, Bill Barrett
;
; :Examples:
;   tle_struct = load_tle(infn)
;
; :Params:
;   NONE
;     
; :Keywords:
;   spacecraft_id : in, optional, type=int
;     A spacecraft id for the tle. The default is '!sc_number'.
;
;   force : in, optional, type=boolean
;     Force the read and filtering of the TLE file, even if data is already
;     present in the common.
;     
; :Returns:
;    Returns the filtered and sorted tle structure from the data
;    in the input file.
;-
function load_tle, spacecraft_id=spacecraft_id, force=force
  common tle_data, result
  
  ; If no spacecraft id is specified, use the project default
  if ~keyword_set(spacecraft_id) then spacecraft_id = !sc_number
  
  ; If the TLE has already been parsed for this spacecraft, and there is no
  ;   request to force a read, return what has been saved.
  if n_elements(result) gt 0 && ~keyword_set(force) && $
    spacecraft_id eq result[0].satnum then return, result

  dummy = {raw_tle_element, line1:'', line2:''}
  raw_elements = []
  space_craft_string = strtrim(string(spacecraft_id), 2)
  ; The first line of each two line element should start with '1 ' followed by
  ;   the space craft identifier. The second line is the same except it
  ;   starts with '2 '.
  line_1_id = '1 ' + space_craft_string
  line_2_id = '2 ' + space_craft_string

  full_tle_path = !tle_path + string(spacecraft_id,format='(%"/%08d.tle")')
  print, get_routine_name() + 'TLE path: ' + full_tle_path
  openr, inf, full_tle_path, /get_lun
  line1=''
  ; Read the entire file searching for pairs of two consecutive lines,
  ;  the first one starting with '1 ' followed by the space craft
  ;  identifier. The second line is the same except it starts with '2 '.
  while ~eof(inf) do begin
    line2=''
    readf,inf,line2
    ; Are the two lines valid as a TLE ('Two Line Element')
    if strlen(line1) gt 0 && strmid(line1,0,7) eq line_1_id $
       && strlen(line2) gt 0 && strmid(line2,0,7) eq line_2_id then begin
      raw_elements = [ raw_elements, {raw_tle_element, line1, line2 } ]
      line1=''
      line2=''
    endif else line1=line2
  endwhile
  free_lun,inf
  result=parse_tle_struct(raw_elements.line1, raw_elements.line2)

  ; Sort the file chronologically
  jdepoch = result.jdepoch
  result = result[SORT(jdepoch)]

  ; Filter out the elements that are not consistent with their neighbors
  filter_tle,result
  return,result
end