FITSOpticalElement

class poppy.FITSOpticalElement(name='unnamed optic', transmission=None, opd=None, opdunits=None, rotation=None, pixelscale=None, planetype=None, transmission_index=None, opd_index=None, shift=None, shift_x=None, shift_y=None, flip_x=False, flip_y=False, **kwargs)[source]

Bases: OpticalElement

Defines an arbitrary optic, based on amplitude transmission and/or OPD FITS files.

This optic could be a pupil or field stop, an aberrated mirror, a phase mask, etc. The FITSOpticalElement class follows the behavior of the Wavefront class, using units of meters/pixel in pupil space and arcsec/pixel in image space.

The interface is very flexible. You can define a FITSOpticalElement either from

  • a single FITS file giving the amplitude transmission (in which case phase is zero)

  • a single FITS file giving the OPD (in which case transmission is 1 everywhere)

  • two FITS files specifying both transmission and OPD.

The FITS file argument(s) can be supplied either as

  1. a string giving the path to a file on disk,

  2. a FITS HDUlist object, or

  3. in the case of OPDs, a tuple consisting of a path to a datacube and an integer index of a slice in that datacube.

A better interface for slice selection in datacubes is the transmission_index and opd_index keyword parameters listed below, but the tuple interface is retained for back compatibility with existing code.

The FITS file header must provide information on the pixel scale, preferentially via a PIXELSCL keyword, or else you must supply the pixel scale directly. See more information just below in the parameter documentation for pixelscale.

Parameters:
namestring

descriptive name for optic

transmission, opdstring or fits HDUList

Either FITS filenames or actual fits.HDUList objects for the transmission (from 0-1) and opd (in meters)

transmission_slice, opd_sliceintegers, optional

If either transmission or OPD files are datacubes, you can specify the slice index using this argument.

opdunitsstring

units for the OPD file. Default is ‘meters’. can be ‘meter’, ‘meters’, ‘micron(s)’, ‘nanometer(s)’, or their SI abbreviations. If this keyword is not set explicitly, the BUNIT keyword in the FITS header will be checked.

planetypeint

either PlaneType.image or PlaneType.pupil

oversampleint

how much to oversample beyond Nyquist.

flip_x, flip_ybool

Should the FITS file be inverted in either of these axes after being loaded? Useful for matching coordinate system orientations. If a flip is specified, it takes place prior to any shift or rotation operations.

shifttuple of floats, optional

2-tuple containing X and Y fractional shifts for the pupil. These shifts are implemented by rounding them to the nearest integer pixel, and doing integer pixel shifts on the data array, without interpolation. If a shift is specified, it takes place after any rotation operations.

shift_x, shift_yfloats, optional

Alternate way of specifying shifts, given in meters of shift per each axis. This is consistent with how AnalyticOpticalElement classes specify shifts. If a shift is specified, it takes place after any rotation operations. If both shift and shift_x/shift_y are specified, an error is raised.

rotationfloat

Rotation for that optic, in degrees counterclockwise. This is implemented using spline interpolation via the scipy.ndimage.interpolation.rotate function.

pixelscaleoptical str or float

By default, poppy will attempt to determine the appropriate pixel scale by examining the FITS header, checking keywords “PIXELSCL”, “PUPLSCAL” and/or ‘PIXSCALE’. PIXELSCL is the default and should be preferred for new files; the latter two are kept for back-compatibility with earlier format input files, for pupil and image planes respectively. If you would like to override and use a different keyword, provide that as a string here. Alternatively, you can just set a floating point value directly too (in meters/pixel or arcsec/pixel, respectively, for pupil or image planes).

transmission_index, opd_indexints, optional

If the input transmission or OPD files are datacubes, provide a scalar index here for which cube slice should be used.

*NOTE:* All mask files must be *squares*.
Also, please note that the adopted convention is for the spectral throughput
(transmission) to be given in appropriate units for acting on the *amplitude*
of the electric field. Thus for example an optic with a uniform transmission
of 0.5 will reduce the electric field amplitude to 0.5 relative to the input,
and thus reduce the total power to 0.25. This distinction only matters in the
case of semitransparent (grayscale) masks.

Attributes Summary

pupil_diam

Diameter of the pupil (if this is a pupil plane optic)

Methods Summary

get_opd(wave)

Return the optical path difference, given a wavelength.

Attributes Documentation

pupil_diam

Diameter of the pupil (if this is a pupil plane optic)

Methods Documentation

get_opd(wave)[source]

Return the optical path difference, given a wavelength.

When the OPD map is defined in terms of wavelength-independent phase, as in the case of the vector apodizing phase plate coronagraph of Snik et al. (Proc. SPIE, 2012), it is converted to optical path difference in meters at the given wavelength for consistency with the rest of POPPY.

Parameters:
wavefloat or obj

either a scalar wavelength or a Wavefront object

Returns:
ndarray giving OPD in meters