LWDAQ Command Reference

Contents

Introduction

When it starts up, LWDAQ installs hundreds of TCL/TK commands for use in instruments and tools. The script commands are those installed by the TCL/TK scripts that LWDAQ runs at start-up. The library commands are those installed by the lwdaq.so shared library that LWDAQ loads at start-up. This library has been compiled from our Pascal source code. Script commands all begin with LWDAQ in upper case letters, while library commands all begin with lwdaq in lower case letters.

The TCL/TK scripts define the script commands are in the ./LWDAQ.app/Contents/LWDAQ directory of the LWDAQ software installation, and its sub-directories. You will also find them on our Sources Page. Here is a list of the LWDAQ Scripts.

Click on any one of the script names, and your browser will take you down the page to a section dedicated to this script and the LWDAQ script commands it defines. We give the TCL declaration of each command, and the description in TCL comments above the declaration in the script. If you do not understand the TCL declaration, search for an "Introduction to TCL/TK Programming" on the web, and look up the syntax for procedure declarations.

The Pascal files that define the library commands are in the ./Sources directory. Each operating system has its own version of lwdaq.so, but all versions define the same commands. Each library command takes some mandatory parameters, and a list of optional parameters. You specify the mandatory parameters by passing their values directly to the command, in the correct order. You specify optional parameters with a list of option names in the form "?option value?". You can specify any number of these options, and in any order. Here is an example library command call from the Rasnik instrument script.

set result [lwdaq_rasnik $image_name \
	-show_fitting $config(analysis_show_fitting) \
	-show_timing $config(analysis_show_timing) \
	-reference_code $config(analysis_reference_code) \
	-orientation_code $config(analysis_orientation_code) \
	-pixel_size_um $info(analysis_pixel_size_um) \
	-reference_x_um $info(analysis_reference_x_um) \
	-reference_y_um $info(analysis_reference_y_um) \
	-square_size_um $config(analysis_square_size_um) ]

The lwdaq.pas file acts as an interface between our Pascal libraries and TCL/TK. It provides init_Lwdaq, which TCL/TK calls when it loads the lwdaq dynamic library, and it defines all the library commands. The init_Lwdaq routine installs these commands in the TCL interpreter. The lwdaq.pas file is a Pascal main program rather than a Pascal unit, even though we compile it into a dynamic library. The GPC compiler expects a main program if it is to include the "_p_initialize" routine in the compiled object. We will need this routine to be present in the lwdaq.o object when we link the final lwdaq.dylib dynamic library with GCC.

The lwdaq command (lower case) grants access to a selection of mathematical routines declared in our Pascal library. We call these the lwdaq routines to distinguish them from the lwdaq commands, of which lwdaq is an exmaple. The following command calls our linear interpolator on a set of x-y data pairs to estimate the value of a curve at x=2.

lwdaq linear_interpolate 2 "0 0 3 3 6 6"

You will find a list of the routines available through the lwdaq command in a table below, as well as descriptions of each of them.

The image parameters taken by many of the library commands are the names of images in the LWDAQ image list. This list of images is maintained in memory by the library commands. Each image contains its pixel intensities and an overlay in which the library routines can draw lines. You draw an image in a TK photo widget with lwdaq_draw. First lwdaq_draw renders the pixel intensity in the photo, and then it renders the overlay. The same image can be rendered in multiple TK photos. When an instrument captures consecutive images from a data acquisition system, it is deleting previous images (now redundant) from the LWDAQ image list, creating a new image, filling it with the acquired pixel intensities, and rendering the image in the same TK photo in the instrument window.

Library Commands

lwdaq_bcam

lwdaq_bcam image ?option value?

lwdaq_bcam finds spots in images. It is called by the BCAM Instrument and the Dosimeter Instrument. The routine clears the image overlay for its own use.

The lwdaq_bcam routine makes a list of spots in the image. The -threshold string tells lwdaq_bcam how to distinguish background pixels from spot pixels. At the very least, the -threshold string must specify a threshold intensity, or a means of calculating a threshold intensity. All the spot-locating routines called by lwdaq_bcam use the net intensity of pixels, which is the image intensity minus the threshold intensity, with negative values clipped to zero.

The -threshold string must begin with an integer, t. After t there can be a non-numerical character, which we call the threshold symbol. If there is no threshold symbol, the routine assumes the "*" symbol has been omitted from the string. The "*" symbol tells the routine to use t directly as the intensity threshold. The string "20 *" means the threshold is pixel intensity 20. When combined with the "*" symbol, the threshold must be between 0 and 255 for eight-bit images.

The "%" symbol means that the number is a percentage. The threshold is the minimum image intensity plus a precentage of the difference between the maximum and minimum intensities. The "#" symbol means that the threshold will be the average intensity plus a percentage of the difference between the maximum and average intensities. The "$" symbol means the threshold is a certain number of counts above the average intensity.

Following the symbol or threshold we have two optional parameters that restrict the routine's choice of spots. The first parameter must be an integer. It specifies the required number of pixels above threshold in a spot for acceptance by the routine. Any spots with fewer than this number will be ignored. Their pixels will be marked white in the overlay.

The second parameter must be a real number. It specifies the maximum eccentricity of the spot, which is the maximum ratio of width to height, or height to width. Spots that have greater eccentricity will be rejected by the routine. The second parameter cannot be included without the first, but if you use 0 for the first, the routine ignores the first parameter and moves on to the second.

The lwdaq_bcam routine identifies all distinct sets of contiguous pixels above threshold, eliminates those that do not meet the test criteria, determines the position and total net intensity of each remaining set, sorts them in order of decreasing total net intensity, and eliminates all but the first -num_spots sets. The total net intensity is the sum of the net intensities of all the pixels in the set. By default, the routine returns the position of each spot in microns with respect to the top-left corner of the image. To convert from pixels to microns, the routine uses -pixel_size_um, and assumes the pixels are square. There are several ways that lwdaq_bcam can calculate the spot position from the net intensity of its pixels.

spot_use_centroid=1;
spot_use_ellipse=2;
spot_use_vertical_line=3;

With return_bounds=1, the routine returns as its result string only the boundaries around the spots. It chooses the same boundaries it draws in the image overlay. Each spot boundary is given as four integers: left, top, right, and bottom. The left and right integers are column numbers. The top and bottom integers are row numbers. Each spot gets four numbers, and these make up the result string, separated by spaces. With return_intensity=1, the routine returns only the total neet intensity of of each spot. The return_intensity option is over-ridden by the return_bounds option.

With analysis_type=1, which is the default, the position of the spot is the weighted centroid of its net intensity. With analysis_type=2, the routine fits an ellipse to the edge of the spot. The position is the center of the ellipse. With analysis_type=3 the routine fits a straight line to the net intensity of the spot and returns the intersection of this straight line with the top of the CCD instead of x, and the anti-clockwise rotation of this line in milliradians instead of y.

The sort_code has the following meanings, and dictates the order in which the spots are returned in the result string.

spot_decreasing_total_intensity=1;
spot_increasing_x=2;
spot_increasing_y=3;
spot_decreasing_x=4;
spot_decreasing_y=5;
spot_decreasing_max_intensity=6;
spot_decreasing_size=7;

Thus with spot_decreasing_x as the value for sort_code, the routine sorts the num_spots brightest spots in order of decreasing x position, which means spots on the right of the image will appear first in the result string. With spot_decreasing_total_intensity, which is the default, the spot with the highest total net intensity comes first. But with spot_decreasing_max_intensity, the spot with the highest maximum intensity comes first. With spot_decreasing_size, the spot with the largest number of pixels comes first.

Example: We have three spots: big, medium, and small. The big one has 1000 pixels with intensity 45 counts. The medium one has 100 pixels with intensity 100 counts. The small one has 10 pixels with intensity 120 counts. We set the threshold at 40 counts. Their total net intensities are 5000, 6000, and 800 respectively. Their maximum intensities are 45, 100, and 120 respectively. With spot_decreasing_total_intensity, the second spot will come first. With spot_decreasing_max_intensity, the third spot will come first. With spot_decreasing_size, the first spot will come first.

With show_pixels=0, which is the default value, the routine draws red boxes around the spots. These boxes are of the same size as the spots, or a little bigger if the spots are small. If num_spots=1, the routine draws a cross centered on the spot instead of a box around it. When show_pxels=1, the routine marks all the pixels in each spot, so you can see the pixels that are above threshold and contiguous.

The color we use to mark the image with the results of analysis is given in the -color option. You specify the color with an integer. Color codes 0 to 15 specity a set of distinct colors, shown here.

See the BCAM Instrument Manual for more information about the option values.

lwdaq_calibration

lwdaq_image_calibration device_calibration apparatus_measurement ?option value?

lwdaq_calibration takes as input an apparatus measurement and a device calibration, and returns a parameter calculation. The routine calls parameter_calculation in the bcam.pas. This routine supports bcam cameras and bcam sources for all types of bcam and both j_plates and k_plates.

lwdaq_config

lwdaq_config ?option value?

lwdaq_config sets global variables that control the operation of the lwdaq analysis libraries. If you specify no options, lwdaq_config returns a string giving you the current values of all the options, except the -eol option. Each option requires a value, which will be assigned to the global variable names in the option. Here are the options and their expected value types. Boolean variables you specify with 0 for false and 1 for true.

The analysis routines can write to TK text windows, and draw in TK photos through -text_name and -photo_name. During execution, they can pause to allow you to view the intermediate results for -wait_ms millisconds. If you set -wait_ms to -1, TK will open a window with a Continue button in it, which you must click before the analysis proceeds. The gamma correction sets the gray scale image display gamma correction used by lwdaq_draw.

Many routines return real numbers in strings. These real numbers will have a fixed number of decimal places equal to the global Pascal variable fsd and a total field size equal to the global Pascal variable fsr.

The global error_string variable is used by all the command routines in lwdaq.pas. Each command routine resets error_string and checks it when it's finished. If error_string is not empty, the routine will return an error condition and error_string will be its result. The append_errors option tells the analysis library to append new errors to error_string instead of over-writing previous errors with the new error. By default, append_errors is false.

lwdaq_data_manipulate

lwdaq_data_manipulate image_name manipulation ?parameters?

lwdaq_data_manipulate operates upon the data in an image, and we intend it for use with instruments that store one-dimensional arrays of data in an image's intensity array. Our convention, when using the intensity array in this way, is to start storing data in the first column of the second row. This leaves the first row free for header information when we store the image to disk. We refer to the block of memory starting with the first byte of the second row, and ending with the last byte of the last row, as the data space. We specify bytes in the data space with their byte address, which is zero at the first byte in the data space. The routine does not return a text string. It either returns an error or an empty string. The data manipulations alter the existing image.

The write function requires two parameters: the data you wish to write to the data space, and the byte address at which you want the first byte of your data to be written. The following command writes the contents of data to the data space of the image named image_name starting at the first byte in the data space (which is the first pixel in the second row).

lwdaq_data_manipulate image_name write 0 $data

The read function requires two parameters: the number of bytes you wish to read from the data space, and the byte address at which you want to start reading. The following command reads 10000 bytes starting at byte address 100. If the image has 100 pixels per row, the first byte the routine reads will be the first pixel in the third row of the image.

lwdaq_data_manipulate image_name read 100 10000

The shift function requires one parameter: the number of bytes to the left by which you want the data to be shifted. Shifting to the left is in the direction of the start of the data space. If you specify a negative shift, the routine shifts the data to the right, in the direction of the end of the data space.

The clear function takes no parameters. It clears all the byte in the data space to zero.

lwdaq_diagnostic

lwdaq_diagnostic image ?option value?

lwdaq_diagnostic analyzes sixteen-bit adc samples from the driver supplies. It assumes that five numbers specifying the relay software version, the driver assembly number, the driver hardware version, the controller firmware version, and the data transfer speed are all saved in the input image's results string. The routine leaves these numbers in the results string after it is done.

lwdaq_draw

lwdaq_draw image photo ?option value?

lwdaq_draw transfers the named image into the named TK photo. You pass the lwdaq image name followed by the tk photo name, and then your options in the form ?option value?. When the routine draws the image, it over-writes the first few pixels in the first image row with a header block containing the image dimensions, its analysis bounds, and its results string.

The -intensify option can take four values: mild, strong, exact, and none. Mild intensification displays anything darker than four standard deviations below the mean intensity as black, and anything brighter than four standard deviations above the mean intensity as white. In between black and white the display is linear with pixel brightness. Strong intensification does the same thing, but for a range of two standard deviations from the mean. Exact displays the darkest spot in the image as black and the brightest as white. In all three cases, we calculate the mean, standard deviation, minimum, and maximum intensity of the image within the analysis bounds, not across the entire image.

The -zoom option scales the image as we draw it in the TK photo. If the TK photo is initially smaller than the size required by the zoomed image, the TK photo will expand to accommodate the zoomed image. But if the TK photo is initially larger than required, the TK photo will not contract to the smaller size of the zoomed image. The -zoom option can take any value between 0.1 and 10. But the effective value of -zoom is dicated by the requirements of sub-sampling. If -zoom is greater than 1, we round it to the nearest integer, e, and draw each image pixel on the screen as a block of e×e pixels. If -zoom is less than 1, we round its inverse to the nearest integer, c. We draw only one pixel out of every c pixels in the TK photo. If -zoom = 0.3, we draw every third pixel. If -zoom = 0.4, we draw every third pixel if your computer rounds 1/0.4 to 3, or every second pixel if your computer rounds 1/0.4 to 2. With -zoom = 0.0, we draw every tenth pixel.

With -clear set to 1, lwdaq_draw clears the overlay in the lwdaq image before drawing in the TK photo. The overlay may contain a graph or oscilloscope display, or analysis indicator lines. If you don't want these to be displayed, set -clear to 1. But note that whatever was in the overlay will be lost.

By default, -show_bounds is 1, and the routine draws a blue rectangle to show the the image analysis boundaries, which are used by image analysis routines like lwdaq_rasnik and lwdaq_bcam. But with -show_bounds set to 0, this blue rectangle is not drawn. If you want to be sure that you don't have a blue rectangle drawn over your gray-scale image, you should also specify -clear 1, so that lwdaq_draw will clear the image overlay of any pre-existing blue rectangles.

lwdaq_fft

lwdaq_fft data ?option value?

lwdaq_fft applies a fast fourier tranfsorm to a waveform and returns the complete discrete fourier transform (DFT). In general, the DFT transforms a set of N complex-valued samples and returns a set of N complex-valued frequency components. We assume the samples, are uniformly-spaced with respect to some one-dimensional quantity such as time or distance. The sample period is the separation of the samples in this one-dimensional quantity. We denote the sample period with T and the one-dimensional quantity we denote as t. We denote the sample at t = nT with x_n, where n is an integer such taht 0≤n≤N−1. We denote the transform components X_k, where k is an integer such that 0≤k≤N−1. Each transform component represents a complex sinusoidal function in t. The k'th sinusoid, S_k, has frequency k/NT. Its magnitude and phase are given by X_k.

In the text-book definition of the discrete fourier transform, X_k is N times larger, and we must divide by N to obtain the sinusoidal amplitude. But we pre-scaled our components by 1/N so we return the sinusoidal comonents directly. If we express X_k as a magnitude, A_k, and a phase Φ_k, we get the following expression for the sinusoid.

When our inputs x_n are real-valued, we find that the the k'th component of the transform is the complex conjugate of component N−k. A feature of all discrete transform is X_k = X_k−N. Thus X_N−k = X_−k, the component with frequency −k/NT. We observe that cos(v) = cos(−v) and sin(v) = −sin(−v), so the −k'th component is the complex conjugate of the k'th component. This means that the N−k'th component is equal to the k'th component.

The 0'th and N/2'th components we cannot sum together using the above trick. But these components always have phase 0 or π when the inputs are real-valued. We can represent them with two real-valued numbers, where the magnitude of the number is the magnitude of the component and the sign is the phase 0 or π.

The lwdaq_fft routine will accept N complex-valued samples in the form x_n = u+iv and return N complex-valued components in the form X_k = U+iV. We specify complex-valued input with option "-complex 1". The default option, however, is "-complex 0", which specifies real-valued input and returns N/2 real-valued components. We obtain the N/2 components by adding each X_k to its complex conjugate X_N−k. We express these real-valued frequency components with two numbers each, 2A_k and Φ_k. These represent a cosine with amplitude 2A_k, angular frequency 2πk/NT (rad/s), and phase shift Φ_k (rad).

The 0'th component of the real-valued transform is an exception. It contains two numbers, but neither of them is a phase. One is the magnitude of the 0'th component, which is the DC component, and the N/2'th component, which is the Nyquist-frequency component.

The lwdaq_fft routine insists upon N being a power of two so that the fast fourier transform algorithm can divide the problem in half repeatedly until it arrives at transforms of length 1. For the fast fourier transform algorithm itself, see the fft routine in utils.pas. For its real-valued wrapper see fft_real.

lwdaq_config -fsr 1 -fsd 2
lwdaq_fft "1 1 1 1 1 1 1 0"
0.88 0.13 0.25 -2.36 0.25 -1.57 0.25 -0.79 

In the example, we supply the routine with eight real-valued samples and obtain a transform of sixteen numbers. The first number tells us the magnitude and phase of the 0-frequency component. This number is equal to the average value of the samples, and is often called the "DC-component". The second number gives us the Nyquist-frequency component, which is the component with period two sample intervals. Here, the Nyquist-frequency component is the 4-frequency component with period N/4 (N=8). We multiply a cosine by this mangnitude and we obtain the 4-frequency component of the transform. Its phase can be either +π or −π, and so is represented by the signe of the component magnitude.

The remaining components in the tranform, 1 through 3, are each represented by two numbers, a magnitude, a, and a phase Φ. We obtain the value of component k at time t with acos(2πkt/NT+Φ). If we use sample number, n, instead of time, the component is acos(2πkn/N+Φ).

lwdaq_fft "1 0 1 0 1 0 1 0 1 0 1 0 1 0 0 0" -complex 1
0.88 0.00 -0.09 -0.09 -0.00 -0.13 0.09 -0.09 0.13 0.00 0.09 0.09 0.00 0.13 -0.09 0.09 

We submit the same data to the complex version of the transform by accompanying each sample with a zero phase, so as to indicate a real value with a complex number. The result is a transform that is equivalent to our first, abbreviated transform. You can see the N/4 component as "0.13 0.00" and the 0 component as "0.88 00". There are two N/1 frequency components "-0.09 -0.09" and "-0.09 0.09". Their magnitude is 0.127 and their phases are −3π/4 and −π/4. When we add these magnitudes together we obtain the N/1 component of the real-valued transform, which is 0.25 as shown above. The phase of the N/1 component is −3π/4 = −2.36 radians, which is also what we see in the real-valued transform above.

Here is another example. In this case, the N/4 component is zero, as is the 0 component.

lwdaq_fft "1 1 1 1 -1 -1 -1 -1"
0.00 0.00 1.31 -1.18 0.00 0.00 0.54 -0.39 
lwdaq_fft "1 0 1 0 1 0 1 0 -1 0 -1 0 -1 0 -1 0" -complex 1
0.00 0.00 0.25 -0.60 0.00 0.00 0.25 -0.10 0.00 0.00 0.25 0.10 0.00 0.00 0.25 0.60 

If the samples were taken over 1 s, the eight components represent frequencies 0, 1, 2, and 3 Hz. So we see the square wave of frequency 1 Hz has harmonics at 1 Hz and 3 Hz. The fourier series expansion of a square wave has harmonics of amplitude 4/nπ for the n'th harmonic. The first harmonic in the fourier series would have amplitude 1.27. Our 1-Hz component has amplitude 1.31. The discrete fourier transform is an exact representation of the original data, but it does not provide all the harmonics of the fourier series. Therefore, the existing harmonics are not exactly of the same amplitude as those in the fourier series.

The phases of the components in our example are also correct. The first harmonic is offset by −1.18 radians, which means it is a cosine delayed by 1.18/2π = 0.188 of a period, or 1.5 samples. We see that a cosine delayed by 1.5 samles will reach its maximum between samples 1 and 2, which matches our input data. In the example below, we change the phase of the input by π and we see the phase of the fundamental harmonic changes by π.

lwdaq_fft "1 1 1 1 0 0 0 0"
0.50 0.00 0.65 -1.18 0.00 0.00 0.27 -0.39 
lwdaq_fft "0 0 0 0 1 1 1 1"
0.50 0.00 0.65 1.96 0.00 0.00 0.27 2.75 

We can use lwdaq_fft to perform the inverse transform, but we must invoke the "-inverse 1" option or else the inverse does not come out quite right.

set dft [lwdaq_fft "1 0 1 0 1 0 1 0 -1 0 -1 0 -1 0 -1 0" -complex 1]
0.00 0.00 0.25 -0.60 0.00 0.00 0.25 -0.10 0.00 0.00 0.25 0.10 0.00 0.00 0.25 0.60 
lwdaq_fft $dft -complex 1
0.12 0.00 -0.12 0.00 -0.12 0.00 -0.12 0.00 -0.12 0.00 0.12 -0.00 0.12 -0.00 0.12 -0.00 
lwdaq_fft $dft -complex 1 -inverse 1
1.00 0.00 0.99 -0.00 1.00 -0.00 0.99 -0.00 -1.00 0.00 -0.99 0.00 -1.00 0.00 -0.99 0.00 

The "-inverse 1" option reverses the order of the input components, which is a trick for getting the forward transform to act like an inverse transform, and then multiplies the resulting sample-values by N to account for the fact that our lwdaq_fft routine scales its frequency components by 1/N to make them correspond to sinusoidal amplitudes. The reversal of the input components and the scaling takes place in fft_inverse of utils.pas.

We can also invert our compact magnitude-phase transforms, which we derive from real-valued inputs with the "-complex 0" option (the default).

set dft [lwdaq_fft "1 1 1 1 -1 -1 -1 -1"]
0.00 0.00 1.31 -1.18 0.00 0.00 0.54 -0.39 
lwdaq_fft $dft -inverse 1
1.00 1.00 1.01 1.00 -1.00 -1.00 -1.01 -1.00 

Note the rounding errors we see because we are using only two decimal places in our examples. For the real-valued inverse transform code, see fft_real_inverse in utils.pas.

The fft, like all discrete fourier transforms, assumes that the N samples are the entire period of a repeating waveform. The N components of the transform, when inverted, give us an exact reproduction of the original N samples. As you are looking at the signal represented by the N samples, be aware that any difference between the 0'th sample and the (N-1)'th sample amounts to a discontinuity at the end of the repeating waveform. A ramp from 0 to 1000 during the N samples gives rise to a sudden drop of 1000. This sudden drop appears as power in all frequency components.

One way to remove end steps is to apply a window function to the data before you take the fourier transform. We provide a linear window function with the "-window w" option, where we apply the window function to the first w samples and the final w samples. This window function is the same one we provide separately in our window function routine. We recommend you calculate w as a fraction of N when you call lwdaq_fft. When we analyze EEG data, we use w = N/20. We implement the window function only for real-valued samples passed to the forward transform. If you try to apply the window function during the inverse transform or when passing complex samples to the forward transform, lwdaq_fft returns an error. That's not to say that there is no point in applying a window function in these other circumstances, but our linear window function does not have any obvious utility or meaning when so appplied.

Some data contains occasional error samples, called spikes or glitches. At some point in our data analysis, we must eliminate these glitches. The lwdaq_fft "-glitch x" option allows you to specify the size of the sample-to-sample change that should be treated as a glitch. The lwdaq_fft routine calls glitch_filter from utils.pas. We provide this routine at the command line with the glitch_filter library command. Any sample that differs by x or more from the previous sample will be over-written by the previous sample, which becomes the standing value. We keep replacing the data with the standing value until the data differs by less than x from the standing value. The "-glitch" option is compatible only with real-valued data passed to the forward transform. A threshold value of 0 disables the filter.

lwdaq_filter

lwdaq_filter data a_list b_list ?option value?

lwdaq_filter applies a recursive filter to a sampled signal. The samples are passed to lwdaq_filter as a string of space-delimited real numbers. By default, lwdaq_filter assumes every number in the string is a sample. With the -tv_format option set to 1, lwdaq_filter assumes every other number in the string is a uniformly-spaced sample, in the form "t v ", where "t" is time and "v" is the sample. In this case, lwdaq_filter reads the v-values only.

The routine returns its answer as a string of space-delimited real numbers. By default, lwdaq_filter returns a signal with as many samples as it received, separated by spaces, and formatted withe the global fsr (field size real) and fsd (field size decimal) values. With -tv_format set to 1, lwdaq_filter copies the t-values from the input string, so as to create an output string with the same t-values, but processed v-values.

We define the digital signal processing we with lwdaq_filter to perform by means of two strings. The first string gives the coefficients a[0]..a[n] by which the input values x[0]..x[k-n] are multiplied before adding to b[k]. The second string gives the coefficients b[1]..b[n] by which the previous outputs y[1]..y[k-n] are multiplied before adding to b[k].

lwdaq_flowmeter

lwdaq_flowmeter image ?option value?

lwdaq_flowmeter analyzes sixteen-bit adc values by calling lwdaq_A2053_flowmeter. It assumes that two numbers specifying the sample period and the number of channels sampled are saved in the input image's results string. The routine leaves these numbers in the results string after it is done.

lwdaq_gauge

lwdaq_gauge image ?option value?

lwdaq_gauge analyzes sixteen-bit adc values by calling lwdaq_A2053_gauge. The routine assumes that two numbers specifying the sample period and the number of channels sampled are saved in the input image's results string. The routine leaves these numbers in the results string after it is done. For each gauge channel in the image, the routine returns a result, according to the result specifiers. With -ave 1, the result for each channel includes the average gauge value. With -stdev 1, the result includes the standard deviation of the gauge value. With both set to zero, the result is an empty string. The default values for ave and stdev are 1 and 0 respectively.

lwdaq_graph

lwdaq_graph data image ?option value?

lwdaq_graph takes a string from TCL that contains consecutive x-y value pairs, and plots a graph of the values in the overlay of an image. The routine fills the analysis bounds of the image with a graph, or it fills the entire image with the graph. You can specify the values of x and y that correspond to the edges of the plotting area. If you do not specify the edgs, the routine will stretch or compress the plot to fit exactly in the available space.

We can specify the graph points as a series of y-values if we like, and lwdaq_graph will fill in the x-values as integers 0 to n-1, where n is the number of y-values. We instruct lwdaq_graph to treat its input data as a string of y-values with the -y_only option.

The color codes for the graph give 255 unique colors. You can try them out to see which ones you like. The colors 0 to 15 specify a set of distinct colors, as shown here. The remaining colors are eight-bit RGB codes. If you don't specify a color, the plot will be red.

lwdaq_image_characteristics

lwdaq_image_characteristics image

lwdaq_image_characteristics returns features of the image: the left, top, right, and bottom edges of the analysis boundries, the average, standard deviation, maximum, and minimum values of intensity, and the height and width of the image.

lwdaq_image_contents

lwdaq_image_contents image

lwdaq_image_contents returns a byte array containing the intensity array from the named image. In the first line of the image the routine records the image dimensions, analysis boundry, and results string. The integers are two-bytes long, and we use big-endian byte ordering, so the high-order byte is first.

If you specify -truncate 1, the routine removes all trailing zero-bytes from the data. When we create a new image to accomodate the same data later, we clear the image intensity array before we copy in the new data, so the image is re-constructed faithfully. This truncation is effective at reducing the size of data files from instruments that don't fill the intensity array with real data, but instead use the intensity array as a place to store one-dimensional data, and use the overlay as a white-board upon which to render the data (like the Voltmeter). If you specify -data_only 1, the routine chops off the leading row of data, leaving only the data from the first pixel of the first row onwards, which is the block of data operated upon by our lwdaq_data_manipulate routines. If you specify -record_size larger than 1, the routine makes sure that the size of the block it returns is divisible by the record size.

lwdaq_image_create

lwdaq_image_create option value ?option value?

lwdaq_image_create creates a new image and returns a unique name for the image, by which the interpreter can identify the image to other lwdaq routines.

The above table lists the options accepted by lwdaq_image_create, and their functions. If you use the -name option and provide the name of a pre-existing image in the lwdaq image list, lwdaq_image_create deletes the pre-existing image. If you specify "-data $value", the routine copies $value into the image's intensity array, starting at the first pixel of the first row. When you combine "-data $value" with "-try_header 1", the routine looks at the first bytes in $value to see if it contains a valid image header, specifying image width and height, as well as analysis bounds and a results string. When the routine looks for the header, it assumes that the bytes in the header specify two-byte integers in big-endian order.

If you have -try_header 0, or if the routine's effort to find a header fails, lwdaq_image_create will look at the values you specify for the analysis bounds with the -left, -top, -right, and -bottom options. A value of −1 directs the routine to place the boundary at the edge of the image. The default values for these options are all −1.

lwdaq_image_destroy

lwdaq_image_destroy image

lwdaq_image_destroy disposes of an image. You can specify multiple images, or image name patterns with * and ? wild cards. You can enter multiple image names on the command line, too.

lwdaq_image_exists

lwdaq_image_exists image ?option value?

lwdaq_image_exists returns a list of images in the lwdaq image list that match the image_name pattern you pass to the routine. If you pass "*", it will return a list of all existing images. If there are no matching images, lwdaq_image_exists returns an empty string.

lwdaq_image_histogram

lwdaq_image_histogram image

lwdaq_image_histogram returns a histogram of image intensity within the analysis bounds of an image. The histogram takes the form of an x-y graph in a space-delimited string, with the x-coordinate representing intensity, and the y-coordinate representing frequency. Suppose we apply the histogram routine to a 20×20 image and we assume that the pixel intensities range from 0 to 3. The string "0 100 1 210 2 40 3 50" confirms that there are 400 pixels in the image, 100 with intensity 0, 210 with intensity 1, and so on.

lwdaq_image_manipulate

lwdaq_image_manipulate image_name manipulation ?option value?

lwdaq_image_manipulate returns the name of a new image derived from one or more images passed to lwdaq_image_manipulate. If we set the -replace option to 1, the routine replaces the original image with the new image. The command takes the name of an image in the LWDAQ image list, and the name of a manipulation to be performed upon this image. The currently-supported manipulations are as follows.

The none manipulation does nothing. It does not return a new image. Instead, the none manipulation allows us to manipulate an existing image's analysis boundaries, result string, and overlay pixels.

The smooth manipulation applies a 3×3 average filter to the image within the analysis boundaries. The value of pixel (i, j) in the new image will be proportional to the sum of the pixels (i-1..i+1, j-1..j+1) in the original image. One of the potential benifits of smoothing is to attenuate stochastic noise. We would like the smoothing to attenuate quantization noise in very dim images. But if we add the nine pixels in the 3×3 block together and dividing by nine to obtain their average, we find that our average itself suffers from quantization noise. For example, suppose eight pixels have value 100 and the ninth is 101. The average should be 100.1, but this will be rounded to 100. The smooth routine calculates the average value of the nine pixels and stores them in an array of real values. Once the array is complete, the routine tranforms the minimum to maximum range in the real-valued array into the pixel value range in the final image. If the smoothed values ranged from 98 to 102 and the final image pixels can be 0 to 255, the smooth routine transforms 98 to 0 and 102 to 255. Thus we obtain the best possible contrast in the final image, and we do the best we can to remove quantization noise.

The combine manipulation allows you to write over the data in an image, starting with the offset'th pixel. You specify offset after the data. The manipulation copies the entire contents of an m-byte binary block into the image, starting at pixel offset, and ending at pixel offset+m-1. If the copy goes past the end of the image array, the manipulation aborts without doing anything, and returns an error.

The crop manipulation extracts the pixels inside the analysis boundaries of the original image, and creates a new image containing only these pixels. The dimensions of the new image will be those of the original analysis boundaries, but with one extra row at the top to accommodate an image header when we save to disk. The new analysis boundaries will include the entire image except for row zero.

The subtract manipulation requires you to name a second image, which will be subtracted from the first to create a third image. The two images must have the same dimensions. All pixels in the second images will be subtracted from the first image. The third image, being the difference, will be the same dimensions as the first two.

The bounds_subtract manipulation is like subtract, but applies the subtraction only within the analysis bounds of the first image. Elsewhere, the difference image is equal to the first image.

The subtract_row manipulation does not require a second images. It is a type of filter function, whereby we subtract the average intensity of each row from the pixels in the row. We thus remove a slope of intensity from top to bottom in the image.

The grad manipulations either return an absolute intensity gradient or a signed intensity gradient. We calculate the horizontal gradient at pixel (i,j) by subtracting the intensity of pixel (i-1,j) from that of pixel (i+1,j). The vertical gradient is (i,j+1) minus (i,j-1). When we return the magnitude of the gradient, the intensity of the gradient image is simply the absolute value of the gradient. When we return the signed gradient, we offset the gradient image intensity by mid_intensity, which is 128 for eight-bit gray scale images. Thus an intensity of 128 means zero gradient, and an intensity of 138 means +10. When the gradient exceeds 127 or -128, we clip its value to 255 and 0 respectively. For more details, see the image_filter and subsequent routine in image_manip.pas.

The rasnik manipulation draws a rasnik pattern in the image. We specify the rasnik pattern with a string of seven numbers: origin.x, origin.y, pattern_x_width, pattern_y_width, rotation, sharpness, and noise amplitude. The origin is the image coordinates of the top-left corner of one of the squares in the chessboard. Units are pixels, not mircons. The x and y width of the squares are in the near-horizontal and near-vertical direction respectively. Units are pixels again. The rotation is counter-clockwise in milliradians of the pattern with respect to the sensor. With sharpness 1, the pattern has sinusoidal intensity variation from black to white. With sharpness less than 1, the amplitude of the sinusoidal variation decreases in proportion. With sharpness greater than one, the sinusoidal amplitude increases in proportion, but is clipped to black and white intensity, so that we obtain a sharply-defined chessboard. With sharpness 0.01 we obtain an image with alternating circles of intensity one count above and below the middle intensity, set in a field of middle intensity, as shown here. When we differentiate such an image in the horizontal direction, we get this, which defeats our frequency-based rasnik analysis. We can add noise to our simulated image with the noise amplitude parameter. If we set this to 1.0, we add a random number between 0.0 and 1.0 to each pixel.

The transfer_overlay manipulation copies the overlay of a second image into the overlay of the first. This manipulation is the only one operating upon the image ovelays. Each image has an overlay area whose colors we draw on top of the image when we display the image on the screen. Thus we can use the overlay to mark features in the image without corrupting the image itself. The overlay transfer scales the original overlay so that it fits into the rectangle of the new image. We can shrink a large image by a factor of four, analyze the quarter-sized image, record the results of analysis in the overlay, and transfer the overlay back into the original full-sized image. The transfer will make sure that the markings are aligned correctly with the features in the original image.

lwdaq_image_manipulate image_name rasnik "0 0 20 30 2 10" -replace 1

In the above example, the the existing image would be replaced by a new image containing a rasnik pattern with origin at the top-left corner of the top-left pixel in the image, each square 20 pixels wide and 30 pixels high, rotated by 2 mrad anti-clockwise, with sharp edges.

With -name you specify the name of the new image created by the manipulation, or the existing image if there is no new image created by the manipulation. Any pre-existing images with this name will be destroyed before the name change occurs.

With -replace 0, the manipulation creates a new image and returns its name. With -replace 1, the manipulation over-writes data in the old image and returns the old image name.

The -paint option instructs lwdaq_image_manipulate to paint the entire area within the analysis bounds with the color given by $value. This value should be a number between 0 and 255. The value 0 is for transparant. Other than the 0-value, the number will be treated like an eight-bit RGB code, with the top three bits for red, the middle three for green, and the bottom three for blue. Thus $E0 (hex E0) is red, $1C is green, and $03 is blue. Note that paint does not convert $value into one of LWDAQ's standard graph-plotting colors, as defined in the overlay_color_from_integer routine of images.pas, and used in lwdaq_graph.

In addition to the pixel manipulations, we also have options to change other secondary properties of the image. The table above shows the available manipulation options, each of which is followed by a value in the command line, in the format ?option value?.

When you specify the analysis bounds, a value of −1 is the code for "do nothing". The boundary will remain as it was. This use of the −1 code contasts with that of lwdaq_image_create, where −1 directs lwdaq_image_create to move the boundary to the edge of the image.

lwdaq_image_profile

lwdaq_image_profile image

lwdaq_image_profile returns a list of the average intensity in the analysis boundaries along the row or column directions. The profile takes the form of series of numbers in a space-delimited decimal string. The first number of a row profile is the average intensity of pixels in the leftmost column of the analysis boundaries. The last number is the average intensity of the right-most column. The first number of a column profile is the average intensity of the topmost row in the analysis boundaries. The last number is the average intensity of the bottom row. To obtain the row profile, use option -row 1, which is the default. To obtain the column profile, use -row 0.

lwdaq_image_results

lwdaq_image_results image

lwdaq_image_results returns an image's results string, which may be up to short_string_length characters long.

lwdaq_inclinometer

lwdaq_inclinometer image ?option value?

lwdaq_inclinometer analyzes an image returned by the Inclinometer instrument. It returns the amplitude of harmonics in signals recorde in an image.

lwdaq_photo_contents

lwdaq_photo_contents photo

lwdaq_photo_contents returns a byte array containing gray-scale intensity array corresponding to a tk photo. The routine uses the red intensity as the gray-scale intensity, which will work in a purely gray-scale image, and assumes that the red intensity is an 8-bit number.

The routine embeds the image dimensions in the first four pixels of the image by over-writing them with j_size-1 and i_size-1 each as two-byte integers in big-endian format. If the image is one that has been previously stored or drawn by lwdaq routines, the first twelve pixels of the first line will already contain the image dimensions, plus the analysis boundaries, all encoded as two-byte big-endian integers. Because the routine already knows for sure what the image dimensions are, it over-writes dimensions in the first row. But it does not over-write the analysis boundaries. These may be correct or incorrect. You can pass this routine's result to lwdaq_image_create, and have the image-creating routine check the first twelve bytes for valid analysis bounds, or ignore these bounds and use newly-specified bounds.

To assemble the 8-bit gray-scale image, the routine uses the lwdaq scratch image. If the routine were to allocate and dispose of an image, the printing activity of the disposal when -track_ptrs is set to 1 would alter the TCL return string.

lwdaq_rasnik

lwdaq_rasnik image ?option value?

lwdaq_rasnik analyzes rasnik images. Specify the image with -image_name as usual. The routine clears the image overlay for its own use. The routine takes the following options, each of which you specify by giving the option name followed by its value, ?option value?. See the Rasnik Instrument for a description of the options.

See the Rasnik Instrument Manual for more information about the option values, in particular the reference and orientation code meanings.

With the -pattern_only option set, the routine returns a description of the chessboard pattern it finds in the image. The result string contains seven numbers: origin.x, origin.y, pattern_x_width, pattern_y_width, rotation, error, and extent. The origin values are the image coordinates of the top-left corner of one of the squares in the chessboard. Units are pixels, not mircons. The next two numbers are the width of the squares in the near-horizontal direction and their width in the near-vertical direction. Units are again pixels. The rotation is counter-clockwise in milliradians. The error is an estimate of the fitting accuracy in pixel widths. The extent is the number of squares from the image center over which the pattern extends.

lwdaq_rasnik_shift

lwdaq_rasnik_shift old_result ?option value?

lwdaq_rasnik_shift takes in a rasnik result string and shifts it to a new reference point. The routine gets the old reference point from the results string, and re-calculates the rasnik measurement using the x and y coordinates you specify with -reference_x_um and -reference_y_um.

lwdaq_recorder

lwdaq_recorder image command

lwdaq_recorder steps through the pixels of an image looking for valid messages from an asynchronous transmitter such as the Subcutaneous Transmitter (A3013) as received by a Data Receiver (A3018). It draws the signals it discovers in the image overlay. See the Recorder Instrument Manual for details.

lwdaq_rfpm

lwdaq_rfpm image ?option value?

lwdaq_rfpm analyzes images from an RFPM instrument.

lwdaq_sampler

lwdaq_sampler image command

lwdaq_sampler steps through the pixels of an image looking for valid samples from a sampling circuit like the ADC Tester (A2100).

lwdaq_voltmeter

lwdaq_voltmeter image ?option value?

lwdaq_voltmeter analyzes image data for the Voltmeter instrument.

lwdaq_wps

lwdaq_wps image ?option value?

lwdaq_wps analyzes wps images. It clears the overlay for its own use. We describe the analysis in our WPS1 Manual.

The -threshold string is used in the same way as in lwdaq_bcam. It can contain an intensity threshold or it can define a means to calculate the threshold. The string can also specify the minimum number of pixels a spot must contain, and its maximum eccentricity. Spots that do not meet these criteria will be marked as invalid. In this case, note that the threshold intensity will be applied to the horizontal gradient of the wire image, not the image itself.

With -pre_smooth set to 1, the routine smooths the original image with a box filter before it applies the gradient and threshold. We use -pre_smooth when noise is obscuring the larger edge features in a wire image.

With -merge set to 1, the routine checks for edge pixel clusters that are closely aligned, and merges these together. We use -merge when image contrast is so poor that the edge pixels along one side of a wire image can break into two or more separate clusters.

The wire positions are given with respect to a horizontal reference line drawing reference_um microns down from the top edge of the top image row. With show_edges equal to zero (the default value), the routine plots the image's horizontal intensity profile in green and the derivative profile in yellow. But when you set show_edges to 1, the routine no longer plots these two graphs, but instead displays the spots it finds in the derivative image, overlayed upon the original image. The edges of a wire will be covered with colored pixels. White pixels are ones that were part of spots that did not satisfy the -threshold critera.

Library Routines

The lwdaq command acts as an entry point into our analysis libraries, making various math functions available at the TCL command line. You specify the routine we wish to call, and pass arguments to the routine in strings or byte arrays or both. Most routines return results as text strings in which real numbers are encoded in characters with a fixed number of decimal places, as defined by the global constants fsr and fsd. You can set both of these with lwdaq_config. Beware that these routines can round small values to zero. In the comments below, we assume that fsr is 8, and fsd is 6.

ave_stdev

lwdaq ave_stdev data

Calculates the average, standard deviation, maximum, and minimum of data, where data contains a string of numbers. The routine returns values separated by spaces, and formatted to fsd significant figures.

bcam_from_global_point

lwdaq bcam_from_global_point point mount

Transforms a point in global coordinates to a point in BCAM coordinates. The point in BCAM coordinates is returned as a string of three numbers, the BCAM x, y, and z coordinates of the point. You specify the point in global coordinates with the point parameter, which also takes the form of a string of three numbers, these numbers being the global x, y, and z coordinates of the point whose BCAM coordinates we want to determine. You specify how the BCAM and global coordinate systems relate to one another with the mount string. The mount string contains the global coordinates of the BCAM's kinematic mounting balls. You specify the coordinates of the cone, slot, and flat balls, and for each ball we give its x, y, and z coordinates. In the following example, we transform the global point (0,1,0) into BCAM coordinates when our cone, slot and flat balls have coordinates (0,1,0), (-1,1,-1), and (1,1,-1).

lwdaq bcam_from_global_point "0 1 0" "0 1 0 -1 1 -1 1 1 -1"
0.000000 0.000000 0.000000

For a description of the BCAM coordinate system, and how it is defined with respect to a BCAM's kinematic mounting balls, consult the BCAM User Manual. We usually use millimeters to specify coordinates, because we use millimeters in our BCAM camera and source calibration constants. But the routine will work with any units of length, so long as we use the same units for both the point and the mount strings.

bcam_from_global_vector

lwdaq bcam_from_global_vector vector mount

Transforms a vector in global coordinates to a vector in BCAM coordinates. See bcam_from_global_point for more details.

lwdaq bcam_from_global_vector "0 1 0" "0 1 0 -1 1 -1 1 1 -1"
0.000000 1.000000 0.000000

For a description of the BCAM coordinate system, and how it is defined with respect to a BCAM's kinematic mounting balls, consult the BCAM User Manual.

bcam_image_position

lwdaq bcam_image_position source_position camera

Calculates the image coordinates of the image generated by a light source at location source_position in BCAM coordinates. We specify the BCAM itself with the camera string, which contains the BCAM's calibration constants. The routine determines the image position by drawing a line from the source through the pivot point and instersecting this line with the plane of the image sensor. The orientation and location of the image sensor is given by the camera calibration constants. The image coordinate origin is the top-left corner of the image sensor as seen on the screen. The units of image coordinats are microns, with x going left-right and y going top-bottom.

lwdaq bcam_image_position "1 0 1000" "P0001 1 0 0 0 0 1 75 0"
1.720000 1.220000

Here we see the image is at (1.72,1.22) in image coordinates, which is the center of a TC255P image sensor. You specify the BCAM itself with its calibration constants using the camera string, just as for bcam_source_bearing.

lwdaq bcam_image_position "1 0 1000" "P0001 1 0 0 0 0 1 100 0"
1.720000 1.220000
lwdaq bcam_image_position "1.1 0 1000" "P0001 1 0 0 0 0 1 100 0"

Here we see movement of 1 mm at a range ten times the pivot-ccd distance causing a 100-um move on the image.

bcam_source_bearing

lwdaq bcam_source_bearing spot_center camera

Calculates the line upon which a light source must lie for its image to be centered at spot_center. The line is returned as a string containing six numbers. The first three numbers are the coordinates of the BCAM pivot point in BCAM coordinates in millimeters. The last three numbers are a unit vector in the direction of the line. The BCAM itself we describe with its calibration constants in the camera string. The camera string contains nine elements, as described in the BCAM User Manual. The camera string specifies length in millimeters and rotation in milliradians.

lwdaq bcam_source_bearing "1.72 1.22" "P0001 1 0 0 0 0 1 75 0"
1.000000 0.000000 0.000000 0.000000 0.000000 1.000000

The first element in the camera string is the name of the camera, even though this calculation does not use the camera name. In the example above, P0001 is the camera name, the pivot point is at (1,0,0) in BCAM coordinates, the camera axis is parallel to the BCAM z-axis, the pivot point is 75 mm from the lens, and the CCD rotation is zero. We transform point (1.72, 1.22) on the CCD (dimensions are millimeters) into a bearing that passes through the pivot point (1,0,0) in the direction (0,0,1). The point (1.72,1.22) is our aribitrarily-chosen center of the CCD in all currently-available BCAMs (it is close to the center of the TC255P image sensor, but not exactly at the center). The BCAM camera axis is the line passing through the CCD center and the pivot point.

bcam_source_position

lwdaq bcam_source_position spot_center bcam_z camera

Calculates the BCAM coordinates of a light source whose image is centered at spot_center, and which itself lies in the plane z = bcam_z in BCAM coordinates. The routine is similar to bcam_source_bearing, but we specify the BCAM z-coordinate of the source as well, in millimeters. The routine determines the position of the source by calling bcam_source_bearing and intersecting the source bearing with the z=range plane. We specify the BCAM calibration constants in the camera string.

lwdaq bcam_source_position "1.72 1.22" 1000 "P0001 1 0 0 0 0 1 75 0"
1.000000 0.000000 1000.000000

Here we see the source is at (1, 0, 1000) in BCAM coordinates, where all three coordinates are in millimeters. You specify the BCAM itself with its calibration constants using the camera string, just as for bcam_source_bearing.

frequency_components

lwdaq frequency_components frequencies waveform

Calculates components of the discrete fourier transform of a real-valued waveform by repeated calls to frequency_component in utils.pas. We specify the M components we want to calculate with a string of M frequencies, each of which is a multiple of the fundamental frequency of the waveform, 1/NT. The frequencies provided by a full discrete fourier transform of N real samples are k/NT for k such that 0≤k≤N−1. If we want to obtain all N/2 components, we can use our lwdaq_fft routine instead. The frequency_components routine is designed to provide a small number of components for real-valued input data.

lwdaq_config -fsr 1 -fsd 2
lwdaq frequency_components "0 1 2 3 4 5" "0 0 0 0 1 1 1 1"
0.50 0.00 0.65 3.50 0.00 -1.91 0.27 0.83 0.00 0.00 0.27 0.30 

Here we ask for components with frequencies "0 1 2 3 4 5" and we specify data "0 0 0 0 1 1 1 1". The routine returns a string containg the amplitude, a, and phase, φ, of each specified component, separated by spaces.

Because the frequency_component routine accepts only real-valued inputs, we are certain that component k for K>0 will be the complex conjugate of component N−k, which means the two components add together to form one component of double the maginitude but with the same phase as component k. Thus frequency_component doubles the magnitude of the k'th component for k equal to 1, 2,..N/2−1 and leaves the phase unchanged.

The phase, φ, is in units of T, and refers to the phase of a sinusoid, so that the frequency component is

asin(2π(t−φ)f/N)

where f is the frequency we specified and t is the quantity that separates the samples. The quantity t might be time or distance.

The frequency need not be an integer, but if it is an integer, then this frequency will be one of those defined for the discrete fourier transform. There are times when choosing an exact frequency outside that finite set of periods is useful. For example, if we have 512 samples taken over 1 s, the discrete fourier transform contains components with frequencies 1 Hz, 2 Hz,.. 255 Hz. If we want to look for a signal at 33.3 Hz, we will find that the discrete fourier transform spreads 33.3 Hz into 33 Hz and 34 Hz, but neither component has the correct amplitude. By specifying a frequency of 33.3 Hz, we will obtain a more accurate estimate of a 33.3 Hz signal. Most of the time, however, the value of the transform outside the frequencies defined in the discrete transform is unreliable.

To improve its accuracy, the routine subtracts the average value of the waveform from each sample before it calculates the frequency components. To further improve the accuracy of the transform, we can apply a window function to waveform before it we call frequency_component. The window function smooths off the first and final few samples so that they converge upon the waveform's average value. We provide a linear window function with window_function.

glitch_filter

lwdaq glitch_filter threshold data

Applies a glitch filter to a sequence of real-valued samples. Any change in sample value that is equal to or greater than threshold will be assumed to be a glitch. This sample is replaced in the data sequence with the previous sample's value. We continue until the sample returns to within less than threshold of the standing value. A threshold value of 0 disables the filter.

As an example, we would have:

lwdaq_config -fsd 2 -fsr 1
lwdaq glitch_filter 4.8 "0 0 7 0 1 2 3 20 20 -30 8 6"
0.00 0.00 0.00 0.00 1.00 2.00 3.00 3.00 3.00 3.00 3.00 6.00 

Here we see a glitch in the third sample being removed. We also see three glitches removed, but then what looks like it might be a good data point, at 8, removed from the data and replaced with the standing value.

global_from_bcam_point

lwdaq global_from_bcam_point point mount

Transforms a point in global coordinates to a point in BCAM coordinates. It is the inverse of bcam_from_global_point. You pass it the global coordinates of a point in the point string, and the coordinates of the BCAM's kinematic mounting balls with the mount string. The routine returns the global coordinates of the point.

lwdaq global_from_bcam_point "0 1 0" "0 1 0 -1 1 -1 1 1 -1"
0.000000 2.000000 0.000000

For a description of the BCAM coordinate system, and how it is defined with respect to a BCAM's kinematic mounting balls, consult the BCAM User Manual.

global_from_bcam_vector

lwdaq global_from_bcam_vector vector mount

Transforms a vector in global coordinates to a vector in BCAM coordinates. It is the inverse of bcam_from_global_vector.

lwdaq global_from_bcam_vector "0 1 0" "0 1 0 -1 1 -1 1 1 -1"
0.000000 1.000000 0.000000

For a description of the BCAM coordinate system, and how it is defined with respect to a BCAM's kinematic mounting balls, consult the BCAM User Manual.

linear_interpolate

lwdaq linear_interpolate x_position x_y_data

Interpolates between the two-dimensional points of x_y_data to obtain an estimate of y at x=x_position. If we pass "2.5" for the x position, and "0 0 10 10" for the x-y data, the routine will return "2.500000".

matrix_inverse

lwdaq matrix_inverse matrix

Calculates the inverse of a square matrix. You pass the original matrix as a string of real numbers in matrix. The first number should be the top-left element in the matrix, the second number should be the element immediately to the right of the top-left element, and so on, proceeding from left to right, and then downwards to the bottom-right element. The command deduces the dimensions of the matrix from the number of elements, which must be an integer square. For more information about the matrix inverter, see matrix_inverse in utils.pas. The "lwdaq matrix_inverse" routine is inefficient in its use of the matrix_inverse function. The routine spends most of its time translating between TCL strings and Pascal floating point numbers. A 10x10 matrix inversion with random elements takes 1800 μs on our 1 GHz iBook, of which only 100 μs is spent calculating the inverse. The routine returns the inverse as a string of real numbers, in the same format as the original matrix.

nearest_neighbor

lwdaq nearest_neighbor point ?library?

Finds the closest point to p in a library of points. The point and the members of the library are all points in an n-dimensional space. When we call this routine, we can specify the library with the after the point by passing another string containing the library of m points. If we don't pass the library, the routine uses the library most recently passed. The routine stores the library in a global array so that it can use it again. We pass the point p as a string of n real numbers. The library we pass as a string of m×n real numbers separated by spaces. The value returned by the routine is an integer that specifies the library point that is closest to the p. The first library point we specify with integer 1 (one) and the last with integer m.

straight_line_fit

lwdaq straight_line_fit data

Fits a straight line to data, where data contains a string of numbers, alternating between x and y coordinates. The routine returns a string of three numbers: slope, intercept, and rms residual. The rms residual is the standard deviation of the difference between the straight line and the data, in the y-direction. The data "0 3 1 5 2 7 5 13" would represent a straight line with slope 2, intercept 3, and rms residual 0. The result would be "2.000000 3.000000 0.000000".

sum_sinusoids

lwdaq sum_sinusoids a.amplitude a.phase b.amplitude b.phase

Adds two sinusoidal waves of the same frequency together. You specify the two waves with their amplitude and phase. The phase must be in radians. The amplitude is dimensionless. The result contains the amplitude and phase of the sum of the two waves. If we pass the numbers "1 0 1 0.1" to the routine, it will return "1.997500 0.050000".

window_function

lwdaq window_function extent data

Applies a linear window function to a series of samples. The window function affects the first and last extent samples in data. The window function calculates the average value of the data, and then scales the deviation of the first and last extent samples so that the first sample and the last sample are now equal to the average, while the deviation of the other affected samples increases linearly up to the edge of the affected sample range. The function returns a new data string with the same number of samples, but the first and last samples are guaranteed to be the same. The window function is useful for preparing data for fourier transforms.

As an example, we would have:

lwdaq_config -fsd 2 -fsr 1
lwdaq window_function 5 "0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1"
0.50 0.40 0.30 0.20 0.10 0.00 0.00 0.00 0.00 0.00 1.00 1.00 1.00 1.00 1.00 0.90 0.80 0.70 0.60 0.50 

Here we see a step function being windowed so that the ends are at the average value. Note that we set the fsd (field size decimal) and fsr (field size real) configuration parameters so that we can get the output data all on one line.

wps_wire_plane

lwdaq wps_source_plane wire_center wire_rotation camera

Calculates the plane that must contain the center-line of a wire given the position and rotation of a wire image in a WPS camera. The units for wire position are millimeters, and for rotation are milliradians. We use the camera's calibration constants to determine the plane. We specify the plane in WPS coordinates, which are defined in the same way as BCAM coordinates, using the positions of the WPS (or BCAM) mounting balls. For a description of the BCAM coordinate system, consult the BCAM User Manual.

lwdaq wps_wire_plane "1.720 1.220" "0.000" "Q0131_1 0 0 0 -10 0 0 0 0 0"
0.000000 0.000000 0.000000 0.000000 0.000000 1.000000

The image position in our example is 1.720 mm from the right and 1.220 mm from the top. This is at the nominal center point of a TC255 image sensor. The wire is rotated by 0 mrad anti-clockwise in the image. The first element in the camera string is the name of the camera, even though this calculation does not use the camera name. In the example above, Q0131_1 is the camera name. It is camera number one on the WPS with serial number Q0131. In this example, the camera pivot point is at (0,0,0) in WPS coordinates, which puts it at the center of the cone ball supporting the WPS. That's clearly impossible, but we're just using simple numbers to illustrate the routine. The center of the image sensor (the CCD) is at (-10,0,0). The x-axis runs directly through the pivot point and the center of the sensor. The rotation of the sensor is (0,0,0), which means the x-axis is perpendicular to the sensor surface. Here is another example.

lwdaq wps_wire_plane "1 1.220" "10.000" "Q0131_1 0 0 0 -10 0 0 0 0 0"
0.000000 0.000000 0.000000 0.071811 0.009974 0.997368

The routine calculates the plane that contains the center of the image and the pivot point. It specifies the plane as the pivot point, which is a point in the plane, and a normal to the plane. The first three numbers in the result are the coordinates of the pivot point. The last three numbers are the normal to the plane. The normal is a unit vector.

xyz_line_plane_intersection

lwdaq xyz_line_plane_intersection line plane

Determines the point at which a line and a plane intersect. We specify the line with a point and a direction. We specify the plane with a point and a normal vector.

xyz_plane_plane_intersection

lwdaq xyz_plane_plane_intersection plane_1 plane_2

Determines the line along which two planes intersect. We specify each plane with a point in the plane and a normal to the plane, making six numbers for each plane.

Driver.tcl

Driver.tcl defines procedures that communicate with data acquisition drivers and system controllers through TCPIP sockets. The Driver.tcl routines call the sockeet-handling routines defined in Utils.tcl.

LWDAQ_byte_poll

proc LWDAQ_byte_poll {sock addr value} 

LWDAQ_byte_poll tells the relay at the other end of TCPIP socket $sock to wait until the byte it reads from address $addr has value $value. The value we pass to the routine is a string of characters that represent a decimal number. The routine converts this string into a binary byte. The strings "-1" and "255" both get converted into the same binary value, 255, which is -1 in 2's compliment.

LWDAQ_byte_read

proc LWDAQ_byte_read {sock addr} 

LWDAQ_byte_read reads a byte from the controller address space on a driver. The read takes place through a socket open with the driver called $sock, and reads a byte from controller address $addr. The routine returns the byte as a decimal number. The addr parameter is a string of characters representing a decimal number. The routine translates the parameter into a four-byte integer before transmitting it to the driver. The routine returns a string of characters that represents a decimal number.

LWDAQ_byte_write

proc LWDAQ_byte_write {sock addr value} 

LWDAQ_byte_write writes byte $value through TCPIP socket $sock to controller address $addr. The addr and value parameters are strings of characters that represent decimal numbers. The routine translates these into a four-byte integer and a single-byte value before transmitting them to the driver.

LWDAQ_config_read

proc LWDAQ_config_read {sock} 

LWDAQ_config_read reads the configuration parameters from the LWDAQ relay at the other end of an open TCPIP socket $sock, and returns them if they are valid. If the contents are not valid, the routine reports an error. The parameters the routine reads are those in the relay's RAM. These are the the ones in effect on the relay. They are not the ones written in the relay's EEPROM configuration file. There is no way to read the EEPROM configuration directly. The EEPROM parameters are loaded into ram after a hardware reset, which can be performed by pressing a button on the driver, or with LWDAQ_relay_reboot.

LWDAQ_config_write

proc LWDAQ_config_write {sock config} 

LWDAQ_config_write writes $config to the configuration EEPROM on the relay. The new configuration parameters will not take effect until you reboot the driver. Until then, the existing parameters in the driver's RAM will remain in effect.

LWDAQ_controller_reset

proc LWDAQ_controller_reset {sock} 

LWDAQ_controller_reset writes the value 1 to the software reset byte on a controller at the other end of socket $sock, thus resetting all its state machines and registers. The relay remains unaffected.

LWDAQ_delay_seconds

proc LWDAQ_delay_seconds {sock value} 

LWDAQ_delay_seconds tells a driver at the other end of $sock to pause for $value seconds. The routine does not itself take $value seconds, but the driver will be busy for $value seconds after it receives the delay instructions. If the delay is larger than $LWDAQ_Driver(max_delay_seconds) then the routine submits multiple delay jobs to create a total delay of $value seconds.

LWDAQ_driver_init

proc LWDAQ_driver_init {} 

LWDAQ_driver_init initializes the global variable LWDAQ_Driver that describes the LWDAQ Relay and LWDAQ Controller sections of the LWDAQ Driver.

LWDAQ_echo

proc LWDAQ_echo {sock s} 

LWDAQ_echo takes a string and sends it to a driver in an echo message. It waits for a data return message containing a string, which should match the string it sent.

LWDAQ_execute_job

proc LWDAQ_execute_job {sock job} 

LWDAQ_execute_job tells a driver to execute job with job identifier $job through socket $sock. The driver will be busy thereafter for however long it takes to execute the job, but the routine will return as soon as the TCPIP messages required to instruct the driver have been transmitted. Note that if you have lazy_flush set to 1, the job won't execute until you flush the socket, close it, or read from it. The job parameter is a string of characters representing a decimal number.

LWDAQ_firmware_version

proc LWDAQ_firmware_version {sock} 

LWDAQ_firmware_version reads the controller's firmware version number through open socket $sock, and returns the version.

LWDAQ_hardware_id

proc LWDAQ_hardware_id {sock} 

LWDAQ_hardware_id reads the controller identifier number from the LWDAQ driver at the other end of TCPIP socket $sock, and returns the identifier.

LWDAQ_hardware_version

proc LWDAQ_hardware_version {sock} 

LWDAQ_hardware_version reads the controller's hardware version number through open socket $sock, and returns it.

LWDAQ_integer_write

proc LWDAQ_integer_write {sock addr value} 

LWDAQ_integer_write writes a four-byte integer $value through open TCPIP socket $sock to controller address $addr. The addr and value parameters are strings of characters that represent decimal numbers.

LWDAQ_job_done

proc LWDAQ_job_done {sock} 

LWDAQ_job_done returns 1 if the driver's job register reads back zero, and 1 otherwise.

LWDAQ_login

proc LWDAQ_login {sock password {error_on_fail 1}} 

LWDAQ_login attempts to log into a LWDAQ relay with a login message and password $password. The routine recognises "no_password" as a key phrase to skip the login attempt and return the value 0. Otherwise, the routine sends the password and waits for an answer from the relay. An answer of 1 is success and 0 is failure. On success, the routine returns 1. On failure, the routine will generate an error by default, or return -1 if you pass the value 0 for error_on_fail.

LWDAQ_loop_time

proc LWDAQ_loop_time {sock} 

LWDAQ_loop_time reads the contents of a LWDAQ Driver's loop timer register and returns it. The driver is at the other end of an open TCPIP socket named $sock.

LWDAQ_mac_read

proc LWDAQ_mac_read {sock} 

LWDAQ_mac_read reads the mac address of the Ethernet chip on the LWDAQ relay at the other end of open TCPIP socket $sock, and returns the address as a string of hexadecimal characters.

LWDAQ_most_recent_byte

proc LWDAQ_most_recent_byte {sock} 

LWDAQ_most_recent_byte reads the contents of a LWDAQ Driver's mrb register and returns it. The driver is at the other end of an open TCPIP socket named $sock. The mrb register contains the most recent byte to be written to the Driver's ram, either by the relay or by the controller.

LWDAQ_off

proc LWDAQ_off {sock} 

LWDAQ_off turns off power to all devices connected to the driver listening at the other end of $sock.

LWDAQ_on

proc LWDAQ_on {sock} 

LWDAQ_on turns on power to all devices connected to the driver listening at the other end of $sock.

LWDAQ_ram_delete

proc LWDAQ_ram_delete {sock addr length {value 0}} 

LWDAQ_ram_delete sets the LWDAQ Controller's data address equal to $addr and then clears a block of $length bytes starting from address $addr in the LWDAQ Controller memory. The bytes are set to zero unless another value is passed to the routine. The addr, length, and value parameter are character strings representing decimal numbers.

LWDAQ_ram_read

proc LWDAQ_ram_read {sock addr length} 

LWDAQ_ram_read sets the LWDAQ Controller's data address equal to $addr, reads $length consecutive bytes from this same address location, and returns these bytes as a byte array. The routine is intended for use with a RAM portal, where each consecutive read from the portal returns a consecutive byte in RAM. The addr and length parameters are character strings representing decimal numbers.

LWDAQ_ram_write

proc LWDAQ_ram_write {sock addr data} 

LWDAQ_ram_write sets the LWDAQ Controller's data address equal to $addr and writes a block of data byte by byte into the RAM Portal. The addr parameter is a string of characters representing a decimal number. The data parameter is a block of binary bytes.

LWDAQ_receive_byte

proc LWDAQ_receive_byte {sock} 

LWDAQ_receive_byte receives a data return message and scans its contents for single-byte integer. It returns this integer as a string of characters representing a decimal number.

LWDAQ_receive_data

proc LWDAQ_receive_data {sock} 

LWDAQ_receive_data receives a LWDAQ Message Protocol data return message from a socket and returns the message contents. The routine returns the data as a block of binary bytes. It supports the lwdaq protocol only.

LWDAQ_receive_integer

proc LWDAQ_receive_integer {sock} 

LWDAQ_receive_integer receives a data return message and scans its contents for a four-byte integer in big-endian byte order (most significant byte received first). The routine returns a string of characters that represent a decimal number.

LWDAQ_relay_reboot

proc LWDAQ_relay_reboot {sock} 

LWDAQ_relay_reboot resets the relay without affecting the controller. This routine is supported only by relay software versions thirteen and up.

LWDAQ_set_base_addr_hex

proc LWDAQ_set_base_addr_hex {sock value} 

LWDAQ_set_base_addr_hex sets the four bytes of the driver's base address to $value. The value parameter is a string of characters representing an eight-digit hexadecimal number, plus an optional colon and number as in daq_driver_socket of an instrument configuration. The routine uses only the hex number. The routine translates the character string into a four-byte integer. The driver is at the other end of open TCPIP socket $sock. The base address register exists in LWDAQ components like the VME-TCPIP Interface (A2064), where it sets the base position in VME address space of the LWDAQ Driver with VME Interface to which subsequent instructions to the A2064 should be directed. We call this routine whenever we open a TCPIP socket to a LWDAQ component. The routine accepts a hex number followed by a colon and an integer "00E00000:7". It uses the hex number before the colon as the base address.

LWDAQ_set_command_reg

proc LWDAQ_set_command_reg {sock value} 

LWDAQ_set_command_reg sets a driver's command register to $value through TCPIP socket $sock. The value parameter is a string of characters representing a decimal number. This decimal number will be translated into a sixteen-bit value before transmission to the driver.

LWDAQ_set_command_reg_binary

proc LWDAQ_set_command_reg_binary {sock value} 

LWDAQ_set_command_reg_binary sets a driver's command register to $value, where $value is a binary string representation of the register's sixteen bits.

LWDAQ_set_command_reg_hex

proc LWDAQ_set_command_reg_hex {sock value} 

LWDAQ_set_command_reg_hex sets a driver's command register to $value, where $value is a hexadecimal string representation of the register's sixteen bits.

LWDAQ_set_data_addr

proc LWDAQ_set_data_addr {sock value} 

LWDAQ_set_data_addr sets the four bytes of the driver's data address to $value. The driver is at the other end of open TCPIP socket $sock. The value parameter is a string of characters representing a decimal number.

LWDAQ_set_delay_seconds

proc LWDAQ_set_delay_seconds {sock value} 

LWDAQ_set_delay_seconds sets a driver's delay timer to a number of ticks that will count down to zero in $value seconds. The driver is at the other end of TCPIP socket $sock. The value parameter is a character string representing a decimal number.

LWDAQ_set_delay_ticks

proc LWDAQ_set_delay_ticks {sock value} 

LWDAQ_set_delay_ticks sets a driver's delay timer to $value through socket $sock. The value parameter is a character string representing a decimal number.

LWDAQ_set_device_addr

proc LWDAQ_set_device_addr {sock value} 

LWDAQ_set_device_addr sets the device address register on a driver to $value through TCPIP socket $sock. The driver will be busy with this instruction for a few tens of microseconds thereafter, as it switches its driver sockets and transmits a new address down the newly active socket. The value parameter is a character string representing a decimal number.

LWDAQ_set_device_element

proc LWDAQ_set_device_element {sock value} 

LWDAQ_set_device_element sets a driver's device type register to $value through socket $sock. The value parameter is a character string representing a decimal number.

LWDAQ_set_device_type

proc LWDAQ_set_device_type {sock value} 

LWDAQ_set_device_type sets a driver's device type register to $value through socket $sock. The value parameter is a character string representing a decimal number.

LWDAQ_set_driver_mux

proc LWDAQ_set_driver_mux {sock driver {mux 1}} 

LWDAQ_set_driver_mux sets the device address register on a driver so as to select driver socket $driver and multiplexer socket (also known as the branch socket) $mux. The driver will be busy for a few tens of microseconds thereafter, as it switches target sockets. The driver socket can be a simple integer specifying the socket on a LWDAQ driver, or it can be of the form b:a, where "b" is a 32-bit "base address" expressed as an eight-digit hex string, and "a" is a decimal number. The base address selects one of several drivers associated with $sock. We might have a VME crate holding twenty LWDAQ Drivers (A2037A) and a single VME-TCPIP interface (A2064). The $sock connection is with the A2064, and we instruct the A2064 to select one of the twenty drivers using "b" in $driver. For example, 00E0000:3 would select the driver at VME base address hexadecimal 00E00000, and socket 3 within that driver. If we do not specify a base address, the routine does not bother setting the base address on the TCPIP interface at $sock. It uses $driver as the decimal socket number.

LWDAQ_set_repeat_counter

proc LWDAQ_set_repeat_counter {sock value} 

LWDAQ_set_repeat_counter sets a driver's repeat counter to $value through socket $sock. The value parameter is a character string representing a decimal number.

LWDAQ_shortint_write

proc LWDAQ_shortint_write {sock addr value} 

LWDAQ_shortint_write writes a two-byte integer $value through open TCPIP socket $sock to controller address $addr. The addr and value parameters are strings of characters that represent decimal numbers.

LWDAQ_sleep

proc LWDAQ_sleep {sock} 

LWDAQ_sleep sends a driver's target device to sleep through $sock.

LWDAQ_software_version

proc LWDAQ_software_version {sock} 

LWDAQ_software_version fetches the relay software version from a driver through an open socket $sock.

LWDAQ_start_job

proc LWDAQ_start_job {sock job} 

LWDAQ_start_job tells a driver to begin a job execution by writing job identifier $job to the job register at socket $sock. The job parameter is a string of characters representing a decimal number.

LWDAQ_stream_delete

proc LWDAQ_stream_delete {sock addr stream_length value} 

LWDAQ_stream_delete writes a constant byte value repeatedly to the same controller address, so as to clear consecutive memory locations. It is like the stream read in reverse, except the data value is always $value, where $value is a string of digits that represent a decimal value. The addr, stream_length, and value parameters are all strings of characters that represent decimal numbers. The routine translates the strings into two four-byte integers and a byte value respectively before transmitting them to the driver.

LWDAQ_stream_read

proc LWDAQ_stream_read {sock addr stream_length} 

LWDAQ_stream_read reads $stream_length bytes out of controller address $addr on the driver at the other end of TCPIP socket $sock, and returns the entire stream. The routine is intended for use with the controller's stream read location, which presents consecutive bytes in the controller RAM on consecutive reads by the relay. The addr and stream_length parameters are strings of characters that represent decimal numbers. The routine translates both into four-byte integers before transmitting them to the driver. The routine returns a block of binary data.

LWDAQ_stream_write

proc LWDAQ_stream_write {sock addr data} 

LWDAQ_stream_write writes a block of bytes to the same controller address so as to transfer them into a memory block through a memory portal. It is like the stream read in reverse. The addr parameter is a strings of characters that represents decimal number. The data parameter is a block of binary bytes that will be transmitted without modification. The routine translates the addr string into a four-byte integer before transmitting to the driver.

LWDAQ_transmit_command

proc LWDAQ_transmit_command {sock value} 

LWDAQ_transmit_command instructs a driver to transmit LWDAQ command $value to its current target device. The routine instructs the driver through open TCPIP socket $sock. The driver will be busy for a few microseconds thereafter as it transmits the command, but the routine will return almost immediately. Note that if you have lazy_flush set to 1, the messages produced by the routine will remain in $sock's output buffer until you flush the socket, close it, or read from it. The value parameter is a string of characters representing a decimal number.

LWDAQ_transmit_command_binary

proc LWDAQ_transmit_command_binary {sock value} 

LWDAQ_transmit_command_binary is the same as LWDAQ_transmit_command except it takes a binary string representation of the command value. Thus "0001001001001000" represents command "1248" in hexadecimal notation, or "4680" in decimal.

LWDAQ_transmit_command_hex

proc LWDAQ_transmit_command_hex {sock value} 

LWDAQ_transmit_command_hex is the same as LWDAQ_transmit_command except it takes a hexadecimal string representation of the command value. Thus "1248" represents command "4680" in decimal and "FFFF" represents "1111111111111111" as a binary string.

LWDAQ_transmit_message

proc LWDAQ_transmit_message {sock id contents} 

LWDAQ_transmit_message sends a message through a socket. The routine detects which protocol the socket uses and formats the message accordingly. The message identifier is passed to the procedure in $id and the contents are in $contents. The routine supports the lwdaq and basic message formats. The id parameter is a string of chracters that represent a decimal number. The contents parameter is a block of binary bytes.

LWDAQ_wait_for_driver

proc LWDAQ_wait_for_driver {sock {approx 0}} 

LWDAQ_wait_for_driver waits until the driver has finished executing all pending commands. If you expect the commands to take more than a few seconds, specify how long you expect them to take with the optional $approx parameter. By specifying the approximate delay, you allow this routine to avoid a TCPIP read timeout.

LWDAQ_wake

proc LWDAQ_wake {sock} 

LWDAQ_wake wakes up a driver's target device through socket $sock.

Init.tcl

Init.tcl is the initialization script that calls all other LWDAQ program scripts. Here we set the LWDAQ environment variables in the LWDAQ_Info array.

LWDAQ_init

proc LWDAQ_init {} 

LWDAQ_init initializes the LWDAQ application. As we modify the scripts, we can call this routine from the console instead of quitting and re-starting the LWDAQ program. We include error-catching in the LWDAQ_init to protect against the interpreter aborting when we start up. The only things that LWDAQ_init will run again is itself and the lwdaq.so, which it will not re-load. If you modify either the dynamic library or this initialization procedure, you must close and re-start the application to implement your changes.

LWDAQ_stdin_console_execute

proc LWDAQ_stdin_console_execute {} 

LWDAQ_stdin_console_execute executes a command supplied from the stdin console, if it exists, and writes the result to the stdout console.

LWDAQ_stdin_console_prompt

proc LWDAQ_stdin_console_prompt {} 

LWDAQ_stdin_console_prompt writes the LWDAQ prompt to the stdin console.

LWDAQ_stdin_console_start

proc LWDAQ_stdin_console_start {} 

LWDAQ_stdin_console_start turns the standard input, which will exist when we start LWDAQ from a terminal on UNIX, LINUX, and even Windows and MacOS. The console is primitive in its current incarnation: no up or down-arrow implementation to give you previous commands, no left or right arrows to navigate through the command. But it's better than nothing.

Instruments.tcl

Instruments.tcl contains the routines that set up the common foundations upon which all LWDAQ instruments are built.

LWDAQ_acquire

proc LWDAQ_acquire {instrument} 

LWDAQ_acquire acquires data for the instrument called $instrument from either a file, or an existing image in memory, or directly from the daq. It returns a result string.

LWDAQ_acquire_button

proc LWDAQ_acquire_button {name} 

LWDAQ_acquire_button is for use with instrument acquire buttons.

LWDAQ_close

proc LWDAQ_close {name} 

LWDAQ_close closes the window of the named instrument.

LWDAQ_info_button

proc LWDAQ_info_button {name} 

LWDAQ_info_button makes a new toplevel window with a button that lets you see the instrument script. Below the button are the elements of the instrument's info array. You can change the elements by typing in the entry boxes.

LWDAQ_instrument_analyze

proc LWDAQ_instrument_analyze {instrument {id ""}} 

LWDAQ_instrument_analyze calls an instrument's analysis routine after checking its analysis_enable flag, and catches errors from the analysis routine. It assumes that the image it is to analyze is the image named in the instrument's memory_name parameter. The routine places an identifier in the result, as provided by the id parameter. By default, id becomes the memory name. The routine also prints the result to the panel text window.

LWDAQ_instrument_print

proc LWDAQ_instrument_print {instrument s {color black}} 

LWDAQ_instrument_print prints the result of analysis to an instrument text window using LWDAQ_print. If the verbose_result is set in the instrument's config array, then the routine uses the verbose_description list in the info array to describe each element of the result on on separate lines. We intend for this routine to be used only for printing instrument results in the instrument window. If you want to print anything else in the instrument window, use LWDAQ_print with the text window name $info(text). The info(text) element is set even if the instrument window is not open, and LWDAQ_print checks to see if the text window exists before it prints.

LWDAQ_instruments_init

proc LWDAQ_instruments_init {} 

LWDAQ_instruments_init initializes the instruments routines.

LWDAQ_loop_button

proc LWDAQ_loop_button {name} 

LWDAQ_loop_button is for use with instrument loop buttons.

LWDAQ_open

proc LWDAQ_open {name} 

LWDAQ_open opens the named instrument's window. We recommend that you post this routine to the event queue, or else it will conflict with acquisitions from the same instrument that are taking place with the window closed.

LWDAQ_read_button

proc LWDAQ_read_button {name} 

LWDAQ_read_button reads an image from disk. It allows the user to specify multiple files, and opens them one after another.

LWDAQ_reset_instrument_counters

proc LWDAQ_reset_instrument_counters {{value 0}} 

LWDAQ_reset_instrument_counters sets all the counters to the specifiec value, or to 1 if no value is specified.

LWDAQ_stop_button

proc LWDAQ_stop_button {name} 

LWDAQ_stop_button is for use with instrument stop buttons.

LWDAQ_stop_instruments

proc LWDAQ_stop_instruments {} 

LWDAQ_stop_instruments stops all looping instruments.

LWDAQ_write_button

proc LWDAQ_write_button {name} 

LWDAQ_write_button writes the current image to disk

Interface.tcl

Interface.tcl creates the LWDAQ graphical user interface.

LWDAQ_about

proc LWDAQ_about {} 

LWDAQ_about creates a message box that pops up and tells us about the program.

LWDAQ_bind_command_key

proc LWDAQ_bind_command_key {window letter command} 

LWDAQ_bind_command_key binds the specified command letter to the specified command on all platforms.

LWDAQ_button_confirm

proc LWDAQ_button_confirm {s} 

LWDAQ_button_confirm opens a toplevel window called "Confirm" and prints message $s in the window. The procedure returns after the user presses a button.

LWDAQ_button_wait

proc LWDAQ_button_wait {{s ""}} 

LWDAQ_button_wait opens a toplevel window with a continue button and waits until the user presses the button before closing the window and continuing.

LWDAQ_button_warning

proc LWDAQ_button_warning {s} 

LWDAQ_button_warning opens a toplevel window called "Warning" and prints message $s in the window. The procedure returns after the user presses a button.

LWDAQ_clock_widget

proc LWDAQ_clock_widget {{wf ""}} 

LWDAQ_clock_widget creates a text widget that displays second-by-second current time. If you specify a window name, the clock widget will appear in the window, packed towards the top. Otherwise the routine creates a new toplevel window for the clock.

LWDAQ_enable_text_undo

proc LWDAQ_enable_text_undo {t} 

LWDAQ_enable_text_undo turns on a text widget's undo stack. This stack will consume memory as it gets larger, so you should leave the stack off when you are repeatedly and automatically updating the text window contents, as we do in the System Monitor or the Acquisifier windows.

LWDAQ_init_main_window

proc LWDAQ_init_main_window {} 

LWDAQ_init_main_window initialize the main window and defines the menubar.

LWDAQ_interface_init

proc LWDAQ_interface_init {} 

LWDAQ_interface_init initializes the interface routines, installs operating-system dependent event handlers, and configures the default fonts for the graphical user interface.

LWDAQ_MacOS_Open_File

proc LWDAQ_MacOS_Open_File {theAppleEvent theReplyAE} 

No description available.

LWDAQ_make_instrument_menu

proc LWDAQ_make_instrument_menu {} 

LWDAQ_make_instrument_menu destroys the current instrument menu and makes a new one that matches the current list of instruments.

LWDAQ_make_tool_menu

proc LWDAQ_make_tool_menu {} 

LWDAQ_make_tool_menu destroys the current tool menu and makes a new one that matches the current selection of tools in the Tools folder.

LWDAQ_monitor_open

proc LWDAQ_monitor_open {} 

LWDAQ_monitor_open opens the system monitor window.

LWDAQ_monitor_refresh

proc LWDAQ_monitor_refresh {} 

LWDAQ_monitor_refresh updates the system monitor window, if it exists, and posts itself for re-execution in the TCL event loop.

LWDAQ_open_document

proc LWDAQ_open_document {fn} 

LWDAQ_open_document takes a file name and opens the file according to its file extensions. On MacOS, we call this procedure from tk::mac::OpenDocument.

LWDAQ_print

proc LWDAQ_print {args} 

LWDAQ_print prints a string to the end of a text device. The text device can be a text window or a file. When the routine writes to a text window, it does so in a specified color, unless the string begins with "ERROR: " or "WARNING: ", in which case the routine picks the color itself. If you pass "-nonewline" as an option after LWDAQ_print, the routine does not add a carriage return to the end of the print string. The routine also recognises "-newline", which is the default. The routine assumes the text device is a text window if its name starts with a period and this period is not followed by a forward slash or a backslash. If the text window exists, the routine writes the print string to the end of the window. If the text device is either "stdout" or "stderr", the routine writes directly to these channels. If the text device is a file name and the directory of the file exists, the routine appends the string to the file, or creates the file if the file does not exist. The routine will not accept any file name that contains a space, is an empty string, or is a real number. If the routine cannot find any valid device that matches the device name, it will write the print string to stdout when the global default_to_stdout flag is set.

LWDAQ_reset

proc LWDAQ_reset {} 

LWDAQ_reset stops all instruments, closes all sockets, stops all vwaits, and the event queue, sets the global reset variable to 1 for a period of time, and then sets all the instrument control variables to Idle.

LWDAQ_save_text_window

proc LWDAQ_save_text_window {window_name file_name} 

LWDAQ_save_text_window saves the contents of text window $window_name to a file named $file_name.

LWDAQ_server_accept

proc LWDAQ_server_accept {sock addr port} 

LWDAQ_server_accept is called when a remote control socket opens. The first thing the routine does is check that the IP address of the TCPIP client matches the server's address_filter. The routine installs the LWDAQ_server_interpreter routine as the incoming data handler for the remote control socket, and it lists the new socket in the LWDAQ open socket list.

LWDAQ_server_info

proc LWDAQ_server_info {{sock "nosocket"}} 

LWDAQ_server_info returns a string giving the name of the specified socket. The routine is intended for use within the System Server, where we pass the name of a socket to the routine, and it returns the name and various other pieces of system information. If, however, you call the routine from the console or within a script, it will return the same information, but with the socket name set to its default value. When you send the command "LWDAQ_server_info" to the System Server over a System Server socket, the System Server calls LWDAQ_server_info with the name of this same socket, and so returns the socket name along with the system information. The elements returned by the routine are a socket number, the time in seconds, the local platform, the program patchlevel, and the TCL version.n

LWDAQ_server_interpreter

proc LWDAQ_server_interpreter {sock} 

LWDAQ_server_interpreter receives commands from a TCPIP socket

LWDAQ_server_open

proc LWDAQ_server_open {} 

LWDAQ_server_open opens the remote control window. In the window, you specify an IP address match string to filter incoming connection requests. You specify the IP port to at whith LWDAQ should listen. You provide match strings for the commands that the remote control command interpreter should process. When you press Run, the remote controller is running and listening. When you press Stop, it stops. You cannot adjust the listening port while the remote controller is running.

LWDAQ_server_start

proc LWDAQ_server_start {} 

LWDAQ_server_start starts up the remote control server socket.

LWDAQ_server_stop

proc LWDAQ_server_stop {} 

LWDAQ_server_stop stops the remote control server socket, and closes all open sockets.

LWDAQ_text_widget

proc LWDAQ_text_widget {wf width height {scrolly 1} {scrollx 0}} 

LWDAQ_text_widget opens a text window within the specified window frame. The text window has its "undo" stack turned off. The text widget is a subwindow of $wf, and has name $wf.text, and it is this name that is returned by the routine. By default, the window has a y scrollbar, but no x scrollbar. If we have an x scrollbar we turn off the text wrapping.

LWDAQ_toplevel_text_window

proc LWDAQ_toplevel_text_window {{width 84} {height 30}} 

LWDAQ_toplevel_text_window creates a new text window. It returns the name of the toplevel window containing the text widget. You can construct the name of the text widget itself by adding .text to the window name.

LWDAQ_toplevel_window

proc LWDAQ_toplevel_window { {title ""} } 

LWDAQ_toplevel_window will make a new top-level window with a unique name, and returns its name.

LWDAQ_view_array

proc LWDAQ_view_array {array_name} 

LWDAQ_view_array opens a new window that displays the contents of a global TCL array. It and allows you to change the values of all elements in the array.

LWDAQ_view_text_file

proc LWDAQ_view_text_file {file_name} 

LWDAQ_view_text_file reads a text file into a new top-level text window. The routine returns the name of the top-level window. The name of the text widget used to display the file is $w.text, where $w is the top-level window name.

LWDAQ_widget_list

proc LWDAQ_widget_list {w} 

LWDAQ_widget_list returns a list of all existing children of the window or widget you pass to the routine. If you pass just ".", then the routine will list all existing widgets and windows. The routine calls itself recursively.

Tools.tcl

Tools.tcl contains routines that configure and manage polite and standard LWDAQ tools. It provides the Tool Maker and Run Tool commands for the Tool menu.

LWDAQ_obsolete_names

proc LWDAQ_obsolete_names {} 

LWDAQ_obsolete_names returns a list of obsolete names and their new values.

LWDAQ_read_script

proc LWDAQ_read_script {{file_name ""}} 

LWDAQ_read_script reads a text file, which we assume to be a LWDAQ tool, or some script that serves a LWDAQ tool. The routine substitutes new names for obsolete names. To see the substitutions the current version of the routine performs, enter LWDAQ_obsolete_names at the console prompt, and it will print a list of obsolete names and their new values. If LWDAQ_read_script finds obsolete names, and it also sees that LWDAQ_Info(quiet_update) is not set, it opens a window, warns the user which obsolete names the script file contains, and asks if the user wants to update the script file with a new file that contains the new names.

LWDAQ_run_tool

proc LWDAQ_run_tool {{file_name ""}} 

LWDAQ_run_tool executes a tool script at the global scope. To read the tool file, the routine uses LWDAQ_read_script, which replaces obsolete parameter and procedure names with their new names. If the routine cannot find the script file, it looks in the Tools folder and the Tools/More folder.

LWDAQ_tool_configure

proc LWDAQ_tool_configure {name} 

LWDAQ_tool_configure opens a configuration window so we can set a tool's configuration array elements. It also provides for extra configuration buttons by returning the name of a frame below the Save button.

LWDAQ_tool_data

proc LWDAQ_tool_data {name} 

LWDAQ_tool_data extracts data lines from a tool's script and returns them as a string. The routine trims white spaces from the start and end of the data.

LWDAQ_tool_help

proc LWDAQ_tool_help {name} 

LWDAQ_tool_help extracts help lines from the tool script and prints them in the tool's text window.

LWDAQ_tool_init

proc LWDAQ_tool_init {name version} 

LWDAQ_tool_init replaces LWDAQ_tool_startup in newer tools. It provides more functionality, and requires that the calling routine, which we assume is a tool initializer, checks to see if the tool window exists. If so, the calling routine should abort. This routine drops support for the embedding of tools in the main window when they are alone in the startup directory. For full support for tool Help and Data, which we extract from the script files, make sure the tool script is in the Tools or Tools/More directory.

LWDAQ_tool_open

proc LWDAQ_tool_open {name} 

LWDAQ_tool_open opens a tool window if none exists. It checks to see if the window is already open, and if so it raises the window to the front and returns an empty string. The calling routine should check to see if this routine returns an empty string, and if so it should not attempt to perform any graphics operations in the existing window without checking for itself the mode in which LWDAQ is running: in no graphics mode, all graphics routines will fail.

LWDAQ_tool_save

proc LWDAQ_tool_save {name} 

LWDAQ_tool_save writes a tool's configuration array to disk.

LWDAQ_tool_startup

proc LWDAQ_tool_startup {name} 

LWDAQ_tool_startup initializes the tool directory and file variables. We are retiring this routine, but keep in for backward-compatibility with older versions of LWDAQ. Before LWDAQ 7.1.10, a solitary too script in the Startup directory would use the main TK window, which is the one called ".". But we dropped this feature in 7.1.10.

LWDAQ_Toolmaker

proc LWDAQ_Toolmaker {} 

LWDAQ_Toolmaker makes a new toplevel window for the Toolmaker. You enter a sequence of commands in the text window, and you can execute this sequence, which we call a script, with the Execute button. When you press Execute, your script will disappear from the text window, but you can make it re-appear with the Back button. The Toolmaker keeps a list of the scripts you have executed, and allows you to navigate and edit the list with the Forward, Back, and Clear buttons. You can save the list to a file with Save, and read a previously-saved list with Load. The file will contain all your scripts delimited by XML-style marks at the beginning and end of each script respectively. For each Execute, Toolmaker creates a new toplevel text window. You can print to the lower one (which is intended for results) by referring to it as $t, and using it with a text widget routine like LWDAQ_print, or calling it directly with its TK widget command, $t.

LWDAQ_Toolmaker_back

proc LWDAQ_Toolmaker_back {} 

LWDAQ_Toolmaker_back clears the script text window, decrements the script index, and displays the previous script in the Toolmaker comamnd list.

LWDAQ_Toolmaker_delete

proc LWDAQ_Toolmaker_delete {} 

LWDAQ_Toolmaker_delete deletes the current entry from the script list.

LWDAQ_Toolmaker_delete_all

proc LWDAQ_Toolmaker_delete_all {} 

LWDAQ_Toolmaker_delete_all clears all entries from the script list.

LWDAQ_Toolmaker_execute

proc LWDAQ_Toolmaker_execute {{save 1}} 

LWDAQ_Toolmaker_execute extracts the script in the Toolmaker's text window, appends it to the Toolmaker script list, writes the script to a new toplevel text window, and executes the script at the global level. It prints out results as the script requires, and print errors in red when they occur. The script can refer to the text widget with the global variable "t". Above the text window is a frame, "f", also declared at the global level, which is packed in the top of the window, but empty unless the script creates buttons and such like to fill it.

LWDAQ_Toolmaker_forward

proc LWDAQ_Toolmaker_forward {} 

LWDAQ_Toolmaker_forward clears the script window, increments the script index, and displays the next script in the Toolmaker script list. If you have reached the end of the list, it displays a blank screen, ready for a fresh script.

LWDAQ_Toolmaker_load

proc LWDAQ_Toolmaker_load {{file_name ""}} 

LWDAQ_Toolmaker_load reads a previously-saved script library or an individual script from a file and appends the script or scripts to the current script list.

LWDAQ_Toolmaker_repeat

proc LWDAQ_Toolmaker_repeat {} 

LWDAQ_Toolmaker_repeat executes the previous script without adding a copy of it to the list of scripts.

LWDAQ_Toolmaker_save

proc LWDAQ_Toolmaker_save {{file_name ""}} 

LWDAQ_Toolmaker_save saves the current Toolmaker script list to a file.

LWDAQ_tools_init

proc LWDAQ_tools_init {} 

LWDAQ_tools_init initializes the Tools routines.

Utils.tcl

Utils.tcl contains file input-output routines, the LWDAQ event queue, time and date routines, debug and diagnostic routines, and LWDAQ help routines. The LWDAQ Event Queue is an event scheduler that allows us to perform simultaneous live data acquisition from multiple instruments by scheduling the acquision actions so they do not overlap with one another.

LWDAQ_close_all_sockets

proc LWDAQ_close_all_sockets {} 

LWDAQ_close_all_sockets closes all open sockets.

LWDAQ_command_reference

proc LWDAQ_command_reference { {file_name ""} } 

LWDAQ_command_reference generates the LWDAQ software command reference manual automatically, using ./Sources/lwdaq.pas and ./LWDAQ.app/Contents/LWDAQ/CRT.html.

LWDAQ_debug_dump

proc LWDAQ_debug_dump {s} 

LWDAQ_debug_dump opens a file called debug_dump.txt in the program directory and appends a string to the end of it, then closes the file.

LWDAQ_decimal_to_binary

proc LWDAQ_decimal_to_binary {decimal {length 32}} 

LWDAQ_decimal_to_binary takes a decimal integer, $decimal, and returns the least significant $length digits of its binary representation as a string of ones and zeros. By default, $length is 32, which is also the maximum value of $length supported by the routine. We include comment in the code to explain our use of binary format and binary scan. It turns out that we have to use both these routines to achieve our end. First we format the integer as a binary object, then we scan this binary object for its bits.

LWDAQ_get_dir_name

proc LWDAQ_get_dir_name {} 

LWDAQ_get_dir_name opens a file browser and allows you to select a directory.

LWDAQ_get_file_name

proc LWDAQ_get_file_name {{multiple 0}} 

LWDAQ_get_file_name opens a file browser window and allows the user to select one or more files in the file system. The user can select multiple files when multiple is one (1). By default, multiple is zero (0).

LWDAQ_global_var_name

proc LWDAQ_global_var_name {} 

LWDAQ_global_var_name will return a unique name for a global variable.

LWDAQ_html_contents

proc LWDAQ_html_contents { {cell_spacing 4} {num_columns 4} {file_name ""} } 

LWDAQ_html_contents creates a table of contents for an HTML document. Each h2 and h3 level heading must have a unique name in the document, because this routine uses the heading text as the identifier for each heading line. The table of contents will be placed underneath an h2 heading with text "Contents". Any pre-existing table of contents between this h2 heading and the next h2 heading will be removed from the document. The routine takes three optional parameters. The first two are cell_spacing and num_columns for the h3 heading tables beneath each h2 heading. The third parameter is the name of the HTML file to be processed.

LWDAQ_html_split

proc LWDAQ_html_split {{file_name ""}} 

LWDAQ_html_split takes a long file with h2-level chapters and splits it into chapter files. It puts the chapter files in a new directory. If the original file is called A.html, the directory is A, and the chapters are named A_1.html to A_n.html, where n is the number of chapters. There will be another file called index.html, which is the table of contents. Each chapter provides a link to the table of contents, to the previous chapter, and to the next chapter. Each preserves the header and stylsheets used in the original file. All local html links get displaced downwards by one level in order to account for the chapters being buried in a new directory. Internal links in the document are broken, so you will have to go in and fix them by hand. Any h2-level heading called "Contents" will be removed from the list of chapter, because we assume it's a table of contents generated by the routine LWDAQ_html_contents.

LWDAQ_html_tables

proc LWDAQ_html_tables { {file_name ""} } 

LWDAQ_html_tables extracts all the tables from an HTML document and writes them to a new HTML document with Tables_ added to the beginning of the original document's file root. The routine takes one optional parameter: the name of the HTML document.

LWDAQ_image_bounds

proc LWDAQ_image_bounds {image {left ""} {top ""} {right ""} {bottom ""}} 

LWDAQ_image_bounds returns a string containing the analysis bounds of an image. You can specify new bounds with four numbers in the order left, top, right, bottom. If you specify zero (0) for the right or bottom bounds, the routine sets them to their maximum values. You can save the result of this routine in a string, change the bounds by calling the routine again, and then restore the earlier values by passing the saved string as its argument. But you have to do this with "eval" so that the TCL interpreter will break the string into four elements before passing it to LWDAQ_image_bounds.

LWDAQ_image_pixels

proc LWDAQ_image_pixels {image_name} 

LWDAQ_image_pixels returns a string containing the intensities of all pixels in the analysis boundaries of an image. The pixels form an array by use of spaces and line breaks. There is a line break at the end of each row of pixels and a space between each column. You can paste the output from this routine directly into Excel and obtain a two-dimensional intensity array.

LWDAQ_ip_addr_match

proc LWDAQ_ip_addr_match {addr_1 addr_2} 

LWDAQ_ip_addr_match takes two IP address strings and compares them to see if they point to the same driver socket. If the addresses match, the routine returns a 1. If they don't match, it returns a 0. A * in either parameter is a wild card, and will match.

LWDAQ_is_error_result

proc LWDAQ_is_error_result {s} 

LWDAQ_is_error_result returns 1 if and only if the first string begins with "ERROR: " (case sensitive).

LWDAQ_list_commands

proc LWDAQ_list_commands { {pattern *} } 

LWDAQ_list_commands lists LWDAQ commands.

LWDAQ_load_settings

proc LWDAQ_load_settings {{file_name ""}} 

LWDAQ_load_settings reads settings out of the specified settings file. If you do not specify a setting file name, the routine opens a file browser window so the user can choose a settings file.

LWDAQ_ndf_create

proc LWDAQ_ndf_create {file_name meta_data_size} 

LWDAQ_ndf_create creates a new Neuroscience Data Format file, which is the format used by LWDAQ to store archives of continuous time-series data. The NDF format begins with a four-byte format identifier, which is the string " ndf" (note the space at the beginning of the identifier string. Next come three four-byte numbers in big-endian format (most significant byte first). These are the byte offset to meta-data space, byte offset to data space, and the length of meta-data string when last written. If the length is zero, routines that read the meta-data string should check the length for themselves. The header may contain additional binary information particular to the application. The meta-data space follows the header and contains only a null-terminated character string. The data space comes next, and occupies the remainder of the file. This routine creates a new file with an empty string and no data.

LWDAQ_ndf_data_append

proc LWDAQ_ndf_data_append {file_name data} 

LWDAQ_ndf_data_append appends new data to an NDF file.

LWDAQ_ndf_data_check

proc LWDAQ_ndf_data_check {file_name} 

LWDAQ_ndf_data_check returns the byte location of the file's data block and the length of the data block. If the file is not NDF, the routine returns an error.

LWDAQ_ndf_data_read

proc LWDAQ_ndf_data_read {file_name start_addr num_bytes} 

LWDAQ_ndf_data_read reads num_bytes of data out of an NDF file data block, starting at byte start_addr. The first byte in the data block is byte zero. If you specify * for num_bytes, the routine reads all available data bytes from the file.

LWDAQ_ndf_string_append

proc LWDAQ_ndf_string_append {file_name meta_data} 

LWDAQ_ndf_string_append appends a meta-data string to the one that already exists in an NDF file. It speeds itself up by using the actual length value stored in the file header. It does not read the existing string from the file. The routine takes roughly 100 us to append a one-byte string regardless of the length of the existing string, and 1 ms to append a 10-kbyte string (on a 1.3 GHz G3 iBook).

LWDAQ_ndf_string_check

proc LWDAQ_ndf_string_check {file_name} 

LWDAQ_ndf_string_check returns the byte location of the file's meta-data string, the maximum length of the string and the actual length of the string. If the file is not NDF, the routine returns an error.

LWDAQ_ndf_string_read

proc LWDAQ_ndf_string_read {file_name} 

LWDAQ_ndf_string_read returns the meta-data string in an NDF file.

LWDAQ_ndf_string_write

proc LWDAQ_ndf_string_write {file_name meta_data} 

LWDAQ_ndf_string_write re-writes the meta-data string in an NDF-file on disk but leaves the data intact. The routine takes roughly 100 us to write a one-byte string and 1 ms to write a 10-kbyte string (on a 1.3 GHz G3 iBook).

LWDAQ_post

proc LWDAQ_post {event {place "end"}} 

LWDAQ_post adds the $event script to the LWDAQ Manager event list. If you set the optional parameter $place to "front" the the event gets added to the front of the queue. Otherwise, the event gets added to the end of the queue.

LWDAQ_proc_declaration

proc LWDAQ_proc_declaration {{proc_name "LWDAQ_*"} {file_name ""} } 

LWDAQ_proc_declaration returns a list of procedure declarations that match proc_name from the script file specified by file_name. The script must indicate a procedure declaration by quoting the procedure name after "proc " on a new line.

LWDAQ_proc_definition

proc LWDAQ_proc_definition {{proc_name "LWDAQ_*"} {file_name ""} } 

LWDAQ_proc_definition returns a list of procedure definitions that match proc_name from the script file specified by file_name. The script must indicate the start of a procedure definition by quoting the procedure name after "proc " on a new line. It must indicate the end of the procedure definition with a line consisting only of a single right-brace "}".

LWDAQ_proc_description

proc LWDAQ_proc_description {{proc_name "LWDAQ_*"} {file_name ""} {keep_breaks 0} } 

LWDAQ_proc_description returns a list of procedure descriptions, such as this one, as exctracted from the TCL/TK script that defines the procedure. If there are procedures in the script that match the proc_name parameter, but do not have their own descriptions, the routine returns an empty element in its list. The script must indicate the description by quoting the procedure name after "" on a new line. If you pass keep_breaks=1, the procedure will retain the original line breaks, which can be useful for printing directly to the TCL console.

LWDAQ_proc_list

proc LWDAQ_proc_list {{proc_name "LWDAQ_*"} {file_name ""} } 

LWDAQ_proc_list returns a list of all procedures declared in the specified file that match the proc_name string. The proc_name can contain wild cards * and ?. Each procedure must be declared on a new line that begins with "proc " followed by the procedure name.

LWDAQ_put_file_name

proc LWDAQ_put_file_name { {name ""} } 

LWDAQ_put_file_name opens a file browser window and allows the user to specify an output file. The browser allows the user to select an existing directory in the file system, and to type in a name for the file within that directory. If the "name" parameter is set when this procedure is called, the value of "name" will be the default file name in the browser window.

LWDAQ_queue_clear

proc LWDAQ_queue_clear {} 

LWDAQ_queue_clear clears the event queue.

LWDAQ_queue_error

proc LWDAQ_queue_error {event error_result} 

LWDAQ_queue_error displays an error for the event queue.

LWDAQ_queue_start

proc LWDAQ_queue_start {} 

LWDAQ_queue_start starts the event queue if it's not running already.

LWDAQ_queue_step

proc LWDAQ_queue_step {} 

LWDAQ_queue_step takes the first event out of the event queue deletes it, executes it, and posts itself to execute again after a delay of queue_ms.

LWDAQ_queue_stop

proc LWDAQ_queue_stop {} 

LWDAQ_queue_stop stops the LWDAQ event manager.

LWDAQ_random

proc LWDAQ_random {{min 0.0} {max 1.0}} 

LWDAQ_random returns a number between min and max. If both min and max are integers, then the number returned is also and integer. If either min or max is real, then the number returned is real. The random calculation we take from Practical Programming in TCL and TK by Brent Welch et al.

LWDAQ_random_wait_ms

proc LWDAQ_random_wait_ms {{min 0} {max 1000}} 

LWDAQ_random_wait_ms waits for a random number of milliseconds between min and max. During the wait, it passes control to the TCL/TK event loop so that idle tasks can be executed.

LWDAQ_read_image_file

proc LWDAQ_read_image_file {infile_name {image_name ""}} 

LWDAQ_read_image_file reads an image file from disk into the lwdaq image list and returns its list name. If the file name ends with ".gif" (case insensitive), the routine reads the file as a GIF image. The gray-scale values in the first line of the image should, for best results, contain a DAQ image header. The DAQ header contains the image dimensions, the analysis bounds, and a result string. Two- dimensional image data begins only on the second line of the image. If the file name ends with ".ndf", the routine reads the file as an NDF (Neuroscience Data Format) file. It creates a new image that is approximately square, and large enough to contain the NDF data. It sets the image result string equal to the NDF meta-data string. It copies the NDF data into the image data area, which begins with the first pixel of the second row in the new image. If the file name ends with any other extension, the routine reads the image in as a DAQ file. You can specify a name for the image if you like, otherwise the routine will assign its own name.

LWDAQ_save_settings

proc LWDAQ_save_settings {{file_name ""}} 

LWDAQ_save_settings saves instrument settings to a settings file, as well as a few elements from the Info array. If you do not specify a settings file name, the routine opens a file browser so the user can choose a file name.

LWDAQ_script_description

proc LWDAQ_script_description {{file_name ""} {keep_breaks 0} } 

LWDAQ_script_description returns the introductory paragraph of a TCL/TK script. It extracts the script name from the file_name parameter. The script name is the tail of the file_name. The script must indicate the introductory paragraph by quoting the script name after "" on a new line. If you pass keep_breaks=1, the procedure will retain the original line breaks, which can be useful for printing directly to the TCL console.

LWDAQ_set_bit

proc LWDAQ_set_bit {binary_string bit_num {value 1}} 

LWDAQ_set_bit takes a string of ones and zeros, called binary_string, and sets bit number $bit_num to $value. By default, $value is 1, in keeping with the electrical engineer's meaning of the word "set".

LWDAQ_socket_accept

proc LWDAQ_socket_accept {sock addr port} 

LWDAQ_socket_accept is an example socket acceptance routine. It sets up the socket to call LWDAQ_socket_interpreter whenever a new line of data arrives from the socket.

LWDAQ_socket_close

proc LWDAQ_socket_close {sock} 

LWDAQ_socket_close closes a socket if it exists, and returns a 1. Otherwise it returns a zero. If the socket is listed in the LWDAQ open sockets list, this routine will remove the socket from the list. If the socket is a LWDAQ client, the routine sends an end of transmission character before closing the socket.

LWDAQ_socket_flush

proc LWDAQ_socket_flush {sock} 

LWDAQ_socket_flush flushes output from a socket. It returns an error message starting with a capitalized nown.

LWDAQ_socket_interpreter

proc LWDAQ_socket_interpreter {sock} 

LWDAQ_socket_interpreter is an example socket interpreter. It calls the LWDAQ socket closing routine to make sure that the open_sockets list is kept up to date.

LWDAQ_socket_listen

proc LWDAQ_socket_listen {{accept ""} {port ""}} 

LWDAQ_socket_listen opens a server socket for listening on the specified port on the local machine. You specify an acceptance procedure that TCL will call when the server accepts a new connection.

LWDAQ_socket_open

proc LWDAQ_socket_open {target {protocol ""}} 

LWDAQ_socket_open opens a connection to a TCPIP server and returns the socket name. The target parameter is of the form a:b where a is an IP address in standard x.x.x.x format or a host name, b is an IP port number in decimal format. The port number can be omitted, in which case the routine assumes a default port number. The optional parameter is the message protocol name. Supported protocols are "lwdaq" and "basic". The default is "lwdaq". To get the basic protocol, specify basic when you open the socket. The lwdaq protocol differs from basic in that it transmits an end of transmission code when we close the socket. The routines that exchange messages with lwdaq servers are in the Driver.tcl file, and there you will see the transmit and receive routines checking the socket info determine the socket protocol.

LWDAQ_socket_protocol

proc LWDAQ_socket_protocol {sock} 

LWDAQ_socket_protocol determines the message protocol in use on a socket.

LWDAQ_socket_read

proc LWDAQ_socket_read {sock size} 

LWDAQ_socket_read reads $size bytes from the input buffer of $sock. If the global LWDAQA_Info(blocking_sockets) variable is 1, the read takes place in one entire data block. While the data arrives, the LWDAQ program freezes. If the same variable is 0, the this procedure reads the data in fragments, allowing the program to respond to menu and window events between fragments. The routine collects all the necessary fragments together and returns them.

LWDAQ_socket_upload

proc LWDAQ_socket_upload {target data} 

LWDAQ_socket_upload opens a socket to a server, writes a data string to the socket, and closes the socket. The target parameter is of the form a:b where a is an IP address in standard x.x.x.x format or a host name, b is an IP port number in decimal format. The routine treats the string as a binary object and transmits it without a carriage return at the end.

LWDAQ_socket_write

proc LWDAQ_socket_write {sock data} 

LWDAQ_socket_write sends data to a socket's output buffer. Normally, we don't send out our data until the buffer is full or we are about to read from the socket. We call this 'lazy flushing'. Sending many instructions in one data packet is more efficient, and we get to use the TCP/IP buffer as a place to construct the string of commands. But if we want to see what is happening on the driver, we might want to send instructions to the LWDAQ Relay immediately. In that case, we set the lazy_flush flag to zero. We must make sure puts does not add a newline character to the end of every binary array it sends.

LWDAQ_split

proc LWDAQ_split {s} 

LWDAQ_split takes a list of parameters delimited by white space, colons, commas, equal-signs, semi-colons, and null characters. It returns a list containing no empty elements.

LWDAQ_stop_vwaits

proc LWDAQ_stop_vwaits {} 

LWDAQ_stop_vwaits sets all vwait variables generated by the above routine, which aborts all the current LWDAQ vwaits. Because TCL vwaits are nested, LWDAQ_stop_vwaits will cause any depth of nesting to terminate, even it the nesting is in deadlock.

LWDAQ_support

proc LWDAQ_support {} 

LWDAQ_support allows you to move windows while running a computation. You simply include a call to this routine in your repeating loop. Every support_ms, the routine will call LWDAQ_update to handle system activity.

LWDAQ_time_stamp

proc LWDAQ_time_stamp { {s ""} } 

LWDAQ_time_stamp returns a year, month, date, hour, seconds time-stamp string for record keeping, or converts a [clock seconds] result into a time-stamp.

LWDAQ_update

proc LWDAQ_update {} 

LWDAQ_update passes control to the TclTk event handler for analysis_update_ms. During this time, the event handler can perform window updates, respond to mouse clicks, and service TCPIP sockets.

LWDAQ_utils_init

proc LWDAQ_utils_init {} 

LWDAQ_utils_init initializes the untils routines.

LWDAQ_vwait

proc LWDAQ_vwait {var_name} 

LWDAQ_vwait calls vwait, but also keeps a list of the current vwait variable stack, which the System Monitor uses to keep track of LWDAQ vwaits.

LWDAQ_vwait_var_name

proc LWDAQ_vwait_var_name {} 

LWDAQ_vwait_var_name will return a unique name for a global vwait variable. All LWDAQ routines that call TCL's vwait routine use a global timeout variable assigned by this routine, so that its partner routine LWDAQ_stop_vwaits can go through all existing timeout variables and set them, which aborts the vwaits.

LWDAQ_wait_ms

proc LWDAQ_wait_ms {time_ms {vwait_var_name ""}} 

LWDAQ_wait_ms waits for the specified time. By default, the routine assigns a unique global name of its own. But it allows you to specify the name of the variable that will be used to control the delay. In this way, you can abort the waiting period by setting the variable from a button or some other event command. When the waiting is done, we unset the waiting variable. When the waiting is aborted, we cancel the waiting command so that the waiting variable will not be set later.

LWDAQ_wait_seconds

proc LWDAQ_wait_seconds {t {vwait_var_name ""}} 

LWDAQ_wait_seconds waits for the specified time.

LWDAQ_watch

proc LWDAQ_watch {watch_var watch_val command} 

LWDAQ_watch waits for a global variable to aquire a particular value, at which point it executes a command. We give the name of the global variable and the awaited value. When the condition is met, the procedure executes the command, otherwise it posts itself to the event queue. The command is a script.

LWDAQ_write_image_file

proc LWDAQ_write_image_file {image_name outfile_name} 

LWDAQ_write_image_file writes an image to disk in the LWDAQ image format. If the file name has tail ".gif" (case insensitive), the routine saves the file in GIF format. If the file name ends with ".ndf", the routine writes the image file as an NDF file. Otherwise, the routine saves the image in the DAQ format. In a GIF or DAQ file, the LWDAQ image header, with dimensions, analysis bounds, and results string, will be embedded in the first line of the image. In an NDF file, this header information is lost. The results string is saved in the meta-data string and the image contents, starting with the first pixel of the first row, are stored in the NDF data block.

LWDAQ_xml_get

proc LWDAQ_xml_get {xml tag} 

LWDAQ_xml_get calls LWDAQ_xml_get_list and returns the contents of the first list entry in the result. We use this routine to extract the value of a field in an xml record.

LWDAQ_xml_get_list

proc LWDAQ_xml_get_list {xml tag} 

LWDAQ_xml_get_list takes an xml string and extracts the list of records from the database that matches a specified tag you specify. If an xml string contains one thousand entries delimited by ..., the routine returns a TCL list of the contents of all the entries when you pass it the xml string and the tag "donar". You don't pass it the brackets on either side of the tag, even though these brackets always appear in the xml string. Each element in the list the routine returns will be the contents of a single record, with its start and end tags removed. You can now apply this same routine to each element in this list sequentially, to extract fields from each record, and you can apply LWDAQ_xml_get to these fields to look at sub-fields and so on.

BCAM.tcl

BCAM.tcl defines the BCAM instrument.

LWDAQ_analysis_BCAM

proc LWDAQ_analysis_BCAM {{image_name ""}} 

LWDAQ_analysis_BCAM applies BCAM analysis to an image in the lwdaq image list. By default, the routine uses the image $config(memory_name).

LWDAQ_daq_BCAM

proc LWDAQ_daq_BCAM {} 

LWDAQ_daq_BCAM captures an image from the LWDAQ electronics and places the image in the lwdaq image list. It provides background subtraction by taking a second image while flashing non-existent lasers. It provides automatic exposure adjustment by calling itself until the maximum image intensity lies within peak_min and peak_max. For detailed comments upon the readout of the image sensors, see the LWDAQ_daq_Camera routine.

LWDAQ_extended_BCAM

proc LWDAQ_extended_BCAM {} 

LWDAQ_extended_BCAM tries to assign optimal values to peak_max and peak_min, and adjust the analysis boundaries to enclose the spots within a number of pixels of their centers. You direct the configuration calculations with the extended_parameters string, which contains parameters as a list. The string "0.6 0.9 20 1" sets peak_min to 60% of saturation, peak_max to 90% of saturation, shrinks the image bounds to 20 pixels around the spot center, and adjusts individual source exposure times. If you don't want a border, specify bounds to be 0 (instead of 20). If you don't want to adjust multiple sources individually, specify 0 for individual_sources.

LWDAQ_infobuttons_BCAM

proc LWDAQ_infobuttons_BCAM {f} 

LWDAQ_infobuttons_BCAM creates buttons that allow us to configure the BCAM for any of the available image sensors.

LWDAQ_init_BCAM

proc LWDAQ_init_BCAM {} 

LWDAQ_init_BCAM creates all elements of the BCAM instrument's config and info arrays.

Camera.tcl

Camera.tcl defines the Camera instrument.

LWDAQ_analysis_Camera

proc LWDAQ_analysis_Camera {{image_name ""}} 

LWDAQ_analysis_Camera applies Camera analysis to an image in the lwdaq image list. By default, the routine uses the image $config(memory_name).

LWDAQ_controls_Camera

proc LWDAQ_controls_Camera {} 

LWDAQ_controls_Camera creates buttons that configure the Camera for various image sensors.

LWDAQ_daq_Camera

proc LWDAQ_daq_Camera {} 

LWDAQ_daq_Camera captures an image from the LWDAQ electronics and places the image in the lwdaq image list.

LWDAQ_init_Camera

proc LWDAQ_init_Camera {} 

LWDAQ_init_Camera creates all elements of the Camera instrument's config and info arrays.

LWDAQ_set_image_sensor

proc LWDAQ_set_image_sensor {{name "TC255"} {instrument "Camera"}} 

LWDAQ_set_image_sensor takes a LWDAQ device type name and sets up instrument $name to acquire images from such a device. We set the image height and width, the device type number, and the analysis boundaries. Some instruments have the daq device type in the config array, and other in the info array, so this routine handles both contingencies.

Diagnostic.tcl

Diagnostic.tcl defines the Diagnostic instrument.

LWDAQ_analysis_Diagnostic

proc LWDAQ_analysis_Diagnostic {{image_name ""}} 

LWDAQ_analysis_Diagnostic displays the power supply measurements carried by the $image_name and displays them in the diagnostic instrument window. It calculates average values for the power supply voltages and current consumption and returns these parameters, as well as other information about the driver. By default, the routine uses the image $config(memory_name).

LWDAQ_controls_Diagnostic

proc LWDAQ_controls_Diagnostic {} 

LWDAQ_controls_Diagnostic creates secial controls for the Diagnostic instrument.

LWDAQ_daq_Diagnostic

proc LWDAQ_daq_Diagnostic {} 

LWDAQ_daq_Diagnostic reads configuration paramters from the LWDAQ hardware, and records them in a result string, which it returns.

LWDAQ_exec_Diagnostic

proc LWDAQ_exec_Diagnostic {operation} 

LWDAQ_exec_Diagnostic opens a socket to a driver and calls the specified operation routine.

LWDAQ_init_Diagnostic

proc LWDAQ_init_Diagnostic {} 

LWDAQ_init_Diagnostic creates all elements of the Diagnostic instrument's config and info arrays.

LWDAQ_loop_Diagnostic

proc LWDAQ_loop_Diagnostic {sock} 

LWDAQ_loop_Diagnostic executes a loop job on the Diagnostic instrument's target device, reads out the LWDAQ Driver's loop timer, and prints the loop time in the Diagnostic text window.

LWDAQ_off_Diagnostic

proc LWDAQ_off_Diagnostic {sock} 

LWDAQ_off_Diagnostic turns off the device power.

LWDAQ_on_Diagnostic

proc LWDAQ_on_Diagnostic {sock} 

LWDAQ_on_Diagnostic turns on the LWDAQ device power.

LWDAQ_psc_Diagnostic

proc LWDAQ_psc_Diagnostic {image_name} 

LWDAQ_psc_Diagnostic checks the power supply voltages recorded in a Diagnostic image to see if they are within the bounds defined by the min_* and max_* info parameters. The routine returns a string of warnings. If this string is empty, no problems were encountered.

LWDAQ_reboot_Diagnostic

proc LWDAQ_reboot_Diagnostic {sock} 

LWDAQ_reboot_Diagnostic re-boots the server.

LWDAQ_refresh_Diagnostic

proc LWDAQ_refresh_Diagnostic {{image_name ""}} 

LWDAQ_refresh_Diagnostic refreshes the display of the data, given new display settings. It calls the Diagnostic instrument's analysis procedure.

LWDAQ_reset_Diagnostic

proc LWDAQ_reset_Diagnostic {sock} 

LWDAQ_reset_Diagnostic reboots the controller logic.

LWDAQ_sleep_Diagnostic

proc LWDAQ_sleep_Diagnostic {sock} 

LWDAQ_sleep_Diagnostic sends the target device to sleep.

LWDAQ_sleepall_Diagnostic

proc LWDAQ_sleepall_Diagnostic {sock} 

LWDAQ_sleepall_Diagnostic sends a range of devices to sleep. The routine starts with driver socket 1 and multiplexer socket 1, and proceeds to driver socket 1, multiplexer socket b, where b is the second number in sleepall_params. The routine moves on to driver socket 2 and repeats the same procedure, and so on, up to driver socket a, where a is the first number in sleepall_params.

LWDAQ_transmit_Diagnostic

proc LWDAQ_transmit_Diagnostic {sock} 

LWDAQ_transmit_Diagnostic transmits each hex word in info(command) to the target device (info(repeat) + 1) times.

LWDAQ_wake_Diagnostic

proc LWDAQ_wake_Diagnostic {sock} 

LWDAQ_wake_Diagnostic wakes up the target device.

Dosimeter.tcl

Dosimeter.tcl defines the Dosimeter instrument.

LWDAQ_analysis_Dosimeter

proc LWDAQ_analysis_Dosimeter {{image_name ""}} 

LWDAQ_analysis_Dosimeter applies Dosimeter analysis to an image in the lwdaq image list. By default, the routine uses the image $config(memory_name).

LWDAQ_daq_Dosimeter

proc LWDAQ_daq_Dosimeter {} 

LWDAQ_daq_Dosimeter captures an image from the LWDAQ electronics and places the image in the lwdaq image list.

LWDAQ_init_Dosimeter

proc LWDAQ_init_Dosimeter {} 

LWDAQ_init_Dosimeter creates all elements of the Dosimeter instrument's config and info arrays.

Flowmeter.tcl

Flowmeter.tcl defines the Flowmeter instrument.

LWDAQ_analysis_Flowmeter

proc LWDAQ_analysis_Flowmeter {{image_name ""}} 

LWDAQ_analysis_Flowmeter takes the flowmeter RTD sensor resistance measurements in $image_name and plots a graph of sensor temperature versus time in the Flowmeter window. It returns a string containing the inverse time-constant of the cool-down phase. By default, the routine uses image $config(memory_name).

LWDAQ_controls_Flowmeter

proc LWDAQ_controls_Flowmeter {} 

LWDAQ_controls_Flowmeter creates secial controls for the Flowmeter instrument.

LWDAQ_daq_Flowmeter

proc LWDAQ_daq_Flowmeter {} 

LWDAQ_daq_Flowmeter reads configuration parameters from the LWDAQ hardware, and records them in a result string, which it returns.

LWDAQ_init_Flowmeter

proc LWDAQ_init_Flowmeter {} 

LWDAQ_init_Flowmeter creates all elements of the Flowmeter instrument's config and info arrays.

LWDAQ_refresh_Flowmeter

proc LWDAQ_refresh_Flowmeter {} 

LWDAQ_refresh_Flowmeter refreshes the display of the data, given new display settings. It calls the Flowmeter analysis procedure.

Gauge.tcl

Gauge.tcl defines the Gauge instrument.

LWDAQ_analysis_Gauge

proc LWDAQ_analysis_Gauge {{image_name ""}} 

LWDAQ_analysis_Gauge takes the RTD resistance measurements contained in $image_name and plots a graph of temperature versus time for each sensor whose resistance is recorded in the image. It calculates the average value of each temperature and returns the averages as a string. By default, the routine uses image $config(memory_name).

LWDAQ_controls_Gauge

proc LWDAQ_controls_Gauge {} 

LWDAQ_controls_Gauge creates secial controls for the Gauge instrument.

LWDAQ_daq_Gauge

proc LWDAQ_daq_Gauge {} 

LWDAQ_daq_Gauge reads configuration paramters from the LWDAQ hardware, and records them in a result string, which it returns.

LWDAQ_init_Gauge

proc LWDAQ_init_Gauge {} 

LWDAQ_init_Gauge creates all elements of the Gauge instrument's config and info arrays.

LWDAQ_refresh_Gauge

proc LWDAQ_refresh_Gauge {} 

LWDAQ_refresh_Gauge refreshes the display of the data, given new display settings. It calls the Gauge analysis routine, which assumes that certain parameters are stored in the image's results string.

Inclinometer.tcl

Inclinometer.tcl defines the Inclinometer instrument.

LWDAQ_analysis_Inclinometer

proc LWDAQ_analysis_Inclinometer {{image_name ""}} 

LWDAQ_analysis_Inclinometer converts the ADC measurements contained in $image_name into voltages, and plots them in the Inclinometer window. It calculates the average value of the voltage, the slope, and the standard deviation, and returns these in a string. By default, the routine uses image $config(memory_name).

LWDAQ_controls_Inclinometer

proc LWDAQ_controls_Inclinometer {} 

LWDAQ_controls_Inclinometer creates secial controls for the Inclinometer instrument.

LWDAQ_daq_Inclinometer

proc LWDAQ_daq_Inclinometer {} 

LWDAQ_daq_Inclinometer reads samples out of an input channel.

LWDAQ_init_Inclinometer

proc LWDAQ_init_Inclinometer {} 

LWDAQ_init_Inclinometer creates all elements of the Inclinometer instrument's config and info arrays.

Rasnik.tcl

Rasnik.tcl defines the Rasnik instrument.

LWDAQ_analysis_Rasnik

proc LWDAQ_analysis_Rasnik {{image_name ""}} 

LWDAQ_analysis_Rasnik applies rasnik analysis to an image in the lwdaq image list. By default, the routine uses image $config(memory_name).

LWDAQ_daq_Rasnik

proc LWDAQ_daq_Rasnik {} 

LWDAQ_daq_Rasnik ccaptures an image from the LWDAQ electronics and places the image in the lwdaq image list. It provides background subtraction by taking a second image while flashing non-existent LEDs. It provides automatic exposure adjustment by calling itself until the maximum image intensity lies withint peak_min and peak_max.

LWDAQ_extended_Rasnik

proc LWDAQ_extended_Rasnik {} 

LWDAQ_extended_Rasnik tries to assign optimal values to peak_max and peak_min. You direct the configuration with info(extended_parameters), which contains min_frac and max_frac. With the string "0.6 0.9", the configuration sets peak_min to 60% of saturation, peak_max to 90% of saturation.

LWDAQ_infobuttons_Rasnik

proc LWDAQ_infobuttons_Rasnik {f} 

No description available.

LWDAQ_init_Rasnik

proc LWDAQ_init_Rasnik {} 

LWDAQ_init_Rasnik creates all elements of the Rasnik instrument's config and info arrays.

Recorder.tcl

Recorder.tcl defines the Recorder instrument.

LWDAQ_analysis_Recorder

proc LWDAQ_analysis_Recorder {{image_name ""}} 

LWDAQ_analysis_Recorder applies Recorder analysis to an image in the lwdaq image list. By default, the routine uses the image $config(memory_name).

LWDAQ_controls_Recorder

proc LWDAQ_controls_Recorder {} 

LWDAQ_controls_Recorder creates secial controls for the Recorder instrument.

LWDAQ_daq_Recorder

proc LWDAQ_daq_Recorder {} 

LWDAQ_daq_Recorder reads data from a data device.

LWDAQ_error_fix_Recorder

proc LWDAQ_error_fix_Recorder {image_name} 

LWDAQ_error_fix_Recorder looks for timestamp errors in the data of an image called image_name. It extracts messages before the first timestamp error and shifts the remaining data one place to the left, so that we discard the first byte in what remains. The routine repeatst this procedure until there are no more timestamp errors, which could be because there are no more messages in the image or because misalignment has been corrected. As it goes along, the routine keeps track of how many times it has shifted the data to the left by one byte and returns this number so the calling routine can apply the same shift to the recorder's data buffer, and so realign the buffer with the message boundaries.

LWDAQ_error_test_Recorder

proc LWDAQ_error_test_Recorder {sock} 

LWDAQ_error_test_Recorder simulates data acquisition errors by reading bytes out of the data recorder without saving them.

LWDAQ_init_Recorder

proc LWDAQ_init_Recorder {} 

LWDAQ_init_Recorder creates all elements of the Recorder instrument's config and info arrays.

LWDAQ_refresh_Recorder

proc LWDAQ_refresh_Recorder {} 

LWDAQ_refresh_Recorder refreshes the display of the data, given new display settings.

LWDAQ_reset_Recorder

proc LWDAQ_reset_Recorder {} 

LWDAQ_reset_Recorder resets the data recorder hardware and the recorder instrument.

RFPM.tcl

RFPM.tcl defines the Radio-Frequency Power Meter (RFPM) instrument.

LWDAQ_analysis_RFPM

proc LWDAQ_analysis_RFPM {{image_name ""}} 

LWDAQ_analysis_RFPM converts the ADC measurements contained in $image_name into voltages, and plots them in the RFPM window. By default, the routine uses image $config(memory_name). If analysis_enable is set to 1, the analysis returns the peak-to-peak value of the signal on all four RFPM signal paths in units of ADC counts. If analysis_enanalysis is 2, the analysis returns the rms values of the signals.

LWDAQ_controls_RFPM

proc LWDAQ_controls_RFPM {} 

LWDAQ_controls_RFPM creates secial controls for the RFPM instrument.

LWDAQ_daq_RFPM

proc LWDAQ_daq_RFPM {} 

LWDAQ_daq_RFPM reads samples out of an input channel.

LWDAQ_init_RFPM

proc LWDAQ_init_RFPM {} 

LWDAQ_init_RFPM creates all elements of the RFPM instrument's config and info arrays.

LWDAQ_refresh_RFPM

proc LWDAQ_refresh_RFPM {} 

LWDAQ_refresh_RFPM refreshes the display of the data, given new display settings. RFPM analysis assumes that certain parameters are stored in the image's results string.

Terminal.tcl

Terminal.tcl defines the Terminal instrument.

LWDAQ_analysis_Terminal

proc LWDAQ_analysis_Terminal {{image_name ""}} 

LWDAQ_analysis_Terminal scans an image received from a Terminal data acquisition, and turns it into a string of numbers.

LWDAQ_daq_Terminal

proc LWDAQ_daq_Terminal {} 

LWDAQ_daq_Terminal reads a string of characters or a block of data froma data device.

LWDAQ_init_Terminal

proc LWDAQ_init_Terminal {} 

LWDAQ_init_Terminal creates all elements of the Terminal instrument's config and info arrays.

Thermometer.tcl

Thermometer.tcl defines the Thermometer instrument.

LWDAQ_analysis_Thermometer

proc LWDAQ_analysis_Thermometer {{image_name ""}} 

LWDAQ_analysis_Thermometer takes the RTD resistance measurements contained in $image_name and plots a graph of temperature versus time for each sensor whose resistance is recorded in the image. It calculates the average value of each temperature and returns the averages as a string. By default, the routine uses image $config(memory_name).

LWDAQ_controls_Thermometer

proc LWDAQ_controls_Thermometer {} 

LWDAQ_controls_Thermometer creates secial controls for the Thermometer instrument.

LWDAQ_daq_Thermometer

proc LWDAQ_daq_Thermometer {} 

LWDAQ_daq_Thermometer reads configuration paramters from the LWDAQ hardware, and records them in a result string, which it returns.

LWDAQ_init_Thermometer

proc LWDAQ_init_Thermometer {} 

LWDAQ_init_Thermometer creates all elements of the Thermometer instrument's config and info arrays.

LWDAQ_refresh_Thermometer

proc LWDAQ_refresh_Thermometer {} 

LWDAQ_refresh_Thermometer refreshes the display of the data, given new display settings. It calls the Thermometer analysis routine, which assumes that certain parameters are stored in the image's results string.

Viewer.tcl

Viewer.tcl defines the Viewer instrument.

LWDAQ_analysis_Viewer

proc LWDAQ_analysis_Viewer {{image_name ""}} 

LWDAQ_analysis_Viewer returns the results string of an image in the lwdaq image list. By default, the routine uses the image $config(memory_name).

LWDAQ_controls_Viewer

proc LWDAQ_controls_Viewer {} 

LWDAQ_controls_Viewer creates secial controls for the Viewer instrument.

LWDAQ_DAQ_to_GIF_Viewer

proc LWDAQ_DAQ_to_GIF_Viewer {} 

LWDAQ_DAQ_to_GIF_Viewer opens a browser in which you select multiple DAQ image files, and converts them to GIF files, writing them into the same directory with suffix ".gif".

LWDAQ_daq_Viewer

proc LWDAQ_daq_Viewer {} 

LWDAQ_daq_Viewer is a dummy procedure for the standard aquire button.

LWDAQ_GIF_to_DAQ_Viewer

proc LWDAQ_GIF_to_DAQ_Viewer {} 

LWDAQ_GIF_to_DAQ_Viewer opens a browser in which you select multiple GIF image files, and converts them to DAQ files, writing them into the same directory with suffix ".daq".

LWDAQ_init_Viewer

proc LWDAQ_init_Viewer {} 

LWDAQ_init_Viewer creates all elements of the Viewer instrument's config and info arrays.

LWDAQ_Set_Bounds_Viewer

proc LWDAQ_Set_Bounds_Viewer {} 

LWDAQ_Set_Bounds_Viewer applies the analyisis boundaries specified in the viewer's info array to the image named by config memory_name.

LWDAQ_Set_Dimensions_Viewer

proc LWDAQ_Set_Dimensions_Viewer {} 

LWDAQ_Set_Dimensions_Viewer takes the contents of the image named by config(memory_name) and creates a new image with the dimensions specified in the dimension control boxes. The routine keeps the analysis boundaries the same.

LWDAQ_Set_Results_Viewer

proc LWDAQ_Set_Results_Viewer {} 

LWDAQ_Set_Results_Viewer sets the results string of an image.

LWDAQ_special_analysis_Viewer

proc LWDAQ_special_analysis_Viewer {instrument} 

LWDAQ_special_analysis_Viewer calls the analysis of other instruments, displays the results on the screen, and prints them to the text window.

Voltmeter.tcl

Voltmeter.tcl defines the Voltmeter instrument.

LWDAQ_analysis_Voltmeter

proc LWDAQ_analysis_Voltmeter {{image_name ""}} 

LWDAQ_analysis_Voltmeter converts the ADC measurements contained in $image_name into voltages, and plots them in the Voltmeter window. It calculates the average value of the voltage, the slope, and the standard deviation, and returns these in a string. By default, the routine uses image $config(memory_name).

LWDAQ_controls_Voltmeter

proc LWDAQ_controls_Voltmeter {} 

LWDAQ_controls_Voltmeter creates secial controls for the Voltmeter instrument.

LWDAQ_daq_Voltmeter

proc LWDAQ_daq_Voltmeter {} 

LWDAQ_daq_Voltmeter reads samples out of an input channel.

LWDAQ_init_Voltmeter

proc LWDAQ_init_Voltmeter {} 

LWDAQ_init_Voltmeter creates all elements of the Voltmeter instrument's config and info arrays.

LWDAQ_refresh_Voltmeter

proc LWDAQ_refresh_Voltmeter {} 

LWDAQ_refresh_Voltmeter refreshes the display of the data, given new display settings. Voltmeter analysis assumes that certain parameters are stored in the image's results string.

WPS.tcl

WPS.tcl defines the WPS instrument.

LWDAQ_analysis_WPS

proc LWDAQ_analysis_WPS {{image_name ""}} 

LWDAQ_analysis_WPS applies WPS analysis to an image in the lwdaq image list. By default, the routine uses the image $config(memory_name).

LWDAQ_daq_WPS

proc LWDAQ_daq_WPS {} 

LWDAQ_daq_WPS captures an image from the LWDAQ electronics and places the image in the lwdaq image list. It provides background subtraction by taking a second image while flashing non-existent lasers. It provides automatic exposure adjustment by calling itself until the maximum image intensity lies within peak_min and peak_max.

LWDAQ_init_WPS

proc LWDAQ_init_WPS {} 

LWDAQ_init_WPS creates all elements of the WPS instrument's config and info arrays.