How to install Odemis


= Installing the dependencies =

You need Ubuntu 16.04 (x86 - 32/64 bits).
The dependencies can be found in the file debian/control. Basically, they can be
installed with:
sudo apt-get install python-pil python-yaml python-serial python-zmq \
python-concurrent.futures python-scipy python-decorator cgroup-bin \
python-libtiff python-comedilib python-h5py libtiff5-dev python-future \
python-pkg-resources python-netifaces python-cairo python-numpy python-scipy \
python-decorator python-xdg python-suds python-matplotlib python-opencv \
python-wxgtk4.0 python-serial python-evdev python-notify2 python-psutil \
graphicsmagick cgroup-bin python2-pyro4 authbind python-setuptools cython

Some of these packages need newer version than what is available in the default
Ubuntu repository. They can be found on Delmic's PPA, or it's possible to
install them from source.

To install the PPA:
sudo add-apt-repository ppa:delmic-soft/odemis

Otherwise, follow the instructions below.

== wxPython ==

The wxPython versions 3.0 and 4.0 are supported. However, version 4.0 compiled
with GTK3 is known to have some small aspects issues, so GTK2 is prefered.

= Installing Comedi =

Used to access the DAQ board to connect to the SEM. It's also used on some simulators,
with the comedi_test driver. You need to calibrate the DAQ board (about once per year).

For the NI PCI 6251:
sudo comedi_soft_calibrate -f /dev/comedi0

For some other boards, which are calibrated in hardware, you need to do:
sudo comedi_calibrate -f /dev/comedi0


To load the comedi simulator driver, you can type the following (once, after every boot):
sudo modprobe comedi comedi_num_legacy_minors=4
sudo modprobe comedi_test
sudo comedi_config /dev/comedi0 comedi_test 1000000,1000000
sudo comedi_config /dev/comedi1 comedi_test 100000,100000

In order for this change to be applied at every reboot, add the following lines to /etc/rc.local (before the "exit 0" line):
sudo gedit /etc/rc.local

modprobe comedi comedi_num_legacy_minors=4
modprobe comedi_test
comedi_config /dev/comedi0 comedi_test 1000000,1000000
comedi_config /dev/comedi1 comedi_test 100000,100000


= Installing Odemis =

Download the source code:
cd ~/development
git clone git://github.com/delmic/Pyro4.git
git clone git://github.com/delmic/odemis.git

Create a "odemis" group and add all the necessary users to it:
sudo addgroup odemis
sudo adduser $(whoami) odemis

(You need to log out to get the user in the new group)

On Linux, install the files this way:
cd odemis
python ./setup.py build
sudo ./setup.py install --root=/ --install-scripts=/usr/local/bin/ --install-data=/usr/ --single-version-externally-managed

To get the fluorophores database (for the SECOM/DELPHI), you can run this command:
./util/getfluodb.py
Then copy all the fluodb directory to /usr/share/odemis/fluodb/

= Installing the vendor device drivers =
Several hardware require a dedicated driver (provided by the hardware manufacturer).
to be installed. That's the case in particular of the Andor cameras and spectrographs (libandor.so.2 and libatcore.so.3).
The IDS uEye cameras (libueye_api.so.1) and the PicoQuant time-correlator (libph300.so) also need a driver.

Please refer to the manufacturer documentation on how to install these drivers.


= Configuring the microscope file =
The "microscope" file describes the available hardware for Odemis. Basically, it lists for each
hardware, which driver to use and the parameters required. It's following the
YAML format (similar to JSON). See the back-end specification in the developer
manual (in doc/develop) for precise syntax and, the example files in install/linux/usr/share/odemis .

To get inspired when starting a new file, you can use "odemis-cli --scan" to
detect some of the hardware connected.

If you're using an SEM and another detector, it is recommended to first
configure the X/Y axes of the SEM to orient the image identically to the vendor
software, and then adjust the orientation of the other detectors.


= Auto start =
To avoid entering the password when starting and stopping the backend, sudo is used.
To allow users to completely avoid typing a password, you can copy the sudoers file:
sudo install -m 0440 install/linux/etc/sudoers.d/odemis /etc/sudoers.d/odemis