BSL

1.1 Introduction

BSL is a 2-D interactive data manipulation package for image data. The program is has a wide range of applications even if some of the instructions and options are specific to X-ray applications. BSL developed by J.Bordas and G.Mant and was based on the OTOKO package sharing the same data format and interface style. This allows data to be reduced to 1-D in BSL and then imported into OTOKO for further processing. The program is now available for all major hardware platforms (Sun, HP, DEC, and SG) in two varieties bsltek and bsl. The former runs on character based terminals and the latter on X windows based workstations. This manual is based on contributions from the original authors, R.Rule (ICI, Runcorn) and I.Dobbie (Kings College).

1.2 The Interface

The interface is based upon a set of 3 letter instructions, that are preceded with either a dot (e.g. .MUC to multiply an image by a constant). Most input is then taken from the keyboard, although some functions require the selection of coordinates using either the keyboard cursors or the mouse. BSL prompts for filenames with the question:

Enter filename (X99999.XXX[/]) or <ctrl-D>

By entering either <ctrl-d>, ^d or ^D will terminate the prompt without any file input. Nearly all BSL functions can be applied to either:

a) a single frame file or a single frame from multi-frame file.

Enter filename (X99999.XXX[/]) or <ctrl-D>: s58026.tmp

In this case only time frame 26 in the file S58001.TMP will be processed.

b) several time frames from one file

Enter filename (X99999.XXX[/]) or <ctrl-D>: s58000.tmp
Enter [1] positional [2] calibrational data or aux[3] [1]: 1
Total number of frames 256
Enter first and last frame, increment or <ctrl-D>: 26,38,2
Memory 1 first and last frame 26 3 incr 2
Enter first and last channel of output [1,256]: <return>

In this case all channels of frames 26,28,30,32,34,36 and 38 of the binary file S58001.TMP will be processed. Another way of obtaining the same result is by giving the name of the first frame followed by a slash (/).

Enter filename (X99999.XXX[/]) or <ctrl-D>: s58026.tmp/
Enter last file number, increment or <ctrl-D>: 58036,2
Enter first and last channel of output [1,256]: <return>

NOTE that the only way to access the contents of binary files other than the SAXS files, is to enter the header file name (e.g. S58000.TMP) and answer the first question with the required choice of file. If a frame number (the last three digits) is non-zero (e.g. S58002.TMP) then the SAXS binary file is always assumed.

c) one time frame from several files in a sequence

Enter filename (X99999.XXX[/]) or <ctrl-D>: s58000.tmp/
Enter last file number, increment or <ctrl-D>: 59000,1000
Enter memory [1]: <return>
Total number of frames: 256
Enter first and last frame, increment or <ctrl-D>: 25
Memory 1 first and last frame 25 25 incr 1
Enter first and last channel of output [1,256]: <return>

In this case all channels of frame 25 of file S58001.TMP and of file S59001.TMP will be processed.

When a command has been executed on a given data file, the output filename is usually given the same extension as the command itself; i.e. after a .DIN command, the output file is Xnn000.DIN.

1.3 The BSL Instruction Set

A full list of commands and a brief description of their operation is provided for the present version:

.ADC	Add a constant to a selected range in spectrum.
.ADD	Weighted addition of two images.
.ADN	Add and normalise image using a calibration file.
.ARG	Display image on X-window terminal
.ASF	Add/subtract a single file/raster to an image.
.AVE	Average a series of images
.BAK	Background subtraction of an image
.CHG	Change a selected value in an image
.CIN	Circular integration and integration
.CNV	Convolve two files
.CON	Generate a contour map
.CUT	Cut part of an image into a smaller image
.DGL	Deglitch an image
.DIC	Divide a selected region of an image by a constant
.DIN	Divide and normalise image using a calibration file.
.DIS	Display image on X-window terminal
.DIV	Weighted division of two images
.DSF	Divide an image by a single file/raster.
.DUP	Duplicate and or remove frames of an image.
.EXP	Exponentiate data values.
.FFT	Perform 2-D fourier transform on an image
.GAU	Generate a 2-D gaussian function 
.HOR	Perform a horizontal integration in a selected region.
.IFT	Calculate the inverse fourier transform.
.INT	Integrate through selected region of image.
.IPO	Transform image from polar to cartesian coordinates.
.ITP	Interpolate a 2-D iamge
.LOG	Calculate natural or base10 log of image.
.LZR	Create postscript output file of image.
.MAX	Calculate minimum & maximum values of an image.
.MIR	Mirror the four quadrants of an image.
.MSF	Multiply an image by a single file/raster.
.MSK	Display an image & create a bit mask of selected areas.
.MUC	Multiply a selected region of an image by a constant.
.MUL	Weighted multiplication of two images.
.MUN	Multiply and normalise image using a calibration file.
.PAK	Pack an image into smaller dimensions by averaging.
.POL	Transform image from cartesian to polar cordinates
.POW	Raises image to specified power.
.PRT	Print values of data on lineprinter or terminal.
.RAD	Create circles around a centre point.
.REM	Duplicate and or remove frames of an image.
.REP	Replace a single raster or rasters in an image.
.RIN	Radial scan and integration
.RMP	Remap an image to a given set of remapping points.
.ROT	Rotate an image.
.SEC	Perform sector integration.
.SHF	Shift an image in x and/or y directions.
.SUM	Sum a series of images.
.SUN	Subtract and normalise image using a calibration file.
.SUR	Surface plot (isometric projection)
.VER	Perform a vertical integration in a selected region.
.WIN	Create a contrast transfer function in 2D from 1D file.
.ZER	Set all negative values in an image equal to 0.0.

1.4 The BSL file format

A set of standard files consists of:

*	Header file
*	One or more binary files.

Data from the NCD experimental stations appears with filenames of the type

Xnn000.mdd	Header file
Xnn001.mdd	SAXS data
Xnn002.mdd	Calibration data
Xnn003.mdd	WAXS data

where the first letter refers to the experimental session and the next two digits to the number of the individual experiment. The number increases by one after each experiment until the 100th experiment after which the number returns to zero. This Xnn format can be used to identify any experiment in a session.

The next three digits refer to the type of information contained in the file. The 000 file is the header file and is in ASCII or readable form. It contains information such as the sample title, the number of frames in the file, the names of the intensity and calibration data files. The 001 file contains the raw SAXS data in binary (unreadable) format. The 002 file contains calibration information, again in binary format and finally, the 003 file contains the raw WAXS data also in binary format.

The mdd gives the date on which the data was recorded. The first digit being the duodecimal month and the other digits the date:

Xnn000.807	7th August
Xnn000.A24	24th October

1.4.1 Header Files

The name of a header file is of the form Xnn000.XXX where X is any alphanumeric character and n is any digit. e.g. M74000.TMP. This header file is always written in ASCII and contains the following information:

*	line 1. Header with up to 80 alphanumeric characters.
*	line 2. Header with up to 80 alphanumeric characters.
*	line 3. Integer indicators for the first binary file

indicator(1)	= number of pixels.
indicator(2)	= number of rasters
indicator(3)	= number of time frames
indicator(4)	= 
indicator(5)	= 
indicator(6)	= 
indicator(7)	= 
indicator(8)	= 
indicator(9)	= 
indicator(10)	= 1, except for the last binary file, when it is zero

*	line 4. File name of the binary file 

The lines 3 and 4 should be repeated for subsequent binary files. The panel below shows an example of a header file with two binary files.

SRS Data recorded on Wed Mar 8 23:54:33 1995 
Collagen 
   512  512    1    0    0    0    0    0    0    1
     1    4    1    0    0    0    0    0    0    0
C01002.308  

1.4.2 Binary Files

The binary files contain the data, in Fortran terms, as direct access, unformatted, fixed length records (frames) containing REAL*4 values and as a stream of 4 byte floats in C terminology. The floating point format, as recorded by the Daresbury data acquisition system, is IEEE format based on "big endian" machines. The contentsof these files are organised as indicated by the header file.

There are some advantages and some disadvantages for this simple flat file format. The files are easy to process and writing conversion routines from one format to another is relatively simple. The fact that there is no header etc. in the actual file means that the number of frames, and even the frame size can be deduced simply from the file size. Mislabelled files can often be rectified from this alone (1x 512*512 frame is 1MB, or 1048576 bytes). The lack of any information in the actual data file means that several files are needed which can lead to confusion and difficulties if the ASCII header is lost. This can often be rectified reasonable easily by constructing a new ASCII header in a text editor.

It is worth noting that the binary data file is written in native byte order. This can lead to problems when transferring from a big-endian to a little-endian machine. There is a program to deal with the conversion.