bs v5.1

bs version August 2003

2D X-ray data processing program

Table of Contents

•	Introduction

•	Interface

•	A Few General Points

•	The BSL/OTOKO File Format

•	Command Set


Introduction

BS is a windows version of the 2D X-ray data processing program BSL in use at the Daresbury Synchrotron radiation source, for the treatmentof low angle x-ray diffraction. It has a shorther command list and hence a shorther name. BSL was written mainly by Geoff Mant for Biology Support Laboratory in DL and it runs on Unix or Unix-like platforms. You may find more about it on Daresbury web site www.srs.dl.ac.uk/ncd/computing/manual.bsl.html

Detailed documentation of BSL was produced by I. Dobbie during his PhD at  Kings College, London. Many paragraphs here are close copies of Ian's  manual.

The core of BS was written in April - June 2000 to make it possible to work with Daresbury data on our home, Windows-based computers. Another aim was to make it more user friendly and to provide greater flexibility to adopt to the ever changing requirements.

The program was written using CBuilder 4, all codes are available on request.

A number of useful tips were obtained from the open source of RasMol Molecular Graphics Program by R.Sayle (rasmol@ggr.co.uk).

I will be forever in debt if you mail me suggestions, bug reports, or just comments.

Natalia Koubassova

natalia@imec.msu.ru


Face

Interface

Unlike BSL the first thing to do is to open a file using MainMenu. The only exception is .usr command, that is discussed separately. From the moment a file is opened it becomes the Source. All commands are applied to the Source. Once you execute any command that generates a new image, that  image is stored as a temporary file, n.tmp, where n is the temporary file count. Temporary files may be saved with a new name, (press SAVE button), or may become a new Source. In the latter case a new command will be applied to the "unsaved" data and you will be prompted with a question:  Data not saved. Continue? . Select Yes and continue.

After every SAVE Source is reversed to the initially opened file.

The commands in BS follow the same nomenclature as in BSL, consisting of a set of 3 letters preceeded with a dot, e.g.  .muc to multiply by a constant. Nearly all functions can be applied to either single time frames or to a set of frames from a time series. Such commands as .mir, process only one selected frame from the source. Commands like .adc, .int, can process a set of frames from an input file.

More details could be found in the description of the command.


General

A Few General Points

Image, Zoom, Mouse, 1D graph, Favourites

Image

The co-ordinate centre is the top-left corner of the image, with the x-axis horizontal and which in BSL corresponds to pixels, and the y-axis is vertical, corresponding to BSL rasters.

Zoom

Zoom works like in Rasmol, press Shift+MouseRightButton and move mouse towards left bottom corner of the image to increase magnification or towards right upper corner to reduce it. For a known reason it works slowly in the beginning and quick at high zoom level. For an unknown reason at the intermediate level of zoom it shows a grid which later dissapears. To shift magnified image press left mouse button and move the mouse.

Mouse

You may use mouse selection in commands where the first two input lines are horizontal and vertical limits of the selected region. Click Left Button to mark Top-Left corner of the selection, then move it to Bottom-Right point and click it again. The limits in the text-input fields will be changed automatically. You can correct them manually before execution of the command.

These commands are: .adc, .ave, .cut, .hor, .int, .log, .max, .muc, .sum, .ver, .zer.

 In .rot session you may select two peaks by Ctrl+Left Button Click. Before doing that, it is useful to call .dis and to select sufficiently narrow threshold values for the image to see the actual peak pixel on the screen. The image centre and rotation angle are calculated after every second peak selection.

In .dis and .rot command mouse movement with Shift + Left button down invokes a zoom of the image. Moving mouse with right mouse button down will shift the image but not futher than the image borders.

1D graph

A separate window to display 1D plot can be opened directly from the main command window or as the result of horizontal/ vertical integration: .hor and .ver functions.

1D data format is ASCII, two columns with x and y co-ordinates.

F6 toggles cursor on the plot. When cursor is ON, use left and right arrows to move it along the data points. F3 selects a point. When two points are selected, the distance along x-axis and the position of the centre is calculated automatically. The latter option can be used to determine the centre of image after horizontal or vertical integration.

Favourites

This is window that contains a dozen of your favourite commands. Click mouse right button over any form button to change its value. Left mouse button changes the button value to a currently selected function.


f_format

The BSL/OTOKO File Format

BSL and OTOKO share a common file format.  A BSL "file" actually consist of at least 2 files on the computer: an ASCII  header and at least one binary file. The header is identified by the file name in the form Xnn000.xxx, where X is an uppercase letter, nn is a 2-digit number and xxx are character extension , uppercase letters or numbers. Case is not significant in Windows, so BS supports both upper and lower-case characters. It is advised to name all your output files in uppercase letters to ease transfer of the data on Unix machines and to avoid manual editing of header files.

Data from the area detector at Daresbury Laboratory is written into a maximum of five(?) files:

Xnn000.mdd      Header file

Xnn001.mdd      SAXS data

Xnn002.mdd      Calibration data

Xnn003.mdd      WAXS data

Xnn004.mdd      ???

where the first letter refers to the experimental session and the next two digits to the number of the individual record. The number increases by one after each record until the 100th record after which the number returns to zero. One should be careful to change the session letter before it happen. The detector data acquisition program will not ask your permission before overwriting the data.

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 frame size, the number of frames in the file, the names of the intensity and calibration data files. All other files are in binary format. The 001 file contains the raw SAXS (Small Angle X-ray Scattering) data, the 002 file contains calibration information, the 003 file contains the raw WAXS (Wide Angle X-ray Scattering) data.

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

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:

*       header 1. Comment line.

*       header 2. Comment line.

*       data line 1. 10 integer indicators for the binary file.

*       data line 2. File name of the binary file

Every line is up to 80 alphanumerical characters.

Integer inducators take 8fields each.The data lines 1 and 2 should be repeated for subsequent binary files. Below is an example of a header file with two binary files dumped from an area detector at Daresbury.

SRS Data recorded on Thu Mar 16 19:39:35 2000

200 s rigor

     512     512       3       0       0       0       0       0       0       1

D38001.316

       3       4       1       0       0       0       0       0       0       0

D38002.316

The first line is automatically generated by the detector control program. It gives a time and date for the generation of the file. The second line is a comment that the detector control program prompts for when you dump that data. These lines are called first and second header in BSL. Both these comment lines are useful if your lab notes do not agree with the files. This happens much more often than it should. The next pairs of data lines are definitions for the X-ray and calibration data files. First comes the data file description. For the X-ray file first three numbers are: number of pixels,  number of rasters, number of time frames. In the given example the image consists of 3 frames, frame size is 512 points horizontally (pixels) and 512 points vertically (rasters).What are they for the calibration channels? The last number is boolean indicator: whether there is another binary file.

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 contents of these files are organised as indicated by the header file. The direction of reading/writing is pixel line, e.g. the second number is 2nd pixel in 1st raster line of the 1st frame , and (2^18+513)number is the 1st pixel in the 2nd raster line of the 2nd frame.

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 (1x512*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 reasonably easily by constructing a new ASCII header in a text editor.It is worth noting that the binary data file is written in "big endian" format, where 4 byte float has native byte order, 0123. BS is written for "little endian" machines and reads BSL files in reverse byte order.


Commands
List of commands :

.inf 	Gives information about the data file.

.adc 	Add a constant to selected range in n frames from file.

.add 	Weighted addition of two images.

.arg 	Display memory contents.

.asc 	Export selection in ASCII format.

.ave 	Average of n frames from one file.

.csv 	Export selection from 1D  file in ASCII, CSV format.

.cut 	Cut part of an image in a smaller image.

.dis 	Displays image with given threshold.

.div 	Weighted division of two images.

.frm 	Select a frame from current file.

.gau 	Generate a 2D gaussian.

.hor 	Horizontal integration.

.int 	Integration though selected region.

.log 	Calculate natural or based 10  logarithm of the image.

.max 	Calculate extremal values of intensity.

.mih 	Mirror two halves horizontally.

.mir 	Mirror the four quadrants of the image.

.miv 	Mirror two halves vertically.

.muc 	Multiply selected region by a constant.

.mul 	Weighted multiplication of the two images.

.muv 	Multiply multiframe image by a vector.

.rot 	Image rotation.

.shf 	Shifts an image in x and/or x directions.

.sum 	Sum frames.

.tim 	Time correction for multiframe image.

.usr 	USER mode.

.wrh 	Bad wire seen horisontally, linear correction.

.wrv 	Bad wire seen vertically, linear correction.

.val 	Intensity value in one point.

.ver 	Vertical integration.

.zer 	Zero negative values.


.inf

Syntax: 	void

Description

Gives information about the Source file and current frame. For example:

* D38001.BK6 *

dim = 512 x 512 x 1

frame = 1

min_I = -414.41

max_I = 106222.27

In this example Source file is D38001.BK6 (data file name), with 1st frame selected. Image has 1 frame of 512x512. In the selected frame values of minimal and maximal intensity are calculated.


.adc

Syntax	        Example

Horizontal limits, [x1, x2]: int, int 	1, 512

Vertical limits, [y1, y2]:  int, int 	1, 512

Constant to add:  float 	1.5

Frames to use: int_list 	2, 3

Zero outrange values? bool 	0

Description

Adds a constant to the rectangular region of an image in a set of frames. Horizontal and vertical limits could be set by mouse selection. The last line is the check box on the form. If you are using USER mode, you should enter boolean value.

Output

Output is an image with n(int_list) number of frames, frame dimensions are the same as in input file.

See also

.muc


.add

Syntax	        Example

Name of ADD-file: char*	D38000.MIR

Frames to use:  int_list 1	3,4

Frames from ADD_file:  int_list 2	1

Weight constants: float, float	1.0, -1.0

Description

Weighted addition of two images. The Source and the ADD-file must have equal frame dimensions.The second file may have 1 frame selected, n(int_list 2) = 1, then this frame is added to all range in the Source. Otherwise number of frames selected from the Source and Second File must be equal. In the example the 1st frame from D38000.MIR is subtracted from 3rd and 4th frames on the Source.

Output

Output is an image with n(int_list 1) (2) number of frames.


.arg

Syntax	        Example

Threshold: float, float	0, 1000

Description

The .arg command displays the selected frame of the Source. All points with the intensity within the threshold interval are separated in 256 layers and coloured from black to white in greyscale. Points with the intensity lower than lower threshlod are black, the points below the upper threshold value are white.

See also

.dis


.asc

Syntax	        Example

Horizontal limits, [x1, x2]: int, int 	1, 512

Vertical limits, [y1, y2]:  int, int 	100, 100

Frames to use:  int_list	34

Write output file:  bool 	1

Description

Export the selected region in ASCII format.

Output

Values are separated with space. If one side of the selected region is one pixel wide/high the output values are in two columns - first is pixel/raster number, the second is its intensity value.

See also

.csv,  .val,  .int.


.ave

Syntax	        Example

Horizontal limits, [x1, x2]: int, int 	1, 512

Vertical limits, [y1, y2]:  int, int 	1, 512

Frames to average: int_list 	3-6

Description

The .ave averages frames from current file.You may restrict the region for averaging selecting rectangle.

Output

Output is an image with n(int_list), 4,  number of frames. Frame dimensions of output are (x2-x1+1)x(y2-y1+1) (512x512).

See also

.sum


.csv

Syntax	        Example

Horizontal limits, [x1, x2]: int, int 	1, 512

Description

Export the selected region in ASCII 'Comma Separated Values' format. This option works only with 1D file format.

Output

Values are written in two columns separated with comma. First column contains pixel number, the second - its intensity value.

See also

.asc,  .val,  .int.


.cut

Syntax	        Example

Horizontal limits, [x1, x2]: int, int 	50, 462

Vertical limits, [y1, y2]:  int, int 	236, 266

Frames to use: int_list 	3-6

Description

Cuts a smaller image from the Source.

Output

Output is an image with n(int_list) number of frames and (x2-x1+1)x(y2-y1+1) frame dimensions. In the example output image is of four 413x31 frames.


.dis

Syntax	        Example

Threshold: float, float	0, 1000

Description

The .dis command displays the selected frame of the input file, the one indicated in the window caption. All points with the intensity within the threshold interval are separated in 256 layers and coloured from black to white in greyscale. Points with the intensity lower than lower threshlod are black, the points below the upper threshold value are white.

See also

.arg


.div

Syntax	        Example

Name of DIV-file: char*	D38000.MIR

Frames to use:  int_list 1	3,4

Frames from DIV-file:  int_list 2	1

Weight constants: float, float	1.0, 0.98

Description

Weighted division of two images. The Source and the DIV-file must have equal frame dimensions.The second file may have 1 frame selected, n(int_list 2) =  1, then this frame is added to the selected frame range in the Source. Otherwise the number of frames selected from the Source and Second File must be equal. In the example the 3rd and 4th frames on the Source are divided by the 1st frame from D38000.MIR, that is multiplyed by 0.98. If the DIV-file has zero values, such points will be zeroed in the output image.

Output

Output is an image with n(int_list 1) number of frames. Example output will have 2 frames.

See also

.add,   .mul


.frm

Syntax	        Example

Select frame:  int	3

Description

Selects a frame from a multiframe image.


.gau

Syntax	        Example

SD_x, SD_y:  float, float	10, 50.25

Centre, (x0, y0):  int, int	256, 256

Amplitude:  float	600

Description

The .gau command generate a 2D gaussian:

f(x,y) = Amplitude* exp((x-x0)/SD_x + (y-y0)/SD_y) .

Output

The output file has one frame with the same xy dimensions as the Source.


.hor

Syntax	        Example

Horizontal limits, [x1, x2]: int, int 	1, 512

Vertical limits, [y1, y2]:  int, int 	1, 512

Frames to use:  int_list	31-36

Display plot:  bool 	1

Description

Horizontal integration in the selected frames. For every y integration is plain sum of all points in the [x1, x2] interval.

If Display plot is true and only one frame is selected, the result is passed to 1D graphics window. If number of selected frames is more than 1, the output files will be written named "fXXver.txt".

Output

The output file is in ASCII format. Data is in two columns:  raster(y) number, integrated value. The dimension of new file is y2-y1+1.

See also

.int,   .ver, 1D graph.


.int

Syntax	        Example

Horizontal limits, [x1, x2]: int, int 	1, 512

Vertical limits, [y1, y2]:  int, int 	1, 512

Frames to use:  int_list	31-36

Write output file:  bool 	1

Description

Integration in the selected region. By default, the result of integration is printed out in the Result Window.

Output

If output file is true the ASCII file is written. The dimension of new file is number of frames, 6 in the given example.

See also

.hor,   .ver,  .val.


.log

Syntax	        Example

Horizontal limits, [x1, x2]: int, int 	1, 512

Vertical limits, [y1, y2]:  int, int 	1, 512

Base, [e or 10]:  char*	e

Frames to proceed:  int_list	4

Description

The .log command takes the logarithm of the given base of the data in the selected region.The output file has n(int_list) number of frames, and the frame dimensions of the Source image. The outrange values are not changed.

Output

The output file has one frame with the same xy dimensions as the Source.


.max

Syntax	        Example

Horizontal limits, [x1, x2]: int, int 	1, 512

Vertical limits, [y1, y2]:  int, int 	1, 512

Description

Gives minimal and maximal values of intensity in the selected region in given frame. Output

The interval [min, max] typed in the text box.

See also

.int.


.mih

Syntax	        Example

Centre, y0:  int.5	10.5

Description

The .mih command is not a BSL command, it mirrors only horizontally, e.g. only pixel lines.

M(x, y0 + d) = M(x, y0 - d) = (Source( x, y0+d) + Source(x, y0-d))/2.

Unpaired lines are zeroed.

Output

Output file as a single frame image, frame dimensions the same as in the Source.

See also

.mir,    .miv


.mir

Syntax	        Example

Centre, x0, y0:  int.5, int.5	126.5, 128

Description

Mirrors four quadrants of the image.

Output

Output file as a single frame image, frame dimensions the same as in the Source.

See also

.mih,    .miv


.miv

Syntax	        Example

Centre, y0:  int.5	10.5

Description

The .miv command is not a BSL command, it mirrors only vertically, e.g. only raster columns.

M(x0 + d, y) = M(x0 - d, y) = (Source( x0 + d, y) + Source(x0 - d, y))/2.

Unpaired rasters are zeroed.

Output

Output file as a single frame image, frame dimensions the same as in the Source.

See also

.mih,    .mir


.muc

Syntax	        Example

Horizontal limits, [x1, x2]: int, int 	1, 512

Vertical limits, [y1, y2]:  int, int 	1, 512

Constant to multiply:  float 	1.5

Frames to use: int_list 	2, 3

Zero outrange values? bool 	0

Description

Muliplies the rectangular region of an image by a constant in a set of frames. Horizontal and vertical limits could be set by mouse selection. The last line is the check box on the form. If you are using USER mode, you should enter boolean value.

Output

Output is an image with n(int_list) number of frames, frame dimensions are the same as in the Source.

See also

.adc


.mul

Syntax	        Example

Name of MUL-file: char*	D38000.MIR

Frames to use:  int_list 1	3,4

Frames from MUL-file:  int_list 2	1

Weight constants: float, float	1.0, -5.5

Description

Weighted multiplication of two images. The Source and the DIV-file must have equal frame dimensions.Second file may have 1 frame selected, n(int_list 2) =  1, then this frame is added to all range in the Source. Otherwise number of frames selected from the Source and Second File must be equal. In the example the 3rd and 4th frames on the Source are multiplied by the 1st frame from D38000.MIR, that is multiplyed by -5.5.

Output

Output is an image with n(int_list 1) number of frames. Example output will have 2 frames.

See also

.add,   .div


.muv

Syntax	        Example

Name of MUV file: filename	vector.txt

Frames to use:  int_list	3,4

Description

Multiplication of selected frames by a vector of floating point values. Vector must be written in ASCII, better with .txt extension to be easily viewed by opening menu. If the vector is shorter than number of frames in the frames list, it will be continued with '1's and the warning will appear unless working in USER mode. The longer list will be cut to the length of frames list int_list.

Output

Output is an image with n(int_list 1) number of frames. Example output will have 2 frames.

See also

.muc,   .mul,   .tim


.rot

Syntax	        Example

Rotation Angle, deg: float	27.53

Rotation centre (x0, y0):  int, int	256, 256

Frames to rotate:  int_list	4-6

Description

Rotation is counter-clockwise.

Output

Output is an image with n(int_list) number of frames. Example output will have 3 frames.


.shf

Syntax	        Example

Shift, x_, y_: int, int	1, -5

Frames to shift: int_list	3

Description

Shifting

 x axis: + for right, - for left

 y axis: + for down, - for up


.sum

Syntax	        Example

Horizontal limits, [x1, x2]: int, int 	1, 512

Vertical limits, [y1, y2]:  int, int 	1, 512

Frames to sum: int_list 	13-15

Description

The .sum command sum frames from current file.You may restrict the region by selecting a rectangle.

Output

Output is an image with n(int_list) number of frames and (x2-x1+1)x(y2-y1+1) frame dimensions. They are 3 frames of 512x512 in the example.

See also

.ave


.tim

Syntax	        Example

Name of TIM file: filename	vector.txt

Frames to use:  int_list	3,4

Description

Division of selected frames by the time of exposure. TIM file is necessarily ASCII format, first lines could contain comments (line starting with ';').

; milliseconds

; current experiment

1   0.01   0.01

2   0.1    0.01

3   50     500

4   50     0.01

first row: frame number

second row: lifetime

[third row](optional): deadtime - does not work!

Deadtime input is in the command line.

Output

Output is an image with n(int_list 1) number of frames. Example output will have 2 frames.

See also

.muc,   .mul,    .tim


.usr

Syntax	        Example

User filename: char* 	usr.txt

Description

User file is a command list. It should start with open and end with close. In between you may place commands with corresponding parameter lines. Every command, filename or parameter line must be placed in the separate lines. Here is an example of user file:

open

D38000.BK6

  .hor

      100, 200

      200, 250

      1

  save

      D38HOR.txt

 .shf

      10, -2

      1 .mih

     256

 save

     D38000.MIH

close

In this example result of horizontal integration is passed to 1D graphics window and saved to the text file. Then the Source file D38000.BK6 is shifted, and the result of the shifting is mirrored horizontally. The output image (shifted and mirrored) is saved as D38000.MIH.


.val

Syntax	        Example

Point (x, y): int, int	10, 50

Description

Gives the intensity value in the point (x, y).


.ver

Syntax	        Example

Horizontal limits, [x1, x2]: int, int 	1, 512

Vertical limits, [y1, y2]:  int, int 	1, 512

Frames to use:  int_list	3,4

Display plot:  bool 	1

Description

Vertical integration in the selected frame. For every x integration is plain sum of all points in the [y1, y2] interval.

If Display plot is true and only one frame is selected, the result is passed to 1D graph window. If number of selected frames is more than 1, the output files will be written named "fXXver.txt".

Output

The output file is in ASCII format. Data is in two columns:  pixel(x) number, integrated value. The dimension of new file is x2-x1+1.

See also

.hor,    .int.


.wrh

Syntax	        Example

Bad wires interval, [x1, x2]: int, int 	1, 512

Npoints to average:  int 	1.5

Frames to use: int_list 	2, 3

Description

A huck. Do not use this command.

See also

.wrv


.wrv

Syntax	        Example

Bad wires interval, [y1, y2]: int, int 	1, 512

Npoints to average:  int 	1.5

Frames to use: int_list 	2, 3

Description

A huck. Do not use this command.

See also

.wrh


.zer

Syntax	        Example

Horizontal limits, [x1, x2]: int, int 	1, 512

Vertical limits, [y1, y2]:  int, int 	1, 512

Frames to proceed: int_list 	2, 3

Description

Zero negative values in the selected rectangle.

Output

Output is n(int_list) file with the same frame dimensions as the Source.

See also

.adc,   .cut