}

TUI

Contents

Introduction

TUI is the user interface for the APO 3.5m telescope. It is written in Python (a free cross-platform language) and runs on unix, MacOS X and Windows. This document describes how to install TUI on your computer.

Installing on MacOS X

  • Download TUI for Mac: TUI_vers_Mac.dmg. Double click the file to mount the disk image and drag TUI to your Applications folder.
  • Download and install SAOImage DS9 and XPA for MacOS X (this is optional but highly recommended).
    • Install SAOImage DS9 by dragging it to your Applications folder (it must be in /Applications or ~/Applications for TUI to find it).
    • Install XPA unpacking the downloaded zip archive and copying or moving the contained unix executables into /usr/local/bin. You will need admin privileges.

That's it; you are done. However, if you want to build from source then read on...

Building From Source for MacOS X

If you prefer, you may install TUI from source and even build your own double-clickable version. See Building TUI from Source On MacOS X for details.

Installing on Unix

If you have a fairly uniform set of unix machines to support (i.e. most users running the same flavor of unix), I recommend installing everything (tcl/tk, python, etc.) on a network mountable disk and have people run tui from there. This saves you the trouble of individually installing extra packages to each machine's existing installation of tcl/tk and python. It also gives you the chance of running current versions of tcl/tk and python (preinstalled versions tend to be quite out of date). This is not very difficult; the installers for tcl/tk and python are both trivial to use and include excellent documentation.

Requirements:

  • Python 2.7, with Tkinter support. Note: TUI is not compatible with Python 3.x (which is intentionally not backward compatible with Python 2.x).
  • tcl/tk 8.4 or later. 8.5 will probably work (requires Python 2.6 or later) but as of 2010-07-21 I had not tested it.
  • The following python packages:
    • numpy
    • Pillow or the older Python Image Library (PIL)
    • matplotlib
    • astropy (you can still use pyfits, instead, but this is deprecated and will stop working at some point).
    • pygame.mixer (optional but highly recommended because it is used to play sound cues)
    • RO (which can be installed via pip or managed via eups)
  • The following are optional, but highly recommended. Both are needed if you want to automatically display science images (via the View Image preference) and are also handy for taking a detailed look at guider images (via the DS9 button on guider windows).
    • SAOImage ds9, an image viewer
    • xpa, a communication interface for ds9 (available at the ds9 site)

Installation instructions:

If you are in doubt as to which python packages you already have installed, try the following test. If any step fails, the corresponding package is not installed (or is mis-installed): 

% python
        Python ???   # must be at least 2.4; the current 2.x release is recommended
        ...
        >>> import Tkinter
        >>> root = Tkinter.Tk()
        >>> import numpy
        >>> import astropy # or pyfits
        >>> import Image
        >>> import pygame.mixer
        >>> pygame.mixer.init()
  • If you don't already have them, download and install an X11 window server (such as xfree86), the associated libraries, and a window manager. Almost all unix installations already have the X11 window server and window manager, but some unix installations do not come with the X11 libraries.
  • Set environment variables. You can set them now while installing and then again in the tui shell script. Or, if you prefer, you can set configure the login process to set them automtically. (The former is usually easier for shared installations.)
    • If any of your libraries are installed in a nonstandard location then set LD_LIBRARY_PATH to include those locations. The usual default (at least on linux) is /usr/local/lib. Relevant libraries include those for tcl/tk.
    • If any of your binaries are installed in nonstandard locations, then set PATH to include those locations. The usual default (at least on linux) is /usr/local/bin. Relevant binaries include those for python.
  • Pick a directory for the source code (any convenient directory you own). Unpack all source code packages in that directory and leave them there until all installation is done (this may make it easier for some of the packages to find necessary files in other packages).
  • Install tcl/tk.
    • Any Tcl/Tk 8.3.x or 8.4.x ought to work, but the current release is recommended.
    • Build and install tcl first, then tk, as per the README files.
    • Generally the installers are smart and trouble free. However, you may get warnings of multiple versions of tcl headers or libraries when you install Tk. You can ignore these so long as they complain of files from the tcl source distribution matching the tcl you just installed.
  • Install Python, if necessary.
  • Version 2.5 or later is required. Most testing of STUI is done on version 2.7.x.
  • Usually it will just build, but always check the README first. In particular, if you are building on RedHat 9 and if you are using RedHat's built in Tcl/Tk, you will need to specify a special flag.
  • Test your new Python and Tkinter:
            % python
        Python ???  # is this the new version you just installed? If not, did you specify environment variable PATH correction?
        >>>import Tkinter  # if this and the next step both work then Tkinter is properly installed
        >>>root = Tkinter.Tk()  # you should see a new empty window
    If there is a problem, try again from a new terminal session or after logging out and back in again. If it still doesn't work, debug the installation:
    • If "_tkinter" cannot be loaded, then python was not built with tcl/tk support. If this is a pre-built python, you probably have to build your own (though you may be able to find instructions for adding _tkinter to your particular python). If this is a python you just built, make sure you really are running that version (and not a built-in version) and review the instructions above and Python's installation instructions.
    • If you see "error while loading shared libraries: libtk8.4.so", then perhaps LD_LIBRARY_PATH is not defined or is mis-defined.
    • An excellent fallback (if you didn't already do this) is to install tcl/tk and python from source (as described above).
  • Install numpy.
  • Install astropy (you can still use pyfits, instead, but this is deprecated).
  • Install Pillow or the older Python Imaging Library (PIL). Build it with support for Tkinter, jpeglib and zlib support (zlib may be unnecessary but leave it out at your own risk).
  • Install matplotlib.
  • Install pygame, making sure to build pygame.mixer. This is optional but strongly recommended; it is used to play sound cues. Note that pygame requires SDL (library and header files) and pygame.mixer requires SDL_Mixer.
  • Install ds9 and xpa. These are optional but strongly recommended; they are used to display sicence images.
  • Download TUI Source and unpack in some convenient directory.
  • Create a shell script named "tui" on your normal binary path (e.g. /usr/local/bin), as follows:
            #!/bin/bash
        python path_to_runtui/runtui.py # the path depends on where you unpacked TUI
    • The first line may have to be adapted to your environment.
    • If you have more than one version of python installed on your system, please replace python with the full path to the correct version (such as /usr/local/bin/python).
    • Make sure the file is executable (e.g. chmod +x tui).
    • If you need to expand LD_LIBRARY_PATH, now is the time to do it.
    • You may wish to unset PTYHONPATH for enhanced robustness (unless you need PYTHONPATH).
    • You may need to set LD_LIBRARY_PATH
  • You may wish to create additional shell scripts to run the previous release and/or the beta version of TUI. To avoid editing these scripts as new versions come out, choose a standard name for the top level of each TUI distribution, such as "tui" for the current release, "tuiold" for the previous release and "tuibeta" for the current beta, if any.
  • Make sure environment variable NUMERIX is either not being set or is being set to "numpy".
  • If you use tcsh then you probably have to type "rehash" before "tui" will work.
  • Test the basics:
    • Type "tui". It should launch.
    • Test image display:
      • Open the NA2 guider window: Guide&NA2 Guider.
      • Click the Choose... button (near the upper right).
      • Select a FITS image.
      • It should be displayed. If not, your Pillow or PIL installation is probably incomplete.
    • Check that sound cues play:
      • Open Preferences.
      • Open the Sounds preferences panel.
      • Click the Play button for several sounds. If you just hear beeps then pygame is not properly installed.

Installing on Windows

Notes:

  • If you get a complaint about MFC71.DLL missing, get a copy from here and install in your system directory; on American systems this defaults to: C:\Windows\System32 for Windows XP; C:\WINNT\System32 for Windows NT or 2000; C:\Windows\System for Windows 95, 98 and Me.
  • If you need software to unpack zip files, one simple option is JustZipIt (simple, free, zips and unzips). A fancier solution is WinZip.
  • Download and install ds9 and xpa (these are optional but highly recommended). Install them in the standard default location suggested by the installers (e.g. C:\\Program Files\ds9\ and C:\\Program Files\xpa\).

    You may install xpa's executables in the same directory as ds9.exe if you prefer, i.e. tell the installer to use ...\xpa\ instead of ...\ds9\. This will allow you to command ds9 via xpa from the command line. Another way to accomplish the same thing is to add xpa's directory to the system PATH.

  • Download and install TUI for Windows: TUI_vers_Windows.zip:
    • Unzip the download.
    • Put the resulting folder in a convenient location (C:\Program Files\ is traditional on American systems).
    • Look inside the unpacked directory. You should see a file TUI.exe (or just TUI if you have extensions hidden); double-click that file to run TUI.
    • To make TUI easier to run, put a shortcut to TUI.exe on the desktop or somewhere similarly convenient.
  • To uninstall TUI simply discard the folder you unpacked.

Building From Source for Windows X

If you prefer, you may install TUI from source and even build your own double-clickable version. See Building TUI from Source On Windows for details.

Git Repository

TUI is kept in a git repository at github. Feel free to clone that if you want to work on the code.

History

  • 2014-09-16 astropy is now supported, and preferred to pyfits.
  • 2014-09-05 Added a link to the git repository.
  • 2014-06-17 Enhanced testing instructions. Simplified tuiscript instructions. Insist on Python 2.7.
  • 2011-08-19 Updated instructions for Python older than 2.6: install simplejson, not json.
  • 2011-08-17 Noted the need for json in Python versions older than 2.6. Cleaned up a few things.
  • 2010-10-07 Updated and simplified the Mac installation instructions.
  • 2009-10-22 Modified for snack -> pygame.
  • 2009-06-29 Added a reference to Building TUI from Source On Windows.
  • 2007-07-09 Added a note about the NUMERIX environment variable.
  • 2007-04-24 Modified to remove references to numarray and Numeric.
  • 2006-12-28 Added instructions to install numpy and matplotlib.
  • 2006-08-10 Updated the links to Numeric.
  • 2006-06-19 Removed erroneous statement that the Mac version is not compatible with intel-based Macs.
  • 2006-03-09 Updated Windows instructions for new name of executable.
  • 2006-02-28 Noted that the Mac version is not compatible with intel-based Macs.
  • 2005-10-12 Windows: xpa can now be installed in the default directory. Mac: the standard Mac installation of ds9 is all you need (though the darwin version works fine).
  • 2005-10-05 Improved Windows installation, including: better recommendation for unzip software, added a note about MFC71.DLL, added detailed instructions for installing snack.
  • 2005-09-30 Fixed the installation instructions for ds9 and xpa on MacOS X and Windows.
  • 2005-09-23 Increased the urgency of ds9 and xpa. Noted that a Windows installer is in the works.
  • 2005-06-22 Added ds9 and xpa to the optional packages.
  • 2005-03-15 Added numarray and PIL to the required packages. Expanded the unix installation instructions to discuss environment variables LD_LIBRARY_PATH and TCLLIBPATH.
  • 2004-10-06 Corrected the windows installation instructions.
  • 2004-09-03 Added Windows installation instructions based on information kindly supplied by Jack Dembicky. Improved the MacOS X installation instructions.
  • 2004-03-03 Modified unix notes for the new, simpler way to run TUI. Updated the Mac X11 notes because an X11 installer is now available for MacOS X 10.3 and is no longer available for 10.2.
  • 2004-02-05 Modified Notes for MacOS X to include one additional common Aqua Tk bug (menus showing up in the wrong place) and removed the note about incorporating TUI additions (since that is done in a more standard fashion in TUI 0.83).
  • 2004-01-23 Modified to the MacOS X binary. Added a link to the TUI downloads (thanks for the reminder, Nicole Silvestri).
  • 2003-12-23 Modified the unix info to suggest an executable script tui instead of environment mods. Updates the Mac info for Panther (MacOS X 10.3).
  • 2003-11-17 Added snack installation.
  • 2003-08-28 Added a note about the need for X11 on unix and corrected a test (root = Tk() -> root = Tkinter.Tk()). Thanks to Bill Ketzeback. Overhauled the MacOS X installation instructions.