io.images¶

pywicta.io.images.fill_nan_pixels(image, noise_distribution=None)[source]¶

Replace in-place NaN values in image by zeros or by random noise.

Images containing NaN values generate undesired harmonics with wavelet image cleaning. This function should be used to “fix” images before each wavelet image cleaning.

Replace NaN (“Not a Number”) values in image by zeros if noise_distribution is None. Otherwise, NaN values are replaced by random noise drawn by the noise_distribution random generator.

Parameters:	image (array_like) – The image to process. NaN values are replaced in-place thus this function changes the provided object. noise_distribution (pywicta.denoising.inverse_transform_sampling.EmpiricalDistribution) – The random generator to use to replace NaN pixels by random noise.
Returns:	Returns a boolean mask array indicating whether pixels in images initially contained NaN values (True) of not (False). This array is defined by the instruction np.isnan(image).
Return type:	array_like

Notes

NaN values are replaced in-place in the provided image parameter.

Examples

>>> import numpy as np
>>> img = np.array([[1, 2, np.nan],[4, np.nan, 6],[np.nan, 8, np.nan]])
>>> fill_nan_pixels(img)
... 
array([[False, False,  True],
       [False,  True, False],
       [ True, False,  True]], dtype=bool)
>>> img
... 
array([[ 1., 2., 0.],
       [ 4., 0., 6.],
       [ 0., 8., 0.]])

pywicta.io.images.image_files_in_dir(directory_path, max_num_files=None)[source]¶

Return the path of FITS and Simtel files in directory_path.

Return the path of all (or max_num_files) files having the extension “.simtel”, “.simtel.gz”, “.fits” or “.fit” in directory_path.

Parameters:	directory_path (str) – The directory’s path where FITS and Simtel files are searched. max_num_files (int) – The maximum number of files to return.
Yields:	str – The path of the next FITS or Simtel files in directory_path.

pywicta.io.images.image_files_in_paths(path_list, max_num_files=None)[source]¶

Return the path of FITS and Simtel files in path_list.

Return the path of all (or max_num_files) files having the extension “.simtel”, “.simtel.gz”, “.fits” or “.fit” in path_list.

Parameters:	path_list (str) – The list of directory’s path where FITS and Simtel files are searched. It can also directly contain individual file paths (or a mix of files and directories path). max_num_files (int) – The maximum number of files to return.
Yields:	str – The path of the next FITS or Simtel files in path_list.

pywicta.io.images.image_generator(path_list, max_num_images=None, tel_filter_list=None, ev_filter_list=None, cam_filter_list=None, rejection_criteria=None, **kwargs)[source]¶

Return an iterable sequence all calibrated images in path_list.

Parameters:

path_list (list of str) – The path of files containing the images to extract. It can contain FITS/Simtel files and directories.
max_num_images (int) – The maximum number of images to iterate.
tel_filter_list (list of int) – Only iterate images from telescopes defined in this list.
ev_filter_list (list of int) – Only iterate images from events defined in this list.
cam_filter_list (list of string) – Only iterate images from cameras defined in this list.
rejection_criteria (function) – A function that contains image rejection criteria. This function takes images and return True for images that should be ignored by the generator and False otherwise. It can be used to ignore images that are not in a given range of energy or images with a shower too close to the borders for instance.

Yields:

Image1D or Image2D – The named tuple Image1D or Image1D of the next FITS or Simtel files in path_list.

pywicta.io.images.load_benchmark_images(input_file_path)[source]¶

Return images contained in the given FITS file.

Parameters:	input_file_path (str) – The path of the FITS file to load
Returns:	A dictionary containing the loaded images and their metadata
Return type:	dict
Raises:	`WrongFitsFileStructure` – If input_file_path doesn’t contain a valid structure

pywicta.io.images.load_fits(input_file_path, hdu_index)[source]¶

Return the image array contained in the given HDU of the given FITS file.

Parameters:	input_file_path (str) – The path of the FITS file to load hdu_index (int) – The HDU to load within the FITS file (one FITS file can contain several images stored in different HDU)
Returns:	The loaded image
Return type:	ndarray
Raises:	`WrongHDUError` – If input_file_path doesn’t contain the HDU hdu_index `NotAnImageError` – If input_file_path doesn’t contain a valid image in the HDU hdu_index

pywicta.io.images.mpl_save(img, output_file_path, title='')[source]¶: img should be a 2D numpy array.

pywicta.io.images.plot(img, title='')[source]¶: img should be a 2D numpy array.

pywicta.io.images.plot_ctapipe_image(image, geom, ax=None, figsize=(10, 10), title=None, title_fontsize=24, norm='lin', highlight_mask=None, plot_colorbar=True, plot_axis=True, colorbar_orientation='horizontal', colorbar_limits=None)[source]¶

Plot an image.

Parameters:

image (array_like) – Array of values corresponding to the pixels in the CameraGeometry.
geometry (~ctapipe.instrument.CameraGeometry) – Definition of the Camera/Image
ax (matplotlib.axes.Axes) – A matplotlib axes object to plot on, or None to create a new one
title (str (default "Camera")) – Title to put on camera plot
norm (str or matplotlib.color.Normalize instance (default ‘lin’)) – Normalization for the color scale. Supported str arguments are - ‘lin’: linear scale - ‘log’: logarithmic scale (base 10)
cmap (str or matplotlib.colors.Colormap (default ‘hot’)) – Color map to use (see matplotlib.cm)

pywicta.io.images.plot_hillas_parameters_on_axes(ax, image, geom, hillas_params=None, plot_ellipse=True, plot_axis=True, plot_actual_axis_pm=True, plot_inner_axes=False, auto_lim=True, hillas_implementation=2)[source]¶: Plot the shower ellipse and direction on an existing matplotlib axes.

pywicta.io.images.quantity_to_tuple(quantity, unit_str)[source]¶

Splits a quantity into a tuple of (value,unit) where unit is FITS compliant.

Useful to write FITS header keywords with units in a comment.

Parameters:	quantity (astropy quantity) – The Astropy quantity to split. unit_str (str) – Unit string representation readable by astropy.units (e.g. ‘m’, ‘TeV’, …)
Returns:	A tuple containing the value and the quantity.
Return type:	tuple

pywicta.io.images.save_benchmark_images(img, pe_img, metadata, output_file_path, sample_imgs=None)[source]¶

Write a FITS file containing pe_img, output_file_path and metadata.

Parameters:	img (ndarray) – The “input image” to save (it should be a 2D Numpy array). pe_img (ndarray) – The “reference image” to save (it should be a 2D Numpy array). output_file_path (str) – The path of the output FITS file. metadata (tuple) – A dictionary containing all metadata to write in the FITS file.

pywicta.io.images.save_fits(img, output_file_path)[source]¶

Save the img image (array_like) to the output_file_path FITS file.

Parameters:	img (array_like) – The image to save (should be a 2D or a 3D numpy array) output_file_path (str) – The path of the FITS file where to save the img
Raises:	`WrongDimensionError` – If img has more than 3 dimensions or less than 2 dimensions.

pywicta.io.images.simtel_event_to_images(event, tel_id, ctapipe_format=False, mix_channels=True, time_samples=False, **kwargs)[source]¶

Extract and return tel_id’s images and metadata from a ctapipe event.

Parameters:	event (ctapipe event object) – TODO tel_id (int) – TODO ctapipe_format (bool) – TODO mix_channels (bool) – TODO
Returns:	Return a named tuple containing tel_id images and metadata from a ctapipe event.
Return type:	Image1D or Image2D

pywicta.io.images.simtel_images_generator(file_path, tel_filter_list=None, ev_filter_list=None, cam_filter_list=None, ctapipe_format=False, integrator='LocalPeakIntegrator', integrator_window_width=5, integrator_window_shift=2, integrator_t0=None, integrator_sig_amp_cut_hg=None, integrator_sig_amp_cut_lg=None, integrator_lwt=None, integration_correction=False, debug=False, rejection_criteria=None, **kwargs)[source]¶

Return an iterable sequence all calibrated images in file_path.

Parameters:

file_path (str) – The path of a Simtel file.
tel_filter_list (sequence of int) – If defined, the generator iterator returns only images from telescopes listed in tel_filter_list.
ev_filter_list (sequence of int) – If defined, the generator iterator returns only images from events listed in ev_filter_list.
cam_filter_list (sequence of str) – If defined, the generator iterator returns only images from instrument listed in cam_filter_list.
ctapipe_format (bool) – The generator iterator returns ctapipe compliant 1D images if True; it returns 2D converted images compliant with iSAP/Sparce2D otherwise.
integrator (str) – Define the trace integration method used in ctapipe.calib.camera.dl1. Should be one of the following: * None: use the default integrator with the default parameters (NeighbourPeakIntegrator); * ‘FullIntegrator’: integrates the entire waveform; * ‘SimpleIntegrator’: integrates within a window defined by the user; * ‘GlobalPeakIntegrator’: integration window about the global peak in each pixel; * ‘LocalPeakIntegrator’: integration window about the local peak in each pixel (default); * ‘NeighbourPeakIntegrator’: integration window defined by the peaks in the neighbouring pixels; * ‘AverageWfPeakIntegrator’: integration window defined by the average waveform across all pixels.
integrator_window_width (int) – Define the width of the integration window. Only applicable to WindowIntegrators.
integrator_window_shift (int) – Define the shift of the integration window from the peakpos (peakpos - shift). Only applicable to PeakFindingIntegrators.
integrator_t0 (int) – Define the peak position for all pixels. Only applicable to SimpleIntegrators.
integrator_sig_amp_cut_hg (float) – Define the cut above which a sample is considered as significant for PeakFinding in the HG channel. Only applicable to PeakFindingIntegrators.
integrator_sig_amp_cut_lg (float) – Define the cut above which a sample is considered as significant for PeakFinding in the LG channel. Only applicable to PeakFindingIntegrators.
integrator_lwt (int) – Weight of the local pixel (0: peak from neighbours only, 1: local pixel counts as much as any neighbour). Only applicable to NeighbourPeakIntegrator.
integration_correction (bool) – If False, switch off the integration correction occurring in ctapipe.calib.camera.dl1.CameraDL1Calibrator.calibrate().
debug (bool) – Print additional values if True.
rejection_criteria (function) – A function that contains image rejection criteria. This function takes images and return True for images that should be ignored by the generator and False otherwise. It can be used to ignore images that are not in a given range of energy or images with a shower too close to the borders for instance.

Notes

For more information about the integrator (integrator*) parameters, see the ChargeExtractorFactory class definition in ctapipe/image/charge_extractors.py or type (in a terminal) ctapipe-chargeres-extract --help-all.

Yields:	image – The next image in file_path.