..... imageCatcher .....
Introduction
"imageCatcher" is a program written in IDL that fetches images acquired
by the VME-based video digitizers, plots them as images or surfaces, creates
X and Y profiles over a user defined Region of Interest, and fits a gaussian
to these profiles to obtain typical beam parameters. The beam parameters
will be calculated in "pixel" units unless a calibration box has been defined
which allows the parameters to be calculated in user defined units (e.g.
mm). Images and associated parameters can be saved in SDDS format files
for further analysis.
Because of the large amount of network traffic required to fetch a digitized
image, the program will only update the image at 1 Hz (even though the
LINAC video digitizer captures images at 2 Hz). Later improvements to this
program will allow the specified Region of Interest to be acquired at 2
Hz.
With the Beta1 version, the image is acquired from the video digitizer
in the LINAC. Currently, more than 20 cameras are "multiplexed" into this
frame grabber, including some from the PAR. Later enhancements will
allow images from the other APS video systems as well.
New Features
BETA1 Additions/Improvements
-
Buttons are now provided for image update options (instead of menus).
-
Region of Interest (ROI) definition is now stored in the calibration file.
It is also "remembered" for each screen index during a imageCatcher session
(i.e. as the selected camera changes, the displayed ROI changes).
-
If in "Get Screen ID from EPICS" mode, changing the selected screen (via
the multiplexer will be detected by the imageCatcher and the appropriate
calibration info will be loaded.
-
"Sub Arrays" (after acquiring 16) can be selected with a text entry field.
Hitting return in this field increments to the next one.
-
Entering a value in the "Floor" field makes all values less than "Floor"
equal to 0 (removes low level noise).
-
Added a user specified Z Rotation angle for Surface Plots.
-
Greatly enhanced the Screen Calibration. All aspects of a screen can now
be defined.
-
Added "multi-catcher lockout" to ensure only one user can fetch the image
(system resource control).
-
If plotted image is from a saved file, the file name is indicated.
-
Calculated beam parameters X sigma, Y sigma, X Amplitude, Y Amplitude,
X peak, Y peak are now saved in the SDDS file.
Startup
BETA1 Version :
Start the program by typing the following on any workstation served by
helios :
~nda/idl/imageCatcher [more specifically, /home/helios/NDA/idl/imageCatcher]
To view this User's Guide, type
~nda/idl/imageCatcher -h
The program will initialize and attempt to connect to the LINAC video
digitizer. Possible messages you may encounter are listed below :
-
NO CALIBRATION FILE FOUND - Upon startup, imageCatcher looks for
a calibration file with the name liScreens.cal. If this file is not found,
the user is warned. The user may load in his own calibration file (See
Calibration) or begin defining his own screens to create a calibration
file from scratch. A template which contains LINAC screen definitions (but
not properly calibrated) may be copied from ~nda/idl/liScreens.adl into
the user's local directory.
-
IMAGE PROCESS VARIABLES NOT FOUND - The program could not connect to the
appropriate process variables. Either the video ioc is not responding or
there is a network problem. A new attempt can be made by pressing the 'return'
key in the 'PV Prefix for Image Records' field.
-
IMAGE PV USED BY: user@host - Because of the substantial system
resources used when transferring images, only one user is allowed to connect
to any given video digitizer. This message indicates the user and workstation
that is currently connected. The program can still be used, however,
to view previously saved image files.
Example Images
If no reasonable image is aquired upon startup, a few test images can
be used for experimenting with the imageCatcher capabilities. Copy the
files /home/helios/NDA/idl/*.idlImage to your own directory. Then use the
Open (IDL) .. option under the file menu to read
in this file. [One could avoid the copying step and navigate to /home/helios/NDA/idl
from the File Picker window].
Operation
If the startup occurred successfully, an initial image will be fetched
from the digitizer and plotted on the screen. The following sections describe
the capabilities of the imageCatcher to process this image.
File Menu
-
Open Raw Image - This option imports a raw image file from
older versions of the LINAC video analysis software. Files usually end
'.image' extension.
-
Open (IDL) - Reads in an image previously saved using the 'Save
(IDL)' option. Only the image is recovered, no calibration data. Files
usually end with '.idlImage' extension.
-
Save (IDL) - Save the image using IDL format. Default extension
will be '.idlImage'. These images can be recalled using the Open (IDL)
menu item.
-
Save as SDDS - Saves the image, calibration data, ROI info, calculated
beam parameters, operator comments, and other data in an SDDS formatted
file.
-
<Open SDDS> - The observant reader will notice that this option
is missing. Soon to come.
-
Screen Cal ... - Starts up the Screen Calibration program to allow
specification of image rotation, screen description, and a calibration
box to convert measurements from pixels to engineering units.
-
Quit - Stops program
Color Menu
The Color menu allows the user to select (or create his own) color table
to implement pseudo color in the displayed image. Different color schemes
enhance different aspects of the image. The most popular one seems to be
"STD GAMMA-II". [NOTE: With this versions of IDL on solaris, it seems necessary
to move the cursor into the image for the newly selected color table to
take effect.]
Screen ID
-
Get Screen ID from EPICS - With this option selected, imageCatcher
will fetch the screen ID (a number from 1 to 100) from the PV "LI:VD:MUX:cameraSelectedCC".
It uses this number to index into an array of calibration info read from
the calibration file. When the video mux changes, the imageCatcher will
automatically select a new calibration set based on the new screen ID.
-
Get Screen ID from User - In this mode, the screen ID is obtained
by the user via the adjacent text entry field. This entry "overrides" the
information available from EPICS. Once again, the screen ID is used to
index into the calibration table read from the calibration file.
View Options
-
View entire image - Plots the entire image within the plot window.
Even though the entire image is displayed, the profiles are always
calculated for only the Region of Interest.
-
View ROI - Plots a magnified view of the Region of Interest. The
magnification is maximized while maintaining the correct aspect ratio of
the ROI, therefore, the entire plotting area may not be used.
-
View as image - Plots image as a 2-dimensional image where the brightness
(or pseudo color) corresponds to the value of the pixel.
-
View as surface - Plots image as a 3-d surface where the pixel values
are represented by height in the Z-dimenstion.
Image Select
-
Raw image - Plot and profile the raw image as obtained from the
LINAC video digitizer (or file).
-
Background - Plot and profile the "background" image as previously
defined by the user.
-
Raw - Background - Plot and profile the difference between
the "raw" and "background" image resulting in background subtraction.
-
Store Raw into Background - Selecting this option defines the current
image (whatever is plotted) as the "background image.
PV Specification
-
PV Entry - This entry specifies the image process variable from
which to fetch the image. The only one currently available is LI:VD1:image.
-
Image Array - This button and text entry specify which of
16 images are to be displayed after acquiring them by the "Acquire 16"
command (see below)
Acquire Options
-
Update Image Once - Selecting this option causes the imageCatcher
to "grab" the next image captured by the LINAC video digitizer. If the
program seems to stall in this mode, make sure the "Camera Triggers" are
enabled on the LINAC Screen Control/Beam Image Acquisition display.
-
Update Image Cont - Causes the imageCatcher to continuously "grab"
images from the LINAC video digitizer. The update rate is limited to 1
Hz.
-
Acquire 16 - This option causes the imageCatcher to acquire 16 images
from the LINAC and display small thumbnail images of them in the plot window.
These can then be viewed by selecting the desired index next to the Image
Array button. Hitting return in this entry box increments the index by
1, allowing for quick scanning of the images.
-
Stop Acq - Stops or aborts image acquisition
Plot Options
-
Show ROI Box - If selected, the Region of Interest box is superimposed
on the image plot.
-
Show Cal Box - If selected, the Calibration Box is superimposed
on the image plot using a dashed line.
-
Scale Intensity - If selected, the image is scaled to utilize the
entire dynamic range of the color table (0 to 255). For example, if the
raw image had intensity values from 0 to 63, selecting the Scale Intensity
option would plot them as if each value was multiplied by 4. This option
greatly enhances dim images,
-
Fetch ROI Only - This option cannot currently be enabled. In the
future, it will instruct the imageCatcher to only fetch the pixels defined
in the ROI. This will conserve network bandwidth and make updates of 2
Hz possible.
Image Data Plot
This window is where the image is plotted. The description field of the
current screen ID is superimposed on the bottom of the image. Also displayed
is the min and max pixel values to indicate how much of the digitizers
dynamic range is being used.
The user can adjust the Region of Interest box by using the Box
Cursor as follows :
-
Depress the left mouse button while the cursor is in the plot window to
enable the Box Cursor
-
Once the Box Cursor is enabled, move the box around by holding down the
left mouse button. Resize the Box Cursor by depressing the middle mouse
button near a corner. When the Box Cursor is sized and positioned correctly,
depress the right mouse button to complete the movement.
When the Box Cursor procedure is finished, a magnified view of the ROI
will be plotted. To toggle between magnified and full view, hit the right
mouse button. The left mouse button will only activate the Box Cursor when
the full image is being displayed.
Profile Plots
The X and Y profile plots represent the Region of Interest. If the Screen
Index is "uncalibrated", the profile plots use pixels as the display units.
If the Screen Index has valid calibration data, the plots use the specified
units for display.
The amplitude of the profiles is a ratio of the actual sum of pixels
as compared to the absolute maximum. This gives at least a relative measurement
of the intensities.
Display Options
-
Floor - Any pixel value less than the "floor" value will be set
to 0. this can be used to eliminate minor background noise.
-
Z Rotation - When plotting the image as a surface, this value specifies
the amount to rotate it around the Z axis. Increasing this value allows
the operator to see the "back" of the peak.
Comment Line
This is a free form comment string that will be saved in the SDDS file.
Associated Snapshot File Name
This is another free form string field that will be saved in the SDDS file.
Its intended purpose is to store the name of a snapshot file that contains
the machine status at the time the image was captured.
Screen Calibration Program
The Screen calibration program allows editing of the calibration index
for a given screen ID. The screen ID (or sometimes referred to as screen
index) that is affected by the Screen Calibration program is the one that
is "active" (shown in the text entry field of the main screen) at the time
Screen Cal is started.
A typical calibration sequence is as follows ...
-
On the Main screen, ensure that the screen index that you want to calibrate
is indicated in the Screen ID # field. The user can enter a value if the
desired one is not shown.
-
Start the Screen Calibration program from the File menu.
-
Select which box you want to position (ROI or CAL) from the select buttons.
Use the Box Cursor position and size the box
as desired.
-
Enter the engineering unit coordinates for the Top Left and the Bottom
Right of the calibration box.
-
Enter in the desired EGU string, select the appropriate rotation, and enter
a description.
-
When all parameters are satisfactory, hit the "Set Calibration Now" button.
This will set the calibration for that screen ID for the remainder of the
imageCatcher session (unless it is changed later). The program will also
prompt to see if you want to save this change permanently to a file.
If this is not desired, simply hit Cancel.
A selected screen can be set to "uncalibrated" by hitting the button at
the bottom. Subsequent plots of this screen ID will be plotted in pixels.