Mapping Image to NumPy Array Without Copying: The image is mapped directly, allowing modifications via the NumPy array without copying. This method is recommended whenever feasible.
Copying Image to NumPy Array and Mapping it to a Wrapped Image: The image is copied to a NumPy array. In this case, modifications to the array do not affect the original image buffer. However, the modified NumPy array can be mapped back to a new cvb.Image using cvb.WrappedImage.from_buffer, which still does not affect the original buffer.

Attention: As a user, it is important to manage the lifetime of objects carefully. It is recommended to use Python's with statement for all objects that hold resources with critical lifetimes, such as devices and images, to ensure proper resource management.

Example Program

Additionally to the code in this section, a sample program can be found in the CVB installation under %cvb%Tutorial\Image Manager\CVBpy\ImagePixelAccess. Alternatively, the example can be accessed via the following link: ImagePixelAccess

Mapping Image to NumPy Array Without Copying

Mapping an image to a NumPy array allows direct access to pixel data without creating a copy, making it an efficient approach whenever supported.

The following example demonstrates how to map an RGB image to a NumPy array:

Python

import cvb
 
width = 16
height = 4
 
# Create an RGB image.
with cvb.Image.from_pixel_format(width, height, cvb.PfncFormat.RGB8) as image: # (1)
 
    # Map the image to a NumPy array without copying (copy=False by default).
    np_array = cvb.as_array(image, copy=False)  # (2)
 
    # Verify if the mapping was successful.
    if np_array.flags["OWNDATA"]:  # (3)
        raise RuntimeError("cannot map to numpy array")
 
    # Modify pixel values (blue image).
    np_array[:,:,0] = 0 # (4)
    np_array[:,:,1] = 0
    np_array[:,:,2] = 255
 
    # Save image.
    image.save("blue_image.tif") # (5)

(1) An RGB 8-bit unsigned image is created. The with statement should be used to manage the image's lifetime automatically.
(2) The image is mapped to a NumPy array without copying, allowing direct access to pixel data.
(3) Check whether the mapping was successful; if OWNDATA is True, the image could not be mapped. In this case, the image has to be copied by setting copy=True in previous call (see the next example).
(4) Modify all pixel values in the NumPy array, which directly updates the underlying image data.
(5) Save the modified image to a file.

Copying Image to NumPy Array and Mapping it to a Wrapped Image

Whenever mapping the image is not possible, it must be copied instead. Note, when copying an image to a NumPy array, the pixel data is duplicated, meaning modifications to the NumPy array do not affect the original image data. To continue processing the modified image, the NumPy array can be mapped to a cvb.WrappedImage.

Python

image = ...
 
# Create a copy of the image data as a NumPy array.
np_array = cvb.as_array(image, copy=True)  # (1)
 
# Modify pixel values (green image). 
np_array[:,:,0] = 0  # (2)
np_array[:,:,1] = 255
np_array[:,:,2] = 0
 
# Since copy=True, modifications to the NumPy array do not affect the original image buffer.
# Therefore map the array to a WrappedImage:
with cvb.WrappedImage.from_buffer(np_array, cvb.BufferLayout.HeightWidthPlane) as image_out:  # (3)
    image_out.save("green_image.tif")  # (4)

(1) Copy the image data to a new NumPy array, being aware that modifications do not affect the original image.
(2) Modify the copied NumPy array; since the image was copied, the original data remains unchanged.
(3) Map the NumPy array to a cvb.WrappedImage without copying. Use cvb.BufferLayout.HeightWidthPlane as the layout for NumPy arrays. The with statement should be used for lifetime management.
(4) Save the modified image to a file.

Table of Contents

Example Program

Mapping Image to NumPy Array Without Copying

Copying Image to NumPy Array and Mapping it to a Wrapped Image