class P1::CameraSdk::Camera

Overview

Representation of a physical Phase One camera. More…

#include <P1CameraCamera.hpp>

class Camera
{
public:
    // construction

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

    // methods

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

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

    static std::vector<CameraListElement> GetAvailableCameras();
    Camera& operator = (Camera&& other);
    void Close();
    bool IsOpen() const;
    int GetId();
    void WakeUpWaitingImageThreads();
    void TriggerCapture();
    void EnableImageReceiving(bool enable);
    void SetHostStorageCapacity(uint32_t capacityMB);
    const IIQImageFile WaitForImage(uint32_t timeoutMs = 0);
    void EnableLiveView();
    void DisableLiveView();
    const LiveViewImage WaitForLiveView(uint32_t timeoutMs = 0);
    LiveViewConfiguration& GetLiveViewConfiguration();
    PropertyValue GetProperty(const uint32_t property) const;
    void SetProperty(const uint32_t propertyId, const PropertyValue& value);

    PropertyTransaction BeginSetProperty(
        const uint32_t propertyId,
        const PropertyValue& value
        );

    PropertySpecification GetPropertySpec(const uint32_t propertyId) const;
    std::vector<uint32_t> GetAllPropertyIds() const;
    P1::CameraSdk::TetherConnection GetConnectionType() const;
};

Detailed Documentation

Representation of a physical Phase One camera.

All interaction with camera are through objects of this class. You work with cameras using two different schemes.

Properties

All Phase One camera expose a dynamic set of properties. These include Aperture, Shutter Time, ISO etc. But properties can also represent other camera settings like shutter mode or the dimension of the LiveView images.

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

A camera exposes different properties at different times. This means that setting 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 is not guaranteed.

Capturing & LiveView

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

Both captured and LiveView images are transferred in data chunks. The captured full resolution RAW images are large, and transferring them in chunks saves memory. You can control the size of each chunk, so you could allocate a giant chunk to transfer the entire image in one go.

The format of the captured images are IIQ files, that can be written directly to disk. However, you must account for data chunks arrive un-ordered. This means the received series of chunks and not a stream of bytes. The end of the IIQ file might arrive in a chunk, before the begining. Each chunk will define its global byte offset.

Creating & disposing objects

There is no (real) public constructor on this class. Since this class represents a association with physical cameras, you cannot construct object on your own. Use the static method OpenUsbCamera() to create cameras.

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

Construction

Camera()

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

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

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(
    const std::string& serial = std::string(),
    const std::string& password = std::string()
    )

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

Parameters:

serial

Optional: The serial of the camera to open. An empty string or nullptr, to open any camera.

Returns:

A camera object, to control the requirested physical camera

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

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

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 requirested physical camera

static std::vector<CameraListElement> GetAvailableCameras()

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

Cameras come and go. The availble 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!

Returns:

A list of cameras attached to your host system

Camera& operator = (Camera&& other)

Assign 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 intialized states to shut down. Likewise all event notifications from this camera are removed.

int GetId()

Get the unique id for this camera.

The Id is unique only for this runtime session.

void WakeUpWaitingImageThreads()

Wakes up any threads block in WaitForImage or WaitForLiveView calls.

To gracefullt terminate a multi-threaded application, use this method to force wake-up threads there are waiting inside WaitFor..() calls.

This method will force the calls to release the treads and return with a time-out exception.

void TriggerCapture()

Take a picture with the camera.

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

If you with 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 need to listen for the trigger event notification, to be sure that triggering occurred.

void EnableImageReceiving(bool enable)

Enable image captures are transmitted to the SDK.

Setting this to true tells the camera that the host computer is ready to receive captures. The camera may choose to ignore this (and not transmit any captures), as the storage configuration on the camera decides.

Parameters:

enable

true is enabled. false otherwise.

void SetHostStorageCapacity(uint32_t capacityMB)

Registers this host’s available storage capacity (in megabytes).

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

Initially, this setting is set to 1GB.

const IIQImageFile WaitForImage(uint32_t timeoutMs = 0)

Wait for the next image to be captured / delivered from camera.

Before any images can be received with this method, you must call EnableImageReceiving to tell the camera to transfer images to you.

The received image structure contains a std::shared_ptr that holds the raw data pointer. This data is temporary, so you must copy it to a new location, either in memory or on the file system. Do not hold on to this pointer, since the memory it holds need to be given back to the SDK subsystem.

Parameters:

timeoutMs

Defines an optional timeout (ms) - 0 is wait forever

Returns:

const IIQImageFile A reference to an in-memory IIQ image file.

void EnableLiveView()

Turn capturing and transferring of LiveView images on.

To receive a stream of LiveView images, set this to true. This causes the camera to begin feeding a stream of bitmap images to you host system.

By default LiveView images are 1024 x 768 pixels, and 24 bit RGB. You can change these settings by getting the LiveView configuration object GetLiveViewConfiguration

void DisableLiveView()

Turn capturing and transferring of LiveView images off.

const LiveViewImage WaitForLiveView(uint32_t timeoutMs = 0)

Get (wait for) the lastest received live image.

Block and wait for the next received LiveView image from the camera. If an LiveView image has already been received, it is returned immediately.

The returned struct contains a pointer to the image’s bitmap data. This memory is the SDK’s internal memory, and you should not hold on to it. Copy the data either to an in-memory location or to a file.

Unlike captured images, LiveView frames does not arrive in a queue. Only the latest live view image is preserved.

Parameters:

timeoutMs

The maximum amount of milliseconds to wait for a LiveView image to arrive

Returns:

const LiveViewImage Struct that hold image data and relevant meta data

LiveViewConfiguration& GetLiveViewConfiguration()

Get the LiveView configuration for the camera.

The returned object represents the LiveView configuration parameters on this camera. Changing the parameters exposed by the object, will change the corrosponding LiveView parameters on the camera.

PropertyValue GetProperty(const uint32_t 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.

Parameters:

property

The Id of the property to get

Returns:

The value object of the property

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

Set a given property’s value.

Parameters:

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