ifm3dpy.device.LegacyDevice

class ifm3dpy.device.LegacyDevice

Bases: Device

Class for managing an instance of an O3D/O3X Camera

__init__(self: ifm3dpy.device.LegacyDevice, ip: str = '192.168.0.69', xmlrpc_port: int = 80, password: str = '') → None

Constructor

Parameters

ip (string, optional) – The ip address of the camera. Defaults to 192.168.0.69.
xmlrpc_port (uint, optional) – The tcp port the sensor’s XMLRPC server is listening on. Defaults to port 80.
password (string, optional) – Password required for establishing an “edit session” with the sensor. Edit sessions allow for mutating camera parameters and persisting those changes. Defaults to ‘’ (no password).

Methods

`__init__`(self[, ip, xmlrpc_port, password])	Constructor
`active_application`(self)	Returns the index of the active application.
`am_i`(self, family)	Checking whether a device is one of the specified device family
`application_list`(self)	Delivers basic information about all applications stored on the device.
`application_types`(self)	Lists the valid application types supported by the sensor.
`cancel_session`(args, *kwargs)	Overloaded function.
`check_minimum_firmware_version`(self, major, ...)	Checks for a minimum ifm camera software version
`copy_application`(self, idx)	Creates a new application by copying the configuration of another application.
`create_application`(self[, type])	Creates a new application on the camera of the given type.
`delete_application`(self, idx)	Deletes the application at the specified index from the sensor.
`device_parameter`(self, key)	Convenience accessor for extracting a device parameter
`device_type`(self[, use_cached])	Obtains the device type of the connected camera.
`export_ifm_app`(self, idx)	Export the application at the specified index into a byte array suitable for writing to a file.
`export_ifm_config`(self)	Exports the entire camera configuration in a format compatible with Vision Assistant.
`factory_reset`(self)	Sets the camera configuration back to the state in which it shipped from the ifm factory.
`firmware_version`(self)	Version of firmware installed on device
`force_trigger`(self)	Sends a S/W trigger to the camera over XMLRPC.
`from_json`(self, json)	Configures the camera based on the parameter values of the passed in JSON.
`heartbeat`(self, hb)	Sends a heartbeat message and sets the next heartbeat interval
`imager_types`(self)	Lists the valid imager types supported by the sensor.
`import_ifm_app`(self, bytes)	Import the IFM-encoded application.
`import_ifm_config`(self, bytes[, flags])	Imports the entire camera configuration in a format compatible with Vision Assistant.
`reboot`(self, mode)	Reboot the sensor
`request_session`(self)	Requests an edit-mode session with the camera.
`set_current_time`(self[, epoch_secs])	Sets the current time on the camera
`set_temporary_application_parameters`(self, ...)	Sets temporary application parameters in run mode.
`to_json`(self)	A JSON object containing the state of the camera
`trace_logs`(self, count)	Delivers the trace log from the camera
`unit_vectors`(self)	For cameras that support fetching the Unit Vectors over XML-RPC, this function will return those data as a binary blob.
`who_am_i`(self)	Retrieve the device family of the connected device

Attributes

`ip`	The IP address associated with this Camera instance
`password`	The password associated with this Camera instance
`session_id`	Retrieves the active session ID
`xmlrpc_port`	The XMLRPC port associated with this Camera instance

active_application(self: ifm3dpy.device.LegacyDevice) → int

Returns the index of the active application.

A negative number indicates no application is marked as active on the sensor.

am_i(self: ifm3dpy.device.Device, family: ifm3dpy.device.Device.device_family) → bool

Checking whether a device is one of the specified device family

Parameters: family (CameraBase.device_family) – The family to check for
Returns: True if the device is of the specified family
Return type: bool

application_list(self: ifm3dpy.device.LegacyDevice) → dict

Delivers basic information about all applications stored on the device. A call to this function does not require establishing a session with the camera.

The returned information is encoded as an array of JSON objects. Each object in the array is basically a dictionary with the following keys: ‘index’, ‘id’, ‘name’, ‘description’, ‘active’

Returns: A JSON encoding of the application information
Return type: dict
Raises: RuntimeError –

application_types(self: ifm3dpy.device.LegacyDevice) → list[str]

Lists the valid application types supported by the sensor.

Returns: List of strings of the available types of applications supported by the sensor. Each element in the list is a string suitable to passing to ‘CreateApplication’.
Return type: list[str]
Raises: RuntimeError –

class boot_mode

Bases: None

Enum: Camera boot up modes.

Members:

PRODUCTIVE : the normal runtime firmware comes up

RECOVERY : allows you to flash new firmware

property name

cancel_session(*args, **kwargs)

Overloaded function.

cancel_session(self: ifm3dpy.device.LegacyDevice) -> bool

Explictly stops the current session with the sensor.

bool
Indicates success or failure. On failure, check the ifm3d system log for details.
cancel_session(self: ifm3dpy.device.LegacyDevice, sid: str) -> bool

Attempts to cancel a session with a particular session id.

sidstr
Session ID to cancel.

bool
Indicates success or failure. On failure, check the ifm3d system log for details.

check_minimum_firmware_version(self: ifm3dpy.device.Device, major: int, minor: int, patch: int) → bool

Checks for a minimum ifm camera software version

Parameters

major (int) – Major version of software
minor (int) – Minor Version of software
patch (int) – Patch Number of software

Returns

True if current software version is greater or equal to the value passed

Return type

bool

copy_application(self: ifm3dpy.device.LegacyDevice, idx: int) → int

Creates a new application by copying the configuration of another application. The device will generate an ID for the new application and put it on a free index.

Parameters: idx (int) – The index of the application to copy
Returns: Index of the new application
Return type: int
Raises: RuntimeError –

create_application(self: ifm3dpy.device.LegacyDevice, type: str = 'Camera') → int

Creates a new application on the camera of the given type.

To figure out valid type`s, you should call the AvailableApplicationTypes() method.

Upon creation of the application, the embedded device will initialize all parameters as necessary based on the type. However, based on the type, the application may not be in an _activatable_ state. That is, it can be created and saved on the device, but it cannot be marked as active.

Parameters: type (str, optional) – The (optional) application type to create. By default, it will create a new “Camera” application.
Returns: The index of the new application.
Return type: int

delete_application(self: ifm3dpy.device.LegacyDevice, idx: int) → None

Deletes the application at the specified index from the sensor.

Parameters: idx (int) – The index of the application to delete
Raises: RuntimeError –

class device_family

Bases: None

Enum: The family of the device

Members:

UNKNOWN

O3D

O3X

O3R

property name

device_parameter(self: ifm3dpy.device.Device, key: str) → str

Convenience accessor for extracting a device parameter

No edit session is created on the camera

Parameters: key (str) – Name of the parameter to extract
Returns: Value of the requested parameter
Return type: str
Raises: RuntimeError –

device_type(self: ifm3dpy.device.Device, use_cached: bool = True) → str

Obtains the device type of the connected camera.

This is a convenience function for extracting out the device type of the connected camera. The primary intention of this function is for internal usage (i.e., to trigger conditional logic based on the model hardware we are talking to) however, it will likely be useful in application-level logic as well, so, it is available in the public interface.

Parameters: use_cached (bool) – If set to true, a cached lookup of the device type will be used as the return value. If false, it will make a network call to the camera to get the “real” device type. The only reason for setting this to false would be if you expect over the lifetime of your camera instance that you will swap out (for example) an O3D for an O3X (or vice versa) – literally, swapping out the network cables while an object instance is still alive. If that is not something you are worried about, leaving this set to true should result in a signficant performance increase.
Returns: Type of device connected
Return type: str

export_ifm_app(self: ifm3dpy.device.LegacyDevice, idx: int) → list[int]

Export the application at the specified index into a byte array suitable for writing to a file. The exported bytes represent the ifm serialization of an application.

This function provides compatibility with tools like IFM’s Vision Assistant.

Parameters: idx (int) – The index of the application to export.
Returns: A list of bytes representing the IFM serialization of the exported application.
Return type: list[int]
Raises: RuntimeError –

export_ifm_config(self: ifm3dpy.device.LegacyDevice) → list[int]

Exports the entire camera configuration in a format compatible with Vision Assistant.

Return type: list[int]

factory_reset(self: ifm3dpy.device.LegacyDevice) → None: Sets the camera configuration back to the state in which it shipped from the ifm factory.

firmware_version(self: ifm3dpy.device.Device) → ifm3dpy.device.SemVer

Version of firmware installed on device

Returns: Firmware version
Return type: SemVer

force_trigger(self: ifm3dpy.device.Device) → None

Sends a S/W trigger to the camera over XMLRPC.

The O3X does not S/W trigger over PCIC, so, this function has been developed specficially for it. For the O3D, this is a NOOP.

from_json(self: ifm3dpy.device.Device, json: dict) → None

Configures the camera based on the parameter values of the passed in JSON. This function is _the_ way to tune the camera/application/imager/etc. parameters.

Parameters: json (dict) – A json object encoding a camera configuration to apply to the hardware.
Raises: RuntimeError – If this raises an exception, you are encouraged to check the log file as a best effort is made to be as descriptive as possible as to the specific error that has occured.

heartbeat(self: ifm3dpy.device.LegacyDevice, hb: int) → int

Sends a heartbeat message and sets the next heartbeat interval

Heartbeat messages are used to keep a session with the sensor alive. This function sends a heartbeat message to the sensor and sets when the next heartbeat message is required.

Parameters: hb (int) – The time (seconds) of when the next heartbeat message will be required.
Returns: The current timeout interval in seconds for heartbeat messages
Return type: int
Raises: RuntimeError –

imager_types(self: ifm3dpy.device.LegacyDevice) → list[str]

Lists the valid imager types supported by the sensor.

Returns: List of strings of the available imager types supported by the sensor
Return type: list[str]
Raises: RuntimeError –

class import_flags

Bases: None

Enum: Import flags used when importing a Vision Assistant configuration

Members:

GLOBAL

NET

APPS

property name

import_ifm_app(self: ifm3dpy.device.LegacyDevice, bytes: list[int]) → int

Import the IFM-encoded application.

This function provides compatibility with tools like IFM’s Vision Assistant. An application configuration exported from VA, can be imported using this function.

Parameters: bytes (list[int]) – The raw bytes from the zip’d JSON file. NOTE: This function will base64 encode the data for tranmission over XML-RPC.
Returns: The index of the imported application.
Return type: int

import_ifm_config(self: ifm3dpy.device.LegacyDevice, bytes: list[int], flags: int = 0) → None

Imports the entire camera configuration in a format compatible with Vision Assistant.

Parameters

bytes (list[int]) – The camera configuration, serialized in the ifm format
flags (int) –

property ip: The IP address associated with this Camera instance

class mfilt_mask_size

Bases: None

Enum: Convenient constants for median filter mask sizes

Members:

_3x3

_5x5

property name

class operating_mode

Bases: None

Enum: Camera operating modes

Members:

RUN : streaming pixel data

EDIT : configuring the device/applications

property name

property password: The password associated with this Camera instance

reboot(self: ifm3dpy.device.Device, mode: ifm3dpy.device.Device.boot_mode = <boot_mode.PRODUCTIVE: 0>) → None

Reboot the sensor

Parameters: mode (CameraBase.boot_mode) – The system mode to boot into upon restart of the sensor
Raises: RuntimeError –

request_session(self: ifm3dpy.device.LegacyDevice) → str

Requests an edit-mode session with the camera.

In order to (permanently) mutate parameters on the camera, an edit session needs to be established. Only a single edit sesson may be established at any one time with the camera (think of it as a global mutex on the camera state – except if you ask for the mutex and it is already taken, an exception will be thrown).

Most typical use-cases for end-users will not involve establishing an edit-session with the camera. To mutate camera parameters, the FromJSON family of functions should be used, which, under-the-hood, on the user’s behalf, will establish the edit session and gracefully close it. There is an exception. For users who plan to modulate imager parameters (temporary parameters) on the fly while running the framegrabber, managing the session manually is necessary. For this reason, we expose this method in the public Camera interface.

NOTE: The session timeout is implicitly set to ifm3d::MAX_HEARTBEAT after the session has been successfully established.

Returns

The session id issued or accepted by the camera (see IFM3D_SESSION_ID environment variable)

Return type

str

Raises

RuntimeError –
@throws ifm3d::error_t if an error is encountered. –

property session_id: Retrieves the active session ID

set_current_time(self: ifm3dpy.device.LegacyDevice, epoch_secs: int = -1) → None

Sets the current time on the camera

Parameters: epoch_secs (int, optional) – Time since the Unix epoch in seconds. A value less than 0 will implicity set the time to the current system time.

set_temporary_application_parameters(self: ifm3dpy.device.LegacyDevice, params: dict[str, str]) → None

Sets temporary application parameters in run mode.

The changes are not persistent and are lost when entering edit mode or turning the device off. The parameters “ExposureTime” and “ExposureTimeRatio” of the imager configuration are supported. All additional parameters are ignored (for now). Exposure times are clamped to their allowed range, depending on the exposure mode. The user must provide the complete set of parameters depending on the exposure mode, i.e., “ExposureTime” only for single exposure modes and both “ExposureTime” and “ExposureTimeRatio” for double exposure modes. Otherwise, behavior is undefined.

Parameters: params (dict[str, str]) – The parameters to set on the camera.
Raises: RuntimeError –

class spatial_filter

Bases: None

Enum: Convenience constants for spatial filter types

Members:

OFF

MEDIAN

MEAN

BILATERAL

property name

class temporal_filter

Bases: None

Enum: Convenience constants for temporal filter types

Members:

OFF

MEAN

ADAPTIVE_EXP

property name

to_json(self: ifm3dpy.device.Device) → dict

A JSON object containing the state of the camera

Returns: Camera JSON, compatible with python’s json module
Return type: dict
Raises: RuntimeError –

trace_logs(self: ifm3dpy.device.Device, count: int) → list[str]

Delivers the trace log from the camera

A session is not required to call this function.

Parameters: count (int) – Number of entries to retrieve
Returns: List of strings for each entry in the tracelog
Return type: list[str]

class trigger_mode

Bases: None

Enum: Image acquisition trigger modes

Members:

FREE_RUN

SW

property name

unit_vectors(self: ifm3dpy.device.LegacyDevice) → list[int]

For cameras that support fetching the Unit Vectors over XML-RPC, this function will return those data as a binary blob.

Return type: list[int]

who_am_i(self: ifm3dpy.device.Device) → ifm3dpy.device.Device.device_family

Retrieve the device family of the connected device

Returns: The device family
Return type: CameraBase.device_family

property xmlrpc_port: The XMLRPC port associated with this Camera instance