Rasnik Image Analysis

Contacts and Links

[Frank Linde] (Analysis Software Code)

[Robert Hart] (Windows application / Icaras / DIM)

[Henk Groenstege] (Rasnik Electronics)

[Harry van der Graaf] (Overall)

[Rasnik homepage]

Documentation

The ASCII output file format

• Each line starts with 2 characters identifying the contents of the line
• First line is written by Icaras and starts with 'st'
• In 'st' line the fields are separated by a comma (historical reason)
• Fields within the other lines are seperated by (at least one) space
• For use under normal operation only the lines 'ud' and 'ue' are interesting. The rest is for debug, quality check, and user data correction if neccesary, and requires insight in the source code of the analysis.

Variables written to file

"st",seq_no,grab_date,grab_time,rasnik_id,channel_id,icaras_version,analysis_version

"ud" ierr X Y M AlphaX AlphaY AlphaZ L Sx Sy

"ue" dum DX DY DM DAlphaX DAlphaY DAlphaZ DL dum dum

"rx" ixcode xpitch xoffset xangle Dxpitch Dxoffset Dxangle Cor_xp-xo Cor_xo-xa Cor_xa-xp

"ry" idem for y;

"rg" dum dMdx dMdy dSdx dSdy DdMdx DdMdy DdSdx DdSdy dum dum

"lr" TO_CENTER TO_LENS FIX_BW_WB BANDS nx_fg ny_fg Mask_B3 Mask_Orient Mask_pitch X_Pix Y_Pix X_Fudge Lens_Focus Lens_Diam LED_Wave Dist_Mask_CCD

"qf" BADFITX BADFITY REALBAD FAILED ndfx ndfy xchsq ychsq avg-bw rms-bw cut_bw "bands:" BANDS BAND_OK dum dum dum dum dum

 Notes:
  - dum = dummy variable not yet or no longer used (=0).
  - The first 5 data lines have the same format.
  - The last 2 data lines have (each) a different format.
  - variable in capitals letters means a boolean and are here separeted
    by a space for readability, but in the file they are NOT separated.
    In the file T=true, F=false.
  - Text between quotes appears litterally in the file.
  - variable starting with a 'D' denotes the error margin on the associated variable.

Explanation of the variables

st = stamp

seq_no sequence number

grab_date date the image was taken (yyyy/mm/dd)

grab_time time the image was taken (hh:mm:ss)

rasnik id rasnik system name (set by user in channel settings)

channel RASMUX hardware channel

icaras_version (decimal integer)

analysis_version (decimal integer)

ud = user data

ierr error given by analysisprogram. (0=OK)

X x reading of mask or lens in mm (depends on TO_LENS boolean)

Y y reading of mask or lens in mm (depends on TO_LENS boolean)

M average magnification factor of the image on the CCD

alphaX rotation mask/CCD around X axis

alphaY rotation mask/CCD around X axis

alphaZ rotation mask/CCD around X axis (= angle seen directly on TV)

Sx average sharpness in x direction

Sy average sharpness in y direction

L absolute distance mask-CCD (not yet implemented)

ue = user error

As ud line, but giving the errors on the variables.

rx = raw x data from fit

ixcode result of decoding in 'X' direction (in units chessboard squares)

xpitch size of chessboard square in unit pixels in X-direction

xoffset fractional part of chessboard squares in X-direction in unit pixels.

xangle angle between columns (!) on CCD and vertical (!) lines of the mask on the CCD

Dxxxxx error on xxxxx

Cor_x.. correlations between the pitch/offset/angle

ry = raw y data from fit

iycode result of decoding in 'Y' direction (in units chessboard squares)

ypitch size of chessboard square in unit pixels in Y-direction

yoffset fractional part of chessboard squares in Y-direction in unit pixels.

yangle angle between lines (!) on CCD and horizontal (!) lines of the mask on the CCD

Dyyyyy error on yyyyy

Cor_y.. correlations between the pitch/offset/angle

rg = raw gradients data from fit

dMdx/y gradient of A in X/Y direction (gives alpha Y/X) given in the form: dMdx/M (unit: 1/Xpixel, 1/Ypixel)

dSdx/y gradient of sharpness in x/y direction (not yet implemented)

Ddxdy error on dxdy

lr = layout of the RASNIK system

TO_CENTER reference point on CCD. T=center, F=top left corner

TO_LENS give x and y of mask or lens. T=lens, F=mask

FIX_BW_WB correct for difference in black->white and white->black transitions?

BANDS determine black (left+right) side bands of image? (result stored, but not used)

nx_fg number of IMAGE pixels in x-direction (determined by framegrabber, NOT by CCD!)

ny_fg number of IMAGE pixels in y-direction (determined by framegrabber, NOT by CCD!)

Mask_B3 size of Basic Building Block (number of squares horizontally (=vertically)). One BBB contains one horizontal code and one vertical code.

Mask_Orient orientation of the mask: 00,01,10 or 11. First digit = x, second digit = y. 0 = normal, 1 = reversed.

Mask_pitch size of the side of one square in mm

X_Pix image pixel size in x-direction in mm (taken from channel settings). This is the net pixel size, which is the result of the digitisation done by the framegrabber. It is NOT the CCD x pixel size!

Y_Pix image pixel size in y-direction in mm (taken from channel settings). This is the CCD y pixel size.

X_Fudge Correction factor for X_Pix (x pixel size can be determined from y pixel size assuming squares on the mask).

Lens_Focus focal length of the lens (mm)

Lens_Diam diameter of the lens (mm)

LED_Wave wavelength of the light used (nm)

Dist_Mask_CCD distance from mask to CCD (mm)

qf = quality of the fit

BADFITX,BADFITY,REALBAD,FAILED booleans to indicate quality of the fit. Should be FFFF. Data cannot be trusted if FAILED = T. The other three are much less serious if T (data still acceptable).

ndfx, ndfy number of points used in the x/y fit

xchsq, ychsq chi-squares of x/y fit

avg-bw average value of CCD image

rms-bw rms of CCD image

cut-bw value used as cut on the derivative

"bands:" the data following this keyword concerns the location of the black side bands (left and right) on the image.

BANDS T if sidebands should be determined

BANDS_OK T if sideband determination has succeeded

The "bands" idea was never really finished and tested. It has therefore never been used to correct the main results (the "ud" line).

Interface between Analysis and Windows

Overview of this section

• Dynamic Link Library
• Routines to supply: InitAnalysis , DoAnalysis , ExitAnalysis
• Analysis Version Numbers
• Analysis Input Arrays
• Results Output format
• Interface to Fortran

Dynamic Link Library

You have to generate an analysis.dll (dynamic link library) that supplies three routines: initanalysis,doanalysis and exitanalysis. The routines should be dll-exported with the following names: "__init_analysis", "__do_analysis", "__exit_analysis" so that icaras can find them inside the library. See for example file interfc.f90.

This analysis.dll has to be in the same directory as the icaras executable. At icaras startup that dll is loaded that was active when icaras was exited for the last time. Default name (at first startup) is "analysis.dll" You can select the analysis dll via the Settings->Analysis menu.

Analysis Routines to supply in the analysis.dll

InitAnalysis

Called: Every time the analysis is called, just before calling "doanalysis"

Input: handle to the message window

Output: analysis version number (see table below).

C++ declaration: void _init_analysis(HWND h_msg_wnd, int* version);

Description:

Should return the version number of the analysis. This number is written by icaras on the 'st' line of the output file. For some reason this number is written by icaras in hex format. But we want to read it as decimal in the output file, so the IVRSN number set in this routine should be different... Sorry for this inconvenience.

Analysis version numbers distribution

Please stick to it, so that analysis software reading the output can, based on this version number, correctly interpret the rest of the data!

Institute	Author	Version Numbers in InitAnalysis (decimal)	Output in file (hex)
NIKHEF	F.Linde	256-511	100-199
Brandeis	K.Hashemi	512-767	200-299
MPI	S.Schael	768-1023	300-399
Saclay	O.Cloue	1024-1279	400-499
unassigned		1280-	500-

DoAnalysis

Called: For every image to be analysed

Input:

• array of integer channel settings
• array of float   channel settings
• array of image bytes, row by row, top-left pixel first.

Output: error number. 0=OK.

C++ declaration: void _do_analysis(int* NIN, float* FIN, BYTE* image, int* error);

Description:

The number cruncher. This is the real image analysis. It gets a pointer to the image and the input settings like image size and pixel size. It should fill in the error number. Zero means success. If it is non-zero, icaras prints an error message in the output window. The results of the analysis should be written to file directly from within the analysis. Results can also be written to screen (the output window). Icaras will add the RASNIK channel name at the beginning of each line written to screen. Writing to file or screen in C++ can be done with SendMessage(). See file interfc.f90 to have an idea on how to do this. In Fortran this can be done with the WINDOUT and FILEOUT outines, which are defined in file interfc.f90.

ExitAnalysis

Called: Every time the analysis is called, just after calling "doanalysis"

Input: none

Output: none

C++ declaration: void _exit_analysis(void);

Description:

Do whatever needed after the analysis. Could very well be nothing...

Analysis input setting arrays.

NIN = array of (4-byte) integer settings

FIN = array of (4-byte) float settings

Categories:

A = automatic (by icaras)

R = required for analysis

B = (pseudo-)boolean. 0=no, 1=yes

C = combination with other parameters redundant, needs check for consistency!

Limit = -1 or -1.0 means no test on limit

Index starts counting from 1 (Fortran style)

Analysis input settings array of integers (NIN)

Index	Name	Catagory	Default	Minimum	Maximum	Comment
1	NIN count	A	32	32	32	# values in NIN
2	FIN count	A	32	32	32	# values in FIN
3	idf version	A	0	0	-1	input definition file version
4	x img	R,C	0	100	768	width of image (#pixels)
5	y img	R,C	0	100	576	height of image (#pixels)
6	nchess	R	9	9	9	size of BBB (code line every nchess squares)
7	debug-level		0	0	-1	level of debug output
8	x orientation		0	0	1	horizontal mask orientation (0=normal, 1= reversed)
9	y orientation		0	0	1	vertical mask orientation (0=normal, 1= reversed)
10	origin on ccd	R	0	0	1	0=top-left corner, 1=centre
11	mask or lens	R	0	0	1	0=give x,y of mask; 1=give x,y of lens
12	x,y rotations	B	1	0	1	calculate rotations around x/y axes? 0=no; 1=yes
13	debug printout	B	0	0	1	yes or no?
14	locate side bands	B	0	0	1	find left/right black edges?
15	plots	B	0	0	1	make plots?
16	B/W bias	B	0	0	1	compensate for difference in B->W vs. W->B transitions?

Analysis input settings array of floats (FIN)

Index	Name	Catagory	Default	Minimum	Maximum	Comment
1	x pix	R,C	ccd_x / x_img	0.001	1000.0	Pixel size in x direction (mm)
2	y pix	R,C	0	0.001	1000.0	Pixel size in y direction (mm)
3	ccd x	C	0	0.1	100.0	ccd size in x direction (mm)
4	ccd y	C	y_pix * y_img	0.1	100.0	ccd size in y direction (mm)
5	ccd x active			0.1	100.0	size of active part of ccd in x direction (mm)
6	mask x pitch	R	0.120	0.010	-1.0	mask pitch in x direction (mm)
7	mask y pitch	R	0.120	0.010	-1.0	mask pitch in y direction (mm)
8	lens focal length		1.0	1.0	-1.0	focal length of lens (mm)
9	lens diameter		1.0	1.0	1000.0	diameter of lens (mm)
10	light wave length		880.0	400.0	1200.0	wave length of IR light used (nm)
11	distance mask-lens	C	1.0	1.0	-1.0	distance between mask and lens (mm)
12	distance ccd-lens	C	1.0	1.0	-1.0	distance between ccd and lens (mm)
13	distance mask-ccd	C	#11 + #12	2.0	-1.0	distance between mask and ccd (mm)

Results output file format

For uniformity and usability of analysis software reading the icaras output, please stick to the following rules.

1. Output file is written by icaras simply in ASCII (this you cannot change).
2. Per analysed image several lines of output can be written.
3. All lines start with a two letter string to identify its contents.
4. What is written further on the line is completely up to the analysis program.
5. The first line is always written by icaras and starts with 'st' (stamp). It contains information like sequence number, time of grabbing, channel name, version numbers. Fields (in this line) are separated by comma's.
6. The following lines contain the actual results of the output. These lines have to be written directly from within the analysis, for example by calling FILEOUT(MSG) in Fortran.

Example (part of NIKHEF analysis, full description in Nikhef Ascii Output):

st seq_no,yyyy/mm/dd,hh:mm:ss,channel_name,rasmux_channel,icaras_version,analysis_version
ud errno  x  y  magn  ax  ay  az sz  sy  L
ue 0     Dx Dy Dmagn Dax Day Daz   0  0 DL
rx ... (raw data in x direction)
ry ... (raw data in y direction)
rg ... (raw gradients)
lr ... (layout of RASNIK system)
qf ... (quality of the fit)

ud = User Data
   The user of the output is usually only interested in the data in this line.
   It gives the RASNIK coordinates (final output of the analysis).
ue = User Error
   The errors (accuracies, uncertainties) on the measurements.

What could (should) be the same in the output of different analyses

• Lines 'ud' and 'ue' since it contains the numbers we want (result of nalysis).
• Line 'lr' because it contains the layout of the RASNIK system (pixel sizes, number of pixels etc.). This is particularly useful for later corrections, e.g. on the pixel size, which directly influences the magnification.

Interface to Fortran

The interface to an analysis in Fortran is coded in file interfc.f90.

This file should of course be included in your project if you want to use its interface. It also exports the functions in the .dll, so they can correctly be called from icaras.

Microsoft Developer Studio You need the Microsoft Visual Fortran Compiler.

The following files you can use as a start, or as an example, are included in a <A HREF="anal_MSDEV_F.zip">zip file </A>:

<A HREF="analysis.f">analysis.f</A>          fortran example with empty routines. To be filled in by you!
<A HREF="interfc.f90">interfc.f90</A>         fortran interface (for non-server based Icaras)
<A HREF="interfc_server.f90">interfc_server.f90</A>  fortran interface (for server based Icaras)
Analysis.mak        makefile.
Analysis.mdp        project file.
analysis.ncb        class definition file
anmod.aps
anmod.rc
resource.f
resource.h

1. Create a Developer Studio project for the analysis.
2. Copy all files to this directory
3. Open the project workspace analysis.mdp.
4. The filenames of the project are stored in the analysis.mak file with the complete pathname. The pathname inside the makefile is: "d:\icaras\my analysis". If you have your project in a different directory (which is likely) you have to remove all files from the project, and then re-insert them in the project from your directory. There might be an easier way, but I'm not an MSDEV expert.
5. Edit the analysis.f file (fill in the 3 subroutines, see below)
6. Rebuild the project using the 'Release' configuration.
7. Copy the file analysis.dll to your ICARAS folder.

Other compilers

No experience yet. You probably only need analysis.f and interfc.f90. You probably also have to edit interfc.f90 to adapt it to your compiler (there are some !MS$ switches).

InitAnalysis Routine

It takes care of the message window handle, and prepares the the Fortran output routines WINDOUT and FILEOUT. It then calls the following subroutine:

       SUBROUTINE INITANALYSIS (IVRSN)
       INTEGER IVRSN

DoAnalysis Routine

Just calls the fortran routine:

       SUBROUTINE DOANALYSIS (NIN,FIN,IMAGE,IERR)
       INTEGER NIN_SIZE, FIN_SIZE
       PARAMETER (NIN_SIZE=32)
       PARAMETER (FIN_SIZE=32)
       INTEGER NIN(NIN_SIZE)
       REAL FIN(FIN_SIZE)
       BYTE IMAGE(*)
       INTEGER IERR

ExitAnalysis Routine

Just calls the fortran routine:

       SUBROUTINE EXITANALYSIS

Writing to screen

       CHARACTER*1024 MSG
       WRITE(MSG,*) 'Whatever I want to write'
       CALL WINDOUT(MSG)

Note: The total length per line is limited to 1024 characters (determined by PARAMETER STR_SIZE=1024 in file interfc.f90). Writing to file

       CHARACTER*1024 MSG
       WRITE(MSG,*) 'Whatever I want to write'
       CALL FILEOUT(MSG)

Note: The total length per line is limited to 1024 characters (determined by PARAMETER STR_SIZE=1024 in file interfc.f90).

For details ask [Robert Hart]

How to run (linux)

Examples of rasnik images can be found in directory:

/project/atlas/projects/rasnik/images

The are two ways to run the rasnik executable:

1) By hand: Execute rasnik.exe (without any arguments), and anwser all the questions.

2) Automatic: Execute the rasnik.run script, with image(s) as arguments. It contains a kind of 'database' to set the correct settings for the images in the example directory.

How to run (windows)

Ask [Robert Hart]

How to make a new rasnik version (linux+windows)

The basic code is kept on linux. The source for windows is created from the linux source.

Once you have checked out the source code from the local cvs repository (see Getting the source code), you can start editing it. If you want to archive certain changes you made, you can store the files in de cvs repository with the command (from your Rasnik/Fortran directory):

cvs commit -m "My comments on the changes I made"

This will add a new version to the repository of the all changed files in the current directory (and below). The string after the -m option will be stored as comments to this version. If you omit the -m option, an editor will startup where you can/must type your comments. Adding the comments is actually a very useful feature. A list of all comments of all revisions is printed with the command:

cvs log <filename>

If you want to add a new file to the repository, you have to tell cvs that you want to include it by the command:

cvs add <filename>

This does not put the file in the repository directly, but it will be put there at the next 'cvs commit' command. If you do not give the 'cvs add' command, any new files in the working directory will NOT be added to the repository at 'cvs commit'! So it is OK to have some temporary working files in your workdir.

Once you are happy with your changes and want to release it as a new analysis version, you need to do several things:

1. Change the PARAMETER (IVERSION=nnn) to the new version number
2. Update the cvs repository with 'cvs commit'
3. Add a cvs tag to the current set of files by going up one directory (to Rasnik), and typing there:
   cvs tag rasnik<nnn> Fortran
   where <nnn> is of course the new version number. The Fortran directory and all files in it will now get the cvs tag rasnik<nnn>, which provides a way to get them back later as a consistent set of files! This is very important.
4. Compile the code to generate the latest rasnik.f file (probably already done)
5. Rename the rasnik.f file to rasnik<nnn>.f
6. Keep this rasnik<nnn>.f file somewhere on the www
7. Make an external link under the Getting the source code section of these wiki pages to point to that file on www.
8. Ask Robert Hart to make and release a new windows dll and tell him where he can find the new source (*.f) file.

Getting the source code

For Windows

Fortran *.f files: [rasnik140.f] [rasnik138.f] [rasnik137.f] [rasnik135.f] [rasnik134.f] [rasnik133.f]

Shared libraries (dll): Ask Robert Hart.

For Linux

The analysis code is stored in a local Nikhef Atlas cvs repository, which contains (a.o.) a rasnik.car file and a Makefile. You can get the latest code by doing a cvs checkout:

cvs -d /project/atlas/cvs co Rasnik/Fortran

This will create in the current directory the subdirectories Rasnik/Fortran and put all the files there.

The repository contains all old versions of the code as far as we kept trace of it, (i.e. starting at version 133). A specific version can be obtained with the command:

cvs -d /project/atlas/cvs co -r rasnik<nnn> Rasnik/Fortran

where <nnn> is the version number. WARNING: This will overwrite whatever is in the your Rasnik/Fortran directory with the same name. The "rasnik<nnn>" is actually a cvs tag that has been assigned to it.