Installation Instructions for XmCCD with the SBIG Library
=========================================================

This is a recipe for installing XmCCD and auxiliary software especially for
those who may not have experience with Linux system management.  If you try
this and find I have left out something, please let me know and I will 
include it in the next version.

This version of xmccd only supports the USB and 2.6 series kernels with udev
support.  It has been tested on Suse 10.0 and 10.1, and it should also
work on other recent Linux distributions.  However, kernels earlier than
about 2.6.13 may not have a fully functional udev subsystem and may
not work well with the SBIG library.  

For LPT camera support, you may use an earlier version of xmccd on a Linux 
distribution such as Slackware that runs a 2.4 series kernel with hotplug 
support. 
  

I.  Resources
-------------

First, you will need the software sources.  It is best to compile xmccd from the
source to be sure that it will work with your system.

1.  XmCCD

Our website

http://www.astro.louisville.edu/moore/software  

provides two files:

xmccd-#.#.#.tar.gz
xmccd_support_source.tar


As root or superuser, copy both of these to /usr/local/src.  Untar xmccd with
the command

tar xvzf xmccd-#.#.#.tar.gz

where "#" here will be a version number.  Also untar the support source 

tar xvf xmccd_support_source.tar

to leave several more source packages in /usr/local/src.   We will take each
of these in order.  You may not need them all if they are already installed on
your system.


2.  LessTif or Motif 

Look for library files such as libXm.a, libXm.la, and
libXm.so which are usually in /usr/X11R6/lib. You might also simply
try to compile xmccd (see below) before you proceed to install Motif, and if
there is an error message that a library is missing, that is a good indication
that you need to install either LessTif or Motif. 

The support source package includes the most recent opensource version of 
Motif that is known to work with xmccd.  If you download another version, try to
identify one that is stable and well tested from

http://www.motifzone.net

or the Gnu-licensed version of LessTif at 

http://www.lesstif.org/

and follow their installation instructions. 

If you use the source we supply then 

cd /usr/local/src/openMotif-2.2.3
./configure
make
make install
ldconfig

This will put the Motif libraries and headers in the standard location
/usr/X11R6


3.  SBIG Library

There will be a version of these in the xmccd package in its sbig 
subdirectory.  You should use the included version.  The sbig directory
in the XmCCD distribution also will include scripts for installing the usb
drivers.  Follow the directions given there.  


4. cfitsio

The FITS file library known as "cfitsio" is required to compile xmccd since we
use fits files exclusively for storing images.  The source is in the support
files package, and it is also linked from our website. As root user

cd /usr/local/src
tar xvf cfitsio_2.510.tar
cd cfitsio/cfitsio
make
cp libcfitsio.a /usr/local/lib
ldconfig


5.  ds9 and xpa

This is the powerful image display software from the Harvard-Smithsonian Center
for Astrophysics . XmCCD uses it to display the images and to provide image
analysis and file handling. 

While you may compile ds9 from source, I recommend that you use the distributed
binary because as of Septebmer 2007 it will not compile with the version of gcc
used in Suse 10.2 and other  recent Linux distributions.  On the other hand, 
xpa compiles flawlessly and if you build it from source.

The binary for ds9 and the source for xpa are availabe from available from

http://hea-www.harvard.edu/RD/ds9/

Install ds9 and the xpa binaries in /usr/local/bin.

              
6.  Cinepaint or GIMP

XmCCD produces images in the FITS (Flexible Image Transport System) file format.
The images are 16-bit unsigned integers, at their best when processed for 
display with a 32-bit image processing program such as Cinepaint.  GIMP, often 
included in Linux distributions, will work but it cannot handle the full
dynamic range of images acquired with SBIG CCD cameras. 

Cinepaint is a large, complex program and has some dependencies that make it
difficult to install, but it is worth the effort.  We may have a recent version
with notes on the XmCCD support page.


II.  Compile and install XmCCD 
------------------------------

Before proceeding make sure you have installed cfitsio and either 
Motif or Lesstif. The libraries must be recognized, so once more try the command
  
  ldconfig
  
if you have not done so recently.  


Set your current working directory to xmccd-#.#/xmccd   
  
  cd /usr/local/src/xmccd-2.0.4/xmccd

In this version you must change the filterwheel designation in the source code.
Check  in the lines at the top of the file xmccd.c that the filter type 
and filter labels match your camera if you are using filterwheel. We will make
this configuration easier soon.  The default is the filterwheel for STL-series
cameras with RGBLC filters installed in the order recommended by SBIG.
  
  make
  cp xmccd /usr/local/bin/
  

The XmCCD distribution includes fits file handling utilities that
for preliminary image processing.  These are in the fits
subdirectory.  From the xmccd-#.# directory 

  cd /usr/local/src/xmccd-2.0.4/fits
  make
  make install
  
The binaries that will be copied to /usr/local/bin provide for dark subtraction,
flat fielding, image arithemtic, spectra extraction parallel to rows or columns,
listing and modifying the image file header.


III. Test that the USB system recognizes the camera and uploads firmware
-----------------------------------------------------------------------

With the camera power off, plug the camera's usb cable into a usb port on your 
computer.  Apply power and after a brief delay the fan on the camera should
start and its indicator LED should come on.  If the fan and light are on, then
the camera is ready to use.


For a diagnositic as root user, you could try 

  lsusb

In response you might see something like this

Bus 5 Device 2: ID 046d:08c5 Logitech, Inc.
Bus 5 Device 1: ID 0000:0000
Bus 3 Device 1: ID 0000:0000
Bus 2 Device 4: ID 0d97:0101 Santa Barbara Instrument Group SBIG Astronomy Camer


The identification 0d97:0101 is the one for a camera after the firmware has been
uploaded.  If the upload was not successful, you will see an identification 
such as 0d97:0001, where the second hex number depends on the camera model.



IV. Take images
---------------

As a normal user, connect the camera and turn on its power.  After a brief
delay, the fan and "on" light should start.   If the fan is running, then 

  xmccd 

will connect to a usb camera and the program will spawn ds9 for image display.


Once an image is acquired and visible in ds9, you should save it with the
ds9 command menu "File -> Save Frame As Fits" to whatever name you prefer. Each 
subsequent exposure will overwrite previous image.fits and track.fits files.
XmCCD relies on the ds9 user interface to allow you to view and save images.
  
This version of XmCCD has been tested with ST-7, ST-9, ST-10, ST-2000, STL-6303, 
and STL-1001 cameras, the CFW-8, 10 and STL filter wheels, and the AO and AO-L
accessories.  


V.  Send your comments
----------------------

Please let me know how this is working for you and what features you would like
to see added. See the list in DEVELOPMENT of what we are planning for xmccd.


John Kielkopf (kielkopf@louisville.edu)
September 30, 2007








  
