(Internal/Review) How to use ENVI's 'Fast PPI' programmatically

This Help Article describes how to use ENVI's Fast Pixel Purity Index (PPI) programmatically using the undocumented routine, PPI_FAST_DOIT.  As with all undocumented procedures, they are not supported by Exelis VIS and could change in a future version of ENVI.
 
The included example code shows how to call the most simple form of the PPI, without any previous runs or mask. To include a mask band (m_pos) would require a return FID from a previously created mask and to use the HIST keyword.

The HIST parameter is used in the Fast PPI with a mask to get the pixel count of the number of pixels in the mask. If you know the number of pixels, you can explicitly set hist = [0L, num_pixels]. If not, you will need to calculate the statistics for this via:

envi_stats_doit, fid=m_fid, pos=m_pos, dims=dims, hist=hist, comp_flag=3

For a mask fid (m_fid/m_pos), HIST will essentially be [0,number of points] since masks should only have two values (0 and 1).

pro example_fast_ppi_doit
  ;
  ; First restore all the base save files.
  ;
  envi, /restore_base_save_files
  ;
  ; Initialize ENVI and send all errors
  ; and warnings to the file batch.txt
  ;
  envi_batch_init, log_file='batch.txt'
  ;
  ; Open the input file
  ;
  envi_open_file, 'bhtmref.img', r_fid=fid
  if (fid eq -1) then begin
    envi_batch_exit
    return
  endif
  ;
  ; Set the POS keyword to process all
  ; spectral data. Output the result
  ; to disk.
  ;
  envi_file_query, fid, dims=dims, ns=ns, nl=nl, $
    nb=nb
  pos  = lindgen(nb)
  out_name = 'testimg'
  ;
  ; Call the PPI processing
  ;
ppi_fast_doit, fid=fid, pos=pos, dims=dims, xfac=1, yfac=1, prev_iter=0, $
    p_fid=-1, m_fid=-1, iterations=1000, thresh=3.0, out_name=out_name, r_fid=r_fid
  ;
  ; Exit ENVI
  ;
  envi_batch_exit
end

-----------------
Undocumented Routine:Review for Compliance/IP