recnode.example.yml

#

This is only part of the Motif documentation

The configuration file is split into several sections

If a config settings was added after a Major release (e.g version 4 or version 5), the version number at which the config setting is supported is indicated in brackets e.g. [5.1]

---
#

Camera Configuration

The Camera section sets default configuration options. The name and value of these settings are typically from the GenICam Standard Feature Naming Convention. The name and value of these settings can be taken from the camera provided configuration tool if required (SpinView or Pylon)

Camera:
  AcquisitionFrameRate: 150.0
  AcquisitionFrameRateEnable: true
  ExposureAuto: 'Off'
  ExposureTime: 20000.0
  Gain: 0.0
  GainAuto: 'Off'
#

This section defines configuration sliders that appear in the User interface to allow adjusting the above default values at runtime. For example

CameraRange:
  AcquisitionFrameRate:                   # Parameter name (should correspond to that above)
  - 10.0                                  # Minimum parameter value (for the slider)
  - 165.0                                 # Maximum parameter value
  ExposureTime:
  - 500.0
  - 30000.0
  Gain:
  - 0.0
  - 15.0
#

[5.1] This section defines low level ‘Transport Stream’ parameters for the camera manfacturer backend and should not need to be set otherwise. This is only supported for some camera manfacturers

CameraStream: {}
#

Common Configuration

Common configuration options which conceptually apply to the camera, playback and other UI tabs

Common:
  APIKey: ''                              # API key required for the REST API (if omitted a system specific default is used)
#

HTTP authentication is enabled if both settings here are provided for the web user interface

  AuthPassword: ''                        # HTTP password
  AuthUsername: ''                        # HTTP username
  CameraCriticalTemperature: 75           # Maximum camera temperature before warnings are shown in the UI
#

The following CameraPreview settings define the quality and rate of the camera live view in the user interface

  CameraPreviewFPS: 3                     # Framerate while recording (while in the Configure tab it is 2x this value)
  CameraPreviewQuality: 95                # JPEG quality (compression)
  CameraPreviewWidth: 600                 # Width while recording (while in Configure tab the image is full size)
  CameraPreviewZoomPercent: 40            # [5.1] Percentage to zoom into the centre of the image in the Configure tab
#

[5.1] Web browsers per default apply an interpolation algorithm to images. While this reduces the pixelated appearance of images, it can be misleading wrt. the true image quality. You can disable this by setting this value to true (disable all the time), null (disable only on Configure tab), or false (do not disable, i.e. the behaviour in Motif versions earler than 5.1

  CameraPreviewDisableBrowserInterpolation: false
  CameraFullsizePreviewWidth: 0           # [5.2] If greater than zero, the width of the full-size camera preview
  CameraSerial: ''                        # In single-camera mode, connect only to this camera
  DiskFullThresholdPercent: 93            # Stop and disable recording if the disk is `>=` this full (percent)
  ExtraCSS: []                            # [5.2] Extra CSS to style UI
#

The following settings define the behaviour of the ‘Experimental Scripts’ in Motif 5, which allow launching user defined scripts from the user interface which can control or program Motif itself, or perform realtime or other user defined processing of images or IO data

  EnableExperimentScripts: true           # Enable/disable script execution (and hide associated UI widgets)
  ExperimentScriptsDirectory: ''          # Directory to look for experiment scripts
  ExperimentScriptsExtension: .py         # Allowed script file extension
  ExperimentScriptsInterpreter: ''        # Path to binary / program to execute scripts (defaults to Python2.7)
  ExperimentScriptsExtraArguments: ''     # Extra arguments to pass to the interpreter
  ExperimentMetadata: {}                  # [5.1] Metadata to be passed to experiment scripts (the format is the same as `ExtraMetadata`, below)
  EnableScheduler: true                   # Enable/disable showing/clearing scheduled operations from the UI
  Mode: ''                                # Motif operation mode (Windows only)
  Name: ''                                # Name of this recording system to show in the UI (defaults to hostname)
#

These settings define how the user interface is made available over the network

  NetworkIP: 127.0.0.1                    # Make the UI available only on this address (if not specified, see below)
  NetworkInterface: ''                    # ... alternatively make the UI available on this interface, at whatever IP address
  NetworkPort: 8081                       # Make the UI available on this port
  Peers: []                               # List of 'slave' Motif addresses (if running in multi-camera 'master' mode)
  ShowSaturationAbove: 0                  # If set, always color saturated pixels in the user interface
#

These settings control the realtime image stream

  StreamEnable: false                     # Enable or disable the realtime stream
  StreamEvery: 1                          # Stream every nth frame
  StreamHost: 127.0.0.1                   # Make stream only available at this address
  StreamInterface: ''                     # [6.1.5] Make stream available at the address of this interface
  StreamWidth: -2                         # Resize the stream to this many pixels (if `>0`). If `<0` then resize to 1/X this value (i.e. -2 = 1/2 width)
  StreamResizeInterpolation: null         # If resizing, use this method to scale the image
  TemperatureSensor: ''                   # Additionally show this system (lm-sensors name) temperature sensor in the UI
  Timezone: ''                            # Timezone of the system (recorded in the imgstore or movie file)
  WebBrowser: ''                          # [6.1.5] Use this webbrowser to open the motif UI
#

IO Configuration

This section defines the IO configuration of Motif. The IO backend can be used to store data in image stores or to control outputs (such as ‘flash this LED’) using the scheduler, the API, or from experimental scripts.

IO:
  EnableIO: true                          # Enable the IO feature and UI elements
  EnableWriting: true                     # Enable automatic writing of all IO inputs and outputs to files along side the current recording
  ProcessPriority: null                   # [5.2] Additional high-priority hint for IO process (advanced use only)
  Backend: ''                             # Which IO backend is connected to this system (phidgets, zmq, http, etc)
  BackendConf: {}                         # Backend specific configuration
#

In addition to the configured IO backend, an additional HTTP address can be provided which allows the insertion of external data along side the current recording. This HTTP address should return a JSON response. Any data returned is then written to a json file, along with the current frame number and timestamp

  ExtraDataURL: ''                        # URL, must return JSON from GET request
  ExtraDataFreq: 1                        # Make get requests at this frequency (maximum 10Hz)
#

A list of configured outputs for the backend. Outputs are things which can be controlled such as digital or analog outputs, LEDs, servos, etc. While backend specific, the dictionary should have have at least a ‘name’ entry. e.g

Outputs:
- {name: 'led'}

  Outputs: []
#

Sensors are named elements whose values are read and included in the output file the IO backend writes While backend specific, the dictionary should have at least a name and fs entry. e.g

Sensors:
- name: voltage
  fs: 1
- name: temperature
  fs: 20

  Sensors: []
#

The previous Output and Sensor sections define the actual connected devices, whereas the UI subsection describe which of the defined devices are shown in the UI - either their most recent value (in the case of sensors), or as a slider which allows them to be manually controlled (in the case of outputs)

  UI:
#

A list of dictionaries with the following keys

Outputs:
- default_val: 0
  label: LED
  max_val: 1
  min_val: 0
  step: 0.1
  name: led

Note that step defines the default increment of the slider. for a switch set min_val=0, max_val=1, step=1

    Outputs: []
#

A list of dictionaries containing at least a name key (which corresponds to the named Sensor from above

Sensors:
- {name: 'voltage'}

    Sensors: []
#

Multiple Camera Mode Configuration

Settings specific to multiple camera master / master + slave configurations

Multicam:
  AllowManualSynchronization: false       # Allow in the UI (add a button) manual multiple camera synchronization (resetting of camera frame_number=0)
  StartRecordingDIO: ''                   # Start recording upon this change of camera DIO line (deprecated)
  SynchronizeOnRecordStart: true          # Automatically synchronize cameras upon recording start
  CameraSerials: []                       # [5.2] Whitelist only these camera serial numbers in a multi-camera setup
  AllowStartingBlacklistedCameras: false  # [5.2] The whitelist should prevent detected cameras from being started
  AutoStartCameras: false                 # [5.2] Automatically start locally connected cameras
  TriggerDevice: ''                       # Hardware device of loopbio trigger device (deprecated)
#

[5.2] To configure the hardware trigger a backend and any backend specific configuration should be added. This setting replaces ‘TriggerDevice’ above

  Trigger:
    Backend: 'none'                       # Accpted values; 'camtrigger' (loopbio trigger hardware device), 'baslerptpd'
    BackendConf: {}                       # 'Device' (the serial port) is required for 'camtrigger'.
#

Playback Configuration

Settings which control playback, copy, export and montage operations of the software, or the appearance of the Export/Copy/Review tab in the user interface

Playback:
  EnableCopy: true                        # Enable copying recordings to locations other than that which they are recorded to
  CopyLocations: []                       # List of pre-configured locations to allow the user to copy to
#

Copy functionality uses rsync. Additional arguments can be passed here to customize its behaviour, such as limiting the bandwidth or making permission adjustments. The default arguments are below

  RsyncArgs:                              # Arguments applied in all cases
  - --partial
  - --info=progress2
  - --no-inc-recursive
  - --recursive
  RsyncArgsLocal:                         # Additional arguments applied when the location is a locally mounted drive / path
  - --size-only
  RsyncArgsRemote: []                     # Additional arguments applied when the location is on another PC (rsync protocol)
  CopyToRemovableDisk: true               # Enable copying to removable disks when inserted
  RemovableDiskMountPrefix: /media        # On linux, also consider disks mounted under this prefix removable
  EnableEject: true                       # Enable ejecting removable disks
  EnableMove: true                        # Enable move operation (a Copy followed by deleting those recordings which copied successfully)
#

Export functionality is the operation of converting an imgstore, usually an uncompressed one, into another format. This is usually necessary when recording at framerates and resolutions too high for realtime compression

  ExportAll: false                        # Enable 'Export All', where all videos can be converted at once
  ExportDeleteAfter: false                # If true, original videos will be deleted after successful export
  ExportToRemovableDisk: false            # If true, allow direct exporting to the selected removable disk (Export + Move in one step)
  ExportToStore: false                    # If enabled, export to imgstore (instead of to files)
#

Motif can be integrated with Loopy to allow automatic importing into loopy after recordings are copied or moved to another location

  LoopyAPIKey: ''                         # A private loopy instance system or user API key
  LoopyImportBasePath: ''                 # Recordings are copied to a configured location, which is configured in loopy at this path
  EnableLoopyUpload: false                # [5.2] Enable upload to a loopy server
  LoopyURL: ''                            # The URL (http://ip:port or http://address) of the loopy instance
#

Recording Configuration

The record section controls operation of the recording process, that is the part of Motif which talks to the configured camera, acquires images, and performs realtime compression

Record:
  Backend: pylon                          # The camera manufacturer backend (pylon, pypylon, spinnaker, ximea, axis, pycapture2, etc)
  BackendConf: {}                         # Backend specific additional configuration
  CameraGrabThreadPriority: null          # [5.1] Additional high priority hint for motif camera grab thread (advanced use only)
  CameraProcessPriority: null             # [5.1] Additional high priority hint for motif camera process (advanced use only)
  Directory: /home/loopbio/DATA           # The directory to save recordings in
  EnableExport: false                     # Enable the export functionality - converting from a raw recording to another compressed format
#

Configured codecs for the export operation, same format as RecordCodecs

  ExportCodecs:
    h264-hq: libx264-crf10-uf
    h264-lossless: libx264-ll-uf
    h264-lq: libx264-crf23-mf
    h264-mq: libx264-crf20-uf
  ExportCodecDefault: ''                  # The default codec name (from `ExportCodecs`) for the export functionality
  ExportFPS: 25
#

This section defines additional text boxes which are shown in the UI that the user may enter to describe the recording, for example ‘genotype’, ‘treatment’, etc. This is a list of 2-tuples or 3-tuples (if 2-tuple, the metadata is not compulsory)

- - name_of_field
  - single_line  # true: single-line text box
  - compulsory  # true or false

  ExtraMetadata:
  - - filename                            # the filename metadata is slightly special, it is the filename prefix of the recording
    - true
  - - description
    - false
  FFmpegPath: null                        # Full path to ffmpeg binary. If omitted, use the system copy
  FFmpegNumThreads: null                  # [5.2] Limit ffmpeg encoding to this many threads per recording (default: unlimited)
  OpenCvNumThreads: null                  # [6.0] Limit OpenCV to this many threads (default: unlimited)
#

The following two settings allow Motif to undistort images according to a provided camera calibration file

  IntrinsicCalibrationFile: null          # [6.0] Path to calibration file (generated in Loopy)
  UndistortionAlpha: 0                    # [6.0] Scaling parameter concerning fitting the undistorted image into the original frame
#

In multi-camera setups, Motif can create synchronized multi-camera montage videos from matching recordings

  EnableMontage: false                    # Enable montage creation
  MontageCodec: libx264-maxcompat         # Codec identifier to be used during montage creation
  MontageFPS: -1                          # Framerate of montaged video (if -1, use framerate of original recordings)
  MontageMaxWidth: 4096                   # Limit montages to this maximum width (are scaled down)
#

These settings define the performance and operation of the core feature of Motif, recording video

  EnableRecord: true                      # Enable (show) the record button in the Ui (useful to disable in certain multi-camera setups)
#

Motif keeps a buffer of a number of frames in memory to account for variations in ease of compression of certain frames, or of computer utilisation

  QueueLen: 1000                          # Keep a maximum of this many frames of video in memory when recording.
  QueueMemoryLimitMB: 0                   # If `>0`, replaces `QueueLen`. Limit the buffer to consume not more than this many megabytes of memory
  RecordingIndicator: null                # [5.2] Indicate that the camera is recording. Supported values; 'Line2High'. 'Line2Low' uses the camera IO line
  RecordingStart: null                    # [5.2] Start recording upon this change. Supported values: 'Line1High', 'Line1Low'
#
Recording Codecs

A list of dictionaries, codec_name: codec_identifier. The codec_identifier is considered an implementation detail and may change across versions of the software. They define the compression parameters. The codec_name is the value the user sees in the software and which is used in the API

note: in a multiple camera setup you can have different configurations per camera, with the same codec_name using different codec_identifiers. This can be helpful, for example if you have insufficient GPU resources to encode all cameras on the GPU and must use CPU compression for some cameras

  RecordCodecs:
    h264-hq: libx264-crf10-uf
    h264-lq: libx264-crf23-mf
    h264-mq: libx264-crf20-uf
  RecordCodecDefault: h264-mq             # The default codec name (from `RecordCodecs`)
  RecordFPS: 25                           # Videos (non-imgstores) are recorded at this framenumber, if `-1` then record at the native acquired framerate
#

Motif can record to imgstore, which is a codec and framerate independent storage format for video and other data. It is optomised to synchronizing multiple cameras recording at once, and for integrating other data, such as from the IO backend.

In a multiple-camera configuration, or one with IO, this should be true, in single-camera or other setups this can be false, or user to allow the user to decide each recording

  RecordToStore: user                     # Possible values: true, false, or user
  StoreChunkSize: 10000                   # Each chunk of the imgstore contains this many frames
#

Configured codecs when recording to imgstore, same format as RecordCodecs

  StoreCodecs:
    h264-hq: libx264-crf10-uf
    h264-lq: libx264-crf23-mf
    h264-mq: libx264-crf20-uf
    raw: npy
  StoreCodecDefault: h264-mq              # The default codec name (from `StoreCodecs`)