User Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 28
Speckle Instrument GUI - Linux User Guide
Dave Mills (rfactory@theriver.com) – June 2018
Table of Contents
1. Introduction.................................................................................................................2
2. Installation...................................................................................................................2
3. Graphical user interface...............................................................................................4
3.1 The main window......................................................................................................4
3.1.1 Configurations menu..........................................................................................5
3.1.2 Temperature menu.............................................................................................5
3.1.3 Set ROI's menu..................................................................................................6
3.1.4 Tools menu.........................................................................................................6
Filter Transmission & Efficiency Curves.....................................................................9
3.2 Observations............................................................................................................13
Number of Image Sets to Acquire Per Target...........................................................14
..................................................................................................................................14
4. Desktop layout..........................................................................................................15
5 Log files......................................................................................................................21
6. Command Line usage................................................................................................22
7. Recompiling the shared libraries................................................................................25
8. Changing hardware components................................................................................26
9.Database.....................................................................................................................27
1. Introduction
The Speckle Instrument GUI has been developed by The Random Factory (Tucson, AZ) in
collaboration with the Speckle Instrument PI (Steve Howell) and collaborators (Nic Scott,
and Mark Everett - KPNO).
2. Installation
The GUI and accompanying packages are packaged using the gzipped tar archives. To
install the package :
cd $HOME
tar xvzf speckle-control-x.y.z.tgz
where x.y.z is the appropriate version number.
This installation will place the files in the directory $HOME/speckle-control. Although it is
possible to install the software to a different location, this is not recommended as it will be
necessary to manually change the location in some of the scripts included with the drivers.
Run the Andor drivers installation script
cd $HOME/speckle-control/andor-driver
sudo ./install_andor
Configure the USB devices for rw access
cd $HOME/speckle-control
./setDevicePermissions
FOR GEMINI :
The Gemini computers are running a different version of Linux and need different links in
the shared libraries. Unpack the prebuilt shared libraries by doing
cd $HOME/speckle-control
tar xzf untar-this-for-speckle-gemini-libs
Once this setup has been completed, the interface can be started with the command
~/startspeckle2
These USB permissions can also be set using the desktop icon, and the program can also
be launched with an icon double-click as well.
3. Graphical user interface.
The graphical user interface provides easy access to the major functions such as image
acquisition, temperature control, and device setup and configuration.
The program will open a small main window, and then create a message window which
shows the progress of the system startup operations.
Once the message window closes, the system is ready for use. The cameras are initialized,
and temperature control has been switched on.
3.1 The main window
Most of the time the controls in this window will be the focus of observing activities.
The following elements are provided :
3.1.1 Configurations menu
This menu provides quick setup for a range of commonly used observing
or setup configurations. Each is a simple script (the sources can be found in
$HOME/speckle-control/config-scripts, and any new scripts which are added
to this directory will be available as menu options after a GUI restart)
3.1.2 Temperature menu
This menu provides control over the camera cooler usage. Cooling may be
switched on or off, and the “ramp to ambient” option may also be selected
(this is applied when the camera is shutdown). The actual temperature setpoints
are individually controlled using entry boxes in the main window.
3.1.3 Set ROI's menu
This menu provides control over the data acquisition geometry. A range of
“region of interest” sizes can be selected, or the geometry can be reset to include the full
frame. If an ROI is chosen, then an image will be taken with each camera , and the best
ROI of the requested size will be automatically generated centered on the brightest target
in the image(s). If it is necessary to manually adjust the calculated ROI's, then selected
that option and then use the ds9 controls to move them, and then click OK on the dialog.
3.1.4 Tools menu
This menu provides access to a set of commonly used option. There are two main types
of item , GUI window visibility/mode, and Zaber stage motions.
The “Engineering” option resizes the main window to make visible an extra set of
controls generally used for equipment characterization and setup.
The detailed readout parameters of each camera can be manipulated, and the zaber
station positions edited and loaded/saved. For Gemini, extra controls for the Focus and
Pickoff stages, and the pico motors are also included.
The “Observing” option returns the main window geometry to the default , hiding the
Engineering controls.
The “Filter Selection” option opens the Filter Wheel control window.
This provides options to rename filters and load/save the configurations. There is a
placeholder for providing focus offset but this is not yet implemented.
Filter Transmission & Efficiency Curves
NESSI uses a dichroic beamsplitter to separate the incoming light (at 686nm) into blue
and red channels before focusing on the two identical cameras, which operate
simultaneously. The speckle filter choice will be one of 467nm or 562nm paired with one
of 716nm or 832nm. NESSI's SDSS filters are also listed below (although not used for
speckle imaging). Data are in nanometers and fractional efficiencies as quoted by the
manufacturer.
Name c. wave FWHM diffraction limit data
(nm) (nm) (arcsec FWHM)
467 467.1 44.0 0.034 nessi_467.dat
562 562.3 43.6 0.040 nessi_562.dat
716 716.0 51.5 0.051 nessi_716.dat
832 832.0 40.4 0.060 nessi_832.dat
u 354.3 32.7 nessi_u.dat
g 480.0 151.1 nessi_g.dat
r 620.0 143.5 nessi_r.dat
i 765.4 146.4 nessi_i.dat
z 943.3 242.7 nessi_z.dat
The “Camera Status” option opens a window showing the current settings of the main
camera configuration and readout parameters.
The “Plot timings” option opens a file selection dialog. Selecting a data cube image-name
will plot the time history of that cube's exposures (delta times with 0 = 1st frame time).
The data can also be examined in the file /tmp/timings after a plot.
The rest of the options command the motion of the relevant Zaber stages to the requested
position(s). Feedback on the positions can be seen in the Mimic diagram, and in the debug
log window.
3.2 Observations
The top left section of the main window contains a group of controls related to the
sequencing and initiation of observations.
The exposure time can be specified ( in seconds) using the spinbox , or a value can
be typed into the entry box area.
The number of frames to take can be specified using the spinbox, or a value can be typed
into the entry box area. For Kinetic series, this specifies the number of exposures in each
datacube. For non-kinetic mode it specifies the number of individual exposures to be
taken.
The Exp Type menu can be used to select common exposure types. Dark, Flat, etc.
This has little effect except over the shutter control, but the type is recorded in the image
headers.
The Num Seq spinbox can be used to repeat a set of observations multiple times.
The Accum spinbox can be used to select the number of exposures to be accumulated
before each camera readout. The exposures are thereby “co-added” by the camera.
This is normally used in conjunction with Kinetic series operations.
The File name entry box is used to specify the base name for the FITS files. It will be
expanded to add Sequence and Frame number where appropriate as the files are stored.
The current frame number is shown to the right , and will auto-increment as data is taken.
The Observe button start a sequence of observations (could be just a singleton).
The Video button starts a display only sequence , it must be canceled using the
Abort button before data acqusition Observations can commence.
The binning spinbox controls the binning factor in both x and y dimensions.
The Display FFT option chooses whether to display the raw image data, or to display an
FFT of the data instead.
The Kinetic mode option selects the Kinetic Series mode where the data is assembled into
a data cube where the third dimension is time. In this mode an array of (TAI) timing
information about the exposures is also included in the FITS file as a Binary table
Extension.
Immediately below the Observing section is a set of options to switch on simulation mode
for the various components. This is primarily intended for off-line testing , but could also
be useful for operating in a degraded mode (eg. No filter control). Simulation options can
also be set before starting the GUI (See the simulationMode file for an example).
The right side of the main window is focused on the meta data which will be included in
the FITS headers. Some of this is automatically populated with data from the Telescope
telemetry services. There are also menus for selecting a variety of Data Quality
specifications, and a comments area (this area may be flagged to auto-clear after each
exposure if required).
The current state of each camera (enabled, temperature) is prominently displayed top-
center of the main window.
The lower section of the window contains the major camera operating control.
From here, the temperature setpoint, Filter, Shutter state, Frame Transfer mode, EM
mode and gain can be changed. There are also options to enable EM gain advisory
popups, and to Auto set the gain. Finally the display of the images in ds9 can be
set to autofit or not (frame size)
Number of Image Sets to Acquire Per Target
The performance of speckle imaging is quite sensitive to conditions like seeing, so there
are no strict rules to follow for determining the ideal number of image sets to acquire on a
target of given brightness.
Observers targeting stars fainter than V=13 should plan on acquiring multiple image sets
and those observing brighter stars may also benefit from taking multiple sets. This will
depend on how they balance better contrast depth/image quality vs. number of targets
visited. Multiple image sets per star can also help under less than optimal observing
conditions and, given the several minutes needed to set up observing of each new target,
many users may want to devote comparable time to exposures.
Each image set requires 1 minute of telescope time. Acquiring a target with a short slew
requires 3 minutes and with a long slew, 5 minutes. Since a science target requires a point
source observation, additional time is needed for that (about 4 minutes). Refer to the
guide on estimating observing time for more information.
Note that we have found the signal-to-noise ratio for detecting secondary sources in
speckle images does not grow as rapidly with exposure time as it would in traditional
CCD imaging (ie. with the square root of time). Proposers may not expect to achieve the
same contrast limits on faint stars as bright ones (5 magnitudes may be achievable on 12th
magnitude stars and 3 magnitudes on 14th magnitude stars.) The table below only
suggests numbers of image sets to take for various magnitude stars:
V or R # image sets
<12 1-3
12-12.5 3
12.5-13 5
13-13.5 7
>13.5 9
(Mark Everett (everett@noao.edu).
4. Desktop layout
A recommend desktop layout is illustrated below. The main visible components are
ds9red image viewer for the Red arm camera images.
ds9blue image viewer for the Blue arm camera images.
Top-center xterm showing the debug log.
Lower left xterm showing the Red camera server operations
Lower right xterm showing the Blue camera server operations.
Mid-screen main GUI window.
The following example also show typical popup windows for the Mimic diagram and Filter
Wheels and Camera status windows.
This desktop shows an example of the appearance after an ROI selection , each ds9
window shows the chosen region, and the numeric parameters can be seen in the camera
server log windows.
This desktop shows a typical observing sequence in progress, the progress bar and
associated status update as the series progresses. Note that in this instance we are
displaying the FFT instead of the raw image data.
5 Log files
All GUI controlled operations are logged to disk. The files are named according to the
cpu clock at the startup and stored in the /tmp directory.
6. Command Line usage
There is a rich set of commands to allow interactive and scripted usage.
To access the command line it is necessary to source the startspeckle-cmds
script from the speckle-control directory and then type
source gui-scripts/gui2.tcl
The following commands are available
Filter Wheel :
loadFiltersConfig [filename]
saveFiltersConfig [filename]
echoFiltersConfig
selectfilter arm filter-number
findWheels
resetFilterWheel arm
Zaber stages :
loadZaberConfig [filename]
saveZaberConfig [filename]
echoZaberConfig
zaberPrintProperties
zaberConnect
zaberDisconnect
homeZabers
zaberCheck
zaberSetPos name position
zabersStopAll
zaberGoto name station
Pico Stages : Gemini only
loadPicosConfig [filename]
savePicosConfig [filename]
echoPicosConfig
picosConnect
picoCommand axis cmd
picoSet axis parameter value
Andor Cameras :
Command may be issued from the GUI command line, scripted , or optionally by
telnet to ports 2001, 2002. When using the command line the syntax is
commandAndor arm “command and parameters”
or commandAndors “command and parameters”
accumulationcycletime seconds
acquisition index
autofitds9 0/1
baseclamp 0/1
comments comment1|comment2|....
configure hbin vbin vstart vend hstart hend preamp vsspeed ccdhss emccdhss
datadir data-directory
dqtelemetry rawiq rawcc raqwv rawbg
emadvanced index
emccdgain 0/1
fastVideo exposure xs ys dim
fitsbits data-format
forceroi xs xe ys ye
frametransfer index
gettemp
grabcube exposure xs ys dim
grabframe exposure
grabroi exposure xs ys dim
hsspeed amp index
imagename image-name
kineticcycletime seconds
locatestar smooth dim
numberaccumulations count
numberkinetics count
outputamp index
positiontelem input-zaber field-zaber filter
preampgain index
programid program-id
readmode index
reset mode
setexposure seconds
setframe mode
setroi mode
settemperature degrees
shutdown
shutter index
status
version
vsamplitude index
vsspeed index
whicharm
7. Recompiling the shared libraries
Low level functionality is provided in C/C++ for speed , and this code is
wrapped using tcl and loaded into the interpreter at runtime.
To move the code to a different version of Linux it may be necessary to
recompile the libraries in the following directories. Each has either a Makefile
or a set of build steps (e.g. andor/buildAndorWrap).
The Vips library may present more difficulty due to it's many dependencies.
The package can be recompiled using the GNU standard incantations
./configure --prefix=some-installation-directory --without-python
make install
If the configure step does not work , try
sudo apt install automake autogen m4
libtoolize
aclocal
automake --add-missing
autoconf
then try the ./configure step again.
8. Changing hardware components
If it becomes necessary to change out either Filter Wheel or Camera components, the
appropriate configuration files will be adjustment. The configuration files are in the
$HOME/speckle-control directory
andorsConfiguration.[telescope]
filtersConfiguration.[telescope]
In each case the serial number information will need to be updated.
The Filter Wheel serial numbers can be found using the lsusb command
The Andor Serial numbers can be found by examining the “dmesg” log at system
boot time.
9.Database
The camera servers automatically log information about each image to the on-board
database (Mysql). The database is named “speckle” and the table name is
“Speckle_Observations”. It can be viewed using the mysql command line program,
or using the TOPCAT GUI.
e.g.
mysql –user=root speckle
select * from Speckle_Observations LIMIT 10;
Or using the TOPCAT gui
