Migrating from Previous Versions

Migrating from Pylon 3 to Pylon 4

What's new in Pylon 4?

Pylon 4 adds support for Basler USB3 Vision compliant cameras. See the section Migrating Existing Code for Using USB Camera Devices under advanced topics for more information.

Block ID

One image is usually seen as block in the image transport. An ID, the Block ID, is assigned to every block. The grab result method Pylon::CGrabResultData::GetBlockID() can now be used to get the Block ID. Previous pylon versions reported Block ID as Frame Number in grab results because Block ID and Frame Number can be equal depending on the camera device used. Therefore, Frame Number and Block ID can also be different for some camera devices. That is why the grab result method Pylon::CGrabResultData::GetFrameNumber() is now deprecated.

Migrating from pylon 2.x to pylon 3

What's new in pylon 3?

pylon 3 extends the API of the previous pylon version by the Instant Camera Classes and further Image Handling Support classes. The Instant Camera classes represent the new API for accessing a camera device. With the new classes it is possible to grab images with a few lines of code giving instant access to grabbed images from a camera device. The previous API used for grabbing is now called Low Level API. It can still be used for existing applications. The Image Handling Support classes help to cover common use cases when working with image data. There are an image class, a new image format converter, and support for loading and saving images. Additionally, the GenICam release used by pylon has been updated from version 2.0 to version 2.3. A new set of code samples shows the use of the Instant Camera classes and the Image Handling Support classes.

pylon3_0_migration.png
pylon 3 Is Still Compatible with pylon 2.3 and Offers a New API for Grabbing and Image Handling.

Frequently Asked Questions Regarding Migration

Can I Keep My Implementation Using the Low Level API?

Yes. The Low Level API will be provided also in future releases.

What Parts of the API Can Be Used Together?

The Image Handling support classes can be used together with the Instant Camera classes or the Low Level API. Either the Instant Camera classes or the Low Level API can be used for grabbing images, events or chunk data.

When to Change to the Instant Camera Classes?

An existing implementation that uses the Low Level API, that is stable and used in the current application should not be changed. In the case of problems you may want to change to the Instant Camera classes. This should drastically reduce the amount of code you need for grabbing and therefore the chance of having a hidden bug.

What to Use When Starting a New Project?

It is recommended to use the Instant Camera classes for new projects. Only in the case of a rare highly advanced use case that cannot be covered using the Instant Camera classes the use of the Low Level API should be considered for a new project. Furthermore, the Instant Camera classes produce only the same overhead a custom grab implementation would cause.

When to Replace Deprecated Pixel Format Converter Classes?

The image format converter classes based on Pylon::CPixelFormatConverter are now deprecated and can be replaced by the Pylon::CImageFormatConverter class. The Pylon::CImageFormatConverter class is much easier to use. A replacement of the old converters could be considered if it results in much less code for the same operations.

The static methods Pylon::CPixelFormatConverterMonoPacked::Unpack10() and Pylon::CPixelFormatConverterMonoPacked::Unpack12() create a Pylon::CImageFormatConverter object on the stack each time when called and, as a consequence, may take more processing time. If the above methods are used and the additional processing time is not acceptable then the methods should be replaced by using the new converter.

Precautions When Copying Code Snippets from Camera Manuals

The code snippets included in the Camera Manuals may not have been updated yet to show the API of the Instant Camera classes. In these cases the code snippets illustrating how to grab events, chunks, image data or how to use GigE Multicast still show the use of the Low Level API.

There is a difference when using generic parameter access. An Instant Camera class returns a node map object as reference and not as pointer. This has been changed to avoid additional NULL pointer checks. Example:

// Low Level API:
CBaslerGigECamera camera;
//...
// Get the camera control object.
INodeMap &control = *camera.GetNodeMap();
const CIntegerPtr Height = control.GetNode("Height");
const CIntegerPtr Height = camera.GetNodeMap()->GetNode("Height");
// Instant Camera Classes:
CBaslerGigEInstantCamera camera;
//...
// Get the camera control object.
INodeMap &control = camera.GetNodeMap();
const CIntegerPtr Width = control.GetNode("Width");
const CIntegerPtr Height = camera.GetNodeMap().GetNode("Height");

There is, however, no difference in parameter access between Low Level Camera classes and Device Specific Instant Camera classes using native parameter access. Example:

// Low Level API:
CBaslerGigECamera camera;
//...
// Maximize the image area of interest (Image AOI).
if (IsWritable(camera.OffsetX))
{
camera.OffsetX.SetValue(camera.OffsetX.GetMin());
}
if (IsWritable(camera.OffsetY))
{
camera.OffsetY.SetValue(camera.OffsetY.GetMin());
}
camera.Width.SetValue(camera.Width.GetMax());
camera.Height.SetValue(camera.Height.GetMax());
// Set the pixel data format.
camera.PixelFormat.SetValue(PixelFormat_Mono8);
// Instant Camera Classes:
CBaslerGigEInstantCamera camera;
//...
// Maximize the image area of interest (Image AOI).
if (IsWritable(camera.OffsetX))
{
camera.OffsetX.SetValue(camera.OffsetX.GetMin());
}
if (IsWritable(camera.OffsetY))
{
camera.OffsetY.SetValue(camera.OffsetY.GetMin());
}
camera.Width.SetValue(camera.Width.GetMax());
camera.Height.SetValue(camera.Height.GetMax());
// Set the pixel data format.
camera.PixelFormat.SetValue(PixelFormat_Mono8);

If code samples are referenced the mapping between old and new code samples can be found in the section Mapping Between Old and New Code Samples.

Mapping Between Old and New Code Samples

pylon 3 provides a new set of code samples. The code samples can be found under <SDK ROOT>\Samples\C++. The following table shows the mapping between old and new code samples.

Old Code Sample New Code Sample Comment
RegisterRemovalCallback DeviceRemovalHandling
AcquireSingleFrame See Pylon::CInstantCamera::GrabOne() for information about single frame acquisition.
AcquireSingleFrame_Gen See Pylon::CInstantCamera::GrabOne() for information about single frame acquisition. The ParametrizeCamera_GenericParameterAccess sample shows how to use generic parameter access.
AcquireContinuous Grab Shows how to grab using continuous acquisition. Continuous acquisition is used as default configuration for Instant Camera classes.
CameraEvents Grab_CameraEvents
AcquireSingleFrame_ChunkImage Grab_ChunkImage
AcquireContinuous_Multicast Grab_MultiCast
Grab_MultipleCameras
Grab_Strategies
Grab_UsingExposureEndEvent
AcquireContinuous_SoftTrigger Grab_UsingGrabLoopThread Shows how to use the grab loop thread that is provided by the Instant Camera object and how to use Software Trigger.
Grab_UsingSequencer
GUI_ImageWindow
AutoFunctions ParametrizeCamera_AutoFunctions
ParametrizeCamera_Configurations
ParametrizeCamera_GenericParameterAccess
LoadSaveCameraFeatures ParametrizeCamera_LoadAndSave
LookupTable ParametrizeCamera_LookupTable
ParametrizeCamera ParametrizeCamera_NativeParameterAccess
RunnerShadingSample ParametrizeCamera_Shading
UserSets ParametrizeCamera_UserSets
Utility_Image
Utility_ImageFormatConverter
Utility_ImageLoadAndSave
WaitForMultiple See the Waiting for Multiple Events section.

Project Setting Changes

Environment Settings

In contrast to the windows version pylon for Linux requires the environment variables PYLON_ROOT and GENICAM_ROOT_V2_3 to be set. See the Common Settings for Running Applications with pylon section for detailed instructions.

API Changes

Continuing the Use of Deprecated Pixel Format Converters

The image format converter classes based on Pylon::CPixelFormatConverter are now deprecated and replaced by wrapper classes that use the new Pylon::CImageFormatConverter class internally. To turn off deprecation warnings define PYLON_UTILITY_3_0_NO_DEPREC either by adding it to your compiler invocation or by defining it before including the header files PylonIncludes.h, PylonUtilityIncludes.h or any pixel format converter header files:

#define PYLON_UTILITY_3_0_NO_DEPRECATE
#include <pylon/PylonIncludes.h>
Attention
The static methods Pylon::CPixelFormatConverterMonoPacked::Unpack10() and Pylon::CPixelFormatConverterMonoPacked::Unpack12() create an Pylon::CImageFormatConverter object on the stack each time when called and, as a consequence, can take more processing time.

Removed Classes

The CBaslerGigETl class is not needed anymore when programming against the pylon C++ API, and has been removed. All include statements for the header file "BaslerGigETl.h" should be removed from application code. Replace all occurrences of Pylon::CBaslerGigETl by Pylon::IGigETransportLayer.

// Old
#include <pylon/gige/BaslerGigETl.h>
//...
CBaslerGigETl* const gigeTL = dynamic_cast<CBaslerGigETl*>(CTlFactory::GetInstance().CreateTl(BaslerGigEDeviceClass));
if ( gigeTL )
{
gigeTL->EnumerateAllDevices(dil);
//...
}
// New
//...
IGigETransportLayer* const gigeTL = dynamic_cast<IGigETransportLayer*>(CTlFactory::GetInstance().CreateTl(BaslerGigEDeviceClass));
if ( gigeTL )
{
gigeTL->EnumerateAllDevices(dil);
//...
}

Deprecated Helper Functions and Classes

The IsValidRGB(), IsValidBGR(), and PixelSize() functions in PixelType.h are now deprecated. Alternative functions are Pylon::IsRGB(), Pylon::IsRGBA(), Pylon::IsBGR(), Pylon::IsBGRA(), Pylon::BitDepth(), and Pylon::BitPerPixel(). However, there is no exact replacement available. The deprecated functions are provided as header only code and can be copied to the application's code if needed. The SRGBAPixel struct is deprecated too and can be replaced by Pylon::SBGRA8Pixel. Only the name of this struct has been changed.


© 2006-2014 Basler (Tue Jul 22 2014 11:41:23)