Commit 555f66d0 authored by Laurent Claustre's avatar Laurent Claustre
Browse files

Merge branch 'improve-plugin-doc' into 'master'

Revamping the documentation.

See merge request !98
parents 1cc656ba 6aabf77a
Pipeline #6520 passed with stages
in 14 minutes and 46 seconds
# LImA
Lima ( **L** ibrary for **Im** age **A** cquisition) is a project for the unified control of 2D detectors. The aim is to clearly separate hardware specific code from common software configuration and features, like setting standard acquisition parameters (exposure time, external trigger), file saving and image processing.
Lima is a C++ library which can be used with many different cameras. The library also comes with a [Python](http://python.org) binding and provides a [PyTango](http://pytango.readthedocs.io/en/stable/) device server for remote control.
## Documentation
The documentation is available [here](http://lima-doc.readthedocs.io/). Thank you to the people running Read the Docs for such an excellent service.
The source for the documentation is in the `docs` folder. Here are the instructions to built and read it locally. The documentation is built with [Doxygen](http://www.doxygen.org/) and [Sphinx](http://www.sphinx-doc.org). The sphinx template is from [ReadtheDocs](https://docs.readthedocs.io). [Breathe](https://breathe.readthedocs.io) provides a bridge between the Sphinx and Doxygen documentation systems.
pip install --user sphinx sphinx-autobuild sphinx_rtd_theme breathe recommonmark
apt-get doxygen
cd docs
doxygen common.dox
doxygen control.dox
doxygen hardware.dox
make html
The html documentation is generated in `docs/.build/html`.
......@@ -2,9 +2,15 @@ LIMA Release Notes
This is the release notes of LIMA, the library for image acquisition.
You can find information releated to new features and bug fixes. The notes are ordered by branch and release number.
You can find information related to new features and bug fixes. The notes are ordered by branch and release number.
The notes are prefixed with a category name for core, subsystems image/saving/processlib/..., camera names andor/andor3/basler..., windows, applications tango python/tango c++/spec and third-party submodules sps/processlib/...
Stable branch core-1.8
----------------------
Revamp the build system to use CMake, a cross-platform family of tools designed to build, test and package software.
Bug Fixes
Stable branch core-1.7
----------------------
......
......@@ -35,12 +35,10 @@ enum AlignDir {
};
LIMACORE_API std::ostream& operator <<(std::ostream& os, AlignDir align_dir);
/**@brief ImageType is the depth of detectors images
* - Bpp8 means 8 bits unsigned
* - Bpp8S means 8 bits signed....
*/
/// The depth of detectors images
enum ImageType {
Bpp8, Bpp8S, Bpp10, Bpp10S, Bpp12, Bpp12S, Bpp14, Bpp14S,
Bpp8, Bpp8S, Bpp10, Bpp10S, Bpp12, Bpp12S, Bpp14, Bpp14S,
Bpp16, Bpp16S, Bpp32, Bpp32S, Bpp32F, Bpp1, Bpp4, Bpp6, Bpp24, Bpp24S
};
......@@ -54,10 +52,17 @@ enum AcqMode {
LIMACORE_API std::ostream& operator <<(std::ostream& os, AcqMode acq_mode);
LIMACORE_API const char* convert_2_string(AcqMode mode);
LIMACORE_API void convert_from_string(const std::string&,AcqMode&);
/// Triggering mode
enum TrigMode {
IntTrig,IntTrigMult,
ExtTrigSingle, ExtTrigMult,
ExtGate, ExtStartStop, ExtTrigReadout,
IntTrig, //!< Internal software triggering
IntTrigMult, //!< Internal multiple software triggering (one prepareAcq, multiple startAcq)
ExtTrigSingle,
ExtTrigMult,
ExtGate, //!< External signal controls start and stop for each frame
ExtStartStop, //!< One external start signal to start acquisition of one frame and one external signal to stop it
ExtTrigReadout,
};
typedef std::vector<TrigMode> TrigModeList;
......@@ -80,15 +85,21 @@ typedef std::vector<ShutterMode> ShutterModeList;
LIMACORE_API std::ostream& operator <<(std::ostream& os, ShutterMode shutter_mode);
LIMACORE_API const char* convert_2_string(ShutterMode);
LIMACORE_API void convert_from_string(const std::string&,ShutterMode&);
/// The global acquisition status
enum AcqStatus {
AcqReady, AcqRunning, AcqFault, AcqConfig
AcqReady, //!< Acquisition is Ready
AcqRunning, //!< Acquisition is Running
AcqFault, //!< An error occured
AcqConfig //!< Configuring the camera
};
LIMACORE_API std::ostream& operator <<(std::ostream& os, AcqStatus acq_status);
/// Compound bit flags specifying the current detector status
enum DetStatus {
DetIdle = 0x00,
DetFault = 0x01,
DetFault = 0x01,
DetWaitForTrigger = 0x02,
DetShutterOpen = 0x04,
DetExposure = 0x08,
......
......@@ -32,6 +32,8 @@
namespace lima
{
/// Control image accumulation settings
class LIMACORE_API CtAccumulation
{
DEB_CLASS_NAMESPC(DebModControl,"Accumulation","Control");
......
......@@ -33,10 +33,11 @@
#include "lima/CtConfig.h"
#include "lima/Debug.h"
namespace lima
{
class LIMACORE_API CtAcquisition
namespace lima
{
/// This class control the acquisition of images given a hardware
/// interface.
class LIMACORE_API CtAcquisition
{
DEB_CLASS_NAMESPC(DebModControl,"Acquisition","Control");
friend class CtControl;
......
......@@ -46,6 +46,7 @@ namespace lima {
CtAccumulation* m_ct_accumulation;
};
/// Controls buffer settings such as number of buffers, binning and rotation
class LIMACORE_API CtBuffer
{
DEB_CLASS_NAMESPC(DebModControl,"Buffer","Control");
......
......@@ -33,7 +33,7 @@
#include "processlib/LinkTask.h"
namespace lima
namespace lima
{
class CtAcquisition;
......@@ -53,16 +53,8 @@ namespace lima
#endif
class SoftOpInternalMgr;
class SoftOpExternalMgr;
/** @brief Main client class.
*
* With this class you have access to all LImA advance feature:
* - Saving (CtSaving)
* - Image control (CtImage)
* - Acquisition control (CtAcquisition)
* - Accumulation (CtAccumulation)
* - Video (CtVideo)
* - Software operation (SoftOpExternalMgr)
*/
/// Main client class which should be instantiated by the users in their acquisition software.
class LIMACORE_API CtControl {
DEB_CLASS_NAMESPC(DebModControl,"Control","Control");
......@@ -95,9 +87,9 @@ namespace lima
};
class LIMACORE_API ImageStatusCallback
class LIMACORE_API ImageStatusCallback
{
DEB_CLASS_NAMESPC(DebModControl,"Control::ImageStatusCallback",
DEB_CLASS_NAMESPC(DebModControl,"Control::ImageStatusCallback",
"Control");
public:
enum RatePolicy {
......@@ -125,7 +117,7 @@ namespace lima
ProcessingOverun,
CameraError,
EventOther}; /* @todo convert to typedef Event::Code */
enum CameraErrorCode {NoCameraError}; /* @todo fix this */
struct LIMACORE_API Status
......@@ -170,29 +162,39 @@ namespace lima
CtConfig* config();
#endif
SoftOpExternalMgr* externalOperation();
HwInterface* hwInterface();
#else //unix
#else //WIN32
/// \{
/// \name Advanced control accessors
/// Returns a pointer to the acquisition control
CtAcquisition* acquisition() { return m_ct_acq; }
/// Returns a pointer to the saving control
CtSaving* saving() { return m_ct_saving; }
#ifdef WITH_SPS_IMAGE
CtSpsImage* display() { return m_ct_sps_image; }
#endif
/// Returns a pointer to the image control
CtImage* image() { return m_ct_image; }
/// Returns a pointer to the buffer control
CtBuffer* buffer() { return m_ct_buffer; }
/// Returns a pointer to the accumulation control
CtAccumulation* accumulation() { return m_ct_accumulation; }
/// Returns a pointer to the video control
CtVideo* video() { return m_ct_video;}
/// Returns a pointer to the shutter control
CtShutter* shutter() { return m_ct_shutter; }
/// Returns a pointer to the event control
CtEvent* event() { return m_ct_event; }
#ifdef WITH_CONFIG
/// Returns a pointer to the config control
CtConfig* config() { return m_ct_config; }
#endif
/// \}
SoftOpExternalMgr* externalOperation() {return m_op_ext;}
HwInterface* hwInterface() {return m_hw;}
#endif
#endif //WIN32
void setApplyPolicy(ApplyPolicy policy);
void getApplyPolicy(ApplyPolicy &policy) const;
......@@ -251,7 +253,7 @@ namespace lima
HwInterface *m_hw;
mutable Cond m_cond;
mutable Status m_status;
CtSaving *m_ct_saving;
#ifdef WITH_SPS_IMAGE
CtSpsImage *m_ct_sps_image;
......@@ -318,7 +320,7 @@ namespace lima
return os;
}
inline std::ostream& operator<<(std::ostream &os,
const CtControl::ErrorCode &err_code)
{
......@@ -340,7 +342,7 @@ namespace lima
}
return os << desc;
}
inline std::ostream& operator<<(std::ostream &os,
const CtControl::Status &status)
{
......@@ -352,7 +354,7 @@ namespace lima
return os;
}
inline bool operator <(const CtControl::ImageStatus& a,
inline bool operator <(const CtControl::ImageStatus& a,
const CtControl::ImageStatus& b)
{
return ((a.LastImageAcquired < b.LastImageAcquired) ||
......@@ -362,7 +364,7 @@ namespace lima
(a.LastCounterReady < b.LastCounterReady));
}
inline bool operator ==(const CtControl::ImageStatus& a,
inline bool operator ==(const CtControl::ImageStatus& a,
const CtControl::ImageStatus& b)
{
return ((a.LastImageAcquired == b.LastImageAcquired) &&
......@@ -372,19 +374,19 @@ namespace lima
(a.LastCounterReady == b.LastCounterReady));
}
inline bool operator <=(const CtControl::ImageStatus& a,
inline bool operator <=(const CtControl::ImageStatus& a,
const CtControl::ImageStatus& b)
{
return (a < b) || (a == b);
}
inline bool operator >(const CtControl::ImageStatus& a,
inline bool operator >(const CtControl::ImageStatus& a,
const CtControl::ImageStatus& b)
{
return !(a <= b);
}
inline bool operator >=(const CtControl::ImageStatus& a,
inline bool operator >=(const CtControl::ImageStatus& a,
const CtControl::ImageStatus& b)
{
return !(a < b);
......
......@@ -130,7 +130,7 @@ class LIMACORE_API CtMaxImageSizeCB : public HwMaxImageSizeCallback
CtImage *m_ct;
};
/// Control image processing settings such as ROI, binning and rotation
class LIMACORE_API CtImage {
friend class CtControl;
DEB_CLASS_NAMESPC(DebModControl,"Image","Control");
......
......@@ -46,13 +46,8 @@ namespace lima {
typedef std::vector<_BufferHelper*> ZBufferType;
typedef std::map<int,ZBufferType*> dataId2ZBufferType;
/** @brief Saving management
*
* With this class you manage the image saving in different format
*/
class LIMACORE_API CtSaving
/// Control saving settings such as file format and mode
class LIMACORE_API CtSaving
{
DEB_CLASS_NAMESPC(DebModControl,"Saving","Control");
......@@ -162,6 +157,8 @@ namespace lima {
void getHardwareFormat(std::string &format) const;
// --- saving modes
///{
/// \name Saving modes
void setSavingMode(SavingMode mode);
void getSavingMode(SavingMode& mode) const;
......@@ -177,6 +174,8 @@ namespace lima {
void setManagedMode(ManagedMode mode);
void getManagedMode(ManagedMode &mode) const;
///}
// --- common headers
void resetCommonHeader();
......
......@@ -33,6 +33,7 @@
namespace lima {
/// Control shutter settings such as open and close time
class LIMACORE_API CtShutter
{
friend class CtControl;
......
......@@ -3,11 +3,37 @@
Build and Install
-----------------
Two methods are provided to build Lima from source.
Install binary packages
^^^^^^^^^^^^^^^^^^^^^^^
We provide Conda_ binary packages for some cameras. This is, by far, the easiest way to get started with LImA! For instance:
::
conda install --channel esrf-bcu lima-camera-basler
would install a fully loaded LImA and all its dependencies with the Basler camera plugin and SDK. The camera comes as a python module but is also C++ development package that includes header files and `CMake package config <https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html>`_ files.
If you need the Tango device server for the camera, run:
::
conda install --channel esrf-bcu lima-camera-basler-tango
.. note:: The runtime libraries of the camera's SDK are provided as well but some cameras requires drivers or specific setups than needs to be installed manually.
Build from source
^^^^^^^^^^^^^^^^^
First, you need to :ref:`get_source`. Two methods are provided to build LImA from source:
- using our install script that aims to hide the complexity of CMake_;
- using CMake_ directly for developers who are already acquainted with the tool and need the extra flexibility.
Using scripts
^^^^^^^^^^^^^
The ``install`` scripts will run cmake, compile and install.
"""""""""""""
The ``install`` scripts will run CMake_ to compile and/or install.
It accepts input arguments (see below) but it also uses a configuration file ``scripts/config.txt``. Feel free to update this file for setting a permanent configuration for your own installation.
......@@ -53,31 +79,31 @@ Options are ``<camera-name> <saving-format> python pytango-server``:
``pytango-server`` will install the PyTango_ server
For example, to install the basler camera, use the TIFF output format, the python binding and the TANGO server, one would run:
For example, to install the Basler camera, use the TIFF output format, the python binding and the TANGO server, one would run:
.. code-block:: bash
$ sudo install.sh --git --install-prefix=./install --install-python-prefix=./install/python tiff basler python pytango-server
Using CMake
^^^^^^^^^^^
"""""""""""
Install first the project submodules:
.. code-block:: bash
git submodule init third-party/Processlib
git submodule init camera/basler
git submodule init applications/tango/python
git submodule update
git submodule init third-party/Processlib
git submodule init camera/basler
git submodule init applications/tango/python
git submodule update
Run ``cmake`` in the build directory:
.. code-block:: bash
mkdir build
cd build
cmake ..
mkdir build
cd build
cmake ..
[-G "Visual Studio 15 2017 Win64" | -G "Visual Studio 15 2017" | -G "Unix Makefiles"]
[-DCMAKE_INSTALL_PREFIX=<desired installation path>]
[-DPYTHON_SITE_PACKAGES_DIR=<desired python installation path>]
......@@ -96,23 +122,29 @@ Then compile and install:
Environment Setup
^^^^^^^^^^^^^^^^^
If you have changed the default destination path for both libraries and python modules you should update your environment variables.
.. warning::
If you are using Conda_, we advice against setting any environment variables that might affect the Conda environment (e.g. ``PATH``, ``PYTHONPATH``)as this one of the most common source of troubles.
If the install path for libraries and python modules are not the default, you need to update your environment variables as follow:
For Linux:
.. code-block:: bash
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<my-new-install-dir>/Lima/lib
export PYTHONPATH=$PYTHONPATH:<my-new-install-dir>
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<my-custom-install-dir>/Lima/lib
export PYTHONPATH=$PYTHONPATH:<my-custom-install-dir>
For Windows:
.. code-block:: bash
set PATH=%PATH%;<my-new-install-dir>\Lima\lib
set PYTHONPATH=%PYTHONPATH%;<my-new-install-dir>
set PATH=%PATH%;<my-custom-install-dir>\Lima\lib
set PYTHONPATH=%PYTHONPATH%;<my-custom-install-dir>
or update the system wide variables ``PATH`` for the libraries and ``PYTHONPATH`` for python.
.. _CMake: https://cmake.org
.. _Conda: https://conda.io
.. _PyTango: http://github.com/tango-cs/pytango
# Doxyfile 1.8.14
# This file describes the settings to be used by the documentation system
# doxygen (www.doxygen.org) for a project.
#
# All text after a double hash (##) is considered a comment and is placed in
# front of the TAG it is preceding.
#
# All text after a single hash (#) is considered a comment and will be ignored.
# The format is:
# TAG = value [value, ...]
# For lists, items can also be appended using:
# TAG += value [value, ...]
# Values that contain spaces should be placed between quotes (\" \").
#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
# This tag specifies the encoding used for all characters in the config file
# that follow. The default is UTF-8 which is also the encoding used for all text
# before the first occurrence of this tag. Doxygen uses libiconv (or the iconv
# built into libc) for the transcoding. See
# https://www.gnu.org/software/libiconv/ for the list of possible encodings.
# The default value is: UTF-8.
DOXYFILE_ENCODING = UTF-8
# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by
# double-quotes, unless you are using Doxywizard) that should identify the
# project for which the documentation is generated. This name is used in the
# title of most generated pages and in a few other places.
# The default value is: My Project.
PROJECT_NAME = LImA
# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
# could be handy for archiving the generated documentation or if some version
# control system is used.
PROJECT_NUMBER =
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a
# quick idea about the purpose of the project. Keep the description short.
PROJECT_BRIEF = "Library for Image Acquisition"
# With the PROJECT_LOGO tag one can specify a logo or an icon that is included
# in the documentation. The maximum height of the logo should not exceed 55
# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
# the logo to the output directory.
PROJECT_LOGO =
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
# into which the generated documentation will be written. If a relative path is
# entered, it will be relative to the location where doxygen was started. If
# left blank the current directory will be used.
OUTPUT_DIRECTORY = .doxygen
# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
# directories (in 2 levels) under the output directory of each output format and
# will distribute the generated files over these directories. Enabling this
# option can be useful when feeding doxygen a huge amount of source files, where
# putting all generated files in the same directory would otherwise causes
# performance problems for the file system.
# The default value is: NO.
CREATE_SUBDIRS = NO
# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII
# characters to appear in the names of generated files. If set to NO, non-ASCII
# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode
# U+3044.
# The default value is: NO.
ALLOW_UNICODE_NAMES = NO
# The OUTPUT_LANGUAGE tag is used to specify the language in which all
# documentation generated by doxygen is written. Doxygen will use this
# information to generate all constant output in the proper language.
# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese,
# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States),
# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian,
# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages),
# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian,
# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian,
# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish,
# Ukrainian and Vietnamese.
# The default value is: English.
OUTPUT_LANGUAGE = English
# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member
# descriptions after the members that are listed in the file and class
# documentation (similar to Javadoc). Set to NO to disable this.
# The default value is: YES.
BRIEF_MEMBER_DESC = YES
# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief
# description of a member or function before the detailed description
#
# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
# brief descriptions will be completely suppressed.
# The default value is: YES.
REPEAT_BRIEF = YES
# This tag implements a quasi-intelligent brief description abbreviator that is
# used to form the text in various listings. Each string in this list, if found
# as the leading text of the brief description, will be stripped from the text
# and the result, after processing the whole list, is used as the annotated
# text. Otherwise, the brief description is used as-is. If left blank, the
# following values are used ($name is automatically replaced with the name of
# the entity):The $name class, The $name widget, The $name file, is, provides,
# specifies, contains, represents, a, an and the.
ABBREVIATE_BRIEF = "The $name class" \
"The $name widget" \
"The $name file" \
is \
provides \
specifies \
contains \
represents \
a \
an \
the
# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
# doxygen will generate a detailed section even if there is only a brief
# description.
# The default value is: NO.
ALWAYS_DETAILED_SEC = NO
# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all
# inherited members of a class in the documentation of that class as if those
# members were ordinary class members. Constructors, destructors and assignment
# operators of the base classes will not be shown.
# The default value is: NO.
INLINE_INHERITED_MEMB = NO
# If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path
# before files name in the file list and in the header files. If set to NO the
# shortest path that makes the file name unique will be used
# The default value is: YES.
FULL_PATH_NAMES = YES
# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.
# Stripping is only done if one of the specified strings matches the left-hand
# part of the path. The tag can be used to show relative paths in the file list.