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 and its sub-directories. 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 analyzes bcam images. The routine clears the image overlay for its own use.

The analysis subtracts the -threshold from all pixels within the image's analysis bounds. Any pixels with negative intensity are set to zero. The routine identifies all distinct sets of contiguous pixels above threshold, determines the centroid of each of them, and returns the characteristics of the -num_spots brightes sets. The centroid coordinates are 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 it assumes the pixels are square. 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.

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.

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 $data 0

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 10000 100

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 -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_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. It replaces the temperature-specific lwdaq_thermometer routine. lwdaq_gauge 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_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.

The color codes for the graph give 255 unique colors. You can try them out to see which ones you like.

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).

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 will delete 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.

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 then lwdaq_image_manipulate replaces the original image with the result 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 subtract manipulation requires you to name a second image, which will be subtracted from the first to create a third image. The none manipulation does nothing. In each case, we have a new image pointer, but with the none manipulation, this image pointer is a pointer to the first image. 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 gradient 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 mean 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.

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.

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_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.

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 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. The threshold must apply to the gradient image, which lwdaq_wps will obtain with image_grad_i. If the calling routine is going to determine the threshold based upon the minimum, average, and maximum intensities in the gradient image, the calling routine must also obtain the gradient image. In the TCL interpreter, you obtain the gradient image using [lwdaq_image_manipulate $image_name grad_i].

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, but overlayed upon the original image. The edges of a wire will be covered with colored pixels.

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 you 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.

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 you 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 you 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 you use the same units for both the point and the mount strings.

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 you 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

Note that 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 we know to lie in the plane z = bcam_z in BCAM coordinates. The routine is similar to bcam_source_bearing, but you 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.

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.

fourier_term

lwdaq fourier_term period waveform

Calculates a term in the discrete Fourier transform of waveform by calling calculate_ft_term from utls.pas. You specify the waveform as a string of real numbers. Each represents the value of the waveform at discrete, consecutive moments in time (or space, or some other one-dimensional metric) separated by the sample interval. You specify which term you want to calculate by giving its period in units of sample intervals with the period parameter. The routine returns a string containg the amplitude and phase of the term in the fourier transform corresponding to period. If you pass "2" for the period and "0 1 0 1 0 1" for the data, the routine returns, "1.000000 0.500000". The phase, as you can see, is given in units of sample interval, and its sine is such that you subtract it from the phase of a sinusoid to create the Fourier term. To obtain the zero-frequency (DC) term, which corresponds to period infinity, pass period "0" to the routine. We use "0" as a code for "infinity", since we cannot calculate the discrete fourier transform at period zero. If you want to calculate a fourier transform made up of many fourier terms, try using the fourier_transform routine instead. It is much faster when you have a large waveform and many frequencies in your desired spectrum, because it translates the TCL data string into a Pascal binary string only once.

fourier_transform

lwdaq fourier_transform periods waveform

Calculates a series of terms in the discrete Fourier transform of waveform. In effect, this option acts like repeated calls to fourier_term, but is more efficient for large waveform strings, because TCL does not have to copy the string for each term. Instead of passing the routine a single period for a single fourier term, you pass a list of periods. The routine returns a list of terms, each term consisting of the period, amplitude and offset, separated by spaces. To improve its accuracy when calculating terms with non-zero frequency, the routine subtracts the average value of the waveform from each term in the waveform before it calculates terms. In response to period "0", the routine returns the average value of the waveform, so "0" is how you indicate period infinity.

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 . 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. It 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

See for more details. 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 you 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 3x3 matrix inversion with random elements takes 1000 us on our 1 GHz iBook, of which only 8 us (0.1% of its time) is spend calculating the inverse. A 40x40 matrix takes 100 ms on the same computer, and spends 4.5 ms (4% of its time) calculating the inverse. The routine returns the inverse as a string of real numbers, in the same format as the original matrix.

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 amlitude 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 you pass the numbers "1 0 1 0.1" to the routine, it will return "1.997500 0.050000".

Driver.tcl

Driver.tcl defines procedures that communicate with Long-Wire Data Acquisition (LWDAQ) Drivers equipped with a TCP/IP interface. There are three components in the ethernet communication. The computer running this TCL/TK script is the "LWDAQ Master". The embedded computer on the LWDAQ Driver that manages the TCP/IP protocol stack is the "LWDAQ Relay", and the programmable logic chip on the driver that communicates with the LWDAQ devices and multiplexers is the "LWDAQ Controller". All three components have their own address spaces, with memory and control registers.

LWDAQ_byte_poll

proc LWDAQ_byte_poll {sock addr value} 

LWDAQ_byte_poll tells the relay at the other end of TCP/IP socket $sock to wait until the byte it reads from address $addr has value $value.

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.

LWDAQ_byte_write

proc LWDAQ_byte_write {sock addr value} 

LWDAQ_byte_write writes byte $value through TCP/IP socket $sock to controller address $addr. Note that value is a string of digits that represent a decimal number.

LWDAQ_clear_data_addr

proc LWDAQ_clear_data_addr {sock} 

LWDAQ_clear_data_addr clears the data address of a driver's data address to zero. The driver is at the other end of an open TCP/IP socket $sock.

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 TCP/IP 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 only by pressing a button on the driver.

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 reset the driver with its hardware reset button. Until then, the existing parameters in the driver's RAM will remain in effect.

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_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 TCP/IP 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.

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 TCP/IP 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 TCP/IP socket $sock to controller address $addr.

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_failure 1}} 

LWDAQ_login sends password $password through $sock to a LWDAQ Driver using a login message. It receives the value sent back by the driver in response to the login. This value will be 1 to indicate success and zero otherwise. If the password is "no_password", the routine does not attempt to login but returns a 1 for success automatically. If the login result is 0, the routine generates an error when $error_on_failure is 1. Otherwise, the routine returns the zero to indicate failure.

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 TCP/IP 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 TCP/IP socket $sock, and returns the address.

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 TCP/IP 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.

LWDAQ_ram_read

proc LWDAQ_ram_read {sock addr length} 

LWDAQ_ram_read sets the LWDAQ Controller's data address equal to $addr and then reads a block of $length bytes starting from address $addr in the LWDAQ Controller memory. The routine returns the bytes as a TCL byte array object.

LWDAQ_receive_data

proc LWDAQ_receive_data {sock} 

LWDAQ_receive_data awaits and receives a data return message from LWDAQ TCP/IP socket $sock and returns the message contents. The message contents are the data requested from the driver by a previous message sent received by the driver through the same socket.

LWDAQ_reset_controller

proc LWDAQ_reset_controller {sock} 

LWDAQ_reset_controller writes 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_send_message

proc LWDAQ_send_message {sock message} 

LWDAQ_send_message sends LWDAQ Driver message $message to a driver socket $sock. The message must have the structure defined in the LWDAQ Driver with Ethernet Interface manual.

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, where $value is a hexadecimal 32-bit number. The driver is at the other end of open TCP/IP 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.

LWDAQ_set_command_reg

proc LWDAQ_set_command_reg {sock value} 

LWDAQ_set_command_reg sets a driver's command register to $value through TCP/IP socket $sock.

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_ct_config

proc LWDAQ_set_ct_config {sock value} 

LWDAQ_set_ct_config sets a driver's counter-timer configuration register to $value through $sock.

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 TCP/IP socket $sock.

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 TCP/IP socket $sock.

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.

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 TCP/IP 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.

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.

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.

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.

LWDAQ_shortint_write

proc LWDAQ_shortint_write {sock addr value} 

LWDAQ_shortint_write writes a two-byte integer $value through open TCP/IP socket $sock to controller address $addr.

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.

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.

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 TCP/IP 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.

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 TCP/IP 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.

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.

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.

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 TCP/IP 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, and install any TCL commands necessary to make the local TCL compatible with TCL/TK 8.4.

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 not update 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 {name {loop Acquire}} 

LWDAQ_acquire acquires data for the instrument called $name from either a file, or an existing image in memory, or directly from the daq. It returns a result string. The optional $loop allows this call of LWDAQ_acquire to post itself again to the event queue if the instrument's info(control) is "Loop". We call the routine with $loop equal to Loop only from the instrument's Loop button.

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_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_new_toplevel_text_window

proc LWDAQ_new_toplevel_text_window {{width 84} {height 30}} 

LWDAQ_new_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_new_toplevel_window

proc LWDAQ_new_toplevel_window { {title ""} } 

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

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 widget or a file. When the routine writes to a text widget, it does so in a specified color, unless the first line of the string contains one of the notification keywords in captial letters, in which case it changes the color itself. If you pass "-nonewline" as an option after LWDAQ_print, then the routine does not add a carriage return to the end of its print-out. The routine also recognises the "-newline" option, which is the default. The routine classifies a text device as a text widget if its starts with a "." and this period is not follwed by either forward slash or backslash. If the text widget exists, the routine writes the string to the end of the text window. If the text device is a file, 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. If the routine cannot find a text widget or file to print to, it will print a message to the console.

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}} 

LWDAQ_text_widget opens a text window within the specified window frame. The text window has its "undo" stack turned off. If you want to turn on the "undo" stack, LWDAQ_enable_text_undo will check that you are using TK 8.4+, and turn on the stack if you are.

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, 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.

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.

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_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.

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_clear

proc LWDAQ_Toolmaker_clear {} 

LWDAQ_Toolmaker_clear clears the sequence of scripts on file.

LWDAQ_Toolmaker_execute

proc LWDAQ_Toolmaker_execute {} 

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 sequence of scripts from a file, and appends them to the current script list.

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 valud 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 line breaks, so the string can be pasted directly into an Excel spreadsheet.

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 iff the first or second word in the string is "error:" (case insensitive).

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_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 in as a GIF image. Otherwise it reads the file as a LWDAQ image. 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, calle 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 {close_string "\x04"}} 

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. The routine sends an end of transmission string before closing the socket, which is by default the ASCII EOT (hex 04) character. You can supress the transmission of this character by passing the routine an empty string for the close_string.

LWDAQ_socket_flush

proc LWDAQ_socket_flush {sock} 

LWDAQ_socket_flush flushes output from a socket. It does nothing more than flush right now, but in the future, we may require it to check something before it performs its flush.

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 {port ""}} 

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. Instead of specifying the port using the above format, you can also specify it as a separate parameter.

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 then 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, with no carriate 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 to zero, which will indicate to all routines in vwait that a global reset has occured. Because TCL vwaits are nested, LWDAQ_stop_vwaits will cause any depth of nesting to terminate, even it the nesting is in deadlock.

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 allows you to move windows while running a computation. You simply include a call to LWDAQ_update in your repeating loop. LWDAQ_update calls the TK update command once every $LWDAQ_Info(update_seconds) seconds. The routine returns the value 0 if it does nothing, and 1 if it calls update.

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 we can use to keep track of our 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 to 0, which indicates to the vwait-calling procedure that the vwait has been aborted by a global LWDAQ reset.

LWDAQ_wait_ms

proc LWDAQ_wait_ms {time_ms} 

LWDAQ_wait_ms waits for the specified time.

LWDAQ_wait_seconds

proc LWDAQ_wait_seconds {t} 

LWDAQ_wait_seconds waits for the specified time.

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. Otherwise, the routine saves the image in the LWDAQ pixel map format. In both cases, the LWDAQ image header, with dimensions, analysis bounds, and results string, will be embedded in the first line of the image.

BCAM.tcl

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.

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_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 instrume