Mainpage

Introduction

IDS peak IPL (Image Processing Library) is an object-oriented C++ library that provides special functionality for processing image data. The IDS peak IPL can be used, for example, to convert raw bayer images from the camera that were captured via the IDS peak genericAPI into color (debayering).

Shallow copy (since 1.8)

All IDS peak IPL classes support shallow copying. Copying increases the internal reference count of an instance and deleting decreases it. If all object referencing the same instance are destroyed, the instance gets destroyed too. Changing values on one object, also changes the value on the underlying instance, which gets reflected on all objects referencing the same instance.

Note

To create a deep copy of a peak::ipl::Image, call peak::ipl::Image::Clone, resulting in a new instance for an existing image.

Static or Dynamic Loading

By default, this library is linked into the user program, therefore is loaded statically at program start. Instead, it can also be loaded dynamically, when the first library function is called. To use this feature, enable the CMake option PEAK_IPL_DYNAMIC_LOADING or set the #define PEAK_IPL_DYNAMIC_LOADING before including any of the libraries files.

Knowledge Base

Packed pixel format handling

The packed pixel formats, denoted by a p in their name, cannot be used by the majority of functions in the library. They must be unpacked to their unpacked counterpart first. So for example, the PixelFormat peak::ipl::PixelFormatName::Mono10p has to be unpacked first to its counterpart peak::ipl::PixelFormatName::Mono10 (note the missing p here) to be used by e.g. the Gain class. So the correct handling if the packed image already exists with the variable name packedImage is as follows:

// unpack the packedImage which uses Mono10p to the unpacked PixelFormat Mono10
auto unpackedImage = packedImage.ConvertTo(peak::ipl::PixelFormatName::Mono10);
 
// apply gain on the unpacked image
peak::ipl::Gain gain{};
gain.SetMasterGainValue(2.5);
gain.ProcessInPlace(unpackedImage);

or using the Converter class for better performance:

// preallocate converter for Mono10p to Mono10 conversion. Only needed once per format combination.
peak::ipl::ImageConverter converter{};
converter.PreAllocateConversion(peak::ipl::PixelFormatName::Mono10p, peak::ipl::PixelFormatName::Mono10, packedImage.Width(), packedImage.Height())
 
// unpack the image to the unpacked PixelFormat
auto unpackedImage = converter.Convert(packedImage, peak::ipl::PixelFormatName::BayerBG10);
 
// apply gain on the unpacked image
peak::ipl::Gain gain{};
gain.SetMasterGainValue(2.5);
gain.ProcessInPlace(unpackedImage);

C# / .NET

For Windows, there is also a .NET version of the library.

To use it in a C# project, add a reference to the ids_peak_ipl_dotnet.dll to the project.

Before starting your application, make sure that the DLL-Loader can find all required libraries. This means that ids_peak_ipl_dotnet.dll, ids_peak_ipl_dotnet_interface.dll and ids_peak_ipl.dll are located next to your application binary or that the directory where they are located is added to the DLL-Loader's search directories. To add their directory to the DLL-Loader's search directories, you could simply append their directory to the environment variable Path:

• PowerShell

  $env:Path="$env:Path;<Installation-Directory-Of-ids_peak_ipl.dll>"
  $env:Path="$env:Path;<Installation-Directory-Of-ids_peak_ipl_dotnet.dll>"
  # Then start your application

• CMD

  set Path=%Path%;<Installation-Directory-Of-ids_peak_ipl.dll>
  set Path=%Path%;<Installation-Directory-Of-ids_peak_ipl_dotnet.dll>
  REM Then start your application

The IDS peak IPL .NET works much like the IDS peak IPL C++. The same principles, class and method names apply.

Python

Prerequisites

To use IDS peak IPL in Python, the ids_peak_ipl package can be installed directly from PyPI via pip, Python's package manager:

pip install ids_peak_ipl

Note

To be able to install the Python wheels on Linux, pip must be installed in version 20.3 or greater. Otherwise pip will detect the wheel as "not supported on this platform".

Offline Installation

In case of an offline installation, there is a separate Python wheel for each supported Python version and CPU architecture. A Python wheel is a package file (with .whl file ending) which can be installed via pip, Python's package manager. Just call pip install <Path-To-Python-Wheel> to install your chosen Python wheel. The respective .whl file can be obtained from the package's PyPI project page under Download files.

While pip will inform you about missing packages and their version requirements, contrary to the online installation, you need to manually resolve dependencies and respect the correct order of installation.

Import

To finally use IDS peak IPL in your Python script, just add import ids_peak_ipl.ids_peak_ipl or import ids_peak_ipl.ids_peak_ipl as some_alias at the top of your Python script. The latter should be preferred.

Comparison to the C++ API

The Python API works much like the C++ API. Nearly the same principles, class and method names apply.

There are only a few differences between the C++ API and the Python API. The most important ones are listed here.

Naming of Enumeration Values

Since Python had no native concept of enumeration types, the values are mapped to individual constants. A rule of thumb is that each scope resolution operator :: in C++ is replaced with an underscore in Python:

• C++

  const auto pixelFormatName = peak::ipl::PixelFormatName::Mono8;
  std::cout << peak::ipl::ToString(pixelFormatName) << '\n';

• Python

  pixel_format_name = ids_peak_ipl.PixelFormatName_Mono8
  print(ids_peak_ipl.PixelFormatNameEnumEntryToString(pixel_format_name))

Image Creation

While images are created directly using the constructor of peak::ipl::Image in C++:

• C++

  const auto width = size_t{ 1 };
  const auto height = size_t{ 1 };
  auto imageFromSize = peak::ipl::Image{
      peak::ipl::PixelFormatName::Mono8, width, height };
   
  // buffer is an instance of IDS peak genericAPI's class Buffer
  auto imageFromSizeAndBuffer = peak::ipl::Image{
      buffer.PixelFormat(), buffer.BasePtr(),
      buffer.Size(), buffer.Width(), buffer.Height() };

Helper functions are the preferred way to create images in Python, although it is possible to use the constructor directly, it is less convenient.

• Python

  width = 1
  height = 1
  image_from_size = ids_peak_ipl.Image.CreateFromSize(
      ids_peak_ipl.PixelFormatName_Mono8, width, height)
   
  # buffer is an instance of IDS peak genericAPI's class Buffer
  image_from_size_and_buffer = ids_peak_ipl.Image.CreateFromSizeAndBuffer(
      buffer.PixelFormat(),
      buffer.BasePtr(),
      buffer.Size(),
      buffer.Width(),
      buffer.Height())
   
  numpy_array = numpy.array([[10, 20, 30]], dtype=numpy.uint8)
  image_from_size_and_python_buffer = ids_peak_ipl.Image.CreateFromSizeAndPythonBuffer(
      ids_peak_ipl.PixelFormatName_RGB8, numpy_array, width, height)
  byte_array = bytearray([255, 10, 128])
  image_from_size_and_python_buffer = ids_peak_ipl.Image.CreateFromSizeAndPythonBuffer(
      ids_peak_ipl.PixelFormatName_RGB8,byte_array, width, height)