add example code for benchmarking tiling speed

Author: raacampbell

diagnostic/stage_motion_times/acquireAnalogWaveform.m

@@ -0,0 +1,112 @@
+function data = acquireAnalogWaveform
+    % Acquire analog waveform on an NI DAQ. Can be used to debug timing during tile scans.
+    %
+    % function data = acquireAnalogWaveform
+    %
+    % Purpose
+    % This function is a bit rough and ready but should do the job. You will need to change
+    % the DAQ name and maybe channel for your purposes. Copy file to a different location to
+    % do this. If you edit in place in the BakingTray path, then you will need to revert
+    % changes if you pull the latest version from GitHub. 
+    %
+    % This function comes from the 'vidrio' AI examples at https://github.com/SWC-Advanced-Microscopy/MATLAB_DAQmx_examples
+    % This code will NOT work with a vDAQ 
+    %
+    % 
+    % Inputs
+    % None -- please read through and edit the code to ensure you understand how it works
+    %
+    % Outputs
+    % data -- vector data values from the desired AI line.
+    %
+    %
+    % Rob Campbell - SWC, 2024
+    
+
+
+    %Define a cleanup function
+    tidyUp = onCleanup(@cleanUpFunction);
+
+    %% Parameters for the acquisition (device and channels)
+    devName = 'resscan';   % the name of the DAQ device as shown in MAX
+    taskName = 'hardAI';   % A string that will provide a label for the task
+    physicalChannels = 0;  % A scalar or an array with the channel numbers
+
+
+
+    % Task configuration
+    sampleRate = 1E3;     % Sample Rate in Hz (1 kHz is plenty for most purposes)
+    secsToAcquire = 10;   % Number of seconds over which to acquire data
+
+
+    try 
+        % Create a DAQmx task
+        hTask = dabs.ni.daqmx.Task(taskName); 
+
+
+        % Set up analog input on device defined by variable devName
+        hTask.createAIVoltageChan(devName,physicalChannels,[],-10,10);
+
+
+        % Configure the sampling rate and the number of samples
+        numberOfSamples = secsToAcquire * sampleRate; % The finite number of samples to acquire
+        hTask.cfgSampClkTiming(sampleRate,'DAQmx_Val_FiniteSamps',numberOfSamples,'OnboardClock');
+
+
+        %We configured no triggers, so the acquisition starts as soon as hTask.start is run
+
+
+        % Start the task and plot the data
+        hTask.start  % start the acquisition 
+
+        fprintf('Acquiring data...')
+        hTask.waitUntilTaskDone;  % wait till all requested samples are acquired
+        fprintf('\n')
+
+        % "Scaled" sets the input to be represented as a voltage value. 
+        % "Native" would have it be a raw integer (e.g. 16 bit number if this is a 16 bit DAQ)
+        data = hTask.readAnalogData([],'scaled',0); % read all available data 
+
+    catch ME
+       daqDemosHelpers.errorDisplay(ME)
+       return
+
+    end %try/catch
+
+
+    % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
+    function cleanUpFunction
+        %This runs when the function ends
+        if exist('hTask','var')
+            fprintf('Cleaning up DAQ task\n');
+            hTask.stop;    % Calls DAQmxStopTask
+            delete(hTask); % The destructor (dabs.ni.daqmx.Task.delete) calls DAQmxClearTask
+        else
+            fprintf('No task variable present for clean up\n')
+        end
+    end %close cleanUpFunction
+
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

diagnostic/stage_motion_times/readme.md

@@ -0,0 +1,67 @@
+# Stage Motion Times
+
+This folder contains code related to timing stage motions. 
+This can be used for debugging if you are concerned that your stages are moving too slowly, not enough time is being allocated to allowing them to settle, etc. 
+
+## Before starting
+
+Before running any code related to stage timing you should quit and restart MATLAB. 
+On a minority of rigs it has been observed that, over time, MATLAB/ScanImage/BakingTray, begins to slow down by factor of 2 or 3 and restarting MATLAB solves this. 
+
+For more accurate values you should have the stages assembled as an X/Y pair and a water bath filled to the typical level placed on top.
+
+It is also a good idea with PI stages to first test how long it takes for a step and settle motion in PI MikroMove. 
+You can generate graphs showing things like position over time, position error over time, etc. 
+This provides a really solid baseline indicating what to expect. 
+
+Once you are ready: start BakingTray at the MATLAB command line. 
+
+
+
+## Quick test of stage motion times
+Run `softwareTimedMotionTime.m` then make plots of the resulting output. 
+Read through the code before running the function! 
+You can edit variables in-line to change behavior.
+It is recommended to copy file to a new location to do this, otherwise you will have to revert changes before pulling the latest version of BakingTray when you want to update. 
+
+## Checking motion times in a tile scan
+You can start a tile scan in BakingTray without having to turn on the laser, the PMTs, make a directory, etc. 
+To do this:
+
+1. Open the Prepare Sample window
+2. Open the Preview window
+3. Hit "ROI" and draw a box in the area you want to tile scan
+4. Select "tiled: manual ROI" under "Scan Mode" in the main BakingTray window
+5. run `hBT.scanner.armScanner` to set up ScanImage for the tile scan
+6. run `hBT.runTileScan` to initiate and run the tile scan. You might need to press "Abort" in ScanImage to do more tile scans or disarm the scanner (below).
+7. run `hBT.scanner.disarmScanner` after the tile scan is finished and if you plan to do no more. 
+
+You can, for example, acquire the Y galvo signal to see how long it takes for each stage motion to complete. 
+You might want to set the number of Z planes to 1 for this. 
+The easiest way to decrease the step size of the stages should you need to, is to increase the zoom number in ScanImage.
+
+
+## Acquiring data from a tile scan 
+The `sitools.ai_recorder` class can be used to pull in data from an AI line while ScanImage runs. 
+Clone from https://github.com/BaselLaserMouse/ScanImageTools and read the docs. 
+It should be compatible with both the vDAQ and an NI DAQ. 
+T the Y galvo waveform into an AI line that is free and set up the AI recorder to acquire this. 
+You can either edit the class file, or instantiate the class and modify properties at the CLI. 
+To save data, check the Save checkbox in ScanImage and choose a directory to which data are to be saved. 
+Then run the tile scan as above. 
+The recorder will keep saving data to disk until you hit Abort in ScanImage. 
+You can use `readAIrecoderBinFile` to read data for analysis;
+
+You can find the interval between frames using MATLAB's findpeaks function:
+```matlab
+findpeaks(yData) % check visually if it looks right
+[pks,loc]=findpeaks(yData);
+plot(lok,pks,'.')
+%Then apply a threshold and get the times. e.g.
+timesOfPeaks = loc(pks>0);
+
+% Divide by the sample rate to get time in seconds
+timesInSec = timesOfPeaks / 1000; % in this case data were acquired at 1kHz
+plot(diff(peakTimes))
+
+``` 

diagnostic/stage_motion_times/softwareTimedMotionTime.m

@@ -0,0 +1,70 @@
+function out = softwareTimedMotionTime
+% Perform a bunch of blocking relative motions in X and Y and see how long they take
+% 
+% Inputs
+% none
+%
+% Outputs
+% A structure containing motion times in seconds
+%
+% Rob Campbell - SWC, 2024
+
+hBT = BakingTray.getObject;
+
+moveBySize = 1;
+nMotions = 100;
+
+xTimes = zeros(1,nMotions);
+
+fprintf('Doing X motions')
+for ii=1:nMotions
+	tic
+	hBT.moveXYby(moveBySize,0,true);
+	moveBySize = moveBySize*-1; % so next mostion is the other way
+	xTimes(ii)=toc;
+
+
+	if mod(ii,2) == 0
+		fprintf('.')
+	end
+
+	pause(0.5); % Because in practice we never rock and back forth with no delay
+end
+
+fprintf('\n')
+
+out.xMotionTimes = xTimes;
+
+
+
+
+yTimes = zeros(1,nMotions);
+
+fprintf('Doing Y motions')
+for ii=1:nMotions
+	tic
+	hBT.moveXYby(0,moveBySize,true);
+	moveBySize = moveBySize*-1; % so next mostion is the other way
+	yTimes(ii)=toc;
+
+	if mod(ii,2) == 0
+		fprintf('.')
+	end
+
+	pause(0.5); % Because in practice we never rock and back forth with no delay
+end
+
+fprintf('\n')
+
+
+
+% Build output structure
+out.xMotionTimes = xTimes;
+out.yMotionTimes = yTimes;
+
+
+
+
+
+
+