documentation continues

.github/workflows/libtomophantom_conda_upload.yml

@@ -1,6 +1,9 @@
 name: libtomophantom_conda_upload
 
-on: [push]
+on:
+  push:
+    branches:
+      - master
 
 jobs:
   build-linux:

.github/workflows/tomophantom_conda_upload.yml

@@ -1,6 +1,9 @@
 name: tomophantom_conda_upload
 
-on: [push]
+on:
+  push:
+    branches:
+      - master
 
 jobs:
   build-linux:

docs/source/howto/build_phantoms.rst

@@ -3,8 +3,8 @@
 Build Phantoms
 ==============
 
-This sections explains how to build phantoms and also describes different ways of doing that. 
+This sections explains how to build phantoms by presenting two main ways of doing that. 
 
-* 1. The easiest and quickest way to build a phantom is to use provided library files, see more in :ref:`howto_libraries`. For someone who is new to TomoPhantom, we recommend to play with already existing models, check this guide and also demos.
+* 1. The easiest and the quickest way to build a phantom is to use provided library files, see more in :ref:`howto_libraries`.  This is the most suitable way to start for someone who is new to TomoPhantom. We recommend to try building already pre-existing models by following this guide on :ref:`tutorial_model`.
 
-* 2. blabla
+* 2. For more advanced approach in building bespoke phantoms consisting of multiple objects, we recommend to use :ref:`ref_object_api`. This is how one can build a phantom directly, i.e., without the use of the library file. One can specify parameters in Python as a dictionary and pass into a function that works with the objects. We recommend to have a look at this tutorial :ref:`tutorial_object`.

docs/source/index.rst

@@ -20,6 +20,16 @@
     howto/libraries
     howto/simulate
 
+
+.. _tutorials_content:
+
+.. toctree::
+    :caption: Tutorials
+    :maxdepth: 2
+
+    tutorials/model_tutorial
+    tutorials/object_tutorial
+
 .. _reference_content:
 
 .. toctree::

docs/source/reference/glossary.rst

@@ -33,8 +33,8 @@ Object blabla
 Library files
 -------------
 
-Library files are the text files which are provided to users with the downloaded repository or installation. Different phantoms are hardcoded using parameters 
-in the files. 2D phantoms and their dynamic extenstions are stored in the :data:`Phantom2DLibrary.dat` file, while 3D phantoms and their dynamic
-extensions are stored in the :data:`Phantom3DLibrary.dat` file. The files are located in the `tomophantom/phantomlib` folder.
+The library files are the text files which are provided to users with the downloaded repository or an installation. Different phantoms are hardcoded using parameters 
+for objects in those files. 2D phantoms and (2D + time) *dynamic* phantoms are stored in the :data:`Phantom2DLibrary.dat` file, while 3D phantoms and (3D + time)  dynamic
+phantoms are stored in the :data:`Phantom3DLibrary.dat` file. The files are located in the :data:`tomophantom/phantomlib` folder.
 
 

docs/source/reference/library_files_api.rst

@@ -3,7 +3,7 @@
 Library files API
 =================
 
-There is a certain API protocol how the user should define objects in the :ref:`ref_glossary_library`. 
+There is a certain API protocol how the user should define objects in the :ref:`ref_glossary_library`. If one is interested to learn about parameters of the objects, it is better to skip to :ref:`ref_object_api` directly.
 
 
 .. _ref_library_files_api2d:
@@ -57,7 +57,7 @@ TomoPhantom converts this string of 7 parameters [#f2]_ into the following behin
     b=0.92
     angle=0.0
 
-As we move here into the :ref:`ref_glossary_object` API territory, it is best to re-direct the reader to the  :ref:`ref_object_2d` section. There the meaning of each parameter of a 2D object is explained in detail. 
+As we move here into the :ref:`ref_glossary_object` API territory, it is best to re-direct the reader to the  :ref:`ref_object_2d` section. The meaning of each parameter for a 2D object is explained in detail there. 
 
 
 .. _ref_library_files_api3d:
@@ -112,7 +112,7 @@ Again, for more in-depth read about parameters of 3D objects see :ref:`ref_objec
 
 .. rubric:: Footnotes
 
-.. [#f2] The developers do understand that the choice of the text format to represent configuration files for libraries might not be the best choice. Potentially choosing YAML language instead would make parameters for objects more informative and readable. However, the choice of text file libraries was historically inherited from the initial implementation of software in C. Of course, it would be great to refactor it at some point.   
+.. [#f2] Arguably, the choice of the text format to represent configuration library files might not be the best choice. Potentially, choosing the YAML language instead would make parameters for objects more informative and readable. However, the choice of text file libraries was historically inherited from the initial implementation of software in C language. We understand that it would be great to refactor it at some point.   
 
 
 

docs/source/reference/object_api.rst

@@ -3,27 +3,51 @@
 Object API
 ==========
 
+In TomoPhantom, we have a dedicated functionality that allows the user to build bespoke phantoms by stacking multiple objects together.
+One should look into the :func:`Object` function of :func:`tomophantom.TomoP2D` or :func:`tomophantom.TomoP3D` modules if one wishes to build a phantom (2D or 3D, respectively).
+If one needs also projection data to be generated, then please see the :func:`ObjectSino` function in the same modules. 
+
+One can notice that one of the input parameters for :func:`Object` and :func:`ObjectSino` functions is :data:`obj_params` (*a dictionary or a list of dictionaries with the parameters for object(s)*).
+This is where one needs the understanding of what those parameters represent. Bellow, we provide the details about these parameters and how these parameters 
+should be passed to the chosen function, see :ref:`ref_object_api_python2d`.
+
 .. _ref_object_2d:
 
 Parameters of 2D objects explained
 ----------------------------------
 
-There are 7 parameters in total to describe an object.
+There are 7 parameters in total to describe a 2D object. Please refer to :numref:`fig_objects2d_notations` when exploring parameters bellow.
 
 .. dropdown:: 1. object's name, type: string
 
 	For 2D phantoms the accepted objects names are :code:`gaussian`, :code:`parabola`, :code:`parabola1`, :code:`ellipse`, :code:`cone` and :code:`rectangle`. See more in the TomoPhantom paper [SX2018]_ for analytical formulae.
 
-.. dropdown:: 1. C0 - intensity level, type: float
+.. dropdown:: 2. :math:`C_{0}`: intensity level, type: float
+
+	Parameter :math:`C_{0}` defines the grayscale intensity level, given as a floating point number. :math:`C_{0}` can be either negative or positive. Objects in the model are concatenated by summation, so one can do a subtraction of objects by defining negative intensities.  
+
+.. dropdown:: 3. :math:`x_{0}` : object's center along the :math:`X` axis, type: float
+
+	Parameter :math:`x_{0}`  defines the location of the object's center along the :math:`X` axis. The range of the parameter is normally within [-0.5, 0.5]. 
+
+.. dropdown:: 4. :math:`y_{0}` : object's center along the :math:`Y` axis, type: float
+
+	Parameter :math:`y_{0}` defines the location of the object's center along the :math:`Y` axis. The range of the parameter is normally within [-0.5, 0.5]. 
+
+.. dropdown:: 5. :math:`a` : object's half-width, type: float
+
+	Parameter :math:`a`  defines the half-width of the object. The range of the parameter is normally within (0, 2). 
+
+.. dropdown:: 6. :math:`b` : object's half-length, type: float
 
-	:math:`C_{0}` defines the grayscale intensity level (see :numref:`fig_objects2d_notations`), given as a floating point number. :math:`C_{0}` can be either negative or positive. Objects in the model are concatenated by summation, so one can do a subtraction of objects by defining negative intensities.  
+	Parameter :math:`b`  defines the half-length of the object. The range of the parameter is normally within (0, 2). 
 
 .. _fig_objects2d_notations:
 .. figure::  ../_static/api_objects/objects2d_notations.png
     :scale: 50 %
     :alt: Notation for a 2D object
 
-    The coordinate system in which objects are defined. Note the location of :math:`X` and :math:`Y` axes and the ranges for the visible field of view. Parameters describing a 2D object are: object's name, :math:`C_{0}`, :math:`x_{0}`, :math:`y_{0}`, :math:`a`, :math:`b` and angle :math:`\phi`.
+    The coordinate system in which the objects are defined and an ellipsoid as an example. Note the location of :math:`X` and :math:`Y` axes and the ranges for the visible field of view. Parameters describing a 2D object are: object's name, :math:`C_{0}`, :math:`x_{0}`, :math:`y_{0}`, :math:`a`, :math:`b` and the rotation angle :math:`\phi`.
 
 .. _ref_object_api2d:
 

docs/source/tutorials/model_tutorial.rst

@@ -0,0 +1,6 @@
+.. _tutorial_model:
+
+Building phantoms using models
+******************************
+
+TODO.

docs/source/tutorials/object_tutorial.rst

@@ -0,0 +1,6 @@
+.. _tutorial_object:
+
+Building phantoms using objects
+*******************************
+
+TODO.