Merge pull request #119 from ufo-kit/update-docs

Update docs

docs/source/_static/css/custom.css

@@ -0,0 +1,6 @@
+@import url("theme.css");
+
+.wy-nav-content {
+    min-width: 50%;
+    max-width: 55%;
+}

docs/source/api.rst

@@ -0,0 +1,9 @@
+Application Programming Interface
+=================================
+
+.. toctree::
+    :maxdepth: 2
+
+    api/preprocessing
+    api/genreco
+    api/util

docs/source/conf.py

@@ -85,7 +85,8 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+html_style = 'css/custom.css'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -96,7 +97,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/source/index.rst

@@ -8,29 +8,9 @@ Welcome to Tofu's documentation!
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
-
-Application Programming Interface
-=================================
-
-.. toctree::
-   :maxdepth: 2
-
-   api/preprocessing
-   api/genreco
-   api/util
-
-
-Usage
-=====
-
-
-.. toctree::
-	:maxdepth: 2
-
-	usage/genreco
-	usage/flow
+   usage
+   api
 
 
 Indices and tables

docs/source/usage.rst

@@ -0,0 +1,10 @@
+Usage
+=====
+
+.. toctree::
+    :maxdepth: 2
+
+    usage/io
+    usage/preprocessing
+    usage/genreco
+    usage/flow

docs/source/usage/genreco.rst

@@ -2,6 +2,7 @@ General 3D Reconstruction
 =========================
 
 
+
 You can use command ``tofu reco`` to reconstruct paralell/cone beam
 tomography/laminography data. The algorithm is filtered back projection for
 parallel beam data and `Feldkamp <https://doi.org/10.1364/JOSAA.1.000612>`_
@@ -10,27 +11,58 @@ parallel to the beam direction. The third dimensions may be the vertical slice
 position (the default) but can also be one of the geometrical parameters in order to find
 their best values for the final reconstruction (see ``tofu reco --help`` and
 check the ``--z-parameter`` entry for possible values). Angular input values are
-in degrees.
+in degrees. Geometry of the 3D reconstruction is depicted in the following
+scheme [#f1]_
+
+.. image:: ../figs/reco-geometry.png
+  :width: 800
+  :align: center
+  :alt: 3D reconstruction geometry
+
+The dimensions are:
+
+- **x = lateral dimension**;
+- **y = beam propagation dimension**;
+- **z = vertical dimension**;
+
+.. note::
+    Pixel counting starts with ``0`` and integer numbers are **boundaries**
+    between pixels. That means that integer pixel specification, e.g.
+    ``--center-position-z 1.0`` means: "use position at the boundary between row
+    0 and row 1", thus the algorithm will interpolate between the two rows,
+    i.e.  blur the result!
+
+    For using solely one row for one CT slice you need to specify
+    ``--center-position-z 1.5``, which means: "Take the second row of the
+    projection and do not consider the one before or after", which is what we
+    need in case of parallel CT (``tofu reco`` automatically adds the ``+ 0.5``
+    in case of paralell beam CT and integer ``--center-position-z``, it also
+    informs you about this on the output).
+
+
+Examples
+--------
 
 To reconstruct slices -100, 100 with the step size 0.5 around the center which
 is defined as 1008.5 from 1500 projections acquired over 180 degrees stored in
 ``projs.tif``, with rotation axis in pixel 951 one would do::
 
-    tofu reco --projections projs.tif --number 1500 --center-position-x 951
-    --overall-angle 180 --center-position-z 1008.5 --region=-100,100,0.5
-    --output slices.tif
+    tofu reco --projections projs.tif --number 1500 --center-position-x 951 --overall-angle 180 --center-position-z 1008.5
+	--region=-100,100,0.5 --output slices.tif
 
 
 To scan the roll angle around -2, 2 degrees with step 0.1 degree, one can use
 the following command::
-    tofu reco --projections projs.tif --number 1500 --overall-angle 180
-    --center-position-x 951 --center-position-z 1008.5 --z-parameter
-    detector-angle-y --region=-2,2,0.1 --output detector-angle-y-scan.tif
-    --disable-projection-crop
+
+    tofu reco --projections projs.tif --number 1500 --overall-angle 180 --center-position-x 951 --center-position-z 1008.5
+	--z-parameter detector-angle-y --region=-2,2,0.1 --output detector-angle-y-scan.tif --disable-projection-crop
 
 
 To scan the rotation axis region from pixel 940 to pixel 960 with step 0.5
 pixels, (the ``center-position-x`` parameter), one can use::
-    tofu reco --projections projs.tif --number 1500 --overall-angle 180
-    --center-position-z 1008.5 --z-parameter center-position-x
-    --region=940,960,0.5 --output center-position-x-scan.tif
+
+    tofu reco --projections projs.tif --number 1500 --overall-angle 180 --center-position-z 1008.5 --z-parameter center-position-x
+	--region=940,960,0.5 --output center-position-x-scan.tif
+
+
+.. [#f1] `Tofu: a fast, versatile and user-friendly image processing toolkit for computed tomography <https://doi.org/10.1107/S160057752200282X>`_

docs/source/usage/io.rst

@@ -0,0 +1,51 @@
+Input/Output
+============
+
+
+Image Reading
+-------------
+
+Tofu uses UFO's `Reader
+<https://ufo-filters.readthedocs.io/en/master/generators.html#read-read>`_ which
+can handle multiple file types, including single- and multi-page tif files. If
+you specify a file, only that file will be read, if you specify a directory, all
+files in the directory will be read. If you specify a pattern, all files
+matching that pattern will be read. The following arguments for reading are
+available for all of the ``tofu`` commands unless stated otherwise:
+
+- ``--y``: Vertical coordinate from where to start reading the input image (default: ``0``);
+- ``--height``: Number of rows which will be read (default: ``None``, meaning: all);
+- ``--bitdepth``: Bit depth of raw files (bits per pixel, default: ``32``);
+- ``--y-step``: Read every "step" row from the input (default: ``1``);
+- ``--start``: Offset to the first read file (default: ``0``);
+- ``--number``: Number of files to read (default: ``None``, meaning: all);
+- ``--step``: Read every "step" file (default: ``1``).
+
+
+Image Writing
+-------------
+
+Tofu writes tif files by UFO's `Writer
+<https://ufo-filters.readthedocs.io/en/master/sinks.html?highlight=write#write-write>`_
+and they can be either single- or multi-page, which is controlled by
+``--output-bytes-per-file`` and ``--outuput`` arguments. If you set
+``--output-bytes-per-file`` to ``0`` or any number smaller than the size of two
+images in bytes, the output will be singe-page. If you specify a larger value,
+there will be multiple images in one tif file. On the top of that, if the file
+size is larger than 4 GB the tif file will be in the bigtiff format (this may
+make it harder to open but ImageJ can handle it).  In the case you specify a
+file name to be a single file, like ``output.tif``, you need to make sure that
+``--output-bytes-per-file`` is large enough to facilitate all images which are
+about to be written. Alternatively, you can specify the output as a *format
+string* e.g. ``output-%04d.tif``, which will create files ``output-0000.tif``,
+``output-0001.tif`` and so on. A new file will be created every time the amount
+of bytes written in the current file would exceed the value specified by
+``--output-bytes-per-file``.
+
+.. note::
+   You may use ``k``, ``m``, ``g``, ``t`` suffixes with
+   ``--output-bytes-per-file`` to indicate respectively kibibytes
+   (:math:`2^{10}` bytes), mebibytes (:math:`2^{20}` bytes) gibibytes
+   (:math:`2^{30}` bytes) and tebibytes (:math:`2^{40}` bytes). When you want to
+   make sure all fits into one file, just use e.g. "1t", which stands for "one
+   tebibyte" and equals 1.099.511.627.776 bytes.