class P1::CameraSdk::Camera

Overview

Representation of a physical Phase One IQ4 or iXM camera. More…

#include <P1CameraCamera.hpp>

class Camera
{
public:
    // construction

    Camera();
    Camera(Camera&& other);

    // methods

    static Camera OpenUsbCamera(
        std::string const& serial = std::string(),
        std::string const& password = std::string()
        );

    static Camera OpenIpCamera(
        std::string const& ipAddress,
        std::string const& password = std::string(),
        int const timeoutSecs = 0
        );

    static std::vector<CameraListElement> AvailableCameras();
    Camera& operator = (Camera&& other);
    void Close();
    bool IsOpen() const;
    int Id() const;
    void TriggerCapture();
    void SetHostStorageCapacity(uint32_t capacityMB);
    bool UpdateCameraFirmware(std::string const& filePath);

    bool UpdateCameraFirmware(
        uint8_t const* fwFileBuffer,
        std::size_t const fwBufferSize
        );

    PropertyValue Property(uint32_t const property) const;
    void SetProperty(uint32_t const propertyId, PropertyValue const& value);
    PropertySpecification PropertySpec(uint32_t const propertyId) const;
    std::vector<uint32_t> AllPropertyIds() const;
    std::vector<std::shared_ptr<IStoredImageHandle>> AllImages();
    std::shared_ptr<ISubscriptionManager> Subscriptions();
    std::shared_ptr<ICameraCapabilities const> Capabilities() const;
    P1::CameraSdk::TetherConnection ConnectionType() const;
    std::vector<std::uint8_t> DiagnosticsLog(void) const;
    bool SaveDiagnosticsLog(std::filesystem::path const logFileDestpath) const;
};

Detailed Documentation

Representation of a physical Phase One IQ4 or iXM camera.

All interaction with cameras are done through objects of this class. You work with cameras using the 3 following schemes.

Properties

All Phase One cameras expose a dynamic set of properties. These include Aperture, Shutter Time, ISO etc. But properties can also represent other camera settings like lens name or the network preferences.

Common for all properties is that they define metadata like human readable names and valid value ranges.

A camera exposes different properties at different times. This means that changing one property, might cause other properties to disappear or become visible. Because of this dynamic nature, we do not include an enum type with all PropertyId. You must query for the name and purpose of the properties to wish to use. And know that their existence or read/write state, is not guaranteed.

Capturing & LiveView

The camera class also defines a set of methods to trigger image capturing, and streaming LiveView images to the SDK host computer. Also, you can control whether captured images should be transferred to the computer.

The format of the transferred images are IIQ files, that can be written directly to disk.

Image Browsing

Starting with the release of CameraSDK 3.0, and accompanying camera firmwares, you can browse images on the camera. List all available images in the cameras storage, download the preview (thumbnail), request a crop of an image, with scaling. You can also request that any image IIQ be transferred to host, on-demand.

Firmware update and logs

Also introduced in 3.0 are updating camera firmware and extracting logs from the camera.

From the point of view of the CameraSDK, firmware updates are purely file transfers. There is no tracking of progress, as the new firmware is applied in the camera. In fact, the camera will instantly drop the SDK connection, as soon as the update is started.

Extracting (internal) logs file from the cameras are made easier, with a dedicated new method for this. The cmaera’s internal log is a rolling window of the latest 10-30MB of logging output. (Depending on the camera model.)

That said, log files are intended for debugging issue in collaboration with Phase One Support. The extracted log files are not user readable.

Creating & disposing objects

There is no (real) public constructor on this class. Since this class represents an association with physical cameras, you cannot construct objects on your own. Use one of the static methods, like OpenUsbCamera(), to create camera objects.

Upon destructing an instance of this class, the connection to the physical camera is terminated and all associated resources are freed.

Any LiveView image frames or transferred image capture objects, is also freed with the camera object.

Version 2.0

Construction

Camera()

Create an empty dummy camera object - with no tether to real world camera.

This default constructor is meant allow initialization of an empty camera variable. Calling any method on a camera object created by this constructor will throw an exception!

@seealso OpenUsbCamera @seealso OpenIpCamera

Camera(Camera&& other)

Move camera from one context to another.

This is the move constructor, allowing move semantics on the camera objects.

Methods

static Camera OpenUsbCamera(
    std::string const& serial = std::string(),
    std::string const& password = std::string()
    )

Opens an USB Camera with the given serial-number. (Or any USB camera if the serial-number is omitted or empty).

This method will open and return the first available USB attached camera. If you have multiple USB cameras attached to your system, there is no guarantee what camera will be opened. In this case, please provide a serial number for the camera you wish to open.

Version 2.0

Parameters:

serial	Optional: The serial of the camera to open. An empty string or `nullptr`, to open any camera.
password	An optional password, if camera is password protected

Returns:

A camera object, to control the requested physical camera

static Camera OpenIpCamera(
    std::string const& ipAddress,
    std::string const& password = std::string(),
    int const timeoutSecs = 0
    )

Opens a TCP/IP camera with a given IP address.

Version 2.0

Parameters:

ipAddress	The IPv4 address of the camera
password	An optional password, if camera is password protected
timeout	An optional connection timeout in seconds. (0 is system’s sockets default timeout)

Returns:

A camera object, to control the requested physical camera

static std::vector<CameraListElement> AvailableCameras()

Returns a list of all USB cameras currently attached to the system.

Cameras come and go. The available cameras might disappear right after this method has returned. Therefore, opening a camera found using this method might still fail.

Cameras connected by TCP/IP can not be discovered by this method!

Version 2.0

Returns:

A list of cameras attached to your host system

Camera& operator = (Camera&& other)

Assign (pass) a camera object to another variable.

This is the move assignment, allowing move semantics on the camera objects.

void Close()

Frees the camera handle, letting other processes or resources take over use of the camera.

Closing the communication with the camera and causes any initialized states to shut down. Likewise all event notifications from this camera are removed.

This method is automatically called by the class’ destructor.

Version 2.0

bool IsOpen() const

Returns whether this camera object is open.

Version 2.0

int Id() const

Get the unique id (handle) for this camera.

The Id is unique only for this runtime session and is not related to the physical camera.

Version 2.0

void TriggerCapture()

Take a picture with the camera.

This method triggers the camera to take a picture, with its current settings and exposure mode.

If you wish to receive the picture taken, you must first call EnableImageReceiving and set it to true. If not, the triggering will fail if there is no storage media in the camera.

Be aware that actual triggering might also fail for a couple of other reasons. You can see if the camera is ready to trigger a capture, by examining the Ready For Capture property.

Also note that USB and TCP/IP transports include a significant of latency with jitter. There is no guarantee on the time from this call to the actual request is received in the camera. You will probably need a more precise control over camera triggering. This offered by the iXLink protocol.

Version 2.0

void SetHostStorageCapacity(uint32_t capacityMB)

Registers this host’s (your PC) remaining storage capacity (in megabytes).

On IQ4 cameras this is used to display the remaining capacity on the host storage. This value is not automatically updated. You must call this manually to reflect changes to your computers disk storage capacity.

If the host’s capacity falls below a certain threshold (depending on capture-settings), the camera will reject new captures (also depended on storage-settings).

If you do not care about relaying the correct remaining disk space (on the your PC), you can simply ignore this setting.

By default, this setting is set to 1GB.

Version 2.0

bool UpdateCameraFirmware(std::string const& filePath)

Update firmware in the camera, using a file on disk.

This method transfers the provided firmware package file to the camera, which then immediately begins the firmware update process.

After a brief validation of the firmwre package, the camera will drop the connection to the CameraSDK, and begin applying the new firmware. If the package validation fails, the camera will discard the package.

This method returns immediately after the file has been transferred to the camera. The returned boolean indicate the status of the file transfer, not the firmware update in itself.

This method will throw if pointed to a non-existing or inaccessible file.

Version 3.0

Parameters:

filePath

Path to the firmware package (.fwr / .fwp) file

Returns:

true if transfer is successful, else false

bool UpdateCameraFirmware(
    uint8_t const* fwFileBuffer,
    std::size_t const fwBufferSize
    )

Update firmware of the camera, using an in memory file buffer.

This method transfers the provided firmware package file buffer to the camera, which then immediately begins the firmware update process.

After a brief validation of the firmwre package, the camera will drop the connection to the CameraSDK, and begin applying the new firmware. If the package validation fails, the camera will discard the package.

This method returns immediately after the buffer has been transferred to the camera. The returned boolean indicate the status of the transfer, not the firmware update in itself.

Version 3.0

Parameters:

fwFileBuffer	Pointer to buffer that holds the firmware (.fwr / .fwp) file.
fwBufferSize	size (in bytes) of buffer.

Returns:

true if transfer is successful, otherwise false

PropertyValue Property(uint32_t const property) const

Gets the current value of a given property.

The returned PropertyValue object is a wrapper that encapsulate the property’s type. Since properties each can have different types, that is only known at runtime - all property values are wrapped in the PropertyValue class.

The PropertyValue class contains only the value - not the associated meta data for the property. To get the metadata use PropertySpec.

Version 2.0

Parameters:

property

The Id of the property to get

Returns:

The value object of the property

void SetProperty(uint32_t const propertyId, PropertyValue const& value)

Set a given property’s value.

Overwrite the existing property on the camera with a new value. You provide the new value as a PropertyValue object. This object can be one you receive earlier from Property and modified. Or, it can be a PropertyValue that you constructed yourself.

Version 2.0

Parameters:

propertyId	The Id for the property to set
value	The new value of the property