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/write 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

create_HDF5_image(imageName, numPixels, fn, kwargs, wavelength, saveNoiseImage=False, saveEquivImage=False, equivalentSignalType='', equivalentSignalUnit='', LinUnits='', seedval=0, fintp=None, fileHandle=None, noSpaces=False)[source]

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.

Parameters:

  • imageName (|) – the image name, used to form the filename.

  • numPixels (|) – number of pixels [row,col].

  • fn (|) – the generating function to be used to calculate the image.

  • kwargs (|) – kwargs to the passed to the generating function.

  • wavelength (|) – wavelength where photon rate calcs are done in [m]

  • equivalentSignalType (|) – type of the equivalent input scale (e.g., irradiance, temperature)

  • equivalentSignalUnit (|) – units of the equivalent scale (e.g., W/m2, K, lux)

  • LinUnits (|) – Lin units and definition separated with : (e.g., ‘W/(m2.sr)’, ‘q/(s.m2.sr)’)

  • seedval (|) – a seed for the photon noise generator

  • saveNoiseImage (|) – save the noisy image to HDF5 file

  • saveEquivImage (|) – save the equivalent image to HDF5 file

  • fintp (|) – interpolation function to map from radiance to equivalent unit,

  • 'original' (| if string)

  • hdf_raw() (then keep the original input image written by)

  • fileHandle (|) – create new file None, use otherwise

  • noSpaces (|) – if True replace all spaces and decimals in filename with ‘-’

Returns:

hdf5 filename or open file | : as a side effect an image file is written

Return type:

string/hdffile (string)

Raises:

| No exception is raised. –

Author: CJ Willers

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

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

Parameters:

  • imghd5 (|) – file to which image must be added

  • filename (|) – Raw file filename, data must be np.float64

  • rad_min (|) – additive minimum radiance value in the image, -1 to not use scaling

  • inputSize (|) – raw image size, number of rows,cols

  • outputSize (|) – size of the output image row,cols

  • rad_dynrange (|) – multiplicative radiance scale factor (max value), -1 to not use scaling

  • imgNum (|) – image number to be loaded from the image sequence

  • inputOrigin (|) – raw image row,col where the image must be extracted from

  • blocksize (|) – row,col blocksize in raw image to be averaged to single output pixel

  • sigma (|) – gaussian spatial filter kernel rms size in raw image pixels

Returns:

as a side effect a set of photon radiance image files are written

Return type:

nothing

Raises:

| No exception is raised. –

Author: CJ Willers

hdf_Uniform(imghd5, rad_dynrange)[source]

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

Parameters:

  • imghd5 (|) – file to which image must be added

  • rad_dynrange (|) – uniform/max radiance value

Returns:

as a side effect a set of photon radiance image files are written

Return type:

nothing

Raises:

| No exception is raised. –

Author: CJ Willers

hdf_disk_photon(imghd5, rad_min, rad_dynrange, fracdiameter, fracblur)[source]

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

Parameters:

  • imghd5 (|) – file to which image must be added

  • rad_min (|) – additive minimum radiance value in the image

  • rad_dynrange (|) – multiplicative radiance scale factor (max value)

  • fracdiameter (|) – diameter of the disk as fraction of minimum image size

  • fracblur (|) – blur of the disk as fraction of minimum image size

Returns:

as a side effect a set of photon radiance image files are written

Return type:

nothing

Raises:

| No exception is raised. –

Author: CJ Willers

hdf_stairs(imghd5, rad_min, rad_dynrange, steps, imtype)[source]

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

Parameters:

  • imghd5 (|) – file to which image must be added

  • rad_min (|) – additive minimum radiance value in the image

  • rad_dynrange (|) – radiance multiplicative scale factor (max value)

  • steps (|) – number of steps in the image

  • imtype (|) – string to define the type of image to be created [‘stairslin’,’stairslog’]

Returns:

as a side effect a set of photon radiance image files are written

Return type:

nothing

Raises:

| No exception is raised. –

Author: CJ Willers

assigncheck(hdf5, path, value)[source]

assign a value to a path, checking for prior existence

analyse_HDF5_image(imghd5, plotfile, gwidh=12, gheit=8)[source]

Summarise the image properties and statistics

Parameters:

  • imghd5 (|) – file to be analysed

  • plotfile (|) – filename for plot graphics

  • gwidh (|) – graph width in inches

  • gheit (|) – graph height in inches

Returns:

as a side effect a set properties are written and graphs created

Return type:

nothing

Raises:

| No exception is raised. –

Author: CJ Willers

analyse_HDF5_imageFile(hdffilename, gwidh=12, gheit=8)[source]

Summarise the image properties and statistics

Parameters:

  • imghd5 (|) – file to be analysed

  • gwidh (|) – graph width in inches

  • gheit (|) – graph height in inches

Returns:

as a side effect a set properties are written and graphs created

Return type:

nothing

Raises:

| No exception is raised. –

Author: CJ Willers

calcTemperatureEquivalent(wavelength, sysresp, tmin, tmax)[source]

Calc the interpolation functions between temperature and photon-rate radiance.

Returns two paired interp1d functions: - fintpLE: photon-rate radiance → temperature - fintpEL: temperature → photon-rate radiance

Parameters:

  • wavelength (|) – wavelength (um), passed directly to ryplanck.planck() with type='ql' which expects um.

  • sysresp (|) – system spectral response vector (same length as wavelength).

  • tmin (|) – minimum temperature [K] for the lookup table.

  • tmax (|) – maximum temperature [K] for the lookup table.

Returns:

pair of scipy interp1d functions; fintpLE maps photon-rate radiance | to temperature [K], fintpEL maps temperature [K] to photon-rate radiance.

Return type:

(fintpLE, fintpEL)

Raises:

| No exception is raised. –

Note

Wavelength units: wavelength must be in micrometres because it is passed directly to ryplanck.planck(type="ql") (planckql), which expects µm. This differs from calcLuxEquivalent, which expects wavelength in SI metres and converts to µm internally.

Author: CJ Willers

calcLuxEquivalent(wavelength, rad_min, rad_dynrange, units)[source]

Calc the interpolation function between lux and photon rate radiance.

Assuming single-wavelength colour, the specified wavelength is used to calculate the lux-equivalent for the given radiance input range. The returned interpolation function maps photon-rate radiance [q/(s.m²)] → lux, regardless of the units parameter. The units parameter only controls how rad_min and rad_dynrange are interpreted (W or q/s) when building the lookup table.

Parameters:

  • wavelength (|) – representative wavelength in SI metres (m).

  • rad_min (|) – minimum radiance value for the lookup table,

  • 'q' (| in watts [W/m²] when units does not contain)

  • in (or)

  • [q/ (| photon-rate units)

  • rad_dynrange (|) – radiance dynamic range (max − min) in the

  • rad_min. (| same units as)

  • units (|) – radiance unit string; if it contains ‘q’ the inputs

  • photon-rate (| are treated as)

  • watts. (otherwise as)

Returns:

scipy interp1d mapping photon-rate radiance → lux.

Return type:

fintp

Raises:

| No exception is raised. –

Note

Wavelength units inconsistency: this function expects wavelength in SI metres (it applies *1e6 internally to convert to µm for the photopic-response formula). This differs from calcTemperatureEquivalent, which passes wavelength directly to ryplanck.planck and therefore expects µm.

Author: CJ Willers