Photon Collection models#
Photon generation models are used to add and manipulate data in Photon
array
inside the Detector
object. If the scene generation model group
is used, a model like Simple collection needs to be enabled in the pipeline to make the conversion from
Scene to Photon.
Otherwise, models like Simple illumination or Load image need to be enabled to initialize the
Photon
array.
Multiple photon generation models can be linked together one after another.
The values in the Photon
array represent photon flux,
i.e. number of photons per pixel area per second. The time scale of the incoming flux can be changed in the model arguments.
Create and Store a detector#
The models Save detector and Load detector
can be used respectively to create and to store a Detector
to/from a file.
These models can be used when you want to store or to inject a Detector
into the current Pipeline.
Save detector#
This model saves the current Detector
into a file.
Accepted file formats are .h5
, .hdf5
, .hdf
and .asdf
.
- name: save_detector
func: pyxel.models.save_detector
enabled: true
arguments:
filename: my_detector.h5
Load detector#
This model loads a Detector
from a file and injects it in the current pipeline.
Accepted file formats are .h5
, .hdf5
, .hdf
and .asdf
.
- name: load_detector
func: pyxel.models.load_detector
enabled: true
arguments:
filename: my_detector.h5
Simple collection#
Note
This model operates with both multi-wavelength and monochromatic photons.
Scene → Photon
Converts scene to photon using a given aperture.
Initially, a xarray Dataset is extracted from the Scene for a selected wavelength band.
The filter_band
input represents the wavelength range of the selected filter band.
By default, the filter_band
argument in cut_on
and cut_off
wavelengths can be defined
in the Environment
.
However, you can override this property by providing the filter_band
as a model argument.
This model supports both monochromatic or multi-wavelength modes, generating a 2D Photon array or 3D Photon array
as output, whereas the 3D Photon array includes the wavelength dimension.
When integrate_wavelength
is set to true (default) the monochromatic mode is selected,
where the flux of objects in the scene is integrated across the wavelength band.
The integrated flux in integrate_wavelength
set to false, the photons are represented with dimensions “wavelength”, “y”, and “x”.
The objects are projected onto the detector, with object coordinates converted from pixel_scale
in pixel_scale
is None, and
the model retrieves the pixel_scale
defined in the Geometry
.
However, it is possible to override this property by providing pixel_scale
as model argument.
- name : simple_collection
func: pyxel.models.photon_collection.simple_collection
enabled: true
arguments:
aperture: 126.70e-3 #m
filter_band: [400, 500] #nm
pixel_scale: 1.65 #arcsec/pixel
integrate_wavelength: true
- pyxel.models.photon_collection.simple_collection(detector, aperture, filter_band=None, resolution=None, pixel_scale=None, integrate_wavelength=True)[source]#
Convert scene in ph/(cm2 nm s) to photon in ph/nm s or ph s.
- Parameters:
detector (
Detector
) – Pyxel detector object.aperture (
float
) – Collecting area of the telescope. Unit: m.filter_band (
Union[tuple[float
,float]
,None]
) – Wavelength range of selected filter band, default is None. Unit: nm.resolution (
Optional[int]
) – Resolution of provided wavelength range in filter band. Unit: nm.pixel_scale (
float
, optional) – Pixel scale of detector, default is None. Unit: arcsec/pixel.integrate_wavelength (
bool
) – If true, integrates along the wavelength else multiwavelength, default is True.
Load image#
Photon → Photon
With this model you can add photons to Detector
by loading an image from a file.
Accepted file formats are .npy
, .fits
, .txt
, .data
, .jpg
, .jpeg
, .bmp
,
.png
and .tiff
. Use argument position
to set the offset from the (0,0) pixel
and set where the input image is placed onto detector. You can preset positions with argument align
.
Values outside of the detector shape will be cropped.
Read more about placement in the documentation of function fit_into_array()
.
With multiplier
you can multiply the photon number by a custom float,
and time_scale
is to set the time scale of the incoming photons, default is 1 second.
By setting convert_to_photons
to true
together with bit_resolution
,
the model converts the values of loaded image array from ADU
to photon numbers for each pixel using the Photon Transfer Function.
ADC conversion factor in this case is
Example of the configuration file:
- name: load_image
func: pyxel.models.photon_collection.load_image
enabled: true
arguments:
image_file: data/HorseHead.fits
position: [0,0]
convert_to_photons: true
bit_resolution: 16
- pyxel.models.photon_collection.load_image(detector, image_file, include_header=False, header_section_index=None, position=(0, 0), align=None, convert_to_photons=False, multiplier=1.0, time_scale=1.0, bit_resolution=None)[source]#
Load FITS file as a numpy array and add to the detector as input image.
- Parameters:
detector (
Detector
)image_file (
str
) – Path to image file.include_header (
bool
,optional.
) – IfTrue
, extract header metadata from the image file. This parameter is provisional and may be removed.header_section_index (
int
orstr
orNone
, optional) – Section index or name of the header data to load if include_header is enabled. This parameter is provisional and may be removed.position (
tuple
) – Indices of starting row and column, used when fitting image to detector.align (
Literal
) – Keyword to align the image to detector. Can be any from: (“center”, “top_left”, “top_right”, “bottom_left”, “bottom_right”)convert_to_photons (
bool
) – IfTrue
, the model converts the values of loaded image array from ADU to photon numbers for each pixel using the Photon Transfer Function: .multiplier (
float
) – Multiply photon array level with a custom number.time_scale (
float
) – Time scale of the photon flux, default is 1 second. 0.001 would be ms.bit_resolution (
int
) – Bit resolution of the loaded image.
Notes
The image array is cropped and aligned based on the shape and position parameters and is scaled by the multiplier and time_scale before being added to the detector.
If include_header is enabled, the header metadata is extracted from image_file and store in the detector`s header storage.
Usaf illumination#
Photon → Photon
With this model you can load a standard USAF-1951 illumination pattern to test your detector with.
It uses the above-mentioned load_image model to load a .png
version of the pattern stored in the pyxel-data repository.
You can check the arguments specification in Load image for more information on setting up the model.
Example of the configuration file:
- name: usaf_illumination
func: pyxel.models.photon_collection.usaf_illumination
enabled: true
arguments:
position: [0,0]
convert_to_photons: true
bit_resolution: 16
- pyxel.models.photon_collection.usaf_illumination(detector, position=(0, 0), align=None, convert_to_photons=False, multiplier=1.0, time_scale=1.0, bit_resolution=None)[source]#
Apply USAF-1951 illumination pattern.
- Parameters:
detector (
Detector
)position (
tuple
) – Indices of starting row and column, used when fitting image to detector.align (
Literal
) – Keyword to align the image to detector. Can be any from: (“center”, “top_left”, “top_right”, “bottom_left”, “bottom_right”)convert_to_photons (
bool
) – IfTrue
, the model converts the values of loaded image array from ADU to photon numbers for each pixel using the Photon Transfer Function: .multiplier (
float
) – Multiply photon array level with a custom number.time_scale (
float
) – Time scale of the photon flux, default is 1 second. 0.001 would be ms.bit_resolution (
int
) – Bit resolution of the loaded image.
Simple illumination#
Photon → Photon
With this model you can create different simple photon distributions: uniform, elliptical/circular
or rectangular, by setting the argument type
. The calculated photon count will be added to the
Photon
array. User can specify the brightness of the object
with the argument level
. If the distribution is not uniform
, then the user also has to provide object_size
,
a list of tho integers, which are the diameters of the object in vertical and horizontal directions.
Object position can be changed with the argument object_position
,
a list of two integers specifying offset of the object center from pixel (0,0),
again in vertical and horizontal direction.
Use the argument time_scale
to set the time scale of the incoming photon flux.
Example of the configuration file for a circular object:
- name: illumination
func: pyxel.models.photon_collection.illumination
enabled: true
arguments:
level: 500
object_center: [250,250]
object_size: [15,15]
option: "elliptic"
- pyxel.models.photon_collection.illumination(detector, level, option='uniform', object_size=None, object_center=None, time_scale=1.0)[source]#
Generate photon uniformly over the entire array or over an elliptic or rectangular object.
- Parameters:
detector (
Detector
) – Pyxel Detector object.level (
float
) – Flux of photon per pixel.option (
str
) – A string indicating the type of illumination:uniform
: Uniformly fill the entire array with photon. (Default)elliptic
: Mask with elliptic object.rectangular
: Mask with rectangular object.
object_size (
list
ortuple
, optional) – List or tuple of length 2, integers defining the diameters of the elliptic or rectangular object in vertical and horizontal directions.object_center (
list
ortuple
, optional) – List or tuple of length 2, two integers (row and column number), defining the coordinates of the center of the elliptic or rectangular object.time_scale (
float
) – Time scale of the photon flux, default is 1 second. 0.001 would be ms.
Stripe pattern#
Photon → Photon
With this model you can add a two-dimensional square signal - a stripe pattern
to the Photon
array. User can specify amplitude with argument level
,
the period
of the square signal in unit of pixels and the angle
of stripes.
The period
should be a multiple of 2 and equal or larger than 2.
Argument startwith
is used to flip zero and non-zero values.
Example of the configuration file:
- name: stripe_pattern
func: pyxel.models.photon_collection.stripe_pattern
enabled: true
arguments:
level: 1000
period: 10
startwith: 0
angle: 5
- pyxel.models.photon_collection.stripe_pattern(detector, period=10, level=1.0, angle=0, startwith=0, time_scale=1.0)[source]#
Stripe pattern model.
- Parameters:
detector (
Detector
) – Detector object.period (
int
) – Period of the periodic pattern in pixels.level (
float
) – Amplitude of the periodic pattern.angle (
int
) – Angle of the pattern in degrees.startwith (
int
) – 1 to start with high level or 0 for 0.time_scale (
float
) – Time scale of the photon flux, default is 1 second. 0.001 would be ms.
Shot noise#
Photon → Photon
Use this model to add shot noise to the Photon
array.
By default (no arguments provided), the model uses the Poisson distribution (numpy.random.poisson
).
User can also set the argument type
to "normal"
for normal distribution (numpy.random.normal
).
As known, for large photon counts seed
.
Example of the configuration file:
- name: shot_noise
func: pyxel.models.photon_collection.shot_noise
enabled: true
arguments:
type: "poisson" # optional
Physical Optics Propagation in PYthon (POPPY)#
Note
This model operates with both multi-wavelength and monochromatic photons.
Photon → Photon
POPPY (Physical Optics Propagation in PYthon) model wrapper.
POPPY [10] simulated physical optical propagation including diffraction. It implements a flexible framework for modeling Fraunhofer and Fresnel diffraction and point spread function formation, particularly in the context of astronomical telescopes.
POPPY calculates the optical Point Spread Function of an optical system and applies the convolution.
It requires the Field of View (FOV) in fov_arcsec
) and the optical_system
as arguments.
By default, the model uses pixel_scale
in wavelength
in
The wavelength
input can either be a float for a monochromatic PSF or a tuple for a multi-wavelength PSF calculations.
Additionally, the ThinLens
optical parameter offers an optional argument reference_wavelength
, which, if provided,
overrides the input wavelength for a single float or calculates the middle wavelength for a range.
When apply_jitter
is set to true (default is false), pointing jitter will be applied using a Gaussian kernel to convolve
with the PSF. The width of the jitter kernel is defined by jitter sigma
in
Developed by: Marshall Perrin et al., STScI
Developed for: James Webb Space Telescope
Documentation: https://poppy-optics.readthedocs.io
Project link: spacetelescope/poppy
See details about POPPY Optical Element classes: https://poppy-optics.readthedocs.io/en/stable/available_optics.html
Supported optical elements:
CircularAperture
SquareAperture
RectangularAperture
HexagonAperture
MultiHexagonalAperture
ThinLens
SecondaryObscuration
ZernikeWFE
SineWaveWFE
Example of the configuration file:
- name: optical_psf
func: pyxel.models.photon_collection.optical_psf
enabled: true
arguments:
fov_arcsec: 5 # FOV in arcseconds
wavelength: 600 # wavelength in nanometer
apply_jitter: true
jitter_sigma: 0.5
optical_system:
- item: CircularAperture
radius: 3.0 # radius in meters
optical_system:
- item: CircularAperture
radius: 1.5 # radius in meters
- item: ThinLens
radius: 1.2 # radius in meters
nwaves: 1
reference_wavelength: 600 # wavelength in nanometer
- item: ZernikeWFE
radius: 0.8 # radius in meters
coefficients: [0.1e-6, 3.e-6, -3.e-6, 1.e-6, -7.e-7, 0.4e-6, -2.e-6]
aperture_stop: false
Note
You can find examples of this model in these Jupyter Notebooks from Pyxel Data:
- pyxel.models.photon_collection.optical_psf(detector, fov_arcsec, optical_system, wavelength=None, pixel_scale=None, apply_jitter=False, jitter_sigma=0.007, extract_psf=False)[source]#
Model function for poppy optics model: convolve photon array with psf.
- Parameters:
detector (
Detector
) – Pyxel Detector object.fov_arcsec (
float
) – Field Of View on detector plane in arcsec.optical_system (
list
ofdict
) – List of optical elements before detector with their specific arguments.wavelength (
Union[float
,tuple[float
,float]
,None]
) – Wavelength of incoming light in meters, default is None.pixel_scale (
float
,Optional
, default:None
) – Pixel scale of detector in arcsec/pix.apply_jitter (
bool
, default:False
) – Defines whether jitter should be applied, default is False.jitter_sigma (
float
) – Jitter sigma value in arcsec per axis, default is 0.007.extract_psf (
bool
, default:False
) – Copy the computed PSF into the data bucketdetector.data['/photon_collection/optical_psf/[name of the model]/psf']
Notes
For more information, you can find examples here:
Load PSF#
Photon → Photon
Load monochromatic PSF#
With this model you can load a Point Spread Function (PSF) from a file.
The model will convolve the Photon
array
inside the Detector
object with the loaded PSF, using the
astropy.convolution.convolve_fft
function.
Example of the configuration file:
- name: load_psf
func: pyxel.models.photon_collection.load_psf
enabled: true
arguments:
filename: "psf.npy"
normalize_kernel: true # optional
Note
You can find an example of this model used in this Jupyter Notebook Scene generation and projection from Pyxel Data.
- pyxel.models.photon_collection.load_psf(detector, filename, normalize_kernel=True)[source]#
Load a point spread function from file and convolve the photon array with the PSF.
- Parameters:
Notes
For more information, you can find an example here: Scene generation and projection.
Load multi-wavelength PSF#
With this model you can load a Point Spread Function (PSF) from a file containing wavelength information.
Currently, only .fits
files are a valid input.
The model will convolve the Photon
array
inside the Detector
object with the loaded PSF, using the
astropy.convolution.convolve_fft
function.
Example of the configuration file:
- name: load_wavelength_psf
func: pyxel.models.photon_collection.load_wavelength_psf
enabled: true
arguments:
filename: "data/psf.fits"
wavelength_col: "dim_0"
x_col: "dim_2"
y_col: "dim_1"
wavelength_table_name: "waves"
normalize_kernel: false # optional
- pyxel.models.photon_collection.load_wavelength_psf(detector, filename, wavelength_col, y_col, x_col, wavelength_table_name, normalize_kernel=True)[source]#
Read psf files depending on simulation and instrument parameters.
- Parameters:
detector (
Detector
) – Pyxel Detector object.filename (
Path
orstr
) – Input filename of the point spread function.wavelength_col (
str
) – Dimension name in the file that contains the wavelength information.y_col (
str
) – Dimension name in the file that contains the y information.x_col (
str
) – Dimension name in the file that contains the x information.wavelength_table_name (
str
) – Column name in the file that contains the wavelength information.normalize_kernel (
bool
) – Normalize kernel.
Wavelength dependence AIRS#
Note
This model is specific for the CMOS detector.
Photon → Photon
This model was specially developed for the ARIEL AIRS instrument. It generates the photon over the array according to a specific dispersion pattern loading the PSF from a file.
Example of the configuration file:
- name: wavelength_dependence_airs
func: pyxel.models.photon_collection.wavelength_dependence_airs
enabled: true
psf_filename: "data/CH1_big_cube_PSFs.fits"
target_filename: "data/target_flux_SED_00005.dat"
telescope_diameter_m1: 1.1 #m
telescope_diameter_m2: 0.7 #m
expand_factor: 18
time_scale: 1.0
- pyxel.models.photon_collection.wavelength_dependence_airs(detector, psf_filename, target_filename, telescope_diameter_m1, telescope_diameter_m2, expand_factor, time_scale=1.0)[source]#
Generate the photon over the array according to a specific dispersion pattern (ARIEL-AIRS).
- Parameters:
detector (
Detector
) – Pyxel Detector object.psf_filename (
string
) – The location and the filename where the PSFs are located.target_filename (
string
) – The location and the filename of the target file used in the simulation.telescope_diameter_m1 (
float
) – Diameter of the M1 mirror of the TA in m.telescope_diameter_m2 (
float
) – Diameter of the M2 mirror of the TA in m.expand_factor (
int
) – Expansion factor used.time_scale (
float
) – Time scale in seconds.