______ _ ___ _____ _____ _ _ __ __ | ____| | | \ \ / /__ \ / ____| | | | \/ | | |__ | | | |\ \ / / ) | | | |__| | \ / | | __| | | | | \ \/ / / /| | | __ | |\/| | | |____| |__| | \ / / /_| |____| | | | | | | |______|\____/ \/ |____|\_____|_| |_|_| |_| EUV2CHM: A ready-to-use MATLAB script for taking STEREO-A/B EUVI 195Å and AIA 193Å images, applying the new preprocessing, detecting coronal holes, and then stitching the results into synchronic EUV and CH maps. Version 1.0.1 ------------- Introduction: ------------- EUV2CHM is an example of how to apply our new preprocessing methods/data to EUV data, perform coronal hole detection on the preprocessed images, and merge them into synchronic EUV and CH maps. The basic outline of what the script does is as follows: 1) Loads EUV image data and preprocessing data. 2) Applies limb-brightening correction to the images. 3) Applies inter-instrument transformations to the images. 4) Uses EZSEG to perform coronal hole detection on each preprocessed disk image. 5) Merges the EUV and CH results into sin-latitude-phi maps. ------------ QUICK START: ------------ a) Uncompress the contents of this file into a folder. b) Run compile_ezseg.m script (you may need to modify the script for your environment). c) Run euv2chm.m script. You should see a series of disk images through each step above and the final maps at the end. ------------------------------------------------------------------- ------------------------------------------------------------------- --- DETAILED INSTRUCTIONS TO RUN IMAGE SEQUENCES USING EUV2CHM: --- ------------------------------------------------------------------- ------------------------------------------------------------------- The basic requirements to apply our preprocessing, coronal hole detection, and mapping are the EUV images themselves, the corresponding LBC and IIT preprocessing data, the time in seconds of the EUV data, and the B0 and central-meridian angles of the spacecrafts at the time of the images (for mapping). The implementation in EUV2CHM assumes certain formats and file structures of the above required data. Therefore, to use EUV2CHM directly for your own image sequences, one needs to prepare their data as described below. To assist in this process, we have included an IDL script called euv2chm_prep_data.pro which takes fits files downloaded using SSW and converts them into the data formats and structure required for use in euv2chm. The script package (which includes example fits files to test with) is in the enclosed euv2chm_prep_data.zip file. Otherwise, you are welcome to modify the euv2chm script to reflect your own data/meta-data formats. ------------ DATA SETUP: ------------ 1) The EUV images need to be in hdf4 format, including an x-y scale in units of solar radii centered at the disk center of the view. The data should be contained in hdf4's default "Data-Set-2" field. 2) The images should be stored in the following folder structures: a) //A/195/los####.hdf b) //B/195/los####.hdf c) //AIA/193/los####.hdf where #### is a 4-digit sequence number starting at 0001 and the data directory names in brackets can be set to whatever the user wants, as long as the names are set properly in the parameters section of the script. 3) The folders a-c need to contain a file named "index.dat" which has all the meta-data for the images (in order) row by row formatted as: #### YYYY-MM-DDTHH:MM:SS.SSS The angles are given in degrees. The TAI time in seconds is defined as standard seconds since January 1,1958. The date string should be UTC corresponding to the TAI time. 4) The preprocessing data provided in this package are for use with EUV images that have been PSF-deconvolved (see [http://www.predsci.com/chd] for details on which PSF and algorithm to use). If you wish to use this script with standard level-1 SSW data, you need to download the appropriate preprocessing data from [http://www.predsci.com/chd] in "mat" format. The mat files can be stored anywhere as long as the correct path is provided in the script. Once your data is set up, you can set the image sequence you want to process by modifying the idx_start and idx_stop parameters. Setting both of these to 0 will cause the script to process all images listed in the index.dat meta-data files. -------------- COMPILE EZSEG: -------------- EUV2CHM uses EZSEG to perform the coronal hole detection. This package comes with a script called "compile_ezseg.m" which needs to be run to create the mex functions which call EZSEG. The script will detect if you have not done this and run it for you. You must have your mex compiler in MATLAB setup for this to work. To do this (only needed once) run "mex -setup". The EZSEG code in CPU mode uses OpenMP, so set the OMP_NUM_THREADS in the EUV2CHM script appropriately. ------------ GPU SUPPORT: ------------ EZSEG comes with a CUDA implementation for use with NVIDIA GPUs. If you have a CUDA-capable NVIDIA GPU, and have already installed the CUDA toolkit, you can choose "y" when prompted in "install_ezseg.m" to compile the GPU version of EZSEG. Then, in the EUV2CHM script, set "use_gpu=1" to use it. The GPU version of EZSEG is about 10X faster than a single CPU (GeForce 670 vs Core i3 3GHz). ----------------------------------------- CORONAL HOLE DETECTION ALGORITHM OPTIONS: ----------------------------------------- The EZSEG algorithm has three parameters that need to be set to perform the CH detection: a) The seed threshold (thresh1) b) The growth threshold (thresh2) c) The connectivity requirement (nc) The default values for these are set to those that work well for the entire time period that we provide preprocesing data for. These values can be modified for more precision detections in smaller windows of time. For details on these parameters, see our paper at [http://www.predsci.com/chd]. ---------------- MAPPING OPTIONS: ---------------- Since there is often overlapping data between the instruments, a choice in how to use the overlap data is needed. EUV2CHM offers two choices: 1) Max weight (merge_type=1): This option selects the data which has the highest μ=cosθ value (farthest from the limb) between the instruments. 2) Minimum intensity (merge_type=2): This option selects the instrument data (pixel-by-pixel) with the minimum intensity between the instruments. This option yields the maximum coronal hole area. For each option above, there is a parameter "mulimit" which sets the μ-value such that all data with μ values lower than mulimit are considered "bad data" and shaded out in the EUV maps and marked as such in the CH maps. For merge option (2), there is another parameter "merge_overlap" which sets how far to the limb data should be used in the overlap regions. This is a way to limit the use of data too near the limb in overlap regions, but allow it in non-overlap regions (for example, setting mulimit=0 and mulimit_overlap=0.4 (default)). Setting mulimit_overlap to 0 will generate the largest coronal holes when they are within overlap regions. Two parameters (mu_fair and mu_good) are the mu-levels for the coronal hole map data to be tagged as "good", "fair", or "bad". ----------------- PLOTTING OPTIONS: ----------------- In the graphical parameters section of EUV2CHM, one can change the limits of the colormap and the coarsening level to make images that are lower resolution. By default, "low_res_map" and "low_res_los" are both set to 4 (so every fourth pixel is plotted). The data thinning is only done in the plots for los images, while for the maps, only the coarse resolution map is generated. For full resolution maps/los images, set each of these to 1 (this will slow down the processing). The option "plot_chm_quality" chooses between a black-and-white coronal hole map (0) and a color-coded map (1) which indicates the instrument and data quality of each pixel of the CHM. ------------- SAVE OPTIONS: ------------- This release version of euv2chm does not save images or data. You must add your own save options to the script where appropriate. Images can be saved in multiple image formats using MATLAB's "print" command, as mat files using "save", or as other data types using various built-in interfaces. ---------- MORE HELP: ---------- For more help, feel free to contact us at caplanr@predsci.com.