euispice_coreg
Welcome to the euispice_coreg python package :artificial_satellite:. This package can be used to correct the pointing information of SPICE or HRIEUV datasets, on board Solar Orbiter.
Description :
This package provides tools to co-align an image from an imager with another one (called "reference" image). It corrects the pointing information on the FITS header using a cross-correlation algorithm. The data you want to align can be either from an imager (i.e. Solar Orbiter/HRIEUV etc.) or a Solar Orbiter/SPICE raster. Examples on how to align different types of data are provided below.
In addition, the package provides tools to create a synthethic raster from a set of images (FSI 174 for instance), given the timing of the exposures of a SPICE raster taken as a reference. In this way the SPICE raster can be co-aligned with the synthetic raster.
As the reference imager, it is advised to use one with a full Sun field of view, with Limb fitting previously applied. Examples of them are the L2 images from the FSI 174 and 304 imagers on board Solar Orbiter. The co-alignment itself is performed using a cross-correlation technique, through the Pearson's coefficient, or the residus method. The alignment can be done in the following frames:
- Helioprojective. In this case both images will be reprojected into the coordinate frame of the image to align.
- Carrington: Slower, you have to provide the information to build a pixel grid in a carrington frame. Required if there is a significant time delay between both instruments, or if they do not share the same spacecraft (HRIEUV and AIA for instance).
- Pixels. The algorithm slicing over the image pixels, complitely neglecting the headers information. (experimental)
Warning As of now, the code works for day to day cases, but has not been thouroughly tested. Please always verify the results with the plot_co_alignment method. Report any bug you encounter with Github or by e-mailing the author (see adress at the end of the readme). We welcome any suggestion for improvement or remarks.
Installation
This package is designed to be used in your personal python projects, and to be imported as a standard package. In your project, a virtual environement can be created with the following command in the shell :
python -m venv env
source env/bin/activate # write "deactivate" in shell to go out of your virtual environement. You can use the pip install + git command, while you are in virtual environment, to install the package into your own project.
pip install git+https://github.com/adolliou/euispice_coregYou can also clone the euispice_coreg repository locally. Then, while you are in the virtual environment of your personal project, you can add the Alignment package with the following command :
cd path/to/euispice_coreg
pip install .Usage
We provide multiple examples on how to use the code, using different data types, and on different frames.
Alignment of an HRIEUV image with FSI 174 in helioprojective coordinates
Here, we co-register an HRIEUV image with an FSI 174 image. We start using Helioprojective coordinates, which is advised if both images are close in time.
import numpy as np
from euispice_coreg.hdrshift.alignment import Alignment
from euispice_coreg.plot.plot import PlotFunctions
from euispice_coreg.utils.Util import AlignCommonUtil
import os
path_hri = "path/to/HRIEUV.fits" # path to the HRI FITS file. It must end with a ".fits"
path_fsi = "path/to/FSI174.fits" # path to the FSI FITS file. It must end with a ".fits"
path_save_fits = "path/where/to/save/aligned_fits/fits.fits" # path to FITS file that .
path_save_fig = "path/where/to/save/figure" # path to the folder where to save the figure illustrating the alignment.
lag_crval1 = np.arange(15, 26, 1)
lag_crval2 = np.arange(5, 11, 1)
lag_cdelta1 = [0]
lag_cdelta2 = [0]
lag_crota = [0]
A = Alignment(large_fov_known_pointing=path_fsi, small_fov_to_correct=path_hri, lag_crval1=lag_crval1,
lag_crval2=lag_crval2, lag_cdelta1=lag_cdelta1, lag_cdelta2=lag_cdelta2, lag_crota=lag_crota,
parallelism=True, use_tqdm=True, counts_cpu_max=20,
)
corr = A.align_using_helioprojective(method='correlation')
max_index = np.unravel_index(corr.argmax(), corr.shape)
parameter_alignment = {
"lag_crval1": lag_crval1,
"lag_crval2": lag_crval2,
"lag_crota": lag_crota,
"lag_cdelta1": lag_cdelta1,
"lag_cdelta2": lag_cdelta2,
}
PlotFunctions.plot_correlation(corr, show=True,
path_save=os.path.join(path_save_fig, "correlation.pdf"), **parameter_alignment)
PlotFunctions.plot_co_alignment(small_fov_window=-1, large_fov_window=-1, corr=corr,
small_fov_path=path_hri, large_fov_path=path_fsi, show=True,
results_folder=path_save_fig, levels_percentile=[95],
**parameter_alignment)
AlignCommonUtil.write_corrected_fits(path_l2_input=path_hri, window_list=[-1],
path_l3_output=path_save_fits, corr=corr,
**parameter_alignment)
Alignment of HRIEUV with FSI 174 using Carrington coordinates
You can also co-register HRIEUV fits files with FSI 174 images within a common Carrington grid, which is advised when both images are taken with significant delay, or if both instruments are on board different spacecrafts. In that case, you have to provide the grid where the aligment is performed.
import os.path
from euispice_coreg.hdrshift.alignment import Alignment
import numpy as np
from euispice_coreg.plot.plot import PlotFunctions
from euispice_coreg.utils.Util import AlignCommonUtil
path_fsi = "path/to/FSI174.fits"
path_hri = "path/to/HRIEUV.fits"
path_save_fig = "path/where/to/save/figure"
path_save_fits = "path/where/to/save/aligned_fits"
parallelism = True
lag_crval1 = np.arange(55, 62, 1)
lag_crval2 = np.arange(-28, -22, 1)
lag_crota = [-39.25]
# Here, we build a common Carrington grid where the alignment will be performed.
lonlims = (200, 300)
latlims = (-20, 20) # longitude min and max (degrees)
shape = [2048, 2048]
lag_cdelta1 = [0]
lag_cdelta2 = [0]
A = Alignment(large_fov_known_pointing=path_fsi, small_fov_to_correct=path_hri, lag_crval1=lag_crval1,
lag_crval2=lag_crval2, lag_cdelta1=lag_cdelta1, lag_cdelta2=lag_cdelta2, lag_crota=lag_crota,
parallelism=True, use_tqdm=True,
small_fov_window=-1, large_fov_window=-1)
corr = A.align_using_carrington(method='correlation', lonlims=lonlims, latlims=latlims, shape=shape)
parameter_alignment = {
"lag_crval1": lag_crval1,
"lag_crval2": lag_crval2,
"lag_crota": lag_crota,
"lag_cdelta1": lag_cdelta1,
"lag_cdelta2": lag_cdelta2,
}
PlotFunctions.plot_correlation(corr, show=True,
path_save=os.path.join(path_save_fig, "correlation.pdf"), **parameter_alignment)
PlotFunctions.plot_co_alignment(small_fov_window=-1, large_fov_window=-1, corr=corr,
small_fov_path=path_hri, large_fov_path=path_fsi, show=True,
results_folder=path_save_fig, levels_percentile=[95],
**parameter_alignment)
AlignCommonUtil.write_corrected_fits(path_l2_input=path_hri, window_list=[-1],
path_l3_output=path_save_fits, corr=corr,
**parameter_alignment)Alignment of a SPICE raster
We show here a typical example to align SPICE data with a synthetic raster created from FSI 304 files.
Creation of a SPICE synthetic raster
First of all, we need to create a synthetic raster for the SPICE raster using a list of FSI 304 FITS files.
from euispice_coreg.synras.map_builder import SPICEComposedMapBuilder
from glob import glob
import astropy.units as u
path_spice = "path/to/spice/l2.fits"
path_to_imager_list = glob("path/to/fsi304/*l2.fits")
window_spice = "Ly-gamma-CIII group (Merged)" # The window of the HDULIST for the SPICE FITS file.
window_imager = -1 # The widow of the HDULIST of the imagers FITS files
threshold_time = u.Quantity(30, "s") # maximum threshold between the SPICE acquisition time, and the closest FSI 304 image. If the code can't any FSI below the threshold, it returns an error
output_L3_fits = "path/to/output/synthetic_raster_folder"
C = SPICEComposedMapBuilder(path_to_spectro=path_spice, list_imager_paths=path_to_imager_list,
window_imager=window_imager, window_spectro=window_spice,
threshold_time=threshold_time)
C.process(folder_path_output=output_L3_fits)Alignment of the SPICE raster with the synthetic raster
The code first creates a SPICE pseudo raster by spectrally summing over the chosen HDUList window (here, the C III window). It then cross-correlates the SPICE image with the synthetic raster, while shifting the header values of the SPICE image. It returns a cross-correlation matrix that can be used to determine the optimal shift to apply to the header values. The header values that can be shifted are CRVAL1, CRVAL2, CROTA, CDELT1 and CDELT2.
import numpy as np
from euispice_coreg.hdrshift.alignment_spice import AlignmentSpice
from euispice_coreg.plot.plot import PlotFunctions
from euispice_coreg.utils.Util import AlignSpiceUtil
path_to_synthetic_raster_fits = "path/to/input/synthetic_raster.fits"
path_spice_input = "path/to/spice/l2.fits"
window_spice_to_align = "Ly-gamma-CIII group (Merged)" # the window used for the co-alignment, here the one which includes the C III line.
windows_spice = ["Mg IX 706 - Peak", # The windows where the pointing will be corrected. It is adviced to correct the shift in all of the spectral windows.
"Ne VIII 770 - Peak",
"S V 786 / O IV 787 - Peak",
"Ly-gamma-CIII group (Merged)",
"LyB- FeX group (Merged)",
"O VI 1032 - Peak"]
window_sr = -1 # the HDULIST index for the synthetic raster.
path_save_figure= "path/to/output/figures/folder"
param_alignment = {
"lag_crval1": np.arange(-30, -15, 4), # lag crvals in the headers, in arcsec
"lag_crval2": np.arange(30, 51, 4), # in arcsec
"lag_crota": np.array([0]), # in degrees
"lag_cdelta1": np.array([0]), # in arcsec
"lag_cdelta2": np.array([0]), # in arcsec
}
parallelism = True
A = AlignmentSpice(large_fov_known_pointing=path_to_synthetic_raster_fits, small_fov_to_correct=path_spice_input,
use_tqdm=True,
parallelism=parallelism, counts_cpu_max=10,
large_fov_window=window_sr, small_fov_window=window_spice_to_align,
path_save_figure=path_save_figure,
**param_alignment)
corr = A.align_using_helioprojective(method='correlation')
PlotFunctions.plot_correlation(corr, **param_alignment)
AlignSpiceUtil.write_corrected_fits(path_spice_l2_input=path_spice_input,
path_spice_l2_output="path/where/to/save/corrected/fits", corr=corr,
window_spice_list=windows_spice,
**param_alignment)
PlotFunctions.plot_co_alignment(large_fov_window=-1, large_fov_path=path_to_synthetic_raster_fits,
corr=corr, small_fov_window= window_spice_to_align,
levels_percentile=[80, 90],
results_folder=None, small_fov_path=path_spice_input, show=True,
**param_alignment)
Example of a results for co-alignment between a SPICE C III image and a FSI 304 synthetic raster, obtained with plot_co_alignment :
Acknowledgments
- Carrington transform: F. Auchère
- SPICE utils: G. Pelouze
- Matrix transform: F. Auchère
Contact
Author: Antoine Dolliou (antoine.dolliou@universite-paris-saclay.fr)
Acknowledgment
If you use this code in your publication, please cite Dolliou et al. (A&A, 2024). DOI: https://doi.org/10.1051/0004-6361/202450439