CameraSDK 3.0 Migration Guide
What has changed from CameraSDK 2.0 to 3.0 and why? How do you port your code to work with the new API’s of 3.0?
Embracing Modern C++
A significant change in the API’s is the use of modern C++ library classes. Both internally and in public APIs. Therefore CameraSDK 3.0 now requires C++17 to compile. We use std::filesystem in APIs and rely heavily on std::shared_ptr to manage shared objects, like image buffers.
New Features
CameraSDK 3.0 introduces new features, where some rely on new firmwares on the cameras to work. The following new features require you to have new iXM or IQ4 firmware:
Image Browsing: Browse, View and download any image in the cameras internal storage.
Jpeg LiveView: Camera can transfer LiveView image frames as Jpeg files, reducing the required bandwidth for LiveView.
Feature Packs. Access to special camera settings for Phase One partners.
To use these new features you must have:
iXM: Firmware 4.23 or later
IQ4: Firmware 6.03 or later
Read more about the new image browsing feature in: Image Browsing.
Firmware Upgrade & Diagnostics Logs
CameraSDK 3.0 also adds the possibility to upgrade the camera firmware and to download diagnostics logs from the cameras. These two new SDK features does not require any new firmware to be present in the cameras.
The diagnostics logs is intended for support scenarios, where our support team requests camera logs to diagnose an issue. Previously, logs could only be written to XQD storage. Now, the SDK can download logs from the cameras, on demand.
Note
Diagnostics logs are not text files, and can be viewed only by Phase One Support.
Read more about the new firmware upgrade and diagnostics logs in: Firmware Upgrade & Diagnostics Logs.
Breaking Changes
Besides the new features like Jpeg LiveView and Image Browsing, CameraSDK 3.0 introduces major changes in how API’s are structured, compared to 2.0.
The refactored APIs breaks source compatibility with 2.0 interfacing code. Many methods have been renamed to a more consistent naming scheme. But the major change are the introduction of a subscription API in the Camera class.
LiveView & Image Receiving
In 2.0, the Camera class contained many methods to handle start, stop, receive and abort LiveView and full images. All these following methods on Camera, have been removed and moved into the subscription API’s:
WakeUpWaitingImageThreadsEnableImageReceivingWaitForImageEnableLiveViewDisableLiveViewWaitForLiveViewGetLiveViewConfiguration
Camera now has a Subscriptions method that returns an object that lets us subscribe to receiving either LiveView, full images or even image previews. All images (including LiveView frames), are now returned using notifications, eliminating the need to separate WaitFor... methods. You can create a single Listener that receives everything.
This however, means you need to create the Listener, enable the relevant notifications and then activate the subscriptions.
The LiveView subscription object also allows you to change the configuration, just like GetLiveViewConfiguration did.
Read more about the new Subscription API’s here: Subscriptions.
Porting
Say, you have an application using CameraSDK 2.0, doing this:
camera.EnableImageReceiving(true);
while(true)
{
try {
IIQImageFile iiq = camera.WaitForImage();
// do something with image
} catch (ImageReceiveTimeoutExc e) {
break; // wait aborted, break while loop
}
}
Since the two essential methods now are removed, this code needs to ported to use the new subscription APIs:
// Create the notification listener
Listener imageListener;
imageListener.EnableNotification(camera, EventType::CameraImageReady);
// enable receiving the images (subscribing)
camera.Subscriptions()->FullImages()->Subscribe();
while(true)
{
std::shared_ptr<INotificationEvent const> notif
= imageListener.WaitForNotification();
if ( ! notif ) {
break; // wait was aborted, break while loop
}
// get the image buffer from the notification object
std::shared_ptr<IFullImage const> iiq =
notif->FullImage();
// do something with the image (iiq)
}
An advantage of delivering subscription content using notifications is everything can be handled by a single thread. You no longer need to have multiple thread hanging in 3 different WaitFor... methods. The same Listener object can receive notifications for all types of subscriptions, besides handling regular notifications.
Likewise, using notifications eliminates the need for dedicated wake up method for LiveView and full images.
No Get-prefixes
Another breaking change is the change in naming of getter methods. To be more concise in naming, we chosen to remove the Get-prefix from all getter methods. E.g. the Camera class has these getter name changes:
2.0 Name |
3.0 Name |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Note that only getter methods no longer use the Get-prefix, setter methods still has their Set-prefix. Also, this change is relevant for all API’s, it is not limited to the Camera class.
Porting
Converting you source code to use this new naming in its calls to CameraSDK, should be a search & replace job.
The compiler will help you identify the places you call methods that no longer exist. Use it to identify the methods in question. Then search and replace references in the code base, simply removing the Get prefix in the replacement.
PropertyTransaction removed
CameraSDK 2.0 contained a helper class called PropertyTransaction. It packed functionality to react to PropertySpec changes. We removed this class from 3.0, for two main reasons:
First, usage case complexity. The functionality in this helper class was very specific, and we doubt that anyone ever used it. If indeed somebody was in need of exactly that functionality, they would probably implement the functionality on their own - assuming no such specific tool is provided by the API.
Second, a convenience class. PropertyTransaction was implemented using only public APIs, meaning everyone can write a similar class. It did not hook into any internals of CameraSDK.