vray.VRayImage

class vray.VRayImage

Bases: object

Contains raw image data in full 32-bit floating point format. Methods allow for some basic image manipulation and saving to popular 8-bit and 16-bit image file formats. Supports sequence, buffer and memoryview protocols.

Attributes

gamma

Gets/sets the output gamma for 8-bit images.

height

Pixel height of this object.

host

Host name that produced the image, if available.

width

Pixel width of this object.

x

Bucket horizontal (left) position.

y

Bucket vertical (top) position.

Methods

__init__(*args, **kwargs)

addColor(self, color)

Adds the color to the image with blending.

calculateDifference(self, image)

Calculates and returns a fast difference approximation between 2 images.

calculateWhiteBalanceMultiplier(self, type)

Returns a color multiplier to pass to mulColor function.

changeContrast(self, contrast)

Changes the image contrast by the specified value (-1, 1).

changeExposure(self, ev)

Increases the image exposure by the specified exposure value (EV).

changeGamma(self, gamma)

Applies the specified gamma correction to the image.

changeSRGB(self, apply)

Applies or removes an sRGB correction curve to/from this image.

compress(self, quality, preserveAlpha, …)

Compresses a V-Ray Image and returns its memoryview.

createFromBuffer(buffer, type, renderer)

Creates a new VRayImage from bmp, png or jpeg data contained in a buffer.

createFromRawData(buffer, type, width, height)

Creates a new VRayImage from raw pixel data.

draw(self, image, x, y, mode)

Draws a V-Ray Image over the current image.

getCropped(self, x, y, width, height)

Creates a new VRayImage from a region in the source one.

getCutIn(self, width, height)

Creates a new resized VRayImage preserving source aspect ratio, touching the specified rectangle from outside and cropping the new image to fit the rectangle.

getDownscaled(self, width, height)

Creates a new resized VRayImage.

getDownscaledCropped(self, x, y, srcWidth, …)

Creates a new resized VRayImage from a region in the source one.

getFitIn(self, width, height)

Creates a new resized VRayImage preserving source aspect ratio and touching the specified rectangle from inside.

getFitOut(self, width, height)

Creates a new resized VRayImage preserving source aspect ratio and touching the specified rectangle from outside.

getResized(self, width, height)

Creates a new resized VRayImage.

getResizedCropped(self, x, y, srcWidth, …)

Creates a new resized VRayImage from a region in the source one.

load(fileName)

Creates a new VRayImage from a file Supported formats: png, jpg, bmp, exr, hdr, sgi/rgb/rgba, pic, tiff, tga, psd, dds Positional (in this order) or keyword arguments:

loadSize(self, fileName)

Helper method to get image size from a file.

makeNegative(self)

Makes this a negative image.

save(self, file, quality, preserveAlpha, …)

Saves VRayImage to file.

toBitmapData(self, preserveAlpha, …)

Creates a buffer (memoryview) and fills it with the 8-bit bitmap data from this image (without the BMP headers that VRayImage.compress(type=’bmp’) includes).

toIntList(self, type)

Creates an IntList from the image data that can be directly assigned to RawBitmapBuffer.pixels
addColor(self, color: Color | AColor) → bool

Adds the color to the image with blending.

Positional arguments:

  • color, Color or AColor - the color to add to each pixel

Returns True on success.

calculateDifference(self, image: VRayImage) → float

Calculates and returns a fast difference approximation between 2 images. If the images have different resolutions FLT_MAX is returned. In your application, you can start with a difference threshold of around 2.0 as a rough estimate and then fine - tune the value.

Positional argument:

  • image, VRayImage - the source image

Returns number designating the difference between the 2 images.

calculateWhiteBalanceMultiplier(self, type: str | int) → AColor

Returns a color multiplier to pass to mulColor function.

Positional argument:

  • type, string or int:

    ‘Average’ (or 1) ‘WeightedAverage’ (or 2) ‘Highlights’ (or 3)

Returns AColor.

changeContrast(self, contrast: float) → bool

Changes the image contrast by the specified value (-1, 1).

Positional arguments:

  • contrast, float - normalized contrast change factor

Returns True on success.

changeExposure(self, ev: float) → bool

Increases the image exposure by the specified exposure value (EV).

Positional arguments:

  • ev, float - target EV difference

Returns True on success.

changeGamma(self, gamma: float) → bool

Applies the specified gamma correction to the image.

Positional arguments:

  • gamma, float - reciprocal of the exponent to apply to each pixel’s color

Returns True on success.

changeSRGB(self, apply: bool) → bool

Applies or removes an sRGB correction curve to/from this image. This is different from the gamma property. Positional arguments:

  • apply, boolean - True to apply or False to remove sRGB

Returns True on success.

compress(self, quality: int | None = None, preserveAlpha: bool | None = None, swapChannels: bool | None = None, type: str | None = None, renderer: Renderer | None = None) → memoryview

Compresses a V-Ray Image and returns its memoryview.

Positional (in this order) or keyword arguments, all optional:

  • quality, int - image quality value (1-9 for png, 1-99 for jpeg)

  • preserveAlpha, bool - whether to keep the alpha channel (PNG, BMP). Defaults to false

  • swapChannels, bool - by default RGBA, but if True swap to BGRA

  • type, string - file type

  • renderer, VRayRenderer - if passed, it will be used to output errors

createFromBuffer(buffer: SupportsBuffer, type: str, renderer: Renderer | None = None) → VRayImage

Creates a new VRayImage from bmp, png or jpeg data contained in a buffer.

Positional or keyword argument:

  • buffer, IntList, bytes, bytearray - a buffer containing image data.

  • type, string:

    ‘bmp’, ‘png’, ‘jpg’ or ‘jpeg’

  • renderer, VRayRenderer - optional; if passed, it will be used to output errors

Returns VRayImage.

createFromRawData(buffer: SupportsBuffer, type: str, width: int, height: int) → VRayImage

Creates a new VRayImage from raw pixel data. The data may come directly from RawBitmapBuffer.pixels, a bytearray or any buffer.

Positional or keyword argument:

  • buffer, IntList, bytes, bytearray - a buffer containing raw pixel data.

  • type, string or int:

    ‘bgra’ (or ‘bgra_byte’ or 0) (default) ‘bgr’ (or ‘bgr_byte’ or 4) ‘rgba16’ (or ‘rgba_16bit’ or 3) ‘rgba32’ (or ‘rgba_float’ or 1) - sRGB or gamma won’t be applied automatically

  • width, int

  • height, int

Returns VRayImage.

draw(self, image: VRayImage, x: int | None = None, y: int | None = None, mode: str | None = None) → bool

Draws a V-Ray Image over the current image.

Positional (in this order) or keyword arguments:

  • image, VRayImage - the source image

  • x, optional int - left pixel index from where to draw

  • y, optional int - top pixel index from where to draw

  • mode, optional string - drawing mode:

    • “copy” - overwrite destination image pixels with the source image pixels(default)

    • “blendFast” - alpha blend using only the source image alpha but keep the original destination image alpha unchanged.

Returns True on success.

getCropped(self, x: int, y: int, width: int, height: int) → VRayImage

Creates a new VRayImage from a region in the source one.

Positional (in this order) or keyword arguments, all obligatory:

  • x, int - left border pixel coordinate (in image space) of the crop region

  • y, int - top border pixel coordinate (in image space) of the crop region

  • width, int - pixel width of the crop region

  • height, int - pixel height of the crop region

getCutIn(self, width: int, height: int) → VRayImage

Creates a new resized VRayImage preserving source aspect ratio, touching the specified rectangle from outside and cropping the new image to fit the rectangle.

Positional (in this order) or keyword arguments, all obligatory:

  • width, int - target width in pixels

  • height, int - target height in pixels

getDownscaled(self, width: int, height: int) → VRayImage

Creates a new resized VRayImage.

Positional (in this order) or keyword arguments, all obligatory:

  • width, int - target width in pixels

  • height, int - target height in pixels

getDownscaledCropped(self, x: int, y: int, srcWidth: int, srcHeight: int, dstWidth: int, dstHeight: int) → VRayImage

Creates a new resized VRayImage from a region in the source one.

Positional (in this order) or keyword arguments, all obligatory:

  • x, int - left border pixel coordinate (in image space) of the croped source region

  • y, int - top border pixel coordinate (in image space) of the croped source region

  • srcWidth, int - pixel width of the cropped source region

  • srcHeight, int - pixel height of the croped source region

  • dstWidth, int - target width in pixels

  • dstHeight, int - target height in pixels

getFitIn(self, width: int, height: int) → VRayImage

Creates a new resized VRayImage preserving source aspect ratio and touching the specified rectangle from inside.

Positional (in this order) or keyword arguments, all obligatory:

  • width, int - target width in pixels

  • height, int - target height in pixels

getFitOut(self, width: int, height: int) → VRayImage

Creates a new resized VRayImage preserving source aspect ratio and touching the specified rectangle from outside.

Positional (in this order) or keyword arguments, all obligatory:

  • width, int - target width in pixels

  • height, int - target height in pixels

getResized(self, width: int, height: int) → VRayImage

Creates a new resized VRayImage.

Positional (in this order) or keyword arguments, all obligatory:

  • width, int - target width in pixels

  • height, int - target height in pixels

getResizedCropped(self, x: int, y: int, srcWidth: int, srcHeight: int, dstWidth: int, dstHeight: int) → VRayImage

Creates a new resized VRayImage from a region in the source one.

Positional (in this order) or keyword arguments, all obligatory:

  • x, int - left border pixel coordinate (in image space) of the croped source region

  • y, int - top border pixel coordinate (in image space) of the croped source region

  • srcWidth, int - pixel width of the cropped source region

  • srcHeight, int - pixel height of the croped source region

  • dstWidth, int - target width in pixels

  • dstHeight, int - target height in pixels

load(fileName: str) → VRayImage

Creates a new VRayImage from a file Supported formats: png, jpg, bmp, exr, hdr, sgi/rgb/rgba, pic, tiff, tga, psd, dds Positional (in this order) or keyword arguments:

  • fileName, string - relative or absolute file path and name

Returns a VRayImage.

static loadSize(self, fileName: str) → tuple[int, int]

Helper method to get image size from a file. Supported formats: png, jpg, bmp, exr, hdr, sgi/rgb/rgba, pic, tiff, tga, psd, dds Positional (in this order) or keyword arguments:

  • fileName, string - relative or absolute file path and name

Returns the image size as a tuple.

makeNegative(self) → bool

Makes this a negative image. In other words, replaces colors with their complementary colors.

save(self, file: str, quality: int | None = None, preserveAlpha: bool | None = None, swapChannels: bool | None = None, type: str | None = None, renderer: Renderer | None = None) → bool

Saves VRayImage to file. Format is deduced from the extension.

Positional (in this order) or keyword arguments, all optional:

  • fileName, string - relative or absolute file path and name

  • quality, int - image quality value (1-9 for png, 1-99 for jpeg)

  • preserveAlpha, bool - whether to keep the alpha channel (PNG, BMP). Defaults to true

  • swapChannels, bool - by default RGBA, but if True swap to BGRA

  • type, string - file type

  • renderer, VRayRenderer - if passed, it will be used to output errors

Returns True on success.

toBitmapData(self, preserveAlpha: bool | None = None, swapChannels: bool | None = None, reverseY: bool | None = None, stride: int | None = None, alphaValue: int | None = None) → memoryview

Creates a buffer (memoryview) and fills it with the 8-bit bitmap data from this image (without the BMP headers that VRayImage.compress(type=’bmp’) includes).

Positional (in this order) or keyword arguments, all optional:

  • preserveAlpha, bool - False: BGR/RGB (bytes_per_pixel = 3), True: BGRA/RGBA (bytes_per_pixel = 4). Defaults to False

  • swapChannels, bool - False: BGR(A) order, True: BRGB(A) order. Defaults to False

  • reverseY, bool - False: fill top-bottom bitmap, True: fill bottom-top bitmap. Defaults to False

  • stride, int - the byte offset between the beginning of two consecutive rows of the output bitmap:

    if (stride > 0) use max(stride, width*bytes_per_pixel) if (stride== 0) use width*bytes_per_pixel rounded up to the smallest factor of 4 (this is the default for BMP) if (stride < 0) use width*bytes_per_pixel rounded up to the smallest factor of -stride; -stride must be a power of 2

  • alphaValue, int - force the alpha channel to the given value in the [0, 255] range; forces BGRA/RGBA format

Returns memoryview.

toIntList(self, type: str | int) → IntList

Creates an IntList from the image data that can be directly assigned to RawBitmapBuffer.pixels

Positional or keyword argument:

  • type, string or int:

    ‘bgra’ (or ‘bgra_byte’ or 0) (default) ‘bgr’ (or ‘bgr_byte’ or 4) ‘rgba16’ (or ‘rgba_16bit’ or 3) ‘rgba32’ (or ‘rgba_float’ or 1) - sRGB or gamma won’t be applied automatically

Returns IntList.

gamma

Gets/sets the output gamma for 8-bit images. Affects the methods compress() and save()

height

Pixel height of this object.

host

Host name that produced the image, if available.

width

Pixel width of this object.

x

Bucket horizontal (left) position.

y

Bucket vertical (top) position.