Configuration Guide

Motif is optimized for regular and consistent use in an experimental setting. This means that most configuration options are not accessible from the user interface (so they can not accidentally be changed between experiments) and are instead stored in the configuration file(s).

Note

Motif is supported software. If you have any difficulties configuring it, or would prefer we assist with configuration, please contact support@loopbio.com

There are three configuration files, in per-platform specific locations. The main configuration file you need to worry about, on Linux, is /etc/recnode.yml. On Windows this file is located at C:\ProgramData\Motif\recnode.yml.

In the multiple-camera case, in addition to /etc/recnode.yml, two other configuration files are (optional, can be) used to further change the appearance of only the web user interface of the individual cameras.

When the multiple-camera interface starts other cameras it parses the following files in the following order (using the Linux configuration file paths for example)

1. /etc/recnode.yml
2. /etc/recnode.multicam.yml
3. /etc/recnode.CAMERA_SERIAL_NUMBER.yml

Thus later files replace earlier files. This means that you can overwrite the 'default' /etc/recnode.yml configuration for all cameras, or per camera, by putting changed settings in the other configuration files. For example, you might want to disable control of individual camera UI elements using the various EnableXXX configuration options in a multiple-camera setup by adding / replacing these configuration values to only the per-camera configuration files.

Configuration Files and Syntax

The configuration files are YAML format.

• The Configuration file is explained here
• An example configuration file (un-annotated) is here
• Advanced configuration tips and tricks are collected here

Tip

Motif needs to be restarted to detect configuration file changes. If your Motif system is linux based, you can restart the entire Motif software without having to restart the computer by executing the command $ sudo systemctl restart supervisor.service

Configuration Values

Despite the existence of a number of industrial standards for cameras, different camera manufacturers still use different parameter names and values for similar settings. If you are unsure why a setting is not working on your camera, please contact loopbio support for guidance.

Complex Properties

Certain camera parameters do not map into the single value paradigm. For example, configuring the IO on basler cameras requires setting several individual parameters in order. To support these sorts of camera properties per camera, parameters in the Camera section which start with Motif, i.e MotifResetFactoryDefaults, will be passed to the camera via set_complex_property. A list of the complex properties and their support in the different backends.

MotifXXX Parameter	R/W	pylon	spinnaker	arena
PTPFrameRate	W	x
EnableChunkTimestamp	W	x	x(^1)
ResetFactoryDefaults	W	x	x
LoadConfigurationSet	W	x
Line0Configure	W		x
Line1Configure	W	x*	x
Line2Configure	W	x*	x
Line3Configure	W		x
Line2Set	W	x	x
PTPStatus	R	x
Line1Get	R	x	x
PhotoMode	R/W	O	O	O
TakePhoto	W	O	O	O
Framelapse	R/W	O	O	O
MulticamFrameRate	R	O	O	O
IsExternallyTriggered	R	O	O	O
Uptime	R	O	O	O
EstimatedFrameRate	R	O	O	O
GPUId	W	O	O	O
SpinnakerBalanceRatio	W		O
BaslerBalanceRatio(^2)	W	x
ImageRotate	W	O	O	O
ImageRotateExpand	W	O	O	O

Key:

• x : supported
• x* : partially supported
• O : supported, backend independent

Notes:

• ^1 : when unset, returns a synthesized frame timestamp. This is the local system time.time() but is
  using the chunk frame time difference plus the system time at the first frame. this is a backwards
  compatibility behavior and will be removed in future. Set the value explicitly to true or false to
  achieve standard behavior of returning either time.time() or the chunk timestamp.

Synchronized and Multiple Camera Configuration

The settings in Multicam configuration mostly concern the triggerbox

• TriggerDevice - /dev/ttyUSB0 for example
• StartRecordingDIO - start recording upon change of this digital input
• SynchronizeOnRecordStart - if true, automatically synchronize cameras before starting recording. This guarentees that stores start at frame_number 0.
• AllowManualSynchronization - show a 'Synchronize Cameras` button and allow users to manually synchronize and thus reset camera frame_number=0. Note: you can only synchronize once per recording, so that only one frame_number=0 is present in a store.

Note

This section applies only to versions of Motif 5.2 or newer

When configuring a synchronized multiple camera Motif system there are a number of small differences in how individual cameras should be configured. Beginning with camera configuration, please note the following

• Camera Configuration
• set AcquisitionFrame to null
• If you are using a loopbio provided triggerbox set MotifMulticamFrameRate to the desired framerate in /etc/recnode.yml
• If you are using Basler cameras synchronized over PTP set MotifPTPFrameRate to the desired framerate in /etc/recnode.yml
• If you are using hardware synchronized cameras but are providing the trigger signal externally, you can set MotifMulticamFrameRate to your external framerate if you wish to receive warning, for example, when an impossible exposure time is selected

Depending on the combination of trigger backend and camera type, you might need to adjust some multicam specific settings

• If using FLIR cameras with the trigger signals on Line0 (Camera: TriggerSource: 'Line0') and a loopbio triggerbox, then you should also set `'CameraTriggerSource': 'Line0' in Multicam / Trigger / BackendConf
• If using the baslerptp trigger backend, cameras are detected to be 'synchronized' when their PTP timestamps are in agreement to a certain precision
• The serial numbers of all cameras to be PTP synchronized must be listed in the Multicam setting CameraSerials
• To change the required precision of time agreement, you can adjust the Multicam / Trigger / Backend Conf setting MaxOffsetFromMaster (it is in nanoseconds and defaults to 100)

Upon synchronization and after successful connection of the trigger box, Motif attempts to automatically configure all cameras to be hardware or externally triggered, specifically by setting the following parameters in this order

• 'CameraAcquisitionFrameRateEnable'=False
• note: CameraAcquisitionFrameRateEnable can be changed to CameraAcquisitionFrameRateEnabled by setting CameraAcquisitionFrameRateEnableProperty to CameraAcquisitionFrameRateEnabled in Multicam / Trigger / BackendConf
• 'TriggerMode'='On'
• 'TriggerSource'='Line0'
• note: LineX can changed from the defailt Line0 by setting CameraTriggerSource property in Multicam / Trigger / BackendConf

This is done for all connected cameras unless CameraSerials is provided, in which case it acts as a whitelist and only the listed camera serial numbers are configured to ensure external triggering.

Automatically Connecting Cameras

It is possible that in multicamera setups, Motif can automatically connect 'start' cameras as they are detected / plugged in. To enable this feature, set the Multicam setting AutoStartCameras: true. To restrict this behaviour to certain cameras only, you can enter their serial numbers in CameraSerials and ensure that AllowStartingBlacklistedCameras is false (the default).

Changing the Framerate

With caveats, the current camera framerate can be changed via the AcquisitionFrameRate property in the single-camera case, and via the MotifMulticamFrameRate property in the multiple synchronized camera case.

Changing Configuration While Running

Some camera configuration parameters can be changed while the camera is running, with the exception of any settings that change the camera resolution. Motif does not support dynamic resolution changes.

To change camera settings you can use the API api.call('cameras/configure', AcquisitionFrameRate=10), or you can use the command line client from the terminal on the PC $ recnode-control --configure 'AcquisitionFrameRate=10'