Working with Images

Table of Contents

• Creating an image
  • Creating from an IDS peak genericAPI buffer
  • Using the image processing pipeline
  • Converting an existing IDS peak IPL image
  • Reading from a file
  • From pixel format and size
  • Creating from a raw buffer
• Setting an image region
• Handling of pixel formats
  • Converting an image to a different pixel format
  • Getting detailed information about pixel formats
• Accessing raw data

The IDS peak ICV library provides a flexible, language-independent image model that allows easy image creation, manipulation, and conversion across all supported programming languages. Each language binding offers APIs that integrate naturally with the language environment while maintaining consistency with the core image model.

This guide describes the primary ways to create and work with images using the IDS peak ICV library.

Creating an image

Images can be created in several ways, depending on your data source and application requirements. The following core methods are available in all supported programming languages:

Creating from an IDS peak genericAPI buffer

When an image is captured into a buffer using the IDS peak genericAPI, an ICV image can be created directly from that buffer by constructing an ImageView.

• C++

  // Get a buffer from IDS peak genericAPI
  std::shared_ptr<peak::core::Buffer> buffer = dataStream->WaitForFinishedBuffer(5'000);
  //
  // Create an ImageView from the buffer
  peak::core::ImageView imageView = buffer->ToImageView();
  //
  // Create an ICV image from the ImageView
  peak::icv::Image icvImage(imageView);

• Python

  # Get a buffer from IDS peak genericAPI
  buffer = data_stream.WaitForFinishedBuffer(ids_peak.Timeout(5000))
  #
  # Create an ImageView from the buffer
  image_view = buffer.ToImageView()
  #
  # Create an ICV image from the ImageView
  image = Image.create_from_image_view(image_view)

Using the image processing pipeline

Use this method when the buffer acquired via the IDS peak genericAPI contains raw camera data that requires processing before it can be used as a ready-to-use image. The Image Processing Pipeline performs essential steps such as debayering, color correction, and format conversion automatically.

This approach can also be used if auto features (e.g., auto exposure, auto gain, or auto white balance) are required.

• C++

  // Initialize pipeline with default settings
  peak::pipeline::DefaultPipeline pipeline;
  //
  // Get a buffer from IDS peak genericAPI
  std::shared_ptr<peak::core::Buffer> buffer = dataStream->WaitForFinishedBuffer(5'000);
  //
  // Process the image view constructed from an acquisition buffer
  peak::icv::Image image = pipeline.Process(buffer->ToImageView());

• Python

  # Initialize pipeline with default settings
  pipeline = DefaultPipeline()
   
  # Get a buffer from IDS peak genericAPI
  buffer = data_stream.WaitForFinishedBuffer(ids_peak.Timeout(5000))
   
  # Process the image view constructed from an acquisition buffer
  image = pipeline.process(buffer.ToImageView())

Converting an existing IDS peak IPL image

Convert an existing IDS peak IPL image into an IDS peak ICV image.

This method is primarily provided for backward compatibility with older code that uses the IPL image format. For new projects, it is recommended to directly work with the ICV image format.

• C++

  peak::ipl::Image IPLImage{ peak::ipl::PixelFormatName::Mono8, 640, 480 };
  peak::icv::Image image{ IPLImage };

• Python

  IPL_image = ids_peak_ipl.Image.CreateFromSize(ids_peak_ipl.PixelFormatName_Mono8, 640, 480)
  image = Image.create_from_ids_peak_ipl_image(IPL_image)

Reading from a file

Create an image by loading it from a supported file format.

• C++

  peak::icv::Image image{ "beads.png" };

• Python

  image = Image.create_from_file("beads.png")

From pixel format and size

Create a blank image by specifying the pixel format and the image dimensions (width × height).

• C++

  peak::icv::Image image{ peak::common::PixelFormat::Mono8, peak::common::Size(640, 480) };

• Python

  image = Image.create_from_pixel_format_and_size(PixelFormat.MONO_8, Size(640, 480))

Creating from a raw buffer

Construct an image directly from a raw byte buffer. The buffer must contain binary image data in a format supported by the IDS peak ICV library.

• C++

  std::array<uint8_t, 3> buffer{ 1, 2, 3 };
  peak::icv::Image image{ peak::common::PixelFormat::Mono8, buffer.data(), buffer.size(),
      peak::common::Size(3, 1) };

• Python

  buffer = np.array([[1, 2, 3]], dtype=PixelFormat.MONO_8.numpy_dtype)
  image = Image.create_from_np_array(PixelFormat.MONO_8, Size(3, 1), buffer)

Setting an image region

Each IDS peak ICV image includes a Region, which by default covers the entire image. When no custom region is specified, the entire image is processed. You can define a custom region to process only a specific part of the image.

The region can be of any shape, depending on the use case, and can be set dynamically at runtime.

If you need to revert to processing the entire image, you can reset the region back to its default full image coverage.

Additionally, the current region of an image can be queried programmatically.

• C++

  // Set region of any shape
  peak::icv::Region region{ std::vector<peak::common::Point>{ { 1, 2 }, { 3, 4 } } };
  image.SetRegion(region);
  // Query region
  auto imageRegion = image.GetRegion();
  // Reset region to full size
  image.ResetRegion();

• Python

  # Set region of any shape
  region = Region.create_from_points(np.array([[1, 2], [3, 4]]))
  image.region = region
  # Query region
  image_region = image.region
  # Reset region to full size
  image.reset_region()

<– TOTO: Add a section describing image meta data -->

Handling of pixel formats

Pixel formats define how pixel data is stored and interpreted. The IDS peak ICV library supports various pixel formats which are described in detail in Pixel and Pixel Format Specifications.

Converting an image to a different pixel format

To convert an image from one pixel format to another, use the appropriate conversion functions provided by the library. Check the documentation for each function to verify format compatibility and any conversion limitations.

• C++

  auto imageConverted = image.ConvertPixelFormat(peak::common::PixelFormat::Mono10);

• Python

  image_converted = image.convert_pixel_format(PixelFormat.MONO_10)

Getting detailed information about pixel formats

To correctly interpret pixel data, you can query details such as the format name, the bit depth, and the minimum and maximum possible channel values.

• C++

  // Create an object for the Mono8 pixel format
  peak::common::PixelFormatInfo info(peak::common::PixelFormat::Mono8);
  // Output pixel format information
  std::cout << info.GetName() << std::endl;                   // Output: Mono8
  std::cout << info.GetStorageBitsPerPixel() << std::endl;    // Output: 8
  std::cout << info.GetMaximumValuePerChannel() << std::endl; // Output: 255

• Python

  # Create an object for the Mono8 pixel format
  pixel_format = PixelFormat.MONO_8
  # Output pixel format information
  print(pixel_format.name)  # Output: MONO_8
  print(pixel_format.storage_bits_per_pixel)  # Output: 8
  print(pixel_format.maximum_value_per_channel)  # Output: 255

By using these methods, you obtain the information required to correctly interpret the image data and make informed decisions about image processing and format conversions.

Accessing raw data

If a transfer from IDS peak ICV to a third-party library is needed, you can get a pointer to raw data:

• C++

  const uint8_t* data = image.GetData();