satsim.image package — SatSim 0.13.0 documentation

# satsim.image package

## Submodules

## satsim.image.augment module

satsim.image.augment.crop_and_resize(image, t, y_start, x_start, y_box_size, x_box_size)

  Crops an image and resizes it to the original image size.

  Parameters:

    - image – array, image to shift.

    - t – time, simulation time. unused but required by interface.

    - y_start – float, starting y box location in normalized coordinates.

    - x_start – float, starting x box location in normalized coordinates.

    - y_box_size – float, y box size in normalized coordinates.

    - x_box_size – float, x box size in normalized coordinates.

  Returns:

    An array, a two dimensional image.

satsim.image.augment.flip(image, t, up_down=False, left_right=False)

  Flips an image about the y and/or x axis.

  Parameters:

    - image – array, image to shift.

    - t – time, simulation time. unused but required by interface.

    - up_down – boolean, flip image about the x axis.

    - left_right – boolean, flip image about the y axis.

  Returns:

    An array, a two dimensional image.

satsim.image.augment.load_from_file(image, t, filename, normalize=True, dtype=tf.float32)

  Load an image from file. Wraps load_sprite_from_file for the SatSim pipeline interface.

  Parameters:

    - image – array, base image. (ignored)

    - t – time, simulation time in seconds from epoch. (unused)

    - filename – float, filename of file to load.

    - normalize – boolean, normalize the output image so its sum is equal to 1.

  Returns:

    An array, an image.

satsim.image.augment.null(image, t)

  Null function.

  Parameters:

    - image – array, image.

    - t – time, simulation time.

  Returns:

    An array, same as input image.

satsim.image.augment.pow(image, t, exponent=1, normalize=True, dtype=tf.float32)

  Returns the image raised to the power exponent.

  Parameters:

    - image – array, base image.

    - t – time, simulation time in seconds from epoch.

    - exponent – float, exponent value.

    - normalize – boolean, normalize output so sum is equal to input, image.

  Returns:

    An array, an image.

satsim.image.augment.resize(image, t, height, width, spacial_osf=1, normalize=True, dtype=tf.float32)

  Resize the image.

  Parameters:

    - image – array, image.

    - t – time, simulation time in seconds from epoch.

    - height – int, height of the new image

    - width – int, width of the new image

    - int (spacial_osf) –

    - number (multiply height and width by this) –

  Returns:

    An array, same as input image.

satsim.image.augment.rotate(image, t, angle=0, rate=0)

  Rotate the image.

  Parameters:

    - image – array, image.

    - t – time, simulation time in seconds from epoch.

    - angle – float, angle to rotate image in degrees.

    - rate – float, rate to rotate image in degrees per second.

  Returns:

    An array, same as input image.

satsim.image.augment.scatter_shift(image, t, y, x, weights, spacial_osf=1, normalize=True, mode='fft', interpolation='nearest', dtype=tf.float32)

  Shifts the images specified by cartesian coordinates. If multiple shifts are specified, each shift is combined into a single image by summing

  Parameters:

    - image – array, image to shift.

    - t – time, simulation time. unused but required by interface.

    - y – float, the amount to shift the image up/down in pixels.

    - x – float, the amount to shift the image left/right in pixels.

    - weights – float, a scale to apply each shift by.

    - spacial_osf – int, oversample factor of input array. x and y are multiplied by it

    - normalize – boolean, normalize the output image so its sum is equal to the original input image.

    - mode – string, specify algorithm: fft, roll, shift. default: fft

    - interpolation – string, specify shift interpolation mode: bilinear, nearest. default: nearest

  Returns:

    An array, a two dimensional image.

satsim.image.augment.scatter_shift_polar(image, t, mag, angle, weights, spacial_osf=1, normalize=True, mode='fft', interpolation='nearest', dtype=tf.float32)

  Shifts the images specified by polar coordinates. If multiple shifts are specified, each shift is combined into a single image by summing.

  Parameters:

    - image – array, image to shift.

    - t – time, simulation time. unused but required by interface.

    - mag – float, the amount to shift the image in pixels.

    - angle – float, the direction to shift the image in degrees.

    - weights – float, a scale to apply each shift by.

    - spacial_osf – int, oversample factor of input array. x and y are multiplied by it

    - normalize – boolean, normalize the output image so its sum is equal to the original input image.

    - mode – string, specify algorithm: fft, roll, shift. default: fft

    - interpolation – string, specify shift interpolation mode: bilinear, nearest. default: nearest

  Returns:

    An array, a two dimensional image.

satsim.image.augment.scatter_shift_random(image, t, loc, scale, length, spacial_osf=1, normalize=True, mode='fft', interpolation='nearest', dtype=tf.float32)

  Shifts the images specified in random directions. If length is greater than 1, each shift is combined into a single image by summing.

  Parameters:

    - image – array, image to shift.

    - t – time, simulation time. unused but required by interface.

    - loc – float, mean of the normal distribution.

    - scale – float, standard deviation of the normal distribution.

    - spacial_osf – int, oversample factor of input array. x and y are multiplied by it

    - normalize – boolean, normalize the output image so its sum is equal to the original input image.

    - mode – string, specify algorithm: fft, roll, shift. default: fft

    - interpolation – string, specify shift interpolation mode: bilinear, nearest. default: nearest

  Returns:

    An array, a two dimensional image.

## satsim.image.fpa module

satsim.image.fpa.add_counts(fpa, r, c, cnt, r_offset=0, c_offset=0)

  Add counts (e.g. digital number (dn), photoelectrons (pe)) to the input image.

  Parameters:

    - fpa – Tensor, input image as a 2D tensor in real or oversample pixel space. Should be a tf.Variable.

    - r – list, list of row pixel coordinates as int

    - c – list, list of column pixel coordinates as int

    - cnt – list, list of absolute counts. For example, dn or pe.

    - r_offset – int, offset to add to r values. Useful to account for image pad.

    - c_offset – int, offset to add to c values. Useful to account for image pad.

  Returns:

    A Tensor, a reference to the modified input fpa image

satsim.image.fpa.add_patch(fpa, r, c, cnt, patch, r_offset=0, c_offset=0, mode='fft')

  Add a patch to the input image, fpa, centered about each row, column coordinate. Patch is multiplied by the cnt. patch is typically normalized.

  Parameters:

    - fpa – Tensor, input image as a 2D tensor.

    - r – list, list of row pixel coordinates as int.

    - c – list, list of column pixel coordinates as int.

    - cnt – list, list of absolute counts. For example, dn or pe.

    - patch – Tensor, patch image as a 2D tensor

    - r_offset – int, offset to add to r values. Useful to account for image pad.

    - c_offset – int, offset to add to c values. Useful to account for image pad.

    - mode – string, specify render mode. fft or overlay. default: fft

  Returns:

    A Tensor, a reference to the modified input fpa image

satsim.image.fpa.analog_to_digital(fpa, gain, fwc, bias=0, dtype='uint16', saturated_pixel_model='max')

  Converts photoelectron counts to digital counts. The linear model digital * gain = analog is used to covert from analog to digital counts. Photoelectron counts for each pixel are bound between 0 and fwc.

  Parameters:

    - fpa – Tensor, input image as a 2D tensor in real pixel space.

    - gain – float, the digital to analog multiplier.

    - fwc – float, the maximum value or full well capacity in photoelectrons.

    - bias – float, bias to add in digital counts. (Default: 0)

    - dtype – string, pixel data type

    - saturated_pixel_model – string, max will set any value greater than the maximum value of the dtype to the maximum value, otherwise saturated pixels behavior is undefined

  Returns:

    A Tensor, the 2D image tensor as whole number digital counts.

satsim.image.fpa.crop(fpa, y_pad, x_pad, y_size, x_size)

  Crops a 2D image tensor. Typically used to remove pixel padding.

  Parameters:

    - fpa – Tensor, input image as a 2D tensor in oversampled pixel space.

    - y_pad – int, starting y pixel location (number of pad pixels at the top).

    - x_pad – int, starting x pixel location (number of pad pixels on the left).

    - y_size – int, total y pixels to crop.

    - x_size – int, total x pixels to crop.

  Returns:

    A Tensor, the cropped 2D image tensor.

satsim.image.fpa.downsample(fpa, osf, method='conv2d')

  Downsample a 2D image tensor. Typically used to calculate the real pixel values in an oversampled image.

  Parameters:

    - fpa – Tensor, input image as a 2D tensor in oversampled pixel space.

    - osf – int, oversample factor of the input image.

    - method – string, conv2d or pool algorithm

  Returns:

    A Tensor, the downsampled 2D image tensor.

satsim.image.fpa.mv_to_pe(zeropoint, mv)

  Converts visual magnitude to photoelectrons per second. The zeropoint of an instrument, by definition, is the magnitude of an object that produces one count (or photoelectron) per second. The visual magnitude (MV) of an arbitrary object producing photoelectrons in an observation of one second is therefore:

  > mv = -2.5 * log10(pe) + zeropoint

  > and

  > mv_to_pe(zeropoint, zeropoint) == 1

  Parameters:

    - zeropoint – float, the zeropoint of the fpa.

    - mv – float, the visual magnitude of the object.

  Returns:

    A float, the visual magnitude in photoelectron per second

satsim.image.fpa.pe_to_mv(zeropoint, pe)

  Converts photoelectrons per second to visual magnitude. The zeropoint of an instrument, by definition, is the magnitude of an object that produces one count (or photoelectron) per second. The visual magnitude (MV) of an arbitrary object producing photoelectrons in an observation of one second is therefore:

  > mv = -2.5 * log10(pe) + zeropoint

  > and

  > mv_to_pe(zeropoint, zeropoint) == 1

  Parameters:

    - zeropoint – float, the zeropoint of the fpa.

    - pe – float, the brightness of the object in photoelectron per second.

  Returns:

    A float, the visual magnitude

satsim.image.fpa.transform_and_add_counts(fpa, r, c, cnt, t_start, t_end, t_osf, rotation, translation, batch_size=500, filter_out_of_bounds=True)

  Applies discrete rotation and translation transformations to a set of input points. This has the effect of “smearing” or “streaking” the point between times t_start and t_end. The number of transforms calculated is specified by the temporal oversample factor, t_osf. The total energy is conserved.

  Parameters:

    - fpa – Tensor, input image as a 2D tensor in real or oversample pixel space. Should be from a Variable node.

    - r – list, list of row pixel coordinates.

    - c – list, list of column pixel coordinates.

    - cnt – list, list of absolute dn or pe counts.

    - t_start – float, start time in seconds from t_epoch where t_epoch=0

    - t_end – float, end time in seconds from t_epoch where t_epoch=0

    - t_osf – int, temporal oversample factor, determines the number of discrete transforms to apply between t_start and t_end. Value should be greather than 0.

    - rotation – float, clockwise rotation rate in radians/sec

    - translation – ‘[float, float]’, translation rate in pixels/sec in [row,col] order

    - batch_size – int: Number of points to process together. Typically a larger batch size will process faster due to vectorization at the expense of increased memory useage. Default: 500)

  Returns:

    fpa: Tensor, a reference to the modified input fpa image

  Return type:

    A tuple

satsim.image.fpa.transform_and_fft(fpa, r, c, cnt, t_start, t_end, t_osf, rotation, translation)

  Applies discrete rotation and translation transformations to the center point and applies the smear to all other points with an FFT. This has the effect of “smearing” or “streaking” the point between times t_start and t_end. This function has the advantage of a much faster runtime than transform_and_add_counts when there are many points to transform and the disadvantage that all points have the identical smear.

  Parameters:

    - fpa – Tensor, input image as a 2D tensor in real or oversample pixel space. Should be from a Variable node.

    - r – list, list of row pixel coordinates.

    - c – list, list of column pixel coordinates.

    - cnt – list, list of absolute dn or pe counts.

    - t_start – float, start time in seconds from t_epoch where t_epoch=0

    - t_end – float, end time in seconds from t_epoch where t_epoch=0

    - t_osf – int, temporal oversample factor, determines the number of discrete transforms to apply between t_start and t_end. Value should be greather than 0.

    - rotation – float, clockwise rotation rate in radians/sec

    - translation – ‘[float, float]’, translation rate in pixels/sec in [row,col] order

  Returns:

    fpa: Tensor, a reference to the modified input fpa image

  Return type:

    A tuple

## satsim.image.model module

satsim.image.model.astropy_model2d(height, width, filename, low=-1, high=1, clip=0)

  Loads an AstroPy Model. The model is evaluated between low and high using evenly spaced values (linspace).

  Parameters:

    - height – int, image height.

    - width – int, image width.

    - filename – string, path to Advanced Scientific Data Format model file.

    - low – float, lowest number in the two dimensional series. Points are sampled linearly spaced between low and high.

    - high – float, highest number in the two dimensional series. Points are sampled linearly spaced between low and high.

  Returns:

    An array, a two dimensional image.

satsim.image.model.polygrid2d(height, width, c, low=-1, high=1)

  Generates a two dimensional image based on NumPy polygrid2d.

  Parameters:

    - height – int, image height.

    - width – int, image width.

    - c – array, Array of coefficients ordered so that the coefficients for terms of degree i,j are contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.

    - low – float, lowest number in the two dimensional series. Points are sampled linearly spaced between low and high. default=-1

    - high – float, highest number in the two dimensional series. Points are sampled linearly spaced between low and high. default=1

  Returns:

    An array, a two dimensional image.

satsim.image.model.radial_cos2d(height, width, y_scale=0.1, x_scale=0.1, power=4, xy_scale=None, mult=1.0, clip=[0.0, 1.0])

  Generates a cosine wave radially from the center of the image. Typically used to simulate optical vignette or irradiance falloff.

  Parameters:

    - height – int, image height.

    - width – int, image width.

    - y_scale – float, the fraction of the cosine wave to generate across the rows from the center to the edge.

    - x_scale – float, the fraction of the cosine wave to generate across the columns from the center to the edge.

    - scale – float, if not None set y_scale and x_scale to this.

    - power – float, the exponent of the cosine. Set to 4 to generate a “cosine fourth” irradiance falloff map. default=4

    - mult – float, multiply cosine. default=1

    - clip – array, clip returned value by minimum and maximum. default=[0.0, 1.0]

  Returns:

    An array, a two dimensional image.

satsim.image.model.sin2d(height, width, amplitude=1, frequency=5, bias=0, minimum=0, maximum=None, direction=0, damped=False)

  Generates a sine wave across the image in a specified direction.

  Parameters:

    - height – int, image height.

    - width – int, image width.

    - amplitude – float, the amplitude of the sine wave. default=1

    - frequency – float, number of full sine waves to generate over the width of the image. default=5

    - bias – float, bias to add to the entire image. default=0

    - minimum – float, set the minimum value in the image. default=0

    - maximum – float, set the maximum value in the image. default=None

    - direction – float, set the direction of the wave in degrees where 0 is horizontal from left to right. default=0

    - damped – boolean, damp the sine wave by e^-t. default=False

  Returns:

    An array, a two dimensional image.

## satsim.image.noise module

satsim.image.noise.add_photon_noise(fpa, samples=None)

  Add photon noise. Photon noise results from the inherent statistical variation in the arrival rate of photons incident on the CCD. Photoelectrons generated within the semiconductor device constitute the signal, the magnitude of which fluctuates randomly with photon incidence at each measuring location (pixel) on the CCD. The interval between photon arrivals is governed by Poisson statistics, and therefore, the photon noise is equivalent to the square-root of the signal. In general, the term shot noise is applied to any noise component reflecting a similar statistical variation, or uncertainty, in measurements of the number of photons collected during a given time interval, and some references use that term in place of photon noise in discussions of CCD noise sources.

  Examples:

      fpa_photon_noise = add_photon_noise(fpa_no_noise+background+dark_current)

  Parameters:

    - fpa – Tensor, input image as a 2D tensor in total photoelectrons per pixel

    - samples – int, number of samples to generate then average. Typically used to estimate averaging of multiple images. default=None (or 1 sample)

  Returns:

    A Tensor, the 2D tensor with photon noise applied.

satsim.image.noise.add_read_noise(fpa, rn, en=0)

  Add read noise. Read noise (RN) is a combination of noise from the pixel and from the analog to digital converter (ADC). The RN of the sensor is the equivalent noise level (in electrons RMS) at the output of the camera in the dark and at zero integration time. Note that the build up is different for a CMOS sensor and a CCD sensor. The ADC with CCD image sensors is done outside the sensor and the ADCs for a CMOS image sensor are in each pixel.

  Examples:

      fpa_with_read_noise = add_read_noise(fpa, 15)

  Parameters:

    - fpa – Tensor, input image as a 2D tensor in real pixels (not oversampled).

    - rn – float, electrons RMS value of the read noise.

    - en – float, electrons RMS value of the electronic noise.

  Returns:

    A Tensor, the 2D tensor with read noise applied.

## satsim.image.psf module

satsim.image.psf.eod_to_sigma(eod, osf)

  Calculates the sigma of a 2D Gaussian required to get a maximum energy on a detector (EOD) or single pixel. EOD is specified as a fraction (0 < EOD < 1). The 2D Gaussian is assumed to be centered on a real pixel.

  Parameters:

    - eod – float, desired maximum energy on detector in real pixel space.

    - osf – int, desired PSF oversample factor.

  Returns:

    A float, the estimated Gaussian sigma for eod in real pixel space.

satsim.image.psf.gen_from_poppy(optical_system, wavelengths=[6e-07], weights=[1])

  Generate a point spread function (PSF) from a POPPY optical system.

  Parameters:

    - optical_system – object, POPPY OpticalSystem.

    - wavelengths – array, an array of wavelengths to simulate.

    - weights – array, an array of same length of wavelength. Each value is

    - wavelength. (used to scale the PSF for corresponding) –

  Returns:

    An array, the PSF as a two dimensional array.

satsim.image.psf.gen_from_poppy_configuration(height, width, y_ifov, x_ifov, s_osf, config)

  Generate a point spread function (PSF) from a POPPY configuration. Configuration example:

      config = {
          "mode": "poppy",
          "optical_system": [
              {
                  "type": "CompoundAnalyticOptic",
                  "opticslist": [
                      {
                          "type": "CircularAperture",
                          "kwargs": {
                              "radius": 0.200
                          }
                      },
                      {
                          "type": "SecondaryObscuration",
                          "kwargs": {
                              "secondary_radius": 0.110,
                              "n_supports": 4,
                              "support_width": 0.010
                          }
                      }
                  ]
              },
              {
                  "type": "ZernikeWFE",
                  "kwargs": {
                      "radius": 0.200,
                      "coefficients": [0, 0, 0, 100e-9]
                  }
              }
          ],
          "wavelengths": [300e-9, 600e-9, 900e-9],
          "weights": [0.3, 0.4, 0.3]
      }

  Parameters:

    - height – int, height of the output PSF.

    - width – int, width of the output PSF.

    - y_ifov – float, field of view of a pixel in y.

    - x_ifov – float, field of view of a pixel in x.

    - s_osf – int, oversample factor.

    - param – dict, a dictionary that describes the optical system. See example.

  Returns:

    An array, the PSF as a two dimensional array.

satsim.image.psf.gen_gaussian(height, width, sigma, dtype=tf.float32)

  Generate a 2D Gaussian point spread function (PSF).

  Examples:

      osf = 11
      sigma = eod_to_sigma(0.8, osf)
      psf = gen_gaussian(512*osf, 512*osf, sigma)

  Parameters:

    - height – int, height of the output PSF.

    - width – int, width of the output PSF.

    - sigma – float, the standard deviation of the Gaussian.

    - dtype – tf.dtype, Defaults to tf.float32.

  Returns:

    A Tensor, the 2D Gaussian PSF with the shape [height,width]

## satsim.image.render module

satsim.image.render.render_full(h_fpa_os, w_fpa_os, h_fpa_pad_os, w_fpa_pad_os, h_pad_os_div2, w_pad_os_div2, s_osf, psf_os, r_obs_os, c_obs_os, pe_obs_os, r_stars_os, c_stars_os, pe_stars_os, t_start_star, t_end_star, t_osf, star_rot_rate, star_tran_os, render_separate=True, obs_model=None, star_render_mode='transform')

  Render an image.

  Parameters:

    - h_fpa_os – int, image height in oversampled space.

    - w_fpa_os – int, image width in oversampled space.

    - h_fpa_pad_os – int, image height with pad in oversample space.

    - w_fpa_pad_os – int, image width with pad in oversample space.

    - h_pad_os_div2 – int, image height with pad divided by 2 in oversample space.

    - w_pad_os_div2 – int, image width with pad divided by 2 in oversample space.

    - s_osf – int, spacial oversample factor.

    - psf_os – image, point spread function with size of image with pad in oversampled space.

    - r_obs_os – int, list of target row coordinates in oversampled space.

    - c_obs_os – int, list of target column coordinates in oversampled space.

    - pe_obs_os – int, list of target brightnesses in photoelectrons per pixel.

    - r_stars_os – list, list of star row coordinates in oversampled space at epoch.

    - c_stars_os – list, list of star column coordinates in oversampled space at epoch.

    - pe_stars_os – list, list of star brightnesses in photoelectrons per second.

    - t_start_star – float, start time in seconds from epoch.

    - t_end_star – float, end time in seconds from epoch.

    - t_osf – int, temporal oversample factor for star transformation.

    - star_rot_rate – float, star rotation rate in degrees per second.

    - star_tran_os – [float, float], star translation rate in oversampled pixel per second (row, col).

    - render_separate – boolean, if True render targets and stars seperately, required to calculate SNR.

    - obs_model – list, list of image arrays in photoelectrons. each array should be the size h_fpa_pad_os by w_fpa_pad_os and is simply added into the image. default=None

    - star_render_mode – string, star render mode. fft or transform. default=transform

  Returns:

    fpa_conv_star: image, rendered image with stars. Stars and targets if render_separate is False. fpa_conv_targ: image, rendered image with targets. Zeros if render_separate is False. fpa_os_w_targets: image, oversample image with targets before blur. fpa_conv_os: None, rendered oversample image with pad. fpa_conv_crop: None, rendered oversample image with no pad.

  Return type:

    A tuple, containing

satsim.image.render.render_piecewise(h, w, h_sub, w_sub, h_pad_os, w_pad_os, s_osf, psf_os, r_obs_os, c_obs_os, pe_obs_os, r_stars_os, c_stars_os, pe_stars_os, t_start_star, t_end_star, t_osf, star_rot_rate, star_tran_os, render_separate=True, star_render_mode='transform')

  Render an image in sub sections. Useful if target supersample image does not fit in GPU memory.

  Parameters:

    - h – int, image height in number of real pixels.

    - w – int, image width in number of real pixels.

    - h_sub – int, sub section height to render in number of real pixels.

    - w_sub – int, sub section width to render in number of real pixels.

    - h_pad_os – int, total vertical pad in oversample space.

    - w_pad_os – int, total horizontal pad in oversample space.

    - s_osf – int, spacial oversample factor.

    - psf_os – image, point spread function with size of h_sub by w_sub plus padding in oversampled space.

    - r_obs_os – int, list of target row coordinates in oversampled space.

    - c_obs_os – int, list of target column coordinates in oversampled space.

    - pe_obs_os – int, list of target brightnesses in photoelectrons per pixel.

    - r_stars_os – list, list of star row coordinates in oversampled space at epoch.

    - c_stars_os – list, list of star column coordinates in oversampled space at epoch.

    - pe_stars_os – list, list of star brightnesses in photoelectrons per second.

    - t_start_star – float, start time in seconds from epoch.

    - t_end_star – float, end time in seconds from epoch.

    - t_osf – int, temporal oversample factor for star transformation.

    - star_rot_rate – float, star rotation rate in degrees per second.

    - star_tran_os – [float, float], star translation rate in oversampled pixel per second (row, col).

    - render_separate – boolean, if True render targets and stars seperately, required to calculate SNR.

    - star_render_mode – string, star render mode. fft or transform. default=transform

  Returns:

    fpa_conv_star: image, rendered image with stars. Stars and targets if render_separate is False. fpa_conv_targ: image, rendered image with targets. Zeros if render_separate is False. _: None, to make output compatible with render_full _: None, to make output compatible with render_full _: None, to make output compatible with render_full

  Return type:

    A tuple, containing