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

Prerequisites

To use IDS peak IPL in dotnet, the IDSImaging.Peak.IPL package can be installed directly from NuGet via dotnet:

dotnet add package IDSImaging.Peak.IPL

The package targets .NET Standard 2.0, making it compatible with:

• .NET Framework 4.6.1 and later
• .NET 5 and later

Note

A separate installation of the runtime setup is required. This provides the necessary Transport Layer (TL) components for communicating with the camera.

Build Instructions

The IDSImaging.Peak.IPL relies on native (unmanaged) DLLs that are distributed inside the referenced NuGet packages.

Because native binaries are involved, you must specify the target architecture via -p:Platform=<arch> when building. This ensures that your application is built for an architecture that can correctly load the required native libraries.

If no RuntimeIdentifier (-r) is specified, all available native runtimes from the packages will be copied to your build output. This would normally maximize compatibility but increase the application size. However, when the Platform parameter is specified, other architectures are not supported (except for x86 on x64).

You may optionally specify -r <rid> to reduce the size of the build output by including only the native libraries for a single runtime.

.NET (modern, SDK-style)

Required (correct architecture selection):

dotnet build -p:Platform=x64 exampleProject.csproj
dotnet run  -p:Platform=x64 --project exampleProject.csproj

Optional (smaller output):

dotnet build -r win-x64 -p:Platform=x64 exampleProject.csproj
dotnet run  -r win-x64 -p:Platform=x64 --project exampleProject.csproj

You can substitute another architecture/runtime pair if needed, e.g.:

-p:Platform=x86 (optionally with -r win-x86)
-p:Platform=x64 with -r linux-x64

.NET Framework (classic)

Use Visual Studio or build from the command line:

Restore packages first

msbuild exampleProjectFramework.csproj /t:Restore

Build for a specific platform (required for native DLLs)

msbuild exampleProjectFramework.csproj /p:Platform=x64

Comparison to the C++ API

The C# API works similarly to the C++ API. Most class and method names are the same, but there are a few key differences.

• Enumerations use . instead of ::.
• Classes implement IDisposable.
• Namespace: IDSImaging.Peak.IPL.

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)