ImageProcessing¶

giant.image_processing:

class giant.image_processing.ImageProcessing(centroiding=<class 'giant.point_spread_functions.gaussians.Gaussian'>, image_denoising=<built-in function GaussianBlur>, denoising_args=((3, 3), 0), denoising_kwargs=None, denoise_flag=False, pae_threshold=40, pae_order=2, centroid_size=1, correlator=<function cv2_correlator_2d>, correlator_kwargs=None, poi_min_size=2, poi_max_size=50, poi_threshold=8, reject_saturation=True, subpixel_method=SubpixelEdgeMethods.PAE, save_psf=False, return_stats=False, zernike_edge_width=0.5, otsu_levels=2, minimum_segment_area=10, minimum_segment_dn=200, image_flattening_noise_approximation=ImageFlatteningNoiseApprox.GLOBAL, flattening_kernel_size=7)[source]¶

This class is a collection of various image processing techniques used throughout GIANT.

All image processing techniques for the GIANT algorithms are contained in this class. This includes centroiding algorithms for stars and unresolved bodies, algorithms for extracting bright spots from an image (particularly useful in the detection of stars and unresolved bodies), denoising algorithms, and edge detection algorithms. The class essentially works as a container for the various options required for each technique. It also makes it easier to pass data between different functions that may be required for individual algorithms.

In general, users will not directly interact with this class, as it is used internally by many other GIANT routines.

Parameters:

centroiding (PointSpreadFunction) – A callable object which takes 3 positional arguments and estimates the centers of a ROI
image_denoising (Callable) – A callable object with takes an image as the first positional argument and returns the denoised image
denoising_args (Tuple | None) – The rest of the positional arguments for the image_denoising callable
denoising_kwargs (Dict | None) – the keyword arguments for the image_denoising callable as a dictionary
denoise_flag (bool) – A flag to indicate whether to denoise the image before applying the other techniques
pae_threshold (float | int) – The threshold for identifying pixel level edges in the PAE method
pae_order (int) – The order of fit for the PAE refinement (must be 1 or 2)
centroid_size (int) – half of the area passed to the centroiding function for refining the poi positions
correlator (Callable) – The cross correlation function to use
correlator_kwargs (Dict | None) – Key word arguments to pass to the correlator function
poi_min_size (int) – The minimum size for blobs to be considered points of interest
poi_max_size (int) – The maximum size for blobs to be considered points of interest
poi_threshold (float | int) – The threshold for coarsely identifying potential points of interest
reject_saturation (bool) – A flag indicating whether to reject blobs that contain saturated pixels when performing poi identification. Note that the saturation dn value must be stored in a saturation attribute for each image object being considered
subpixel_method (SubpixelEdgeMethods) – An enumeration specifying which method to use for identifying subpixel edges
save_psf (bool) – A flag specifying whether to save the fit psf in the centroiding methods
return_stats (bool) – A flag specifying whether to return stats about each point of interest in the locate_poi methods
zernike_edge_width (float) – The expected width of the edges for the zernike ramp edge method.
otsu_levels (int) – The number of levels to attempt to split the histogram by for Otsu thresholding.
minimum_segment_dn (Real) – The minimum average DN for a segment to be considered foreground instead of background
minimum_segment_area (int) – The minimum area for a segment to be considered foreground instead of noise in pixels squared.
image_flattening_noise_approximation (ImageFlatteningNoiseApprox) – A
flattening_kernel_size (int) –

centroiding: PointSpreadFunction¶

The PSF object that estimates the center of a region of interest.

This should be of the form:

res = centroiding(x, y, illums)
x0, y0 = res.centroid

where x0, y0 is the subpixel center of the blob, […] are optional outputs containing information about the fit, x, y are arrays of the column and row locations corresponding to illums, and illums are the illumination values at x, y.

There are a few built in options for centroiding in the point_spread_functions package or you can build your own.

save_psf: bool¶

A boolean flag specifying whether to save the point spread function fit.

If this parameter is set to true then resulting PSF object from the centroiding attribute is saved in addition to just the centroid. To ensure that the fit statistics are also saved for each PSF ensure the save_residuals class attribute on the PSF object is set to True as well.

image_denoising: Callable¶

A callable that is used to decrease the effects of noise in an image.

This should take the form of:

denoised_image = image_denoising(original_image, *denoising_args, *denoising_kwargs)

where original_image is the original 2D grayscale image as a numpy array, denoising_args are additional positional arguments to the image_denoising callable in a list, denoising_kwargs are a dictionary of key word arguments to pass to the image_denoising method, and denoised_image is a grayscale 2D image containing the noise suppressed version of the input image.

By default this applies a 2D Gaussian blurring kernel of size 3, 3 to the image to suppress the noise effects.

subpixel_method: SubpixelEdgeMethods¶

An enumeration (string) specifying what subpixel edge refinement method to use.

This can specified as an attribute of the SubpixelEdgeMethods enumeration directly or as a string that corresponds to that enumeration.

zernike_edge_width: float¶

A tuning parameter for the Zernike Ramp method specifying half the total edge width in pixels.

Typically this is set to 1.66*sigma where sigma is the point spread function full width half maximum for the camera.

denoising_args: list¶

A list of additional arguments to pass to the image_denoising callable after the image.

This list is expanded using the typical python expansion.

denoising_kwargs: dict¶

A dictionary of keyword arguments to pass to the image_denoising callable after the image.

This dictionary is expanded using the typical python expansion.

denoise_flag: bool¶

A boolean specifying whether to apply the image_denoising callable before applying other image processing routines to an image.

Set this attribute to True to apply the denoising routine and False to not apply the denoising routine.

correlator: Callable¶

A callable that is used to perform cross correlation between an image and a template

This should take the image as the first argument, the template as the second argument, and correlator_kwargs as the key word arguments. That is, it should be of the form:

cor_surf = correlator(image, template, **correlator_kwargs)

where cor_surf is the correlation surface. By default this is set to cv2_correlator_2d().

correlator_kwargs: dict¶

A dictionary of keyword arguments to pass to the correlator callable after the image and the template.

This dictionary is expanded using the typical python expansion.

pae_threshold: float¶: This tuning parameter specifies the minimum absolute image gradient for a location in an image to be considered an edge for the Partial Area Effect Method.

pae_order: int¶

This specifies whether to fit a linear (1) or quadratic (2) to the limb in the PAE method.

Typically quadratic produces the best results.

centroid_size: int¶

This specifies how many pixels to include when identifying a centroid in a region of interest.

This sets the +/- number from the peak brightness pixel in both axes (so that a value of 1 means a 3x3 grid will be considered, a value of 2 will result in a 5x5 grid, etc).

poi_threshold: float¶

This specifies the sigma multiplier to use when identifying a pixel as a point of interest.

The sigma multiplier is applied to a rough noise estimate of the image (see flatten_image_and_get_noise_level()) and then any pixels above this DN value are labeled as interesting pixels that require further processing (see locate_subpixel_poi_in_roi()).

poi_min_size: int¶

This specifies the minimum number of pixels that must be connected for a blob to be considered a point of interest.

Individual pixels are clumped using a connected components algorithm, and then the size of each blob is compared against this value. See locate_subpixel_poi_in_roi() for more details.

poi_max_size: int¶

This specifies the maximum number of pixels that must be connected for a blob to be considered a point of interest.

Individual pixels are clumped using a connected components algorithm, and then the size of each blob is compared against this value. see locate_subpixel_poi_in_roi() for more details.

reject_saturation: bool¶

This boolean flag specifies whether to ignore clumps of pixels that contain saturated DN values when identifying points of interest in an image.

Set to True to reject any clumps containing saturated pixels.

return_stats: bool¶: This boolean flag specifies whether to return statistics about each blob when identifying points of interest in the image.

image_flattening_noise_approximation: ImageFlatteningNoiseApprox¶

This specifies whether to globally flatten the image and compute a single noise level or to locally do so.

Generally global is sufficient for star identification purposes. If you are trying to extract very dim stars (or particles) then you may need to use the 'LOCAL' option, which is much better for low SNR targets but much slower.

This is used in find_poi_in_roi() and flatten_image_and_get_noise_level()

flattening_kernel_size: int¶

This specifies the half size of the kernel to use when locally flattening an image.

If you are using global flattening of an image this is ignored.

The size of the kernel/region used in flattening the image will be 2*flattening_kernel_size+1.

This is used in flatten_image_and_get_noise_level().

Summary of Methods

`flatten_image_and_get_noise_level`	This method is used to sample the noise level of an image, as well as return a flattened version of the image.
`corners_to_roi`	This method provides a convenient way to convert a set of corners to a region of interest that can be passed to `find_poi_in_roi()` and `locate_subpixel_poi_in_roi()`.
`find_poi_in_roi`	This method identifies pixel level centers for all points of interest inside of some region of interest.
`refine_locations`	This method is used to estimate the subpixel centers of blobs in an image given the pixel level location of the blobs.
`locate_subpixel_poi_in_roi`	This method identifies the subpixel locations of points of interest in an image.
`denoise_image`	This method is used to optionally denoise the image before a number of the other techniques contained in this class.
`correlate`	This method generates a cross correlation surface between template and image.
`identify_subpixel_limbs`	This method identifies illuminated limbs in an image to sub-pixel accuracy.
`identify_pixel_edges`	This method determines pixel level edges in an image by thresholding the image gradients.
`pae_edges`	This method locates edges in an image with subpixel accuracy.
`refine_edges_pae`	This method refines pixel level edges to subpixel level using the PAE method.
`refine_edges_zernike_ramp`	This method refines edge locations using the Zernike Ramp method described in https://arc.aiaa.org/doi/full/10.2514/1.A33692?mobileUi=0.

Navigation

Related Topics

ImageProcessing¶