This directory, http://mx.iit.edu/src/soleil/, contains source code, documentation, and binaries for controlling a software emulated area detector from MX. I do not know what kinds of computers that you have on hand at the moment, so I have compiled binaries for several different platforms. Since the "hardware" is a software emulation, the binaries should run equally well on all of the supplied platforms. Here is a list of the files in this directory and a description of what they are: READ_ME.txt This is the file you are currently reading. ad_manual.pdf MX area detector manual. It contains a user guide and a reference manual. area_detector_manual-1.4.0-1026a.tar.gz This is the LaTeX source used to generate the manual. The source code for the example programs can be found here as well. mx-1.4.0-1027a.tar.gz This is the source code for MX. mx_debian_sarge_1.4.0-1027a.tar.gz Binaries for the Debian 3.1 (sarge) Linux distribution. mx_fedora_core_5-1.4.0-1027a.tar.gz Binaries for the Fedora Core 5 Linux distribution. mx_macosx_10.3-1.4.0-1027a.tar.gz Binaries for MacOS X (powerpc). mx_solaris_10-1.4.0-1027a.tar.gz Binaries for Solaris 10 (sparc) mx_windows_xp_sp2-1.4.0-1027a.zip Binaries for Windows XP SP2 compiled with Visual Studio 2003. Here is a short description of how to get started: 1. Pick a location to unpack the binary archive appropriate for your computer. On Linux/Unix systems, the standard location is /opt/mx, while on Windows systems the standard location is c:\opt\mx. This is the type of location you would use for a production system. However, for testing, you can unpack the archive anywhere you want. MX does not require root or Administrator privilege to run, so both the server and the client can be run from a non-privileged account. For the purposes of this document, I will assume that you have unpacked the archive in a subdirectory of your home directory that is called 'mxtest'. I will refer to this directory by the name ~/mxtest from now on. 2. You will need to modify a few files to reflect the location in which you installed MX. The details are somewhat different depending on whether you are running on Linux/Unix systems or on Windows systems. For Linux/Unix systems: In the ~/mxtest/bin directory, I have included a shell script fragment called ~/mxtest/bin/setupmx. On a production system, this fragment would probably be incorporated into /etc/profile, /etc/bash.bashrc, or whatever startup file fits your location. If you are not using a Bourne shell derivative like Bash, then you will need to modify the instructions accordingly. The only thing you have to change in ~/mxtest/bin/setupmx is the environment variable MXDIR, which must be set to the name of the directory that you have unpacked MX in. This should be the directory that has bin, etc, include, lib, log, run, sbin, and state as subdirectories. Once you have done this, you can all the environment variables needed by MX by merely sourcing the script like this: . ~/mxtest/bin/setupmx You also need to change the files in the ~/mxtest/etc directory. ~/mxtest/etc/motor.dat The configuration files here, as distributed, are configured to have the MX client on the same computer as the MX server. If the server is on a different computer than the client, then you must change the string 'localhost' in the first line of this file to either the IP address or the domain name of the computer that the server is running on. ~/mxtest/etc/mxserver.acl You must change this file to list all of the computers that are permitted to connect to the server. It is possible to use wildcards here. For example, if you want to let all machines on the 192.168.137 subnet connect to the server, you can put a single entry in the file like this 192.168.137.* rather than listing all of the files separately. ~/mxtest/etc/mxserver.dat This is the server's database file. You will probably not need to change this file. ~/mxtest/etc/mxuser.dat This file contains the name of the account that will be running the server. If you try to start the server from a different account, the server will not start. On production systems, we normally set up a special account called "mx" and have the system startup routines start the server under that account. For testing, this is not necessary. For Windows systems: On a Windows system, there are two files you need to change: ~/mxtest/bin/motor.bat ~/mxtest/sbin/mx.bat In both of these file, you must change the MXDIR and MXWDIR variables to match the directory that MX was unpacked in. 3. Now you must start the MX server that controls the simulated area detector. On Linux/Unix systems, this is done with the following command ~/mxtest/sbin/mx start This will start the server running in the background. The server will write log messages to the file ~/mxtest/log/mxserver.log. On Windows system, you must start the server batch file as follows ~/mxtest/sbin/mx On Windows, this will start the server running in the command window that you started it in. The server will take over this window until it is explicitly stopped. 4. At present, the only MX client included with the binaries is a command line program called 'motor'. At a later date, we will be providing a GUI for controlling the area detector, but this may not matter to you if you are planning to write your own GUI anyway. On Linux/Unix, if you have set up the environment variables with the ~/mxtest/bin/setupmx script, then all you should have to do is to type the command 'motor' in your terminal window. On Windows, currently you have to specify the full path to the motor.bat batch script as follows: ~/mxtest/bin/motor The command syntax for the part of motor that controls area detectors is described in Appendix A of the area detector manual mentioned above. To help you get started quickly, we show here an example session of controlling the area detector. In this session, Region of Interest 4 is configured to have the dimensions Xmin=1000, Xmax=2000, Ymin=250, and Ymax=750. Then the detector is told to take an exposure for 2.5 seconds, transfer the frame to the client computer, and then write the frame to the client's disk in PNM format. After doing this, the contents of ROI 4 are extracted and written to a different file in PNM format. Here is the example session: persephone:~$ persephone:~$ . ~/mxtest/bin/setupmx persephone:~$ persephone:~$ ~/mxtest/sbin/mx start Starting the MX servers. persephone:~$ persephone:~$ motor MX version 1.4.0 (October 27, 2006) Scan database '/home/lavender/scan.dat' is empty. motor> area ad set roi 4 1000 2000 250 750 motor> area ad get roi 4 Area detector 'ad' ROI 4: Xmin = 1000, Xmax = 2000, Ymin = 250, Ymax = 750 motor> motor> area ad snap 2.5 pnm snap1.pgm Starting a 2.5 second exposure for area detector 'ad'. Exposure complete. Now transferring the frame. Transfer complete. Now writing image file 'snap1.pgm'. Image file 'snap1.pgm' successfully written. motor> motor> area ad get roiframe 4 motor> area ad write roiframe pnm roi4.pgm motor> exit persephone:~$ persephone:~$ ~/mxtest/sbin/mx stop Stopping the MX servers. /home/lavender/mxtest/sbin/mx: line 148: kill: (6315) - No such process persephone:~$ The 'No such process' message should be ignored for now. PNM Image Format ---------------- At the moment we are using PNM image format for the files read and written by the area detector software, specifically 16-bit PGM files. This is being used temporarily since it is easy to implement and since there are a variety of display programs on Linux and Windows that will display them. On Linux, you can use the ImageMagick 'display' program to look at the files, while on Windows you can use the Irfanview program. The old 'xv' program on Linux really only supports 8-bit PGM files, but it almost works for 16-bit PGM files. For 16-bit PGM files, 'xv' displays 8-bit pixel values which are the 16-bit value modulo 256. We will provide a more full featured datafile format by the time of the final release of the software. We plan to use one of the already existing formats, with the leading contender currently being the SMV format as used by previous AVIEX detectors and by ADSC detectors. One final comment is that we have not yet implemented an emulation of the streak camera mode. We will do this, but it will come later. I hope that this is enough information for you to get started with the software emulated area detector packages. If you have any questions, do not hesitate to contact me. William Lavender