XmCCD
-----

The programs provided here offer a Linux graphical user interface to
astronomical and scientific CCD cameras.  XmCCD was developed initially for 
SBIG (now Diffraction Limited) cameras and it still focuses on maintaining
accessibility to SBIG cameras for Linux operating systems.  However with canges
in sensor technology we are limited to supporting cameras for which we have
hardware, and for which Diffraction Limited releases either a library or an API.
We added support for Apogee USB cameras based on Dave Mills opensource library,
and that is maintained here for legacy cameras that were included in his work. 
Currently we are adding support for ASI/ZWO cameras based on their SDK,
primarily to integrate their cameras into the XPA protocol.

Operating systems
=================

The current release is tested with OpenSUSE's rolling Tumbleweed release.  It
should compile with any recent Linux distribution once the development libraries
are installed.  Since the programs are dependent on libraries and software
development kits provided by the manufacturers (notably for SBIG and ZWO),
support for non-Intel CPU hardware may be problematic, and use on the latest OSX
is unlikely to work out of the box. XmCCD will not run in Windows because of its
dependency on the Unix features of XPA.  It will run well in a virtual machine
running under Virtualbox, a concept that enables mixing Windows and Linux code
on either operating system.  It is untested in the Windows Subsystem for Linux
(WSL) at this time.


SBIG
====

SBIG has kindly provided the library used here.  It is the latest one they
offerred that supports the earlier cameras that we have. Please note
that these  SBIG library materials are subject to their copyright.

In 2020/2021 SBIG introduced newer cameras, many based on CMOS technology,  that
are not supported by this library, but many legacy CCD cameras are supported and
will be used for science for years to come. XmCCD has been tested with cameras
that have used or are using now. It should be suitable for USB-interfaced
ST7/8/9/10, STX, STXL, or STL camera manufactured before 2020. 

Diffraction Limited offers a Linux library for its new Aluma series which we
expect would adapt to this framework. However we do not have a camera for
software development at this time. Should we add new SBIG hardware will also
provide Linux support in this framework if libraries are available.



Apogee
======

Apogee was purchased by Andor which was then acquired by Oxford Instruments. 
The entire entire product line was discontinued in 2020 following the end of
production of Kodak "Truesense" CCDs.     Therefore the
support provided here is USB Alta and Aspen cameras that
were manufactured before 2019.  It is dependent on the open source code
developed by Dave Mills, The Random Factory,  http://www.randomfactory.com . 
Please see the directory libapogeedrv for notes on the changes needed to the
source distribution in order to use it with XmCCD. 


ASI/ZWO
=======

As of Version 7.0 RC1 XmCCD includes support for ASI/ZWO cameras through their
library and software development kit. It is intended for operation of monochrome
cameras in gain 0, that is, the full 16-bits of dynamic range.  Other features
may be added in the future.  It has been tested with the ASI16200MM and ASI174 
cameras.

We may add support for ASI filterwheel and focuser control which is integrated
in the SDK but not implemented.  The ST4 guider controls are implemented but 
untested.  Please consider this support in beta stage. Changes may come in the
final release of XmCCD Version 7.0.

For color and video we recommend running ASI's own image capture code.



Other cameras and interfaces
============================

It is our intent to provide at least basic support (that may be customized by
the users) for Fingerlakes Instruments.

The ASI/ZWO library (see libasi and drvasi) provides a model on how to add
support for a camera of your own that we cannot test.  Typically there is a
simple software layer between the manufacturer's library and its APIs, and the
requirements of the various programs within XmCCD.  This is met by a protocol
code for which there are examples here designed for ASI, Apogee, and SBIG.  A
possible complication has been that libraries are often written in C++, while
XmCCD is written in C.  This requires a wrapper around the C++ so that its
functions are recognized by the C compiler.  The ASI library and wrapper provide
the most recent example.   If you have a recent camera from QHY, Fingerlakes, or
SBIG then you could add support to XmCCD given the manufacturer's librarie by
following these templates.


Scripting and other software
============================

With XPA, it is possible to script XmCCD and XmTel along with other
instrumentation and to link those to other server-client code.  For example, the
XPA interface may be used within cgi-bin routines in a web-based interface to
supported cameras. Information is available on request. 


The most recent version of XmCCD may be downloaded from 
http://www.astro.louisville.edu/software and you are encouraged to check 
there for the latest release, sources for other software needed to compile 
and run XmCCD, and supporting utilities.

  
License and use
===============

Please see the files  LICENSE and COPYRIGHT for more information. XmCCD is
opernsource code, but it does use other libraries.  Please respect the copyright
and constraints of those contributions.  



Building and installing
=======================

SBIG, ASI, and APOGEE describe how to build and install XmCCD. It does require
other programs to compile and run, some of which are not usually present in
Linux distributions.  Before building and running XmCCD, you will need to
install the following if they are not already on your system:

Motif development libraries and headers
fxload

Motif development libraries and the firmware loader fxload are not installed  by
default in OpenSuse,  but are available from software repositories. 

The XmCCD source package includes source code for:

xpa
cfitsio

which you should install and compile first if it is not already on your system.
The source code for each of these libraries is in a separate named directory in
the package that includes installation instructions if needed.

SAOimage ds9 is the primary image display for XmCCD. A binary that works in
a recent Opensuse release is included.  Other binaries and source code are
available on github from the ds9 developers.


The software is designed to work in parallel with AstroImageJ (AIJ) for data
processing.  Typically we use ds9 to monitor the image acquisition, and AIJ
to process photometric data in real time.  Imaging data for other uses may be
processed using our Alsvid package or your own custom routines built with Python
and Astropy. 
 
XPA is a communication protocol used by ds9. It enables xmccd to notify the
display when a new image is available, and to accept coordinates from ds9 
to select regions of interest.  XPA should be installed system-wide with
the source code included here. Earlier versions will work if the library and
include files are in /usr/local/lib/ and /usr/local/include/.

The cfitsio library package provides standard FITS library support for 
the image file format in xmccd. A recent version is included in the XmCCD
source code, and should be used if possible. Earlier versions should work as
well.  If you use a different version, the fits library and header files are
expected in /usr/local/lib and /usr/local/include/.  

  
Links to sources for AstroImagej, AstroCC, and Alsvid are  on the web site 

                         www.astro.louisville.edu/software
                         



John Kielkopf
2021 February 11




