Target Radiance Image Generator (rytarggen)

Overview

This module provides a simple model for an optical target image radiance calculator, given the radiometric sensor characteristics and the target spatial temperature and emissivity distribution. The calculator accounts for

  1. the sensor spectral band
  2. target self-emission
  3. target reflected sunlight.

The model does not account for reflected ambient radiance.

HDF5 File

The Python implementation of the model uses an HDF5 file to capture the input and output data for record keeping or subsequent analysis. HDF5 files provide for hierarchical data structures and easy read/save to disk. See the file hdf5-as-data-format.md ([hdf5asdataformat]) in the pyradi root directory for more detail.

Input images are written to and read from HDF5 files as well. These files store the image as well as the images’ dimensional scaling in the focal plane. The intent is to later create test targets with specific spatial frequencies in these files.

Code Overview

For more detail see the documentation at

http://nelisw.github.io/pyradi-docs/_build/html/index.html,
http://nelisw.github.io/pyradi-docs/_build/html/rytarggen.html, or
pyradi/doc/rytarggen.rst

Module functions

pyradi.rytarggen.create_HDF5_image(imageName, numPixels, fn, kwargs, wavelength, saveNoiseImage=False, saveEquivImage=False, equivalentSignalType='', equivalentSignalUnit='', LinUnits='', seedval=0, fintp=None, fileHandle=None, noSpaces=False)

This routine serves as calling function to a generating function to create images. This function expects that the calling function will return photon rate images, irrespective of the units of the min/max values used to create the image. Each generating function creates an image of a different type, taking as input radiant, photon rate, temperature or some other unit, as coded in the generating function.

if fileHandle is None, the file is created anew, if fileHandle is not None, use as existing file handle

This calling function sets up the image and writes common information and then calls the generating function of add the specific image type with radiometric units required. The calling function and its arguments must be given as arguments on this functions argument list.

The image file is in HDF5 format, containing the * input parameters to the image creation process * the image in photon rate units without photon noise * the image in photon rate units with photon noise * the image in some equivalent input unit radiant, photometric or photon rate units.

The general procedure in the generating function is to convert the radiance input values in units [W/m2] or [q/m2.s)] to photon rate radiance in units [q/m2.s)] by converting by one photon’s energy at the stated wavelength by Q_p=\frac{h\cdot c}{\lambda}, where \lambda is wavelength, h is Planck’s constant and c is the speed of light. The conversion is done at a single wavelength, which is not very accurate. The better procedure is to create the photon rate image directly using a spectral integral.

The following minimum HDF5 entries are required by pyradi.rystare:

'image/imageName' (string): the image name
'image/PhotonRateRadianceNoNoise' np.array[M,N]: a float array with the image pixel values no noise
'image/PhotonRateRadiance' np.array[M,N]: a float array with the image pixel values with noise
'image/imageSizePixels': ([int, int]): number of pixels [row,col]
'image/imageFilename' (string): the image file name
'image/wavelength' (float): where photon rate calcs are done um
'image/imageSizeRows' (int): the number of image rows
'image/imageSizeCols' (int): the number of image cols
'image/imageSizeDiagonal' (float): the FPA diagonal size in mm
'image/equivalentSignal' (float): the equivalent input signal, e.g. temperature or lux (optional)
'image/irradianceWatts' (float): the exitance in the image W/m2 (optional)
'image/temperature' (float): the maximum target temperature in the image K (optional)

A few minimum entries are required, but you can add any information you wish to the generaring function, by adding the additional information to the generating function’s kwargs.

Args:
imageName (string/hdffile): the image name, used to form the filename.
numPixels ([int, int]): number of pixels [row,col].
fn (Python function): the generating function to be used to calculate the image.
kwargs (dictionary): kwargs to the passed to the generating function.
wavelength (float): wavelength where photon rate calcs are done in [m]
equivalentSignalType (str): type of the equivalent input scale (e.g., irradiance, temperature)
equivalentSignalUnit (str): units of the equivalent scale (e.g., W/m2, K, lux)
LinUnits (str): Lin units and definition separated with : (e.g., ‘W/(m2.sr)’, ‘q/(s.m2.sr)’)
seedval (int): a seed for the photon noise generator
saveNoiseImage (bool): save the noisy image to HDF5 file
saveEquivImage (bool): save the equivalent image to HDF5 file
fintp (function or str): interpolation function to map from radiance to equivalent unit,
if string ‘original’, then keep the original input image written by hdf_raw()
fileHandle (filehandle): create new file None, use otherwise
noSpaces (bool): if True replace all spaces and decimals in filename with ‘-‘
Returns:
string/hdffile (string): hdf5 filename or open file
: as a side effect an image file is written
Raises:
No exception is raised.

Author: CJ Willers

pyradi.rytarggen.hdf_Raw(imghd5, filename, inputSize, outputSize, rad_min=-1, rad_dynrange=-1, imgNum=0, inputOrigin=[0, 0], blocksize=[1, 1], sigma=0)

A generating function to create a photon rate image from raw image.

The output image is extracted from the raw image, with blocks of raw image pixels averaged to single output image pixels. inputOrigin (lowest row,col values) defines from where in the raw input image the slicing takes place. blocksize defines how many raw image pixels must be averaged/aggregated together to define a single output image pixel, resolution is lowered by this factor. sigma is the kernel size to be used in scipy.filters.gaussian_filter.

The subsampled image will be rescaled to rad_min + rad_dynrange.

The raw image sequence must be of type np.float64 with no header or footer.

The function accepts radiant or photon rate minimum and dynamic range units. The equivalent image value is expressed as in the same units as the output image

This function must be called from rytarggen.create_HDF5_image

Args:
imghd5 (handle to hdf5 file): file to which image must be added
filename (string): Raw file filename, data must be np.float64
rad_min (float): additive minimum radiance value in the image, -1 to not use scaling
inputSize ([int,int]): raw image size, number of rows,cols
outputSize ([int,int]): size of the output image row,cols
rad_dynrange (float): multiplicative radiance scale factor (max value), -1 to not use scaling
imgNum (int): image number to be loaded from the image sequence
inputOrigin ([int,int]): raw image row,col where the image must be extracted from
blocksize ([int,int]): row,col blocksize in raw image to be averaged to single output pixel
sigma (float): gaussian spatial filter kernel rms size in raw image pixels
Returns:
nothing: as a side effect a set of photon radiance image files are written
Raises:
No exception is raised.

Author: CJ Willers

pyradi.rytarggen.hdf_Uniform(imghd5, rad_dynrange)

A generating function to create a uniform photon rate image. The uniform value in the image will have a value of rad_dynrange. The equivalent image value is expressed as in the same units as the input

The function accepts radiant or photon rate dynamic range units inputs.

This function must be called from rytarggen.create_HDF5_image

Args:
imghd5 (handle to hdf5 file): file to which image must be added
rad_dynrange (float): uniform/max radiance value
Returns:
nothing: as a side effect a set of photon radiance image files are written
Raises:
No exception is raised.

Author: CJ Willers

pyradi.rytarggen.hdf_disk_photon(imghd5, rad_min, rad_dynrange, fracdiameter, fracblur)

A generating function to create an image with illuminated circle with blurred boundaries.

The function accepts radiance radiant or photon rate minimum and dynamic range units. The equivalent image value is expressed as in the same units as the input

This function must be called from rytarggen.create_HDF5_image

Args:
imghd5 (handle to hdf5 file): file to which image must be added
rad_min (float): additive minimum radiance value in the image
rad_dynrange (float): multiplicative radiance scale factor (max value)
fracdiameter (float): diameter of the disk as fraction of minimum image size
fracblur (float): blur of the disk as fraction of minimum image size
Returns:
nothing: as a side effect a set of photon radiance image files are written
Raises:
No exception is raised.

Author: CJ Willers

pyradi.rytarggen.hdf_stairs(imghd5, rad_min, rad_dynrange, steps, imtype)

A generating function to create a staircase image, with log/linear and prescribed step count.

The increment along stairs can be linear or logarithmic.

The function accepts radiance radiant or photon rate minimum and dynamic range units. The equivalent image value is expressed as in lux units.

This function must be called from rytarggen.create_HDF5_image

Args:
imghd5 (handle to hdf5 file): file to which image must be added
rad_min (float): additive minimum radiance value in the image
rad_dynrange (float): radiance multiplicative scale factor (max value)
steps (int): number of steps in the image
imtype (string): string to define the type of image to be created [‘stairslin’,’stairslog’]
Returns:
nothing: as a side effect a set of photon radiance image files are written
Raises:
No exception is raised.

Author: CJ Willers

[hdf5asdataformat]https://github.com/NelisW/pyradi/blob/master/pyradi/hdf5-as-data-format.md