Merge branch 'master' into deepsim-ximea

Author: carandraug

INSTALL

@@ -0,0 +1,91 @@
+Microscope is available on the Python Package Index (PyPI) and can be
+`installed like any other Python package
+<https://packaging.python.org/tutorials/installing-packages/>`_.  The
+short version of it is use pip::
+
+  pip install microscope
+
+Note that you need to have Python and pip already installed on your
+system.
+
+
+Requirements
+============
+
+Microscope can run in any operating system with Python installed but
+individual devices and intended usage may add specific requirements:
+
+- **hardware performance**: control of devices at high speed, namely
+  image acquisition at very high rates, may require a fast connection
+  to the camera, high amount of memory, or a disk with fast write
+  speeds.  In such case, it may be advantageous to have a dedicated
+  machine for the camera.
+
+- **external libraries**: control of many devices is performed via
+  vendor provided external libraries which are often limited to
+  specific operating systems.  For example, Alpao does not provide a
+  library for Linux systems so control of Alpao deformable mirrors is
+  limited to Windows.  See the :ref:`Dependencies
+  <install-dependencies>` sections below.
+
+If there are multiple devices with high resources or incompatible
+requirements they can be distributed over multiple computers.  For
+example, two cameras acquiring images at a high frame rate or a camera
+that requires Windows paired with a deformable mirror that requires
+Linux.  See the :ref:`Examples <examples>` section.
+
+
+.. _install-dependencies:
+
+Dependencies
+============
+
+Microscope has very few dependencies.  All are Python packages
+available on PyPI and will be automatically resolved if Microscope is
+installed with pip.  However, the interface to many devices is done
+via an external library (or SDK, or driver) that is only provided by
+the device vendor.
+
+To identify if an external library is required, check the associated
+module documentation.  If an external library is required, contact the
+device vendor for install instructions.  Cameras, deformable mirrors,
+and spatial light modulators all require an external library.  Filter
+wheels, lasers, and stages typically do not but there are exceptions.
+
+
+Development sources
+===================
+
+Microscope development sources are available on github.  To install
+the current development version of Microscope::
+
+  git clone https://github.com/MicronOxford/microscope.git pip
+  pip install --no-index microscope/
+
+Also consider using editable mode if you plan to make changes to the
+project::
+
+  pip install --no-index --editable microscope/
+
+Multiple Microscope versions
+----------------------------
+
+Python package system will not by default handle multiple versions of
+a package.  If installing from development, beware to not overwrite a
+previous installation.  A typical approach to address this issue is to
+use `virtual environments
+<https://packaging.python.org/tutorials/installing-packages/#creating-and-using-virtual-environments>`_.
+
+Un-merged features
+------------------
+
+Many features are still in development and have not been merged in the
+master branch.  To try such features, you will need to know the branch
+name and the repository where such feature is being developed.  For
+example, to try Toshiki Kubo's implementation of the Mirao52e
+deformable mirror::
+
+  git remote add toshiki https://github.com/toshikikubo/microscope.git
+  git fetch toshiki
+  git checkout toshiki/mirao52e
+  pip install --no-index ./

NEWS

@@ -1,31 +1,130 @@
 The following is a summary of the user-visible changes for each of
 python-microscope releases.
 
-Version 0.3.0 (yyyy/mm/dd)
+Version 0.4.0 (upcoming)
+------------------------
+
+* Selected most important, backwards incompatible, changes:
+
+  * The `Setting` class is now private.  The only supported method to
+    add settings to a `Device` is via its `add_setting` method.
+
+* New devices supported:
+
+  * Coherent Obis laser
+  * Lumencor Spectra III light engine
+  * Prior ProScan III controller
+  * Prior filter wheels
+  * Toptica iBeam laser
+
+* Changes to device ABCs:
+
+  * Device:
+
+    * The `Device._logger` attribute has been removed.  It is
+      recommended to use a logger for the module.
+
+  * DeformableMirror:
+
+    * Concrete classes must implement the `n_actuators` public
+      property instead of the private _n_actuators`.
+
+* The device server and clients no longer force pickle protocol
+  version 2.  If the client and server are running different Python
+  versions it may be necessary to specify a version number.  This
+  should be done on the side with the highest support version number
+  by setting `Pyro4.config.PICKLE_PROTOCOL_VERSION`.
+
+
+Version 0.3.0 (2019/11/07)
 --------------------------
 
-* Backwards incompatible changes:
+* Selected most important, backwards incompatible, changes:
 
-  * `microscope.device()`, function used create a device definition,
+  * `microscope.device`, function used to create a device definition,
     changed signature.  The arguments to the device constructor must
-    now be passed as a dict.
+    now be passed as a dictionary.
+
+  * Python 2 is no longer supported.
+
+  * New requirements:
+
+    * Python >= 3.5
+    * hidapi
+
+* New devices supported:
+
+  * Andor (EM)CCD cameras (requires Andor's atmcd C library)
+  * Aurox Clarity (requires hidapi Python package)
+  * Imagine Optic Mirao 52-e deformable mirror (requires mirao52e C library)
+  * Linkam Correlative Microscopy Stage (requires LinkamSDK C library)
+  * Ximea cameras (requires Ximea's xiAPI Python package)
+
+* Changes to device ABCs:
+
+  * New ABC `ControllerDevice` for controller devices.
+
+  * Laser devices:
+
+    * New abstract methods:
+
+      * `LaserDevice.get_min_power_mw`
+      * `LaserDevice.is_alive`
+
+    * `LaserDevice.set_power_mw` now clips the set value to the device
+      actual range.  Previously, the behaviour was undefined and
+      device specific.
+
+  * Camera devices:
+
+    * Added ROIs and binning support.
+
+    * New abstract methods:
+
+      * `CameraDevice._get_binning`
+      * `CameraDevice._get_roi`
+      * `CameraDevice._set_binning`
+      * `CameraDevice._set_roi`
+
+  * DataDevices:
+
+    * Data clients are now on a stack to facilitate temporary
+      redirection of data to some other client.
+
+  * Filterwheel devices:
+
+    * New method `FilterWheelBase.get_num_positions`
+
+    * New abstract methods:
+
+      * `FilterWheelBase.get_position`
+      * `FilterWheelBase.set_position`
+
+* Device specific changes:
+
+  * Omicron TA Deepstar laser:
+
+    * Now returns actual laser power instead of the set laser power.
+      Requires device to be fitted with the APC option.
 
-* Python 3.5 or later is now required.  Python 2 is no longer
-  supported.  This drops the dependency on the six and enum34.
+  * Test camera:
 
-* `CoboltLaser` now has a default value for its `baud` argument.
+    * Added new setting to control created image.  In addition of
+      noise, can also return stripes, spots, or gradients.  See
+      `microscope.testsuite.devices.ImageGenerator`.
 
-* `LaserDevice.set_power_mw` now clips the set value to the device
-  actual range.  Previously, the behaviour was undefined.
+* Removed requirements:
 
-* Added Device server support for Windows services.
+  * enum34
+  * six
 
-* DataDevices now handle a stack of clients to receive data.
+* The `deviceserver` program can now be used as a Windows service.
 
-* New abstract methods:
+* Fixed PyPI releases to include the `microscope.mirrorq and
+  `microscope.filterwheels` subpackages.
 
-  * `LaserDevice.get_min_power_mw`
-  * `LaserDevice.is_alive`
+* New `microscope.devices.ROI` and `microscope.devices.Binning`
+  classes to represent those camera settings.
 
 
 Version 0.2.0 (2018/06/13)

doc/conf.py

@@ -8,6 +8,7 @@
 ## notice and this notice are preserved.  This file is offered as-is,
 ## without any warranty.
 
+import datetime
 import sys
 
 sys.path.insert(0, '../microscope')
@@ -17,10 +18,11 @@
 ## pkg_resources to avoid duplication?
 author = 'Micron Oxford'
 project = 'Microscope'
-copyright = '2017, Micron Oxford'
 
+copyright = '%s, %s' %(datetime.datetime.now().year, author)
 
 master_doc = 'index'
+nitpicky = True
 
 
 extensions = [
@@ -47,3 +49,9 @@
 
 html_theme = 'agogo'
 html_static_path = ['_static']
+html_title = 'Python Microscope documentation'
+html_short_title = 'import microscope'
+html_show_copyright = False
+html_show_sphinx = False
+html_copy_source = False
+html_show_sourcelink = False

doc/contributors.rst

@@ -15,5 +15,7 @@ Microscope:
 
 - Amy Howard
 - David Miguel Susano Pinto
+- Ian Dobbie
+- Julio Mateos-Langerak
 - Mick Phillips
 - Tiago Susano Pinto

doc/design.rst

@@ -1,4 +1,4 @@
-.. Copyright (C) 2017 David Pinto <david.pinto@bioch.ox.ac.uk>
+.. Copyright (C) 2019 David Pinto <david.pinto@bioch.ox.ac.uk>
 
    Permission is granted to copy, distribute and/or modify this
    document under the terms of the GNU Free Documentation License,
@@ -13,12 +13,16 @@ Design
 Problem
 =======
 
-Bespoke microscopes are built in research labs by physicists and
-biologists that are often not interested in programming.  However,
-such microscopes are complex systems that rely on the tight
-integration between many components and can only be controlled by
-custom software.  The end result is in-house software that is both
-limited in scope and unusable in other projects.
+Research laboratories are constantly developing new microscopes that
+are are complex systems that rely on the tight integration between
+many components.  Instead of focusing on the microscopy, these teams
+spend substantial time and effort in software development to control
+their new microscopes.  Such software is limited to the specific
+microscope setup and components and becomes unshareable, difficult to
+maintain, or incur ongoing licensing costs.  A huge amount of time,
+effort, and resources is wasted as scientists in different labs, and
+even in the same lab, repeatably implement solutions to the same
+problems.
 
 
 Project aims
@@ -43,16 +47,34 @@ Project aims
 Choices
 =======
 
-µManager
---------
+Why not using µManager
+----------------------
 
-Why we didn't choose µManager...
+`µManager <https://micro-manager.org/>`_ is an existing open source
+software for the control of microscopes.  It is written in Java and
+based on top of ImageJ, an open source image analysis program.
+However, µManager design has issues when controlling more complex
+microscopes where devices are spread over multiple computers, with
+multiple cameras, and devices are synchronised with TTL signals.  In
+addition, while Java makes it easier to access ImageJ it makes more
+difficult to use the whole of numpy and scipy.
 
 Python
 ------
 
-Python is extensively used for scientific computing, and is the most
-likely language the projects users will be familiar with.
+Python has multiple features:
+
+#. it is widely used in the scientific community.  This increases the
+   odds that users of Microscope will be capable to participate in its
+   development.
+
+#. unlike other widespread languages in the scientific community, it
+   is a general purpose programming language and not mainly for
+   numerical or symbolic computation.
+
+#. while Python is not firstly a language for numerical computations,
+   numpy and scipy are the basis for this.  Most algorithms for image
+   analysis are available in Python.
 
 
 Use cases
@@ -116,3 +138,13 @@ State machine
 Devices do not report back their state which prevents from modelling
 Microscope as a state machine.  For example, users will change
 objectives or move the stage.
+
+History
+=======
+
+Development of Python Microscope started at `Oxford Micron Bioimaging
+Unit <https://www.micron.ox.ac.uk>`_ to provide remote control of
+microscope devices independent of hardware specifics.  Locally,
+development was guided to support development of a new version of
+`cockpit <https://www.micron.ox.ac.uk/software/cockpit/>`_, a
+graphical user interface for the control of microscopes.