corgidrp.star_center#

Attributes#

`spot_separation_nfov`
`spot_separation_spec`
`spot_separation_wfov`
`satellite_spot_parameters_defaults`

Functions#

`validate_satellite_spot_parameters`(params)	Checks if a dictionary conforms to the required satellite spot parameters format.
`update_parameters`(params, new_values)	Updates a nested dictionary of parameters with new values.
`circle`(nx, ny, roiRadiusPix, xShear, yShear[, nSubpixels])	Generates a circular aperture with an antialiased edge at specified offsets.
`find_optimum_1d`(xVec, arrayToFit)	Fits a parabola to a 1D array and returns the location of the minimum or maximum.
`find_optimum_2d`(xVec, yVec, arrayToFit, mask)	Fits a paraboloid to a 2D array and returns the location of the minimum or maximum.
`calc_star_location_and_spot_separation`(spotArray, ...)	Calculates the center of the occulted star using satellite spots.
`calc_star_location_from_spots`(spotArray, xOffsetGuess, ...)	Calculates the center of the occulted star using satellite spots.
`calc_spot_separation`(spotArray, xOffset, yOffset, ...)	Calculates the radial separation in pixels of the satellite spots.
`star_center_from_satellite_spots`(img_ref, ...)	Estimates the star center and spot locations from satellite spot images and science data.

Module Contents#

corgidrp.star_center.spot_separation_nfov = 14.794749999999999[source]#

corgidrp.star_center.spot_separation_spec = 17.33806153846154[source]#

corgidrp.star_center.spot_separation_wfov = 42.454499999999996[source]#

corgidrp.star_center.satellite_spot_parameters_defaults[source]#

corgidrp.star_center.validate_satellite_spot_parameters(params)[source]#

Checks if a dictionary conforms to the required satellite spot parameters format.

Parameters:: params (dict) – Dictionary to validate.
Returns:: True if valid, False otherwise.
Return type:: bool

corgidrp.star_center.update_parameters(params, new_values)[source]#

Updates a nested dictionary of parameters with new values.

Parameters:

params (dict) – Original nested dictionary containing initial parameter values. The structure should be: {key1: {subkey1: val, subkey2: val}, key2: {…}}
new_values (dict) – Nested dictionary containing new parameter values to update. Must match the structure of params.

Returns:

The updated nested dictionary.

Return type:

dict

Raises:

KeyError – If new_values contains keys or subkeys not present in params.

Example

>>> params = {'a': {'x': 1, 'y': 2}, 'b': {'z': 3}}
>>> new_values = {'a': {'x': 10}}
>>> update_parameters(params, new_values)
{'a': {'x': 10, 'y': 2}, 'b': {'z': 3}}

>>> new_values = {'b': {'w': 5}}
>>> update_parameters(params, new_values)
KeyError: "Subkey 'w' is not a valid parameter under key 'b'."

corgidrp.star_center.circle(nx, ny, roiRadiusPix, xShear, yShear, nSubpixels=100)[source]#

Generates a circular aperture with an antialiased edge at specified offsets.

This function is used as a software window for isolating a region of interest. Grayscale edges are applied to account for low detector sampling, ensuring that fractional values along the edges are preserved.

Parameters:

nx (int) – Width of the 2D array to create.
ny (int) – Height of the 2D array to create.
roiRadiusPix (float) – Radius of the circle in pixels.
xShear (float) – Lateral offset of the circle’s center from the array’s center pixel along the x-axis.
yShear (float) – Lateral offset of the circle’s center from the array’s center pixel along the y-axis.
nSubpixels (int, optional) – Number of subpixels per edge pixel used for antialiasing. Each edge pixel is subdivided into a square subarray of nSubpixels across, where binary values are assigned and averaged to produce grayscale edge values between 0 and 1. Defaults to 100. Must be a positive integer.

Returns:

A 2D array containing the generated circular aperture mask.

Return type:

numpy.ndarray

corgidrp.star_center.find_optimum_1d(xVec, arrayToFit)[source]#

Fits a parabola to a 1D array and returns the location of the minimum or maximum.

Parameters:

xVec (array_like) – 1D array of coordinate values corresponding to arrayToFit.
arrayToFit (array_like) – 1D array of values to fit.

Returns:

Best-fit value for the optimum (i.e., minimum or maximum) of the parabola.

Return type:

xOpt (float)

corgidrp.star_center.find_optimum_2d(xVec, yVec, arrayToFit, mask)[source]#

Fits a paraboloid to a 2D array and returns the location of the minimum or maximum.

Parameters:

xVec (array_like) – 1D array of coordinate values along axis 1 of arrayToFit.
yVec (array_like) – 1D array of coordinate values along axis 0 of arrayToFit.
arrayToFit (array_like) – 2D array of values to fit.
mask (array_like) – 2D boolean mask indicating which pixels to use. Must have the same shape as arrayToFit.

Returns:

xBest (float): Best-fit value along axis 1.
yBest (float): Best-fit value along axis 0.

Return type:

tuple

Notes

Modified from code at [MATLAB Central](https://au.mathworks.com/matlabcentral/answers/5482-fit-a-3d-curve).
Based on equations from [Math StackExchange](https://math.stackexchange.com/questions/2010758/how-do-i-fit-a-paraboloid-surface-to-nine-points-and-find-the-minimum).

corgidrp.star_center.calc_star_location_and_spot_separation(spotArray, xOffsetGuess, yOffsetGuess, tuningParamDict)[source]#

Calculates the center of the occulted star using satellite spots.

A single processed image of satellite spots is used. Multiple software masks are generated and applied to the measured spots to determine the stellar location. The best estimate of the star’s location is the one that maximizes the total summed energy, as determined by a 2D quadratic fit.

All filenames may be absolute or relative paths. If relative, they will be relative to the current working directory, not to any particular location in Calibration.

Parameters:

spotArray (numpy.ndarray) – 2D array of the DM-generated satellite spots. Calculated outside this function from probed images as (Iplus + Iminus)/2 - Iunprobed.
xOffsetGuess (float) – Starting guess for the number of pixels in the x direction that the star is offset from the center pixel of spotArray. The convention for the center pixel follows that of FFTs.
yOffsetGuess (float) – Starting guess for the number of pixels in the y direction that the star is offset from the center pixel of spotArray. The convention for the center pixel follows that of FFTs.
tuningParamDict (dict) –
Dictionary containing tuning parameter values.
- spotSepPix (float): Expected separation of the satellite spots from the star. Used as the separation for the center of the region of interest. Units of pixels. Compute beforehand as separation in lambda/D multiplied by pixels per lambda/D.
- roiRadiusPix (float): Radius of each region of interest used when summing the intensity of a satellite spot. Units of pixels.
- probeRotVecDeg (array_like): 1D array of angles (in degrees) counterclockwise from the x-axis to rotate the regions of interest when summing the satellite spots. A pair of satellite spots is given by just one value. - Example for a single pair along the x-axis: [0] (not [0, 180]). - Example for a plus-shaped layout of spots: [0, 90].
- nSubpixels (int): Number of subpixels across used to make edge values of the region-of-interest mask. The value of the edge pixels in the ROI is the mean of all subpixel values.
- nSteps (int): Number of points used along each direction for the grid search. Odd numbers are preferable for symmetry when the array is truly centered.
- stepSize (float): Step size used in the grid search. Units of pixels.
- nIter (int): Number of iterations in the loop that refines the stellar center location.

Returns:

xOffsetEst (float): Estimated lateral offset of the stellar center from the center pixel of spotArray in the x direction.
yOffsetEst (float): Estimated lateral offset of the stellar center from the center pixel of spotArray in the y direction.

The convention for the center pixel follows that of FFTs.
roi_mask (numpy.ndarray): 2D float array of the best-fit region-of-interest mask used to fit the translation and scaling of the ROI regions to spotArray.

Return type:

tuple

corgidrp.star_center.calc_star_location_from_spots(spotArray, xOffsetGuess, yOffsetGuess, tuningParamDict)[source]#

Calculates the center of the occulted star using satellite spots.

All filenames may be absolute or relative paths. If relative, they will be relative to the current working directory, not to any particular location in Calibration.

Parameters:

spotArray (numpy.ndarray) – 2D array of the DM-generated satellite spots. Calculated outside this function from probed images as (Iplus + Iminus)/2 - Iunprobed.
xOffsetGuess (float) – Starting guess for the number of pixels in the x direction that the star is offset from the center pixel of spotArray. The convention for the center pixel follows that of FFTs.
yOffsetGuess (float) – Starting guess for the number of pixels in the y direction that the star is offset from the center pixel of spotArray. The convention for the center pixel follows that of FFTs.
tuningParamDict (dict) –
Dictionary containing tuning parameter values.
- spotSepPix (float): Expected separation of the satellite spots from the star. Used as the separation for the center of the region of interest. Units of pixels. Compute beforehand as separation in lambda/D multiplied by pixels per lambda/D.
- roiRadiusPix (float): Radius of each region of interest used when summing the intensity of a satellite spot. Units of pixels.
- probeRotVecDeg (array_like): 1D array of angles (in degrees) counterclockwise from the x-axis to rotate the regions of interest when summing the satellite spots. A pair of satellite spots is given by just one value. - Example for a single pair along the x-axis: [0] (not [0, 180]). - Example for a plus-shaped layout of spots: [0, 90].
- nSubpixels (int): Number of subpixels across used to make edge values of the region-of-interest mask. The value of the edge pixels in the ROI is the mean of all subpixel values.
- nSteps (int): Number of points used along each direction for the grid search. Odd numbers are preferable for symmetry when the array is truly centered.
- stepSize (float): Step size used in the grid search. Units of pixels.
- nIter (int): Number of iterations in the loop that refines the stellar center location.

Returns:

xOffsetEst (float): Estimated lateral offset of the stellar center from the center pixel of spotArray in the x direction.
yOffsetEst (float): Estimated lateral offset of the stellar center from the center pixel of spotArray in the y direction.

The convention for the center pixel follows that of FFTs.

Return type:

tuple

corgidrp.star_center.calc_spot_separation(spotArray, xOffset, yOffset, tuningParamDict)[source]#

Calculates the radial separation in pixels of the satellite spots.

A single processed image of satellite spots is used. Several software masks are generated and applied to the measured spots to determine the radial separation of the spots from the given star center. The best estimate of the radial spot separation is the one that maximizes the total summed energy in the software mask, as determined by a 1D quadratic fit.

All filenames may be absolute or relative paths. If relative, they will be relative to the current working directory, not to any particular location in Calibration.

Parameters:

spotArray (numpy.ndarray) – 2D array of the DM-generated satellite spots. Calculated outside this function from probed images as (Iplus + Iminus)/2 - Iunprobed.
xOffset (float) – Previously estimated stellar center offset from the array’s center pixel. Units of pixels. The convention for the center pixel follows that of FFTs.
yOffset (float) – Previously estimated stellar center offset from the array’s center pixel. Units of pixels. The convention for the center pixel follows that of FFTs.
tuningParamDict (dict) –
Dictionary containing tuning parameter values.
- spotSepPix (float): Expected (model-based) separation of the satellite spots from the star. Used as the starting point for the separation for the center of the region of interest. Units of pixels. Compute beforehand as separation in lambda/D multiplied by pixels per lambda/D (e.g., 6.5 * (51.46 * 0.575 / 13)).
- roiRadiusPix (float): Radius of each region of interest used when summing the intensity of a satellite spot. Units of pixels.
- probeRotVecDeg (array_like): 1D array of angles (in degrees) counterclockwise from the x-axis to rotate the regions of interest when summing the satellite spots. A pair of satellite spots is given by just one value. - Example for a single pair along the x-axis: [0] (not [0, 180]). - Example for a plus-shaped layout of spots: [0, 90].
- nSubpixels (int): Number of subpixels across used to make edge values of the region-of-interest mask. The value of the edge pixels in the ROI is the mean of all the subpixel values.
- nSteps (int): Number of points used along each direction for the grid search. Odd numbers are preferable for symmetry when the array is truly centered.
- stepSize (float): Step size used in the grid search. Units of pixels.
- nIter (int): Number of iterations in the loop that refines the radial separation of the satellite spots.

Returns:

Estimated radial separation of the satellite spots from the stellar center. Units of pixels.

Return type:

float

corgidrp.star_center.star_center_from_satellite_spots(img_ref, img_sat_spot, star_coordinate_guess, thetaOffsetGuess, satellite_spot_parameters)[source]#

Estimates the star center and spot locations from satellite spot images and science data.

Parameters:

img_ref (numpy.ndarray) – 2D image representing a clean occulted focal-plane image with a base DM setting.
img_sat_spot (numpy.ndarray) – 2D image representing a clean occulted focal-plane image with a relative satellite-spot DM setting added.
star_coordinate_guess (tuple of float) – Starting guess for the absolute (x, y) coordinate of the star (in pixels). The offset calculation is referenced to the image center, which is assumed to be (image_size // 2, image_size // 2).
thetaOffsetGuess (float) – Theta rotation (in degrees) of spot locations on the camera, which might be different from expected due to clocking error between the DM and the camera.
satellite_spot_parameters (dict, optional) –
Dictionary containing tuning parameters for spot separation and offset estimation. The dictionary should have the following structure:

offsetdict
Parameters for estimating the offset of the star center:

spotSepPixfloat
Expected (model-based) separation of the satellite spots from the star. Units: pixels.

roiRadiusPixfloat
Radius of the region of interest around each satellite spot. Units: pixels.

probeRotVecDegarray_like
Angles (degrees CCW from x-axis) specifying the position of satellite spot pairs.

nSubpixelsint
Number of subpixels across for calculating region-of-interest mask edges.

nStepsint
Number of points in grid search along each direction.

stepSizefloat
Step size for the grid search. Units: pixels.

nIterint
Number of iterations refining the radial separation.

separationdict
Parameters for estimating the separation of satellite spots from the star:

spotSepPixfloat
Expected separation between star and satellite spots. Units: pixels.

roiRadiusPixfloat
Radius of the region of interest around each satellite spot. Units: pixels.

probeRotVecDegarray_like
Angles (degrees CCW from x-axis) specifying the position of satellite spot pairs.

nSubpixelsint
Number of subpixels across for calculating region-of-interest mask edges.

nStepsint
Number of points in grid search along each direction.

stepSizefloat
Step size for the grid search. Units: pixels.

nIterint
Number of iterations refining the radial separation.

Returns:

Estimated absolute coordinates [x, y] of the star center in the spots image. numpy.ndarray:

Calculated locations of the satellite spots. (Note: Currently returning ‘None’, since this isn’t being used)

Return type:

numpy.ndarray