ScanImage 2019 : ROI Integration Output Channels

ScanImage can use the Integration Outputs to drive software, analog or digital outputs. A user defined function is called to generate an output value from a list of selected Integration ROIs.

Channel Configuration

To configure output channels, open the Machine Configuration Editor section 'Closed-Loop Experiment Outputs'. Each output channel can be of one of the following types:

 Daq NameChannel IDDescription
SoftwareNoneNoneDoes not generate an output, just calls the user defined output function
Analog Output<DAQ Name>AOxOutputs an analog signal on the specified analog output
Digital Output<DAQ Name>PFIxOutputs a digital signal on the specified PFI channel
Icon

A 'Software' output channel does not require any data acquisiton hardware. It can be used with the ScanImage API to control the Acquisition, similar to a User Function.

Icon

After configuring the output channels in the machine configuration editor, ScanIage needs to be restarted to apply the changes.

Configuration Editor

 Configuration of three output channels: (1) Software (2) Analog Output (3) Digital Output; The Channel Name can be chosen arbitrarily.

 

 

Output Configuration

Each output channel can be configured to process the the value of multiple integration ROIs. In the Integration Controls, select the ROIs to be passed to the output function.

The output function needs to accept the following inputs:

input namedescription
vals1xN array of integration values of the selected ROIs
vararginadvanced parameters

The output function needs to generate the follwing outputs:

 Function outputDescription
Software ChannelEmpty array []Any output by the function is ignored
Analog ChannelNumeric scalar within range -10..10Voltage level to drive the analog output
Digital ChannelLogical scalarLogic level to drive the digital output

The physical channels are only updated when the output value changes (i.e. if the function generates the same output multiple times, the physical channel is only update once).

Icon

Updating the physical channel is a blocking call in Matlab. This means that the Matlab execution needs to wait until the update is completed. To improve performance and reduce latency, PCI(e)/PXI(e) are preferable over USB devices.

Icon

Since the ROI Integration and output calculation is done in Matlab, there is a time delay between the frame acquisition and the channel output on the physical DAQ board.

Channel Output Configuration

The output channel 'Analog Output 1' is configured to output the average of Cell2 and Cell 3.

 

 

User defined output function

Instead of the default anonymous function, ScanImage can call a function defined in a .m file on the path. To call a function, replace the anonymous function call as follows:

Output function call
@(varargin)myOutputFunction(varargin{:})

The user defined output function can be used to perform a variety of tasks. The following example averages all passed integration values and 

Example output function
function outputVal = myOutputFunction(vals,varargin)
  persistent hLine
  persistent history
  persistent historyPointer
  historyLength = 100;

  if isempty(hLine) || ~isvalid(hLine)
    hFig = figure();
    hAx = axes('Parent',hFig,'XLim',[1,historyLength]);
    hLine = line('Parent',hAx,'XData',NaN,'YData',NaN,'Color','b');
  end

  if isempty(history) || length(history) ~= historyLength
    history = nan(1,historyLength);
  end

  if isempty(historyPointer) || historyPointer > historyLength
    historyPointer = 1;
  end

  outputVal = mean(vals); % calculate the output value by averaging all input values
  history(historyPointer) = outputVal;
  historyPointer = historyPointer + 1;
  if historyPointer > historyLength
    historyPointer = 1;
  end
 
  history(historyPointer) = NaN;
  
  hLine.XData = 1:historyLength;
  hLine.YData = history;
end
Plot generated by myOutputFunction

Plot generated by myOutputFunction