Skip to content

Advanced Configuration Tips

General Concepts

  • Motif by default always sets selected camera parameters to sensible defaults. If you wish to change these values, you may nauturally override them in your config file, if however you need to disable setting the value at all (see note about standards below), then you can set the parameter to the value none. The default values are;
    • ExposureAuto: 'Off'
    • ExposureTime: 20000.0
    • GainAuto: 'Off'
    • Gain 0.0
    • AcquisitionFrameRateEnable: true
    • AcquisitionFrameRate: 150.0
  • If you need to set a camera parameter to 'On' or 'Off', you must use quotes because otherwise YAML translates the values to boolean. E.g. you must write DeviceLinkThroughputLimitMode: 'On' in the config file

Further Explanations of Certain Parameters

  • If specifying a ipv6 custom CopyLocations then the username must go in the square brackets [user@foo:bar]:/path/to/thing
  • Depending on the value or presence of RecordToStore, StoreCodecs and ExportCodecs you can control what recording options the user can select. These options are set in Recording configuration section.
  • if RecordToStore = true the user can record to a store files or to a store of compressed movies. Stores hold complete metadata (frame number, timestamp, camera setting, extra data, etc). To configure the type of data in the store fill out StoreCodecs.
  • StoreCodecs is a dictionary {name_to_show_to_user: store_format}
  • To store to uncompressed numpy arrays, use something like {'raw': 'npy'}
  • To store to compressed movies, use something like {'mp4': 'libx264'}
  • If RecordToStore = false then the user can real-time encode movies using ffmpeg. In this case, the GUI lists those codecs available in RecordCodecs. Metadata is recorded into comments in the file header. RecordFPS defines the framerate of the video files. If this is set to < 0 then the currently estimated true acquisition framerate is used.
  • StoreCodecs is a dictionary {name_to_show_to_user: movie_codec}
  • To store to compressed movies, use something like {'mp4': 'libx264'}
  • If Recording ExportCodecs = {} or RecordingEnableExport = False then the GUI shows no options to export stores to later compressed formats.
  • Otherwise provide ExportCodecs in the same format as above
  • To export to compressed movies, use something like {'mp4': 'libx264'}

You can specify different arguments to be passed to rsync depending on if the destination is local or remote. Note: --partial and --recursive are always passed. Some suggested configuration strategies include

  • if you store in stores, with 1000's of files, you can use --info=progress2 --no-inc-recursive.
  • if you store to large files, and not stores, use --progress instead
  • if you copy mainly to usb disks with weird filesystems that don't preserve modification times, add --size-only to RsyncArgsLocal. For the opposite behaviour and maximum safety, you can specify --checksum instead.

Motif can be configured to add files to loopy after the copy process. This is controlled by the Playback configuration settings + LoopyURL=http://xx:xx, LoopyAPIKey and LoopyImportBasePath variables.

The visibility of many UI elements can be controled with the EnableXXX keys in the Recording and in the Playback configuration. You might want set one or more of these to false in a multi-camera setup to disable features on the single-camera pages.

Extra Metdata

This is metadata that the user may (or must) fill out in the UI before they may start recording. It is configured using ExtraMetadata in the Record section of the config file

ExtraMetadata is a list of 2 or 3 elements. The elements of the list are interpreted as follows

  1. the name of the metadata field to be collected
  2. if it is a single line of text (or a single word)
  3. (optional) if it is compulsory or not.

Compulsory metadata fields must be filled out before recording. For example, the following example features; a single line 'title' field, multiple line 'description' field, and a single compulsory (must be entered before recording can be started) 'genotype' field;

- - title
  - true
- - description
  - false
- - genotype
  - true
  - true

Note, the special metadata name title, if supplied (the default), value is prepended to the resulting movie/store name. For example if the user supplies 'foo', then the filename will be foo_20170123.mp4 (according to your correct date etc)

Camera Specific Config

In multiple camera configurations, additional per-camera configuration files - recnode.SERIAL.yml;, explained here

Camera Configuration Pitfalls

Thanks to the power of standards, there are several traps when setting camera values.

  • certain cameras do not support AcquisitionFrameRateEnable, but rather use AcquisitionFrameRateEnabled (note the d). In this case should disable setting of AcquisitionFrameRateEnable. e.g

    • AcquisitionFrameRateEnable: none
    • AcquisitionFrameRateEnabled: true
  • If you are having trouble with network cameras, you might need to set ExposureTimeAbs instead of ExposureTime.

High Performance Tips

For some very demanding situations such as multiple very high resolution cameras at high framerates, certain camera CameraStream specific configuration may be required. However, please note that not all settings are supported on all backends or all operating systems.

Basler Cameras (Linux only)

You could try adding the following settings to the CameraStream config section.

  • set MaxTransferSize=XXX to increase the size of the buffer used when transferring data
  • increase the priority of the internal threads
    • set InternalGrabEngineThreadPriority=XX where XX should be ≥ 25
    • set GrabLoopThreadPriority=XX where XX should be ≥ 24
    • InternalGrabEngineThreadPriority must be ≥ GrabLoopThreadPriority


Changes to these low level values will affect the compression performance by moving more system resources to image acquisition rather than compression. Be careful to ensure that the compression settings are still compatible with the camera framerate and that the buffer does not become full while recording.