6.7. tracer.image Submodule¶

6.7.1. tracer.base_image¶

class optrace.tracer.image.base_image.BaseImage(data, s=None, extent=None, projection=None, quantity='', limit=None, **kwargs)¶

Init an Image object. Parent class of ScalarImage, GrayscaleImage and RGBImage

Image dimensions should be either provided by the s or extent parameter.

When parameter ‘data’ is provided as array, element [0, 0] defines the lower left corner (negative x, negative y)

Parameters:

image – Three-dimensional numpy array with data range [0, 1] or a file path to an image
s (list | ndarray) – image side lengths, x-dimension first
extent (list | ndarray) – image extent in the form [xs, xe, ys, ye]
quantity (str) – name of the stored image quantity/property
limit (float) – resolution limit information. Single value in micrometers.
kwargs – additional keyword arguments for the BaseClass
data (ndarray | str)
projection (str)

profile(x=None, y=None)¶

Create an image profile. Only specify one of parameters x or y.

There is no interpolation, the nearest pixel value is chosen (nearest neighbor ‘interpolation’)

Parameters:

x (float) – x-value for the profile
y (float) – y-value for the profile

Returns:

bin edge array, list of image cuts (one for linear images, three for rgb images)

Return type:

tuple[ndarray, list[ndarray]]

save(path, params=[], flip=False)¶

Save the image data as image file. The image is rescaled (and therefore interpolated) so we have square pixels before the export.

Parameters:

path (str) – path with file ending to save the image to
params (list) – additional parameters for cv2.imwrite, see cv ImwriteFlags
flip (bool) – if image should be flipped (rotated 180 degrees)

Return type:

None

property Apx: float¶: area per pixel in mm^2

property data: ndarray¶: image data array

property s: list[float, float]¶: image side lengths, x-dimension first

property shape: tuple[int, int, int]¶: data shape of the image. y-dimension first

6.7.2. tracer.scalar_image¶

class optrace.tracer.image.scalar_image.ScalarImage(data, s=None, extent=None, **kwargs)¶

Init a ScalarImage object.

When provided as numpy array, the image data must be non-negative and have only one channel (simple 2D array). When provided as image path, the image must have no color information.

When parameter ‘data’ is provided as array, element [0, 0] defines the lower left corner (negative x, negative y)

Parameters:

data (ndarray | str) – Image filepath or two dimensional numpy array.
s (list | ndarray) – image side lengths, x-dimension first
extent (list | ndarray) – image extent in the form [xs, xe, ys, ye]
kwargs – additional keyword arguments for the BaseImage and BaseClass class. These include the limit and quantity option.

6.7.3. tracer.grayscale_image¶

class optrace.tracer.image.grayscale_image.GrayscaleImage(data, s=None, extent=None, **kwargs)¶

Init a GrayscaleImage object. Subclass of ScalarImage, but communicates an image in sRGB grayscale with gamma compression.

When parameter ‘data’ is provided as array, element [0, 0] defines the lower left corner (negative x, negative y)

Parameters:

data (ndarray | str) – Image filepath or two dimensional numpy array.
s (list | ndarray) – image side lengths, x-dimension first
extent (list | ndarray) – image extent in the form [xs, xe, ys, ye]
kwargs – additional keyword arguments for the BaseImage and BaseClass class. These include the limit and quantity option.

to_rgb_image()¶

Create an RGBImage from this object. :return: RGBImage

Return type:: RGBImage

6.7.4. tracer.render_image¶

class optrace.tracer.image.render_image.RenderImage(extent, projection=None, **kwargs)¶

Init an RenderImage object. This class is used to calculate and hold an Image consisting of the channels X, Y, Z, Illuminance and Irradiance.

Parameters:

extent (list | ndarray) – image extent in the form [xs, xe, ys, ye]
projection (str) – string containing information about the sphere projection method, if any
kwargs – additional keyword arguments for the BaseClass, like for instance desc and long_desc

static load(path)¶

Load a saved RenderImage (.npz) from disk.

Parameters:: path (str) – path of the RenderImage archive
Returns:: a saved image object from numpy archive to a image object
Return type:: Self

get(mode, N=315, L_th=0, chroma_scale=None)¶

Get a converted image with mode ‘mode’. Must be one of RenderImage.image_modes.

N describes the pixel count (of the smaller side) to which the image is rescaled to. N should be one of RenderImage.SIZES, but the nearest value is automatically selected. Rescaling is done by joining bins, so there is no interpolation.

Depending on the image mode, the returned image is an RGBImage with three channels or a ScalarImage with one channel.

Parameters L_th and chroma_scale are only needed for mode=’sRGB (Perceptual RI)’, see function color.xyz_to_srgb_linear for more details.

Parameters:

mode (str) – one of RenderImage.image_modes
N (int) – pixel count of smaller side, nearest of RenderImage.SIZES is automatically selected
L_th (float) – lightness threshold for mode “sRGB (Perceptual RI)”
chroma_scale (float) – chroma_scale option for mode “sRGB (Perceptual RI)”

Returns:

RGBImage or ScalarImage, depending on ‘mode’

Return type:

RGBImage | ScalarImage

has_image()¶

Check Image object contains an calculated image.

Return type:: bool

luminous_power()¶

Returns:: calculated total image luminous power
Return type:: float

power()¶

Returns:: calculated total image power
Return type:: float

render(p=None, w=None, wl=None, limit=None, _dont_filter=False)¶

Creates an pixel image from ray positions on the detector.

Parameters:

p (ndarray) – ray position matrix, xyz components in columns, (numpy 2D array)
w (ndarray) – ray weight array (numpy 1D array)
wl (ndarray) – ray wavelength array (numpy 1D array)
limit (float) – rayleigh limit, used to approximate wave optics using a airy disc kernel
_dont_filter (bool)

Return type:

None

save(path)¶

Save the RenderImage as .npz archive. Files are overridden. Throws IOError if the file could not been saved.

Parameters:: path (str) – path to save to
Return type:: None

property Apx: float¶: area per pixel

EPS: float = 1e-09¶: Used for minimal extent

K: float = 683.0¶: Luminous Efficacy

MAX_IMAGE_RATIO: int = 5¶: maximum ratio of image side lengths. Images with ratios beyond will be corrected

MAX_IMAGE_SIDE: int = 945¶: maximum size of smaller image side in pixels

SIZES: list[int] = [1, 3, 5, 7, 9, 15, 21, 27, 35, 45, 63, 105, 135, 189, 315, 945]¶: valid image side lengths (smallest side)

property data: ndarray¶: image data array

extent: ndarray¶: the image extent as [x0, x1, y0, y1] array

image_modes: list[str] = ['sRGB (Absolute RI)', 'sRGB (Perceptual RI)', 'Outside sRGB Gamut', 'Irradiance', 'Illuminance', 'Lightness (CIELUV)', 'Hue (CIELUV)', 'Chroma (CIELUV)', 'Saturation (CIELUV)']¶: possible display modes for the RenderImage

property limit: float¶: the resolution limit the RenderImage was rendered with

property s: list[float, float]¶: geometric side lengths of image in direction (x, y)

property shape: tuple[int, int]¶: data image shape (y, x)

6.7.5. tracer.rgb_image¶

class optrace.tracer.image.rgb_image.RGBImage(data, s=None, extent=None, **kwargs)¶

Init a RGBImage object.

When provided as numpy array, the image data must have values in range [0, 1] and three channels in the third dimension. When provided as image path, the image is loaded with three channels regardless of colorspace.

When parameter ‘data’ is provided as array, element [0, 0] defines the lower left corner (negative x, negative y)

Parameters:

data (ndarray | str) – Image filepath or three dimensional numpy array.
s (list | ndarray) – image side lengths, x-dimension first
extent (list | ndarray) – image extent in the form [xs, xe, ys, ye]
kwargs – additional keyword arguments for the BaseImage and BaseClass class. These include the limit and quantity option.

to_grayscale_image()¶

Create an GrayscaleImage from this object. Channel values are averaged.

Returns:: GrayscaleImage
Return type:: GrayscaleImage