Rasnik Image Analysis
Contacts and Links
Contact persons
[Frank Linde] (Analysis Software Code)
[Robert Hart] (Windows application / Icaras / DIM)
[Henk Groenstege] (Rasnik Electronics)
[Harry van der Graaf] (Overall, mechanics, lenses, calibration, ...)
Links to other Rasnik pages
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).
The algorithms
How to compile (linux)
Once you got the code from the cvs repository (see Getting the source code), go to the Rasnik/Fortran directory and type the following sequence of commands:
gmake
This will transform the rasnik.car file into a rasnik.f file with the help of the cmz program
and the rasnik.kumac file. This rasnik.f file then gets compiled into the executable rasnik.exe.
How to compile (windows)
Overview of this section
- Routines to supply: InitAnalysis , DoAnalysis , ExitAnalysis
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)
| Comment | ||||||
| NIN count | # values in NIN | |||||
| FIN count | # values in FIN | |||||
| idf version | input definition file version | |||||
| x img | width of image (#pixels) | |||||
| y img | height of image (#pixels) | |||||
| nchess | size of BBB (code line every nchess squares) | |||||
| debug-level | level of debug output | |||||
| x orientation | horizontal mask orientation (0=normal, 1= reversed) | |||||
| y orientation | vertical mask orientation (0=normal, 1= reversed) | |||||
| origin on ccd | 0=top-left corner, 1=centre | |||||
| mask or lens | 0=give x,y of mask; 1=give x,y of lens | |||||
| x,y rotations | calculate rotations around x/y axes? 0=no; 1=yes | |||||
| debug printout | yes or no? | |||||
| locate side bands | find left/right black edges? | |||||
| plots | make plots? | |||||
| B/W bias | compensate for difference in B->W vs. W->B transitions? |
Analysis input settings array of floats (FIN)
| Comment | ||||||
| x pix | Pixel size in x direction (mm) | |||||
| y pix | Pixel size in y direction (mm) | |||||
| ccd x | ccd size in x direction (mm) | |||||
| ccd y | ccd size in y direction (mm) | |||||
| ccd x active | size of active part of ccd in x direction (mm) | |||||
| mask x pitch | mask pitch in x direction (mm) | |||||
| mask y pitch | mask pitch in y direction (mm) | |||||
| lens focal length | focal length of lens (mm) | |||||
| lens diameter | diameter of lens (mm) | |||||
| light wave length | wave length of IR light used (nm) | |||||
| distance mask-lens | distance between mask and lens (mm) | |||||
| distance ccd-lens | distance between ccd and lens (mm) | |||||
| distance mask-ccd | 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.
- Output file is written by icaras simply in ASCII (this you cannot change).
- Per analysed image several lines of output can be written.
- All lines start with a two letter string to identify its contents.
- What is written further on the line is completely up to the analysis program.
- 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.
- 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.
Windows Interface to Fortran
The interface between Windows and an analysis in Fortran is coded in file interfc.f90. The section Getting the source code indicates how to get a zip file containing a number of files (inferfc.f90 and a few others) that worked for and old version of Microsoft Developer Studio (I think version 4 or 5) with both the C++ and Fortran modules installed. Below the inferface routines in interfc.f90 are described.
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
Example code for 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).
Example code for 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:
- Change the PARAMETER (IVERSION=nnn) to the new version number
- Update the cvs repository with 'cvs commit'
- 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. - Compile the code to generate the latest rasnik.f file (probably already done)
- Rename the rasnik.f file to rasnik<nnn>.f
- Keep this rasnik<nnn>.f file somewhere on the www
- Make an external link under the Getting the source code section of these wiki pages to point to that file on www.
- 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 analysis code *.f files: [rasnik140.f] [rasnik138.f] [rasnik137.f] [rasnik135.f] [rasnik134.f] [rasnik133.f]
Windows Fortran analysis interface files: [anal_MSDEV_F.zip]
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.
Getting the Windows analysis library
Ask Robert Hart.