Utility functions

Colors

plotoptix.utils.make_color(c: Any, exposure: float = 1.0, gamma: float = 1.0, input_range: float = 1.0, extend_scalars: bool = True, channel_order: Union[ChannelOrder, str] = ChannelOrder.RGB) → ndarray[source]

Prepare 1D array of colors to account for the postprocessing corrections.

Colors of geometry objects or background in the ray traced image may look very different than expected from raw color values assigned at the scene initialization, if post-processing corrections are applied. This method applies inverse gamma and exposure corrections and returns RGB values resulting with desired colors in the image.

Input values range may be specified, so RGB can be provided as 0-255 values, for convenience.

The output array shape is (n, 3), where n is deduced from the input array. Single scalar value and values in 1D arrays are treated as a gray levels if extend_scalars=True.

Parameters

c (Any) – Target color values, array_like of any shape or single scalar value.
exposure (float, optional) – Exposure value applied in post-processing.
gamma (float, optional) – Gamma value applied in post-processing.
input_range (float, optional) – Range of the input color values.
extend_scalars (bool, optional) – Convert single scalar and 1D arrays to gray values encoded as RGB.
channel_order (ChannelOrder, optional) – Swap RGB to BGR and add aplha channel if necessary.

Returns

out – C-contiguous, float32 numpy array with RGB color values pre-calculated to account for post-processing corrections.

Return type

np.ndarray

plotoptix.utils.make_color_2d(c: Any, exposure: float = 1.0, gamma: float = 1.0, input_range: float = 1.0, extend_scalars: bool = True, channel_order: Union[ChannelOrder, str] = ChannelOrder.RGB, alpha: float = 1.0) → ndarray[source]

Prepare 2D array of colors to account for the postprocessing corrections.

Colors of geometry objects in the ray traced image may look very different than expected from raw color values assigned at objects initialization, if post-processing corrections are applied. This method applies inverse gamma and exposure corrections and returns RGB values resulting with desired colors in the image. Optionally, alpha channel may be added and filled with provided value.

Input values range may be specified, so RGB can be provided as e.g. 0-255 values, for convenience.

Input array shape should be (n, m), (n, m, 1), or (n, m, 3). The output array shape is (n, m, 3) or (n, m, 4). Single scalar values are treated as a gray levels if extend_scalars=True.

Parameters

c (Any) – Target color values, array_like of shape (n, m), (n, m, 1), or (n, m, 3).
exposure (float, optional) – Exposure value applied in post-processing.
gamma (float, optional) – Gamma value applied in post-processing.
input_range (float, optional) – Range of the input color values.
extend_scalars (bool, optional) – Convert single scalar values to gray levels encoded as RGB.
channel_order (ChannelOrder, optional) – Swap RGB to BGR and add aplha channel if necessary.
alpha (float, optional) – Value used to fill alpha channel, if necessary.

Returns

out – C-contiguous, float32 numpy array with RGB color values pre-calculated to account for post-processing corrections.

Return type

np.ndarray

plotoptix.utils.map_to_colors(x: Any, cm_name: str) → ndarray[source]

Map input variable to matplotlib color palette.

Scale variable x to the range <0; 1> and map it to RGB colors from matplotlib’s colormap with cm_name.

Parameters

x (array_like) – Input variable, array_like of any shape.
cm_name (string) – Matplotlib colormap name.

Returns

out – Numpy array with RGB color values mapped from the input array values. The output shape is x.shape + (3,).

Return type

np.ndarray

Image I/O

plotoptix.utils.get_image_meta(file_name: str) → Tuple[Optional[int], Optional[int], Optional[int], Optional[int]][source]

Get image metadata from file.

Read image file header and return width, height, samples per pixel and bits per sample values.

Parameters: file_name (string) – Image file name.
Returns: out – Image width, height, samples per pixel, bits per sample.
Return type: tuple (int, int, int, int)

plotoptix.utils.read_image(file_name: str, normalized: bool = False) → Optional[ndarray][source]

Read image from file.

Read image file into numpy array. Array shape is (height, width, 3(4)) for RGB(A) images and (height, width) for grayscale images. Image data type is preserved (numpy.uint8 or numpy.uint16) by default, or values are scaled to [0; 1] range and numpy.float32 type is returned, if normalized is set to True. Color channel order is preserved.

Tiff images are supported with size up to your memory limit (files >> GB are OK). Bmp, gif, jpg, and png formats are supported as well.

Parameters

file_name (string) – Image file name.
normalized (bool, optional) – Normalize values to [0; 1] range.

Returns

out – Image data.

Return type

np.ndarray

Noise generators

plotoptix.utils.simplex(pos: Any, noise: Optional[ndarray] = None) → ndarray[source]

Generate OpenSimplex noise.

Generate noise using OpenSimplex algorithm. 2D, 3D or 4D algorithm is used depending on the pos.shape[-1] value. Output array shape is pos.shape[:-1]. Noise can be generated ‘in place’ if optional noise array is provided (noise.shape has to match pos.shape[:-1]).

Parameters

pos (array_like) – Noise inputs, array_like of shape (n, ..., d), where d is 2, 3, or 4.
noise (np.ndarray, optional) – Array used to write the output noise (same as return value). New array is created if noise argument is not provided.

Returns

out – Noise generated from pos inputs.

Return type

np.ndarray

Miscellaneous

plotoptix.utils.get_gpu_architecture() → Optional[GpuArchitecture][source]

Get configured SM architecture.

Returns effective configuration of the PTX selection and -arch option of the shader compilation. Can verify matched SM architecture after constructing objects of plotoptix.NpOptiX and derived classes.

Returns: out – SM architecture or None if not recognized.
Return type: GpuArchitecture or None