fiberlab.fullcone module

Module with methods used to analyze and plot full-cone test images.

class fiberlab.fullcone.EECurve(img, mask=None, circ_p=None, smooth=None, level=None, threshold=None, clip_iter=10, sigma_lower=100.0, sigma_upper=3.0, bkg_lim=None, bkg_lim_sig=3.0)[source]

Bases: object

Construct an encircled energy curve provided an output image with a single output beam.

Parameters:

  • img (numpy.ndarray) – Image data to analze.

  • mask (numpy.ndarray, optional) – Boolean mask image (True=masked pixel). Must be the same shape as img. If None, all pixels in img are considered valid.

  • circ_p (numpy.ndarray, optional) – Parameters of the circle used to define where the output beam is located in the image. Shape must be (3,), providing (1) the center along the image 2nd axis (following the numpy convention of this being the x coordinate), (2) the center along the 1st axis (numpy y axis), and (3) a fiducial radius of the spot. If None, these parameters are determine by fitting an image contour. If provided, smooth and threshold are ignored.

  • smooth (float, optional) – When using an image contour to find the output beam center, first smooth the image using a Gaussian kernel with this (circular) sigma. If None, img is not smoothed before the contour is determined.

  • level (float, optional) – The exact pixel value to use when finding the contour used to set the beam center.

  • threshold (float, optional) – The threshold in units of image background standard deviation used to set the contour level. If None and circ_p is not provided, the default value is set by default_threshold().

  • clip_iter (int, optional) – Number of clipping iterations to perform when measuring the background and standard deviation in the input image. This is used only when setting the image contour level to find the beam center. If None, no clipping iterations are performed. The purpose of this clipping is to remove most/all pixels with light from the spot.

  • sigma_lower (float, optional) – Sigma rejection used for measurements below the mean. Must be provided (or left at the default) if clip_iter is not None. Typically this number should be large: pixels at relatively low values should be background pixels, where as pixels above the mean have light from the output spot.

  • sigma_upper (float, optional) – Sigma rejection used for measurements above the mean. Must be provided (or left at the default) if clip_iter is not None. Typically this number should be small: pixels at relatively low values should be background pixels, where as pixels above the mean have light from the output spot.

  • bkg_lim (array-like, optional) – Perform a +/- sigma rejection in a background region defined by this object. This must be a two element array-like object, and the first element cannot be None. If the last element is None, all pixels beyond that multiple of the beam radius, defined by the last element of circ_p, is included in the rejection. If the last element is not None, the two elements define an inner (first element) and outer (last element) radius factor for the background region. If the object is None, no additional background region rejection is performed.

  • bkg_lim_sig (float, optional) – Number of sigma for the background rejection performed based on bkg_lim.

build_interpolator(model=False, smooth=True)[source]
build_model()[source]
property ee_interpolator
get_ee_norm()[source]
property model_ee_interpolator
fiberlab.fullcone.calculate_fratio(z0_radius, z0_ee, z1_radius, z1_ee, sep, smooth=False, z0_bkg_lim=None, z1_bkg_lim=None)[source]

Given the normalized EE curves from two images separated by a known distance, calculate the distance from each image to the origin of the output beam and the beam focal ratio.

Image z0 is taken closer to the output beam, and image z1 is taken further away.

Parameters:

  • z0_radius (numpy.ndarray) – Radius in mm from the center of the spot in image z0.

  • z0_ee (numpy.ndarray) – Normalized encircled energy for the spot in image z0.

  • z1_radius (numpy.ndarray) – Radius in mm from the center of the spot in image z1.

  • z1_ee (numpy.ndarray) – Normalized encircled energy for the spot in image z1.

  • sep (float) – Separation between the two images in mm along the output axis.

  • smooth (bool, optional) – Smooth the raw data before interpolating the radius at a fixed set of EE values.

  • z0_bkg_lim (float, optional) – Radius in mm from the center of the spot at which the background flux was determined in image z0.

  • z1_bkg_lim (float, optional) – Radius in mm from the center of the spot at which the background flux was determined in image z1.

Returns:

A set of ten objects: (1) the EE samples, (2-3) the radii at which the spot reaches the sampled EE for z0 and z1, respectively, (4-5) the distances between the origin of the output beam and the image as measured at each EE sample for z0 and z1, respectively, (6-7) the “median” distance estimate using 0.2 < EE < 0.9 for image z0 and z1, respectively, (8-9) the focal ratios calculated using the median distances and the measured radii for image z0 and z1, respectively, and (10) a boolean indicating if the calculation was successful.

Return type:

tuple

fiberlab.fullcone.default_threshold()[source]

The default threshold to use for defining the contour used to determine the center of the output beam.

fiberlab.fullcone.ee_to_fratio(radius, ee, distance=None, smooth=False, bkg_lim=None)[source]

Given the normalized EE curve from an image at a known distance from an output spot, calculate the focal ratio at uniformly sampled EE values.

Parameters:

  • radius (numpy.ndarray) – Radius in mm from the center of the spot.

  • ee (numpy.ndarray) – Normalized encircled energy for the spot.

  • distance (float, optional) – Distance from the image to the output plain. If not provided, all the focal-ratio values are -1, and this function simply resamples the EE data.

  • smooth (bool, optional) – Smooth the raw data before interpolating the radius at a fixed set of EE values.

  • bkg_lim (float, optional) – Radius in mm from the center of the spot at which the background flux was determined.

Returns:

A set of four objects: (1) the EE samples, (2) the radii at which the spot reaches the sampled EE, (3) the focal ratios calculated using the provided distance and the measured radii, and (4) a boolean indicating if the calculation was successful.

Return type:

tuple

fiberlab.fullcone.fullcone_farfield_output(img_file, bkg_file=None, pixelsize=None, distance=None, plot_file=None, snr_img=False, window=None, box=None, **kwargs)[source]

Analyze an output far-field image for a full-cone input beam.

Parameters:

  • img_file (str, Path) – Image file

  • bkg_file (str, Path, optional) – Background image to subtract

  • pixelsize (float, optional) – Size of the native image pixels in mm (i.e., before any boxcar average; see box).

  • distance (float, optional) – Distance from the fiber output to the detector in mm.

  • plot_file (str, Path, optional) – Name of the QA file to produce. If 'show', no file is produced, but the QA plot is displayed in a matplotlib window.

  • snr_img (bool, optional) – If creating the QA plot, plot the estimated S/N (used to set the contour level) instead of the measured counts.

  • window (float, optional) – Limit the plotted image regions to this times the best-fitting peak of the ring flux distribution. If None, the full image is shown.

  • box (int, optional) – Boxcar average the image by this number of pixels. If None, full resolution of image is used.

  • **kwargs – Parameters passed directly to EECurve used to derive the encircled-energy curve.

Returns:

Three floating-point objects providing the radius at which the peak flux is found, the flux at the peak, and the width of the ring.

Return type:

tuple

fiberlab.fullcone.fullcone_farfield_output_plot(img_file, img, model, trace, circ_p, radius, flux, ee, model_radius, model_flux, snr_img=False, img_sig=None, bkg_lim=None, r_units='pix', window=None, pixelsize=None, distance=None, ofile=None)[source]

UPDATE Diagnostic plot for the measurements of a collimated far-field output beam.

Parameters:

  • img_file (str, Path) – Image file

  • img (numpy.ndarray) – The background subtracted far-field image data.

  • model (numpy.ndarray) – The model of the far-field image.

  • threshold (float) – S/N threshold of the contour used to define the center of the ring.

  • trace (numpy.ndarray) – The contour tracing the outside of the ring used to define the ring center.

  • circ_p (tuple) – Tuple with the best-fitting parameters for the ring contour: x center (along 2nd axis), y center (along 1st axis), and radius.

  • radius (numpy.ndarray) – A (sorted) 1D array with the radii of all pixels in img relative to the ring center.

  • flux (numpy.ndarray) – A 1D array with the flux of all pixels in img sorted by radius relative to the ring center.

  • smooth_flux (numpy.ndarray) – The smoothed version of the flux vector, used to measure the radius of the ring, its peak flux, and its full-width at half maximum.

  • peak_indx (int) – The index of the element in smooth_flux at which the peak (ring center) was found.

  • left (float) – The inner radius of the ring at half its maximum.

  • right (float) – The outer radius of the ring at half its maximum.

  • snr_img (bool, optional) – Plot the estimated S/N (used to set the contour level) instead of the measured counts.

  • level (float, optional) – The level in the image that corresponds to the S/N threshold.

  • r_umits (str, optional) – The units of the radius vector.

  • window (float, optional) – Limit the plotted image regions to this times the best-fitting contour radius. If None, the full image is shown.

  • ofile (str, Path, optional) – Name of the QA file to produce. If 'show', no file is produced, but the QA plot is displayed in a matplotlib window.

fiberlab.fullcone.fullcone_throughput(inp_img, out_img, bkg_file=None, threshold=None, clip_iter=10, sigma_lower=100.0, sigma_upper=3.0, local_bg_fac=None, local_iter=1)[source]

Analyze an output far-field image for a full-cone input beam.

Parameters:

  • inp_img (str, Path) – Image of the input beam

  • out_img (str, Path) – Image of the output beam

  • bkg_file (str, Path, optional) – Background image to subtract

  • threshold (float, optional) – S/N threshold of the contour used to define the center of the ring. If None, see default_threshold().

  • clip_iter (int, optional) – Number of clipping iterations used to measure background

  • sigma_lower (float, optional) – Lower sigma rejection used to measure background

  • sigma_upper (float, optional) – Upper sigma rejection used to measure background

  • local_bg_fac (float, optional) – Number of HWHM at which to determine the local background level. If None, no local background is estimated.

  • local_iter (int, optional) – Number of iterations used for determining the local background. Ignored if local_bg_fac is None.