Properties

Interaction with the camera’s settings and features primarily happens through the the concept of Properties. A property could be “aperture”, “shutter time”, “ISO” and so on. All Phase One cameras have a dynamic set of properties. The CameraSDK simply exposes the properties made available by the connected camera. The CameraSDK itself does not specify any properties nor does it know anything about the properties provided by the cameras.

Each property is identified by a unique ID. The property IDs can change dependent on the camera. For more information on how to obtain these IDs for specific cameras, see Camera Property Model. In the following sections, the code examples assume that a Camera Property Model is included (as an “include file”).

The set of properties can change dynamically. For example, if the lens on the camera is changed, a different set of properties related to this new lens may be exposed.

When a camera is opened, the CameraSDK reads all available properties from that camera. When you request a list of the available properties, the CameraSDK simply provides you with the list, it received from the camera itself.

Note

CameraSDK does not have any internal knowledge about the connected camera or its features. This means it cannot assess anything about the properties that the camera provides. CameraSDK conveys the properties from the camera, it does not define any of them!

3 factors determine what properties are available from a camera:

Camera model

Firmware version

Camera Profile setting

Property Specifications

In CameraSDK terms, each property is defined inside a property specification, often just called a property spec. The specification specifies meta data around the property’s value. Such as name, description, permissions, visibility, valid input ranges, etc.

Using property specifications, you can explore what properties are available and how they can be altered, without knowing anything about them in advance.

Here is an example of the property for the “aperture” setting:

Spec	Example
Id	1003
Name	Aperture
Type	Float
Value	5.6
Default	2.8
Read Only	No
Enabled	Yes
Min/Max*
Value Map*

* Optional

Hint

For clarity, CameraSDK uses the terms property value and property specification, to distinguish between working with just the value or the complete set of meta data, surrounding a property.

Changing Property Values

Before we dive into the API’s to change properties, let us first look at the internals. Changing the value of a property is a two-step process:

First, set “aperture” to “5.6” from the Host computer. This will cause CameraSDK library to asynchronously push the new value to the camera.

Caution

If the value is read immediately after setting it from the CameraSDK, it will most likely return the old value, since it may not yet have been applied in the camera.

When CameraSDK passes the value to the camera, “aperture” will be set to the new value. Often, this process is nearly instant. However, the property may be related to mechanical movement, e.g. of a lens for focusing. In those cases, it might take a few seconds to actually bring the value of the property in effect in the camera.

The camera will report, through a notification, that the value of the property has changed.

Note

If the value was set to the same value, there will be no notification of this (as the value is unchanged).

To receive the notifications in the application, the application has to enable this for the specific property. Read more about notifications in Notifications.

Getting / Setting Properties

The CameraSDK can be used to get and set properties of an opened camera.

In the following example, a list of all available properties for the connected camera, along with their type, is printed to console:

std::cout << "Get a list of available properties" << std::endl;
std::vector<uint32_t> propertyIdList = camera.GetAllPropertyIds();

for (auto propertyId : propertyIdList)
{
	// Get the property specification for the current propertyId
	P1::CameraSdk::PropertySpecification property = camera.GetPropertySpec(propertyId);

	// Print a brief one-line description to console
	std::cout << "[" << propertyId << "] " << property.mName << " : " << property.mValue.ToString() << " , " << std::endl;
}

Console.WriteLine("Get a list of available properties");
IEnumerable<uint> propertyIdList = camera.GetAllPropertyIds();
// Iterate through list of PropertyIds
foreach (uint propertyId in propertyIdList)
{
    // Get the property specification for the current propertyId
    PropertySpec property = camera.GetPropertySpec(propertyId);
    // Print a brief one-line description to console
    Console.WriteLine("[{0}] {1} ({2}) : {3} {4}",
    propertyId,
    property.Name,
    property.GetType(), // try GetType since Type does not exist
    property.Value.ToString(), 
    property.ValueMapper
    );
}

Console output:

[1206] Message (String) :
[1207] Acknowledge (Bool) : False
[1000] Exposure Program (Enum) : [0] = Manual
[120] ISO (Float64) : 80
[10] Model Id (UInt32) : 293
:    :      :
:    :      :
[207] System Battery Capacity (UInt32) : 67
[1401] Diagnostics To Storage Config (UInt32) : 0

Note

The properties are not listed in any particular order.

To get the value of a specific property, use the GetProperty method. In the following example, the camera’s “model ID” is fetched and printed to console:

// Define the PropertyId for the 'Model' property
uint32_t modelId = IQ4150MP::Property::Model; // ID is defined by the Camera Property Model

// Get the PropertyValue object from the camera
PropertyValue cameraModel = camera.GetProperty(modelId);

// Print its value to the console
std::cout << "Camera Model: " << cameraModel << std::endl;

// Define the PropertyId for the 'Model' property
uint modelId = IQ4150MP.Property.Model; // ID is defined by the Camera Property Model

// Get the PropertyValue object from the camera
PropertyValue cameraModel = camera.GetProperty(modelId);

// Print its value to the console
Console.WriteLine("Camera Model: {0}", cameraModel);

Output:

Camera Model: IQ4 150MP

Setting a Property

To set (change) a specific property’s value, you must be aware of the valid values for the property. For some integer typed properties, there might be a limited range valid values. Other properties have a discrete list of valid values, where each of these values have a PresentationString describing their meaning. We call these types “Value Maps” or “enum types”. An example is the “exposure program” property:

Value	PresentationString
0	Manual
1	AV (Aperture Priority)
2	TV (Shutter Priority)
3	P (Automatic Program)

To set a specific property’s value, use the SetProperty method. In the following example, the “exposure program”-property is set:

// Create the new propertyValue object, that will be sent to camera
P1::CameraSdk::PropertyValue exposureProgram = P1::CameraSdk::PropertyValue(P1::CameraSdk::kPropertyTypeEnum);
exposureProgram.mInt = 0; // The value “0” corresponds to setting “M”

// Define the Id for the 'Exposure Program' property
uint32_t exposureProgramId = 1000;

// Set the property in the camera
camera.SetProperty(exposureProgramId, exposureProgram);

// Create the new propertyValue object, that will be sent to camera
PropertyValue exposureProgram = new PropertyValue(PropertyType.Enum);
exposureProgram.IntValue = 0; // The value “0” corresponds to “M”

// Define the Id for the 'Exposure Program' property
uint exposureProgramId = 1000;

// Set the property in the camera
camera.SetProperty(exposureProgramId, exposureProgram);

Caution

When you set a property value, the change is first in effect when you receive a change notification for that property. If you call SetProperty instantly followed by GetProperty, you will receive the old value - not the one you just set!

For value map types, the value we set is the index in the value map - not mapped value itself (the presentation string). This is especially important if the value map consist of values (presentation strings), that resemble integers or boolean values. If a property defines a value map like the one below, you must still use the index value, when setting it:

Value	PresentationString
0	Yes (1)
1	No (0)

Notice, how this example goes against our C programmers intuition - because index 0 denotes Yes or True.

Property Groups

Each property belongs to a group, which can also be seen in the property spec (see Property Specification Example). The property-groups determine which part of the set-up that the property belongs to; e.g. “camera” or “lens”. As such, there may be multiple properties with the same “human readable” name (e.g. “serial”), and the group of the property then determines what the property pertains to (the camera’s serial number or the lens’s serial number). This is intended to be used to e.g. build a user interface in which all properties of a specific group may want to be placed together. Note, that all properties have a unique ID.

In the example below, two properties with the same name (“serial”) can be seen. It can be determined from the property-group whether the “serial” corresponds to the camera or the lens. Note also the unique IDs for both properties, despite the identical names:

Camera Model: iXM-50
[   3] About::Camera                    Serial                           (String) : MH000001
[1161] About::Lens                      Serial                           (String) : UH001001

Note

The property groups can be seen as a kind of namespace.

Invalid Values when Setting Properties

Most camera properties has a valid input range. In case an invalid value is passed, the camera can have different reactions. This depends on the specific property and camera hardware.

Note

In both SDKs, error handling is done through exceptions. When something goes wrong, it is thus likely that the SDK will throw an exception as a reaction. To read more about error handling in the SDKs, see Error Handling and Logging.

Reaction	Description	Example
Best Effort	The CameraSDK sets the value that it determines to be the closest match to the input.	User-input: Aperture, 5.5 Output: Aperture, 5.6
Type Error / Exception	The CameraSDK throws an exception, and sets nothing.	User-input: Aperture, “two” Output: “Invalid type”- exception
Change Notification	The camera itself does not accept the new value. (E.g. out-of-range)	User-Input: Exposure Program, 99 Output: “change notification”

If a value-input for a property-change is invalid, the camera will not update the property value. In this event, the camera will ensure the property specification in the CameraSDK is updated, to reflect the actual value in the camera. A notification will be generated to reflect this.

Setting an invalid value sequence diagram

Notice that the SDK’s internal property value state is not updated. The asterisk (*) denotes that the internal property state is marked must update. This means that there will always be generated a change notification. This notification will contain the old value A, since B was never put in effect on the camera.

Warning

As a consequence of this behavior, any other threads calling GetProperty will never see the value B.

Multiple Input Sources

The properties of the camera can be set from multiple sources. In the earlier examples, it is assumed that the input comes from the CameraSDK alone, but this is not always the case.

The camera could set a property from an auto exposure algorithm, or by a changing dial on an XF system, or it could be through a communication link e.g. when connected to a drone.

There is no protection mechanism, and the property value will always be set to the latest valid input received.

1) Two users each set a value (“A” and “B”), from two different sources. “B” is set slightly later.

2) The value in the CameraSDK is set to “A”, as this was the first input.

3) The camera tells the CameraSDK of its new value, “B”.

4) The value in the CameraSDK is set to “B”, as this was the last input.

Caution

If the property requires mechanical movement within the camera (e.g. to adjust the focus), the camera adjusts to the new value (“B”). If the property is digital (e.g. adjusting the ISO), this will be near-instantly applied in the camera.

Note

If “capture image” has been initiated, the values related to image capturing are “locked in” for that image. The values are thus writeable for the next capture, even while the camera is currently capturing an image.

Properties Affecting Each Other

Setting the value of one property can affect which values are available to another property. Similarly, in rare cases, changing a property can have the side effect that other properties will adjust their values.

For example, the Phase One XF cameras usually do not support the same range of shutter speed for all shutter types. Consequently, if a fast shutter speed is selected, the shutter type will be automatically selected to a shutter type supporting the desired shutter speed. When the shutter speed is changed back again, the shutter type will revert to the previous shutter type.

Camera Property Model

Phase One provides specifications for each camera, in the form of an include file, which consist of:

The set of properties
The set of values pertaining to each property

This is called a Camera Property Model (not to be confused with Camera Model ID or Camera Model Name). These models can be provided in source code form for either C# or C++. An excerpt of a possible Camera Property Model could be as follows:

enum class Property : uint32_t
{
    Manufacturer = 1,                          // Type: String
    Model = 2,                                 // Type: String
    Serial = 3,                                // Type: String
    Firmware = 4,                              // Type: String
    FirmwareCompatibility = 5,                 // Type: UInt32
    // ...
    ISO = 120,                                 // Type: Float64 Map
    // ...
};

enum Property : uint
{
    Manufacturer = 1,                          // Type: String
    Model = 2,                                 // Type: String
    Serial = 3,                                // Type: String
    Firmware = 4,                              // Type: String
    FirmwareCompatibility = 5,                 // Type: UInt32
    // ...
    ISO = 120,                                 // Type: Float64 Map
    // ...
}

Utilizing a Camera Property Model allows the usage of “sensible” names, as opposed to numbers, for the camera properties, as exemplified below:

Camera camera = Camera::OpenUsbCamera();

PropertyValue iso = camera.GetProperty(IQ4150MP::Property::ISO);
std::cout << "ISO: " << iso.ToString();

Camera camera = Camera.OpenUsbCamera();

PropertyValue iso = camera.GetProperty(IQ4150MP.Property.ISO);
Console.WriteLine("ISO: " + iso);

Output:

ISO: 800

In this example, the user can use IQ4150MP.Property.ISO as opposed to 120 to refer to the camera’s “ISO” property.

A Camera Property Model is identified by the following three properties of a camera:

Camera Model Name (e.g. iXM150)
Camera Profile (e.g. Aerial)
Firmware Version (e.g. 4.00)

Older cameras do not support the profile property; for these, the Camera Property Model is given by the Camera Model Name and the Firmware Version.

Caution

The Camera Property Model will usually not specify any relationship among properties, e.g. if setting one property influences the list of values for another property.

When an application uses the CameraSDK to control a camera, it can do this entirely based on the CameraSDKs discovery capabilities, to e.g.:

Provide a list of connected cameras.
Provide a list of property specifications – including a “human readable” name for the property.
Provide the type of each property.
Provide a PresentationString for each property value.
Provide a list of values allowed for a property, or minimum/maximum values.
Provide a list of default values for each property.

Often it is not desirable to use discovery, since in a given application it is usually well-known what cameras are being used and what properties the application will need access to. Thus, there is no need to re-discover the data abstractions every time.

Property Specification Example

All properties in the camera have a property specification (also called a property spec). This specification contains information about the attributes of the property: “Id”, “Type”, “Name”, “Value”, “Default” and so on.

In the table below, the property spec for the “aperture” value is explained.

Attribute			Example	Definition
Id			1003	The unique identification number.
Value			12	The current value.
Name			Aperture	The “human readable” name.
Group			IQ::Capture	The group to which the property belongs (see section Property Groups).
ReadOnly			No	If the value cannot be set (changed) by the user.
Enabled			Yes	Whether the property is accessible.
UserLevel			Basic	Determines what access level the user needs to have, to be able to access the property.
SelectOnly			Yes	Determines whether the value has to be selected from the `ValueList`.
DisplayAsHex			No	A display hint that the property should be displayed as a hexadecimal value.
RefreshRequired			No	If “no”, the property is automatically updated in the CameraSDK and a notification will be generated on change. E.g. “System time” will not generate a notification every millisecond.
UnitString			“f/”	The unit of measurement for the value (as a string). Optional.
Description			“”	Descriptive text. Optional – rarely used.
DisplayIndex			6	The suggested display order within the property group when presenting the property to the user.
Default			2.799	The default value.
Range				Whether there is a specific range of values (i.e. if min/max is applicable).
		Has	Yes
		Min	2.799	The minimum acceptable value.
		Max	22	The maximum acceptable value.
ValueList				A list of valid values for the property. Note, that each value contains a “human readable” string (`PresentationString`), so it is possible to see it as a value map for presenting a choice on a user interface.
	2.79999995		“2.8”
	3.20000004		“3.2”
	3.5		“3.5”
	…		…