Update documentation

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 688e180c636424fa7131b68b7068aeaf
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_panels_static/panels-variables.06eb56fa6e07937060861dad626602ad.css

@@ -0,0 +1,7 @@
+:root {
+--tabs-color-label-active: hsla(231, 99%, 66%, 1);
+--tabs-color-label-inactive: rgba(178, 206, 245, 0.62);
+--tabs-color-overline: rgb(207, 236, 238);
+--tabs-color-underline: rgb(207, 236, 238);
+--tabs-size-label: 1rem;
+}

_sources/api/tomophantom.TomoP2D.rst

@@ -0,0 +1,6 @@
+:mod:`tomophantom.TomoP2D`
+============================================
+.. automodule:: tomophantom.TomoP2D
+   :members:
+   :undoc-members:
+   :show-inheritance:

_sources/api/tomophantom.TomoP3D.rst

@@ -0,0 +1,6 @@
+:mod:`tomophantom.TomoP3D`
+============================================
+.. automodule:: tomophantom.TomoP3D
+   :members:
+   :undoc-members:
+   :show-inheritance:

_sources/api/tomophantom.artefacts.rst

@@ -0,0 +1,6 @@
+:mod:`tomophantom.artefacts`
+============================================
+.. automodule:: tomophantom.artefacts
+   :members:
+   :undoc-members:
+   :show-inheritance:

_sources/api/tomophantom.ctypes.dtype.rst

@@ -0,0 +1,6 @@
+:mod:`tomophantom.ctypes.dtype`
+============================================
+.. automodule:: tomophantom.ctypes.dtype
+   :members:
+   :undoc-members:
+   :show-inheritance:

_sources/api/tomophantom.ctypes.external.rst

@@ -0,0 +1,6 @@
+:mod:`tomophantom.ctypes.external`
+============================================
+.. automodule:: tomophantom.ctypes.external
+   :members:
+   :undoc-members:
+   :show-inheritance:

_sources/api/tomophantom.ctypes.rst

@@ -0,0 +1,19 @@
+tomophantom.ctypes package
+==========================
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   tomophantom.ctypes.dtype
+   tomophantom.ctypes.external
+
+Module contents
+---------------
+
+.. automodule:: tomophantom.ctypes
+   :members:
+   :undoc-members:
+   :show-inheritance:

_sources/api/tomophantom.flatsgen.rst

@@ -0,0 +1,6 @@
+:mod:`tomophantom.flatsgen`
+============================================
+.. automodule:: tomophantom.flatsgen
+   :members:
+   :undoc-members:
+   :show-inheritance:

_sources/api/tomophantom.generator.rst

@@ -0,0 +1,6 @@
+:mod:`tomophantom.generator`
+============================================
+.. automodule:: tomophantom.generator
+   :members:
+   :undoc-members:
+   :show-inheritance:

_sources/api/tomophantom.qualitymetrics.rst

@@ -0,0 +1,6 @@
+:mod:`tomophantom.qualitymetrics`
+============================================
+.. automodule:: tomophantom.qualitymetrics
+   :members:
+   :undoc-members:
+   :show-inheritance:

_sources/api/tomophantom.rst

@@ -0,0 +1,32 @@
+tomophantom package
+===================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   tomophantom.ctypes
+   tomophantom.supp
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   tomophantom.TomoP2D
+   tomophantom.TomoP3D
+   tomophantom.artefacts
+   tomophantom.flatsgen
+   tomophantom.generator
+   tomophantom.qualitymetrics
+
+Module contents
+---------------
+
+.. automodule:: tomophantom
+   :members:
+   :undoc-members:
+   :show-inheritance:

_sources/api/tomophantom.supp.libraryToDict.rst

@@ -0,0 +1,6 @@
+:mod:`tomophantom.supp.libraryToDict`
+============================================
+.. automodule:: tomophantom.supp.libraryToDict
+   :members:
+   :undoc-members:
+   :show-inheritance:

_sources/api/tomophantom.supp.rst

@@ -0,0 +1,19 @@
+tomophantom.supp package
+========================
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   tomophantom.supp.libraryToDict
+   tomophantom.supp.speckle_routines
+
+Module contents
+---------------
+
+.. automodule:: tomophantom.supp
+   :members:
+   :undoc-members:
+   :show-inheritance:

_sources/api/tomophantom.supp.speckle_routines.rst

@@ -0,0 +1,6 @@
+:mod:`tomophantom.supp.speckle_routines`
+============================================
+.. automodule:: tomophantom.supp.speckle_routines
+   :members:
+   :undoc-members:
+   :show-inheritance:

_sources/howto/installation.rst

@@ -0,0 +1,94 @@
+.. _ref_installation:
+
+Installation Guide
+------------------
+TomoPhantom consists of two parts: C-library that is build 
+as a shared object using Cmake and Ctypes bindings and 
+pure Python part that can be installed separately. 
+Bellow we provide various recipes how software can be 
+installed. We recommend to use TomoPhantom in Python as 
+:ref:`ref_matlab` is not maintained at the moment.
+
+.. _ref_python:
+
+Python
+======
+
+Install TomoPhantom as a pre-built conda Python package:
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. code-block:: console
+
+   $ conda install -c httomo tomophantom
+
+or install with dependencies to perform reconstruction:
+
+.. code-block:: console
+
+   $ conda install -c httomo -c astra-toolbox tomophantom tomobar astra-toolbox ccpi-regularisation-cupy
+
+Developers environment
++++++++++++++++++++++++
+This sets the development environment to work in-place on the code.
+It installs the library from the `httomo` conda channel.
+If one needs to build the library first, please see how to 
+:ref:`ref_libtomophantom`.
+
+.. code-block:: console
+    
+   $ conda install -c httomo libtomophantom # get the library only
+   $ git clone git@github.com/dkazanc/TomoPhantom.git # clone the repo   
+   $ pip install -e .[dev] # the editable environment
+   $ pytests tests/ # all tests should pass
+
+Conda build
++++++++++++++
+First one needs to build the `libtomophantom` C-library, the recipes for which are located in `conda-recipe_library/` folder:
+
+.. code-block:: console
+    
+   $ export CIL_VERSION=3.0 # OR set CIL_VERSION=3.0 for Windows
+   $ git clone git@github.com/dkazanc/TomoPhantom.git # clone the repo
+   $ conda build conda-recipe_library # conda-build the library
+   $ conda install path/to/the/tarball
+
+Second, build the Python part of the library:
+
+.. code-block:: console
+    
+   $ conda build conda-recipe -c httomo
+   $ conda install path/to/the/tarball
+
+.. _ref_libtomophantom:
+
+Install libtomophantom from sources
++++++++++++++++++++++++++++++++++++++
+With `Cmake <https://cmake.org>`_ one can build the `libtomophantom` library, which is a set of C functions. 
+On Unix systems you will need a C compiler (gcc) and VC compiler on Windows. Note that in our 
+`httomo <https://anaconda.org/httomo/>`_ conda channel we provide the pre-built binaries of libtomophantom.
+
+Here an example of the `libtomophantom` library build on Linux. The shared library object 
+will be installed into the conda lib location, 
+see `echo $CONDA_PREFIX`.
+
+.. code-block:: console
+    
+   $ git clone https://github.com/dkazanc/TomoPhantom.git
+   $ mkdir build
+   $ cd build
+   $ cmake ../ -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX -DCMAKE_VERBOSE_MAKEFILE:BOOL=ON
+   $ cmake --build . # on Windows add a flag --config Release
+   $ cmake --install .
+
+The library should now be installed in your conda environment, you can `pip install` the Python part. 
+
+.. _ref_matlab:
+
+Matlab
+======
+Initially TomoPhantom was created as a Matlab application with mex compiled Matlab wrappers.
+After 2018, however, the developers decided to stop supporting Matlab. We believe it still can be 
+compiled and installed in Matlab, but its functionality is not garanteed. We recommend using it in :ref:`ref_python`. 
+For Matlab installations please see the older `versions <https://github.com/dkazanc/TomoPhantom/releases>`_ of TomoPhantom.
+
+

_sources/index.rst

@@ -0,0 +1,27 @@
+.. include:: ../../README.rst
+
+.. _intro_content:
+
+.. toctree::
+    :caption: Introduction
+    :maxdepth: 2
+    :glob:
+
+    introduction/about
+    introduction/libraries
+
+.. _how_to_content:
+
+.. toctree::
+    :caption: How To's
+    :maxdepth: 2
+
+    howto/installation
+
+.. _reference_content:
+
+.. toctree::
+    :caption: Reference guides
+    :maxdepth: 2
+
+    reference/api

_sources/introduction/about.rst

@@ -0,0 +1,52 @@
+About TomoPhantom
+*******************
+
+The general concept
+=====================
+The variety of image processing techniques, such as, reconstruction, 
+denoising, deblurring, inpainting, and segmentation require simulated 
+ground truth data in order to numerically verify, benchmark and evaluate 
+the proposed methods. The ground truth data can have various 
+characteristics specific to the acquisition hardware, which also can be 
+the focus of image processing method developers. In many situations, 
+however, over-simplistic or unsuitable simulated data are used for testing.
+
+In TomoPhantom, projection data is calculated following analytical 
+Radon transform derrivations applied to elementary functions. 
+This approach is different to conventional numerical calculation 
+of projections for the forward X-ray acquisition model using 
+ray-tracing algorithms. Analytical projections 
+are exact and discretized over a different grid which normally 
+used for projection and backprojection steps in reconstruction
+methods. TomoPhantom enables a convinient testing environment 
+for novel reconstruction methods, therefore avoiding the "inverse crime"
+issue (data simulation using the same grid). Overall, the use of exact
+projections and known ground truth is especially beneficial for
+benchmarking of iterative reconstruction algorithms.
+
+TomoPhantom also offers simple linear dynamic extensons of 2D and 3D phantoms.
+
+.. figure::  ../_static/models4D/model11_4D.gif
+    :scale: 50 %
+    :alt: 4D phantoms
+
+The generated byt TomoPhantom projection data is
+compatable with widely-used open-source tomographic reconstruction 
+software: the ASTRA-toolbox and the TomoPy packages.
+
+What TomoPhantom can do
+=========================
+* Generate 2D and 3D synthetic phantoms made of Gaussians, parabolas, ellipses, cones and rectangulars.
+* Generate simple temporal extensions of 2D and 3D phantoms.
+* Calculate analytical Radon transforms of 2D-4D models and also their numerical projections.
+* Model a variety of tomographic data artefacts (noise models, zingers, rings, shifts, partial volume effect and others). 
+
+.. figure::  ../_static/models3D/model05.jpg
+    :scale: 50 %
+    :alt: 3D phantoms
+
+.. figure::  ../_static/models3D/tomo3d.jpg
+    :scale: 50 %
+    :alt: 3D phantoms
+
+See more on API of TomoPhantom in :ref:`ref_api`.

_sources/introduction/libraries.rst

@@ -0,0 +1,15 @@
+Phantom Libraries
+*******************
+
+TomoPhantom provides a variety of phantoms that are static (2D,3D) and dynamic one (3D, 4D).
+The users can start using them right away by specifying a **model** number from 
+the associated library file. Model is usually reffered to a combined phantom which 
+consists of simpler geometrical **objects**. Note that objects can be 
+also build independently, please see :ref:`ref_api`.
+
+`Phantom2DLibrary.dat` and `Phantom3DLibrary.dat` are editable 
+text files located in `tomophantom/phantomlib` folder with parametrised models.
+For instance, 2D/3D versions of Shepp-Logan, Defrise, and QRM phantoms. 
+
+The generation of new phantoms is highly encouraged, 
+please submit them through the pull requests to the repo.

_sources/reference/api.rst

@@ -0,0 +1,20 @@
+.. _ref_api:
+
+==========================
+API reference
+==========================
+
+This section contains the API reference and usage information for Tomophantom.
+
+Tomophantom Modules
+--------------------
+v.3.0
+'''''
+
+.. toctree::
+   :glob:
+
+   ../api/tomophantom.TomoP2D
+   ../api/tomophantom.TomoP3D  
+   ../api/tomophantom.artefacts  
+   ../api/tomophantom.flatsgen