From 309a93eb4aad3b824e8daaf281e87ad3990ab815 Mon Sep 17 00:00:00 2001 From: dkazanc Date: Wed, 8 May 2024 14:43:22 +0100 Subject: [PATCH 1/3] creating documentation for httomolibgpu --- .github/workflows/doc_conda.yml | 43 +++++++ README.rst | 17 ++- doc/decorators.rst | 98 --------------- docs/source/__init__.py | 0 docs/source/_templates/module.rst_t | 7 ++ docs/source/api/httomolibgpu.cuda_kernels.rst | 10 ++ docs/source/api/httomolibgpu.cupywrapper.rst | 6 + docs/source/api/httomolibgpu.misc.corr.rst | 6 + docs/source/api/httomolibgpu.misc.morph.rst | 6 + docs/source/api/httomolibgpu.misc.rescale.rst | 6 + docs/source/api/httomolibgpu.misc.rst | 20 +++ .../api/httomolibgpu.prep.alignment.rst | 6 + .../api/httomolibgpu.prep.normalize.rst | 6 + docs/source/api/httomolibgpu.prep.phase.rst | 6 + docs/source/api/httomolibgpu.prep.rst | 21 ++++ docs/source/api/httomolibgpu.prep.stripe.rst | 6 + .../api/httomolibgpu.recon.algorithm.rst | 6 + .../api/httomolibgpu.recon.rotation.rst | 6 + docs/source/api/httomolibgpu.recon.rst | 19 +++ docs/source/api/httomolibgpu.rst | 29 +++++ docs/source/bibliography/biblio.rst | 8 ++ docs/source/bibliography/references.bib | 91 ++++++++++++++ docs/source/conf.py | 114 ++++++++++++++++++ docs/source/css/general.css | 4 + docs/source/doc-conda-requirements.yml | 14 +++ .../source/examples}/DistortionCorr.ipynb | 29 +---- .../source/examples}/pipeline1_FBP.ipynb | 30 +---- .../examples}/pipeline2_iterative.ipynb | 29 +---- docs/source/index.rst | 30 +++++ docs/source/introduction/about.rst | 4 + docs/source/reference/api.rst | 23 ++++ docs/sphinx-build.sh | 40 ++++++ docs/sphinx_build_setup.rst | 38 ++++++ httomolibgpu/misc/morph.py | 2 +- httomolibgpu/prep/alignment.py | 2 +- httomolibgpu/prep/phase.py | 4 +- httomolibgpu/prep/stripe.py | 24 ++-- httomolibgpu/recon/algorithm.py | 11 +- httomolibgpu/recon/rotation.py | 25 ++-- 39 files changed, 622 insertions(+), 224 deletions(-) create mode 100644 .github/workflows/doc_conda.yml delete mode 100644 doc/decorators.rst create mode 100644 docs/source/__init__.py create mode 100644 docs/source/_templates/module.rst_t create mode 100644 docs/source/api/httomolibgpu.cuda_kernels.rst create mode 100644 docs/source/api/httomolibgpu.cupywrapper.rst create mode 100644 docs/source/api/httomolibgpu.misc.corr.rst create mode 100644 docs/source/api/httomolibgpu.misc.morph.rst create mode 100644 docs/source/api/httomolibgpu.misc.rescale.rst create mode 100644 docs/source/api/httomolibgpu.misc.rst create mode 100644 docs/source/api/httomolibgpu.prep.alignment.rst create mode 100644 docs/source/api/httomolibgpu.prep.normalize.rst create mode 100644 docs/source/api/httomolibgpu.prep.phase.rst create mode 100644 docs/source/api/httomolibgpu.prep.rst create mode 100644 docs/source/api/httomolibgpu.prep.stripe.rst create mode 100644 docs/source/api/httomolibgpu.recon.algorithm.rst create mode 100644 docs/source/api/httomolibgpu.recon.rotation.rst create mode 100644 docs/source/api/httomolibgpu.recon.rst create mode 100644 docs/source/api/httomolibgpu.rst create mode 100644 docs/source/bibliography/biblio.rst create mode 100644 docs/source/bibliography/references.bib create mode 100644 docs/source/conf.py create mode 100644 docs/source/css/general.css create mode 100644 docs/source/doc-conda-requirements.yml rename {examples => docs/source/examples}/DistortionCorr.ipynb (99%) rename {examples => docs/source/examples}/pipeline1_FBP.ipynb (99%) rename {examples => docs/source/examples}/pipeline2_iterative.ipynb (99%) create mode 100644 docs/source/index.rst create mode 100644 docs/source/introduction/about.rst create mode 100644 docs/source/reference/api.rst create mode 100644 docs/sphinx-build.sh create mode 100644 docs/sphinx_build_setup.rst diff --git a/.github/workflows/doc_conda.yml b/.github/workflows/doc_conda.yml new file mode 100644 index 00000000..9e72e92c --- /dev/null +++ b/.github/workflows/doc_conda.yml @@ -0,0 +1,43 @@ +name: HTTomolibGPU doc test + +on: + workflow_dispatch: + pull_request: + branches: + - main + push: + branches: + - main + +jobs: + build-linux: + runs-on: ubuntu-latest + defaults: + run: + shell: bash -el {0} + steps: + - name: Checkout repository code + uses: actions/checkout@v3 + + - name: Setup Python 3.10 + uses: actions/setup-python@v3 + with: + python-version: "3.10" + + - name: httomolibgpu + uses: conda-incubator/setup-miniconda@v2 + with: + auto-update-conda: false + activate-environment: httomolibgpu + environment-file: ./docs/source/doc-conda-requirements.yml + + - name: Build api docs + run: sphinx-apidoc -feT -t=./docs/source/_templates -o ./docs/source/api ./httomolibgpu + + - name: Build html + run: sphinx-build -a -E -b html ./docs/source/ ./docs/build/ + + - name: Run ghp-import + run: ghp-import -n -p -f ./docs/build + env: + GITHUB_TOKEN: ${{ github.token }} \ No newline at end of file diff --git a/README.rst b/README.rst index f5251973..5f73f0d8 100644 --- a/README.rst +++ b/README.rst @@ -4,14 +4,15 @@ HTTomolibGPU is a library of GPU accelerated methods for tomography **HTTomolibGPU** is a collection of image processing methods in Python for computed tomography. The methods are GPU-accelerated with the open-source Python library `CuPy `_. Most of the methods migrated from `TomoPy `_ and `Savu `_ software packages. -They have been optimised to ensure higher computational efficiency. +Some of the methods also have been optimised to ensure higher computational efficiency, before ported to CuPy. -Purpose of HTTomolibGPU -======================= +The purpose of HTTomolibGPU +=========================== -**HTTomolibGPU** can be used as a stand-alone library, but it has been specifically developed to -work together with the `HTTomo `_ package. -HTTomo is a user interface (UI) written in Python for fast big data processing using MPI protocols. +**HTTomolibGPU** can be used as a stand-alone library, see `examples `_. +However, it has been specifically developed to work together with the `HTTomo `_ package as +its backend for data processing. HTTomo is a user interface (UI) written in Python for fast big tomographic data processing using +MPI protocols. Install HTTomolibGPU as a pre-built conda Python package ========================================================= @@ -40,7 +41,3 @@ Build HTTomolibGPU as a conda Python package $ conda build conda/recipe/ -c conda-forge -c httomo -c astra-toolbox -c rapidsai -Examples -========= - -There are series of Jupyter Notebooks located in :code:`examples/*` to demonstrate how some of the functions can be used. diff --git a/doc/decorators.rst b/doc/decorators.rst deleted file mode 100644 index a901e0a3..00000000 --- a/doc/decorators.rst +++ /dev/null @@ -1,98 +0,0 @@ -Method Decorators -================= - -All tomography methods exported by the ``httomolib`` package require to be decorated using one -of the ``method_all``, ``method_proj``, or ``method_sino`` decorators. -These add the method to the global ``method_registry`` object, with information about their -supported patterns, module location, parameters, GPU support, etc. -See the relevant documentation about these methods in ``httomolib.decorator`` for a description -of their parameters. - -All these decorators take a function as parameter to determine the maximum number of slices -that the method can process given the amount of available memory on the GPU. -This function is passed using the ``calc_max_slices`` parameter - required for GPU methods (the default). - -Max Slices Calculation ----------------------- - -The ``calc_max_slices`` function must have the following signature:: - - def calc_max_slices(slice_dim: int, - other_dims: Tuple[int, int], - dtype: np.dtype, - available_memory: int, - **kwargs) -> Tuple[int, np.dtype]: ... - -The ``httomo`` package will call this function, passing in the dimension along which it will slice -(``0`` for projection, ``1`` for sinogram), the other dimensions of the data array shape, -the data type for the input, and the avaialble memory on the GPU for method execution. -Additionally it passes all other parameters of the method in the ``kwargs`` argument, -which can be used by the function in case parameters determine the memory consumption. -The function should calculate how many slices along the slicing dimension it can fit into the given memory. -Further, it returns the output datatype of the method (given the input ``dtype`` argument), -which ``httomo`` will use for calling subsequent functions. - -**Example (All Patterns):** - -The ``httomo`` package will have to determine the number of slices along the projection dimension -it can fit, given the other two dimension sizes. For example: - -* ``data.shape`` is ``[x, 10, 20]``, and ``httomo`` needs to determine the value for ``x`` -* The data type for ``data`` is ``float32`` (which means 4 bytes are needed per element) -* Assume the available free memory on the GPU is 14,450 bytes -* It will call the function as:: - - max_slices, outdtype = my_method.meta.calc_max_slices(0, (10, 20), np.float32(), 14450, **method_args) - -* The developer of the given method needs to provide this function implementation, - and it needs to calculate the maximum number of slices it can fit. -* Assuming that the method is very simple and does not need any local temporary memory, - requiring only space for the input and output array, it could be implemented as follows:: - - def _my_calc_max_slices(slice_dim: int, - other_dims: Tuple[int, int], - dtype: np.dtype, - available_memory: int, - **kwargs) -> int: - input_mem_per_slice = other_dims[0] * other_dims[1] * dtype.nbytes - output_mem_per_slice = input_mem_per_slice - max_slices = available_memory // (input_mem_per_slice + output_mem_per_slice) - return max_slices, dtype - - (note that `//` denotes integer division, which rounds towards zero) -* If the method needs extra memory internally, this should be taken into account in the implementation. - There are several methods in this respository which can serve as an example. -* This is then passed to the decorator as follows:: - - @method_all(_my_calc_max_slices) - def my_method(data: cp.ndarray, ...): - ... -* With the example data given above, the function would determine that 9 slices can fit: - - * call ``calc_max_slices(0, (10, 20), np.float32(), 14450, **method_args)`` - * ``input_mem_per_slice = 800`` - * ``output_mem_per_slice = 800`` - * => ``max_slices = 14450 // 1600 = 9`` - -Note also for methods that only support the sinogram or project patterns (a single pattern), -the ``method_proj`` or ``method_sino`` decorators can be used and the ``calc_max_slices`` -function signature simplifies, removing the ``slice_dim`` parameter. - -Max Slices Tests ----------------- - -In order to test that the slice calculation function is reflecting reality, each method has a -unit test implemented that verifies that the calculation is right (within bounds). -That is, it tests that the estimated slices are between 80% and 100% of the actually used slices. -These tests also help to keep the memory estimation functions in sync with the implementation. - -The strategy for testing is the other way around: - -* We first run the actual method, given a specific data set, and record the maximum memory actually - used by the method. -* Then, retrospectively, we call the ``calc_max_slices`` estimator function and pass in this memory - as the ``available_memory`` argument. So we're asking the estimation function to assume that - the memory availalbe is the actually used memory in the method call. -* The estimated number of slices should then be less or equal to the actual slices used earlier. -* To make sure the function is not too conservative, we're checking that it returns at least 80% - of the slices that actually fit. \ No newline at end of file diff --git a/docs/source/__init__.py b/docs/source/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/docs/source/_templates/module.rst_t b/docs/source/_templates/module.rst_t new file mode 100644 index 00000000..bd7adc13 --- /dev/null +++ b/docs/source/_templates/module.rst_t @@ -0,0 +1,7 @@ +{%- if show_headings %}:mod:`{{ basename }}` +============================================ +{%- endif %} +.. automodule:: {{ qualname }} +{%- for option in automodule_options %} + :{{ option }}: +{%- endfor %} diff --git a/docs/source/api/httomolibgpu.cuda_kernels.rst b/docs/source/api/httomolibgpu.cuda_kernels.rst new file mode 100644 index 00000000..7ef07975 --- /dev/null +++ b/docs/source/api/httomolibgpu.cuda_kernels.rst @@ -0,0 +1,10 @@ +httomolibgpu.cuda\_kernels package +================================== + +Module contents +--------------- + +.. automodule:: httomolibgpu.cuda_kernels + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/api/httomolibgpu.cupywrapper.rst b/docs/source/api/httomolibgpu.cupywrapper.rst new file mode 100644 index 00000000..91fd8ed1 --- /dev/null +++ b/docs/source/api/httomolibgpu.cupywrapper.rst @@ -0,0 +1,6 @@ +:mod:`httomolibgpu.cupywrapper` +============================================ +.. automodule:: httomolibgpu.cupywrapper + :members: + :show-inheritance: + :undoc-members: \ No newline at end of file diff --git a/docs/source/api/httomolibgpu.misc.corr.rst b/docs/source/api/httomolibgpu.misc.corr.rst new file mode 100644 index 00000000..ee9c349c --- /dev/null +++ b/docs/source/api/httomolibgpu.misc.corr.rst @@ -0,0 +1,6 @@ +:mod:`httomolibgpu.misc.corr` +============================================ +.. automodule:: httomolibgpu.misc.corr + :members: + :show-inheritance: + :undoc-members: \ No newline at end of file diff --git a/docs/source/api/httomolibgpu.misc.morph.rst b/docs/source/api/httomolibgpu.misc.morph.rst new file mode 100644 index 00000000..37b14602 --- /dev/null +++ b/docs/source/api/httomolibgpu.misc.morph.rst @@ -0,0 +1,6 @@ +:mod:`httomolibgpu.misc.morph` +============================================ +.. automodule:: httomolibgpu.misc.morph + :members: + :show-inheritance: + :undoc-members: \ No newline at end of file diff --git a/docs/source/api/httomolibgpu.misc.rescale.rst b/docs/source/api/httomolibgpu.misc.rescale.rst new file mode 100644 index 00000000..d1c42a3f --- /dev/null +++ b/docs/source/api/httomolibgpu.misc.rescale.rst @@ -0,0 +1,6 @@ +:mod:`httomolibgpu.misc.rescale` +============================================ +.. automodule:: httomolibgpu.misc.rescale + :members: + :show-inheritance: + :undoc-members: \ No newline at end of file diff --git a/docs/source/api/httomolibgpu.misc.rst b/docs/source/api/httomolibgpu.misc.rst new file mode 100644 index 00000000..6a05d823 --- /dev/null +++ b/docs/source/api/httomolibgpu.misc.rst @@ -0,0 +1,20 @@ +httomolibgpu.misc package +========================= + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + httomolibgpu.misc.corr + httomolibgpu.misc.morph + httomolibgpu.misc.rescale + +Module contents +--------------- + +.. automodule:: httomolibgpu.misc + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/api/httomolibgpu.prep.alignment.rst b/docs/source/api/httomolibgpu.prep.alignment.rst new file mode 100644 index 00000000..e0f04ada --- /dev/null +++ b/docs/source/api/httomolibgpu.prep.alignment.rst @@ -0,0 +1,6 @@ +:mod:`httomolibgpu.prep.alignment` +============================================ +.. automodule:: httomolibgpu.prep.alignment + :members: + :show-inheritance: + :undoc-members: \ No newline at end of file diff --git a/docs/source/api/httomolibgpu.prep.normalize.rst b/docs/source/api/httomolibgpu.prep.normalize.rst new file mode 100644 index 00000000..9ebb6370 --- /dev/null +++ b/docs/source/api/httomolibgpu.prep.normalize.rst @@ -0,0 +1,6 @@ +:mod:`httomolibgpu.prep.normalize` +============================================ +.. automodule:: httomolibgpu.prep.normalize + :members: + :show-inheritance: + :undoc-members: \ No newline at end of file diff --git a/docs/source/api/httomolibgpu.prep.phase.rst b/docs/source/api/httomolibgpu.prep.phase.rst new file mode 100644 index 00000000..83cbe74b --- /dev/null +++ b/docs/source/api/httomolibgpu.prep.phase.rst @@ -0,0 +1,6 @@ +:mod:`httomolibgpu.prep.phase` +============================================ +.. automodule:: httomolibgpu.prep.phase + :members: + :show-inheritance: + :undoc-members: \ No newline at end of file diff --git a/docs/source/api/httomolibgpu.prep.rst b/docs/source/api/httomolibgpu.prep.rst new file mode 100644 index 00000000..3b05deaf --- /dev/null +++ b/docs/source/api/httomolibgpu.prep.rst @@ -0,0 +1,21 @@ +httomolibgpu.prep package +========================= + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + httomolibgpu.prep.alignment + httomolibgpu.prep.normalize + httomolibgpu.prep.phase + httomolibgpu.prep.stripe + +Module contents +--------------- + +.. automodule:: httomolibgpu.prep + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/api/httomolibgpu.prep.stripe.rst b/docs/source/api/httomolibgpu.prep.stripe.rst new file mode 100644 index 00000000..12123a20 --- /dev/null +++ b/docs/source/api/httomolibgpu.prep.stripe.rst @@ -0,0 +1,6 @@ +:mod:`httomolibgpu.prep.stripe` +============================================ +.. automodule:: httomolibgpu.prep.stripe + :members: + :show-inheritance: + :undoc-members: \ No newline at end of file diff --git a/docs/source/api/httomolibgpu.recon.algorithm.rst b/docs/source/api/httomolibgpu.recon.algorithm.rst new file mode 100644 index 00000000..bec9bea2 --- /dev/null +++ b/docs/source/api/httomolibgpu.recon.algorithm.rst @@ -0,0 +1,6 @@ +:mod:`httomolibgpu.recon.algorithm` +============================================ +.. automodule:: httomolibgpu.recon.algorithm + :members: + :show-inheritance: + :undoc-members: \ No newline at end of file diff --git a/docs/source/api/httomolibgpu.recon.rotation.rst b/docs/source/api/httomolibgpu.recon.rotation.rst new file mode 100644 index 00000000..515c70ee --- /dev/null +++ b/docs/source/api/httomolibgpu.recon.rotation.rst @@ -0,0 +1,6 @@ +:mod:`httomolibgpu.recon.rotation` +============================================ +.. automodule:: httomolibgpu.recon.rotation + :members: + :show-inheritance: + :undoc-members: \ No newline at end of file diff --git a/docs/source/api/httomolibgpu.recon.rst b/docs/source/api/httomolibgpu.recon.rst new file mode 100644 index 00000000..105ad389 --- /dev/null +++ b/docs/source/api/httomolibgpu.recon.rst @@ -0,0 +1,19 @@ +httomolibgpu.recon package +========================== + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + httomolibgpu.recon.algorithm + httomolibgpu.recon.rotation + +Module contents +--------------- + +.. automodule:: httomolibgpu.recon + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/api/httomolibgpu.rst b/docs/source/api/httomolibgpu.rst new file mode 100644 index 00000000..9de44c43 --- /dev/null +++ b/docs/source/api/httomolibgpu.rst @@ -0,0 +1,29 @@ +httomolibgpu package +==================== + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + httomolibgpu.cuda_kernels + httomolibgpu.misc + httomolibgpu.prep + httomolibgpu.recon + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + httomolibgpu.cupywrapper + +Module contents +--------------- + +.. automodule:: httomolibgpu + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/bibliography/biblio.rst b/docs/source/bibliography/biblio.rst new file mode 100644 index 00000000..c3497111 --- /dev/null +++ b/docs/source/bibliography/biblio.rst @@ -0,0 +1,8 @@ +.. only:: html + + ************ + Bibliography + ************ + +.. bibliography:: references.bib + :style: plain diff --git a/docs/source/bibliography/references.bib b/docs/source/bibliography/references.bib new file mode 100644 index 00000000..a9c3ca5c --- /dev/null +++ b/docs/source/bibliography/references.bib @@ -0,0 +1,91 @@ +@article{Paganin02, + title={Simultaneous phase and amplitude extraction from a single defocused image of a homogeneous object}, + author={Paganin, David and Mayo, Sheridan C and Gureyev, Tim E and Miller, Peter R and Wilkins, Steve W}, + journal={Journal of microscopy}, + volume={206}, + number={1}, + pages={33--40}, + year={2002}, + publisher={Wiley Online Library} +} +@article{vo2021data, + title={Data processing methods and data acquisition for samples larger than the field of view in parallel-beam tomography}, + author={Vo, Nghia T and Atwood, Robert C and Drakopoulos, Michael and Connolley, Thomas}, + journal={Optics Express}, + volume={29}, + number={12}, + pages={17849--17874}, + year={2021}, + publisher={Optica Publishing Group} +} +@article{vo2014reliable, + title={Reliable method for calculating the center of rotation in parallel-beam tomography}, + author={Vo, Nghia T and Drakopoulos, Michael and Atwood, Robert C and Reinhard, Christina}, + journal={Optics express}, + volume={22}, + number={16}, + pages={19078--19086}, + year={2014}, + publisher={Optica Publishing Group} +} +@article{guizar2008efficient, + title={Efficient subpixel image registration algorithms}, + author={Guizar-Sicairos, Manuel and Thurman, Samuel T and Fienup, James R}, + journal={Optics letters}, + volume={33}, + number={2}, + pages={156--158}, + year={2008}, + publisher={Optica Publishing Group} +} +@article{vo2018superior, + title={Superior techniques for eliminating ring artifacts in X-ray micro-tomography}, + author={Vo, Nghia T and Atwood, Robert C and Drakopoulos, Michael}, + journal={Optics express}, + volume={26}, + number={22}, + pages={28396--28412}, + year={2018}, + publisher={Optica Publishing Group} +} +@article{titarenko2010analytical, + title={An analytical formula for ring artefact suppression in X-ray tomography}, + author={Titarenko, Sofya and Withers, Philip J and Yagola, Anatoly}, + journal={Applied Mathematics Letters}, + volume={23}, + number={12}, + pages={1489--1495}, + year={2010}, + publisher={Elsevier} +} +@article{vo2015radial, + title={Radial lens distortion correction with sub-pixel accuracy for X-ray micro-tomography}, + author={Vo, Nghia T and Atwood, Robert C and Drakopoulos, Michael}, + journal={Optics express}, + volume={23}, + number={25}, + pages={32859--32868}, + year={2015}, + publisher={Optica Publishing Group} +} +@article{van2016fast, + title={Fast and flexible X-ray tomography using the ASTRA toolbox}, + author={Van Aarle, Wim and Palenstijn, Willem Jan and Cant, Jeroen and Janssens, Eline and Bleichrodt, Folkert and Dabravolski, Andrei and De Beenhouwer, Jan and Batenburg, K Joost and Sijbers, Jan}, + journal={Optics express}, + volume={24}, + number={22}, + pages={25129--25147}, + year={2016}, + publisher={Optica Publishing Group} +} + +@inproceedings{kazantsev2020tomographic, + title={TOmographic MOdel-BAsed Reconstruction (ToMoBAR) software for high resolution synchrotron X-ray tomography}, + author={Kazantsev, Daniil and Wadeson, Nicola}, + booktitle={CT Meeting}, + volume={2020}, + year={2020} +} + + + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..b5fea06c --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,114 @@ +# -- General configuration ------------------------------------------------ +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +#!/usr/bin/env python +import os +import sys +from datetime import date +from unittest import mock + + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. + +sys.path.insert(0, os.path.abspath("../..")) + +# -- Mock imports ------------------------------------------------------------- + + +# Mock imports instead of full environment in readthedocs +MOCK_MODULES = [ + "numpy", + "nvtx", + "cupy", + "cupyx", + "PIL", + "skimage", + "scipy", + "scipy.fft", + "scipy.ndimage", +] + +for mod_name in MOCK_MODULES: + sys.modules[mod_name] = mock.Mock() + +# ------------------------------------------------------------------------------ + +project = "HTTomolibgpu" +copyright = f"{date.today().year}, Diamond Light Source" + +# Specify a base language to help assistive technology +language = "en" + +# Save the commit hash, this is displayed in the page title +release = os.popen('git log -1 --format="%H"').read().strip() + +# Set version as the latest tag in the current branch +version = os.popen("git describe --tags --abbrev=0").read().strip() + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + # Generates api files + "sphinx.ext.autodoc", + # Generates a short summary from docstring + "sphinx.ext.autosummary", + # Allows parsing of google style docstrings + "sphinx.ext.napoleon", + # Add links to highlighted source code + "sphinx.ext.viewcode", + # Allows a grid layout and dropdown boxes + "sphinx_panels", + # copy to clipboard button + "sphinx_copybutton", + #'IPython.sphinxext.ipython_console_highlighting', + "sphinx.ext.githubpages", + # Generate .nojekyll file for git pages build + "sphinxcontrib.bibtex", + # required for bibtex reference generation + "nbsphinx", + # required for jupyter notebook +] + +bibtex_bibfiles = ["bibliography/references.bib"] + +autosummary_generate = True +numfig = True +template_patterns = ["_templates"] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + +# -- Options for HTML output -------------------------------------------------- + +html_theme = "sphinx_book_theme" +html_title = "HTTomolibgpu Documentation page" +html_copy_source = True +html_last_updated_fmt = "" +html_static_path = ["_static"] +html_use_smartypants = True + +""" +html_theme_options = { + "logo_only": True, + "display_version": False, + "githuburl": "https://github.com/DiamondLightSource/httomolibgpu", +} +""" + +html_theme_options = { + "show_toc_level": 1, + "navbar_align": "left", # [left, content, right] For testing that the navbar items align properly +} + +html_context = { + "github_user": "httomolibgpu", + "github_repo": "https://github.com/DiamondLightSource/httomolibgpu", + "github_version": "main", + "doc_path": "docs", +} + + +def setup(app): + app.add_css_file("css/general.css") diff --git a/docs/source/css/general.css b/docs/source/css/general.css new file mode 100644 index 00000000..ff71c1de --- /dev/null +++ b/docs/source/css/general.css @@ -0,0 +1,4 @@ +/* Colour dropdown for dark mode */ +.sphinx-bs.dropdown.card{ + background-color: var(--pst-color-surface); +} \ No newline at end of file diff --git a/docs/source/doc-conda-requirements.yml b/docs/source/doc-conda-requirements.yml new file mode 100644 index 00000000..c7517ff4 --- /dev/null +++ b/docs/source/doc-conda-requirements.yml @@ -0,0 +1,14 @@ +name: httomolibgpu +channels: + - conda-forge + - defaults +dependencies: + - python=3.10 + - sphinx + - sphinx-book-theme + - jinja2 + - sphinx-panels + - sphinx-copybutton + - sphinxcontrib-bibtex + - pyyaml + - ghp-import diff --git a/examples/DistortionCorr.ipynb b/docs/source/examples/DistortionCorr.ipynb similarity index 99% rename from examples/DistortionCorr.ipynb rename to docs/source/examples/DistortionCorr.ipynb index 367b76df..9cb31159 100644 --- a/examples/DistortionCorr.ipynb +++ b/docs/source/examples/DistortionCorr.ipynb @@ -4,34 +4,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### This example shows how to use methods from the httomolibgpu library to do the following:\n", - "* perform distortion correction" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "____! BM3D module is required to use for dynamic flat fields calculation !____\n", - "____! CCPi-regularisation package (CuPy part needed only) is missing, please install !____\n", - "____! CCPi-regularisation package is missing, please install to support regularisation !____\n", - "____! Wavelet package pywpt is missing, please install for wavelet regularisation !____\n" - ] - } - ], - "source": [ - "import os\n", - "import matplotlib.pyplot as plt\n", - "from imageio.v2 import imread, imwrite\n", - "\n", - "import cupy as cp\n", - "import numpy as np\n", - "import httomolibgpu" + "### Example 3 (Distortion corr)" ] }, { diff --git a/examples/pipeline1_FBP.ipynb b/docs/source/examples/pipeline1_FBP.ipynb similarity index 99% rename from examples/pipeline1_FBP.ipynb rename to docs/source/examples/pipeline1_FBP.ipynb index 65ecae12..a6372f58 100644 --- a/examples/pipeline1_FBP.ipynb +++ b/docs/source/examples/pipeline1_FBP.ipynb @@ -4,35 +4,17 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### This example shows how to use methods from the httomolibgpu library to do the following:\n", - "* normalise the data \n", - "* calculate the centre of rotation \n", - "* reconstruct using the FBP algorithm" + "### Example 1 (FBP)" ] }, { - "cell_type": "code", - "execution_count": 1, + "cell_type": "markdown", "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "____! BM3D module is required to use for dynamic flat fields calculation !____\n", - "____! CCPi-regularisation package (CuPy part needed only) is missing, please install !____\n", - "____! CCPi-regularisation package is missing, please install to support regularisation !____\n", - "____! Wavelet package pywpt is missing, please install for wavelet regularisation !____\n" - ] - } - ], "source": [ - "import os\n", - "import matplotlib.pyplot as plt\n", - "\n", - "import cupy as cp\n", - "import numpy as np\n", - "import httomolibgpu" + "#### This example shows how to use methods from the HTTomolibgpy library to do the following:\n", + "* normalise the data \n", + "* calculate the centre of rotation \n", + "* reconstruct using the FBP algorithm" ] }, { diff --git a/examples/pipeline2_iterative.ipynb b/docs/source/examples/pipeline2_iterative.ipynb similarity index 99% rename from examples/pipeline2_iterative.ipynb rename to docs/source/examples/pipeline2_iterative.ipynb index 173198da..78404ea8 100644 --- a/examples/pipeline2_iterative.ipynb +++ b/docs/source/examples/pipeline2_iterative.ipynb @@ -4,35 +4,18 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### This example shows how to use methods from the httomolibgpu library to do the following:\n", - "* normalise the data \n", - "* calculate the centre of rotation \n", - "* reconstruct using the iterative algorithm" + "### Example 2 (Iterative Rec)" ] }, { - "cell_type": "code", - "execution_count": 1, + "cell_type": "markdown", "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "____! BM3D module is required to use for dynamic flat fields calculation !____\n", - "____! CCPi-regularisation package (CuPy part needed only) is missing, please install !____\n", - "____! CCPi-regularisation package is missing, please install to support regularisation !____\n", - "____! Wavelet package pywpt is missing, please install for wavelet regularisation !____\n" - ] - } - ], "source": [ - "import os\n", - "import matplotlib.pyplot as plt\n", + "#### This example shows how to use methods from the HTTomolibgpu library to do the following:\n", "\n", - "import cupy as cp\n", - "import numpy as np\n", - "import httomolibgpu" + "* normalise the data \n", + "* calculate the centre of rotation \n", + "* reconstruct using the iterative algorithm" ] }, { diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..ec0a2d97 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,30 @@ +.. include:: ../../README.rst + +.. _intro_content: + +.. toctree:: + :caption: Introduction + :maxdepth: 2 + :glob: + + introduction/about + +.. _jn_examples: + +.. toctree:: + :caption: Examples + :titlesonly: + :hidden: + + examples/pipeline1_FBP + examples/pipeline2_iterative + examples/DistortionCorr + +.. _reference_content: + +.. toctree:: + :caption: Reference guides + :maxdepth: 2 + + reference/api + bibliography/biblio \ No newline at end of file diff --git a/docs/source/introduction/about.rst b/docs/source/introduction/about.rst new file mode 100644 index 00000000..81e636b2 --- /dev/null +++ b/docs/source/introduction/about.rst @@ -0,0 +1,4 @@ +HTTomolibGPU +************ + +.. include:: ../../../README.rst diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst new file mode 100644 index 00000000..e767bbb8 --- /dev/null +++ b/docs/source/reference/api.rst @@ -0,0 +1,23 @@ +========================== +API reference +========================== + +This section contains the API reference and usage information for HttomolibGPU. + +HTTomolibGPU Modules +--------------------- +v.2.0 +''''' + +.. toctree:: + :glob: + + ../api/httomolibgpu.misc.corr + ../api/httomolibgpu.misc.morph + ../api/httomolibgpu.misc.rescale + ../api/httomolibgpu.prep.alignment + ../api/httomolibgpu.prep.normalize + ../api/httomolibgpu.prep.phase + ../api/httomolibgpu.prep.stripe + ../api/httomolibgpu.recon.algorithm + ../api/httomolibgpu.recon.rotation \ No newline at end of file diff --git a/docs/sphinx-build.sh b/docs/sphinx-build.sh new file mode 100644 index 00000000..ccd3a7d0 --- /dev/null +++ b/docs/sphinx-build.sh @@ -0,0 +1,40 @@ +#!/bin/bash + +echo "***********************************************************************" +echo " Starting the sphinx script" +echo "***********************************************************************" +echo " Creating plugin API files and html pages .." + +DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" + +# members will document all modules +# undoc keeps modules without docstrings +# show-inheritance displays a list of base classes below the class signature +export SPHINX_APIDOC_OPTIONS='members,show-inheritance,undoc-members' + +# Remove directory for api so that there are no obsolete files +rm -rf $DIR/source/api/ +rm -rf $DIR/build/ + +# sphinx-apidoc [options] -o [pathnames to exclude] +# -f, --force. Usually, apidoc does not overwrite files, unless this option is given. +# -e, --separate. Put each module file in its own page. +# -T, --no-toc. Do not create a table of contents file. +# -E, --no-headings. Do not create headings for the modules/packages. This is useful, for example, when docstrings already contain headings. +# -t template directory +# add -Q to suppress warnings + +# sphinx-apidoc generates source files that use sphinx.ext.autodoc to document all found modules +sphinx-apidoc -feT -t=$DIR/source/_templates -o $DIR/source/api $DIR/../httomolibgpu + +# sphinx-build [options] [filenames] +# -a Write all output files. The default is to only write output files for new and changed source files. (This may not apply to all builders.) +# -E Don’t use a saved environment (the structure caching all cross-references), but rebuild it completely. The default is to only read and parse source files that are new or have changed since the last run. +# -b buildername, build pages of a certain file type +sphinx-build -a -E -b html $DIR/source/ $DIR/build/ + + +echo "***********************************************************************" +echo " End of script" +echo "***********************************************************************" + diff --git a/docs/sphinx_build_setup.rst b/docs/sphinx_build_setup.rst new file mode 100644 index 00000000..c3341fe7 --- /dev/null +++ b/docs/sphinx_build_setup.rst @@ -0,0 +1,38 @@ +=================================== +How to build the html pages locally +=================================== + +Create a conda environment +========================== + +Setup a new conda environment using the requirements file docs/source/doc-conda-requirements.yml +If you are using a diamond computer you can load python into your path to do this. + + >>> module load python + >>> conda env create --prefix /path/to/env/doc-env --file /path/to/httomolibgpu/docs/source/doc-conda-requirements.yml + + +Update API documentation and build +================================== + +While inside your virtual environment, run the sphinx-build.sh script. + + >>> conda activate /path/to/env/doc-env + >>> source /path/to/httomolibgpu/docs/sphinx-build.sh + +The script will: + +1. Remove previous api and build directories. +2. Generate current httomolibgpu api files +3. Run a python script to add yaml file downloads for every function for every module rst file. +4. Run sphinx to create html documentation pages in docs/build. + +You can view the completed pages by opening the httomolibgpu/docs/build/index.html page inside a browser. + +To conclude +=========== + +When you have finished, you can deactivate the virtual environment and remove python from your path. + + >>> conda deactivate + >>> module unload python diff --git a/httomolibgpu/misc/morph.py b/httomolibgpu/misc/morph.py index 098d1712..61190689 100644 --- a/httomolibgpu/misc/morph.py +++ b/httomolibgpu/misc/morph.py @@ -40,7 +40,7 @@ def sino_360_to_180( """ Converts 0-360 degrees sinogram to a 0-180 sinogram. If the number of projections in the input data is odd, the last projection - will be discarded. + will be discarded. See :cite:`vo2021data`. Parameters ---------- diff --git a/httomolibgpu/prep/alignment.py b/httomolibgpu/prep/alignment.py index 480db1af..e9d1dcc1 100644 --- a/httomolibgpu/prep/alignment.py +++ b/httomolibgpu/prep/alignment.py @@ -45,7 +45,7 @@ def distortion_correction_proj_discorpy( order: int = 1, mode: str = "reflect", ): - """Unwarp a stack of images using a backward model. + """Unwarp a stack of images using a backward model. See :cite:`vo2015radial`. Parameters ---------- diff --git a/httomolibgpu/prep/phase.py b/httomolibgpu/prep/phase.py index a6febe10..3df2f80e 100644 --- a/httomolibgpu/prep/phase.py +++ b/httomolibgpu/prep/phase.py @@ -293,8 +293,8 @@ def paganin_filter_tomopy( alpha: float = 1e-3, ) -> cp.ndarray: """ - Perform single-material phase retrieval from flats/darks corrected tomographic measurements - :cite:`Paganin:02`. + Perform single-material phase retrieval from flats/darks corrected tomographic measurements. See + :cite:`Paganin02` for a reference. Parameters ---------- diff --git a/httomolibgpu/prep/stripe.py b/httomolibgpu/prep/stripe.py index 46ba04a0..928e8dff 100644 --- a/httomolibgpu/prep/stripe.py +++ b/httomolibgpu/prep/stripe.py @@ -42,14 +42,12 @@ def remove_stripe_based_sorting( ) -> Union[cp.ndarray, np.ndarray]: """ Remove full and partial stripe artifacts from sinogram using Nghia Vo's - approach, algorithm 3 in Ref. [1]. Angular direction is along the axis 0. - This algorithm works particularly well for removing partial stripes. + approach, see :cite:`vo2018superior`. This algorithm works particularly + well for removing partial stripes. - Steps of the algorithm: - 1. Sort each column of the sinogram by its grayscale values. - 2. Apply a smoothing (median) filter on the sorted image along each row. - 3. Re-sort the smoothed image columns to the original rows to - get the corrected sinogram. + Steps of the algorithm: 1. Sort each column of the sinogram by its grayscale values. + 2. Apply a smoothing (median) filter on the sorted image along each row. 3. Re-sort the smoothed image columns to the original rows to + get the corrected sinogram. Parameters ---------- @@ -65,9 +63,6 @@ def remove_stripe_based_sorting( ndarray Corrected 3D tomographic data as a CuPy or NumPy array. - References - ---------- - .. [1] https://doi.org/10.1364/OE.26.028396 """ if cupywrapper.cupy_run: return __remove_stripe_based_sorting(data, size, dim) @@ -126,7 +121,8 @@ def remove_stripe_ti( beta: float = 0.1, ) -> Union[cp.ndarray, np.ndarray]: """ - Removes stripes with the method of V. Titarenko (TomoCuPy implementation) + Removes stripes with the method of V. Titarenko (TomoCuPy implementation). + See :cite:`titarenko2010analytical`. Parameters ---------- @@ -199,7 +195,7 @@ def remove_all_stripe( ) -> cp.ndarray: """ Remove all types of stripe artifacts from sinogram using Nghia Vo's - approach :cite:`Vo:18` (combination of algorithm 3,4,5, and 6). + approach, see :cite:`vo2018superior` (combination of algorithm 3,4,5, and 6). Parameters ---------- @@ -220,10 +216,6 @@ def remove_all_stripe( ndarray Corrected 3D tomographic data as a CuPy or NumPy array. - References - ---------- - .. [1] https://doi.org/10.1364/OE.26.028396 - """ if cupywrapper.cupy_run: return __remove_all_stripe(data, snr, la_size, sm_size, dim) diff --git a/httomolibgpu/recon/algorithm.py b/httomolibgpu/recon/algorithm.py index 1de5400d..1e294946 100644 --- a/httomolibgpu/recon/algorithm.py +++ b/httomolibgpu/recon/algorithm.py @@ -49,8 +49,9 @@ def FBP( gpu_id: int = 0, ) -> cp.ndarray: """ - Perform Filtered Backprojection (FBP) reconstruction using ASTRA toolbox and ToMoBAR wrappers. - This is a 3D recon from a CuPy array and a custom built filter. + Perform Filtered Backprojection (FBP) reconstruction using ASTRA toolbox :cite:`van2016fast` and + ToMoBAR :cite:`kazantsev2020tomographic` wrappers. + This is a 3D recon from a CuPy array directly and a custom built filter. Parameters ---------- @@ -128,7 +129,8 @@ def SIRT( gpu_id: int = 0, ) -> cp.ndarray: """ - Perform Simultaneous Iterative Recostruction Technique (SIRT) using ASTRA toolbox and ToMoBAR wrappers. + Perform Simultaneous Iterative Recostruction Technique (SIRT) using ASTRA toolbox :cite:`van2016fast` and + ToMoBAR :cite:`kazantsev2020tomographic` wrappers. This is 3D recon directly from a CuPy array while using ASTRA GPUlink capability. Parameters @@ -208,7 +210,8 @@ def CGLS( gpu_id: int = 0, ) -> cp.ndarray: """ - Perform Congugate Gradient Least Squares (CGLS) using ASTRA toolbox and ToMoBAR wrappers. + Perform Congugate Gradient Least Squares (CGLS) using ASTRA toolbox :cite:`van2016fast` and + ToMoBAR :cite:`kazantsev2020tomographic` wrappers. This is 3D recon directly from a CuPy array while using ASTRA GPUlink capability. Parameters diff --git a/httomolibgpu/recon/rotation.py b/httomolibgpu/recon/rotation.py index dbade838..fe6acc47 100644 --- a/httomolibgpu/recon/rotation.py +++ b/httomolibgpu/recon/rotation.py @@ -18,7 +18,7 @@ # Created By : Tomography Team at DLS # Created Date: 01 November 2022 # --------------------------------------------------------------------------- -"""Modules for finding the axis of rotation""" +"""Modules for finding the axis of rotation for 180 and 360 degrees scans""" import numpy as np from httomolibgpu import cupywrapper @@ -48,8 +48,8 @@ def find_center_vo( drop: int = 20, ) -> float: """ - Find rotation axis location using Nghia Vo's method. See the paper - https://opg.optica.org/oe/fulltext.cfm?uri=oe-22-16-19078&id=297315 + Find rotation axis location (aka CoR) using Nghia Vo's method. See the paper + :cite:`vo2014reliable`. Parameters ---------- @@ -384,8 +384,6 @@ def _downsample(sino, level, axis): ##%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% # # %%%%%%%%%%%%%%%%%%%%%%%%%find_center_360%%%%%%%%%%%%%%%%%%%%%%%%% # --- Center of rotation (COR) estimation method ---# - - def find_center_360( data: cp.ndarray, ind: Optional[int] = None, @@ -396,11 +394,8 @@ def find_center_360( use_overlap: bool = False, ) -> Tuple[float, float, Optional[Literal[0, 1]], float]: """ - Find the center-of-rotation (COR) in a 360-degree scan with offset COR use - the method presented in Ref. [1] by Nghia Vo. - - This function supports both numpy and cupy - the implementation is selected - by where the input data array resides. + Find the center-of-rotation (COR) in a 360-degree scan and also an offset + to perform data transformation from 360 to 180 degrees scan. See :cite:`vo2021data`. Parameters ---------- @@ -433,10 +428,6 @@ def find_center_360( overlap_position : float Position of the window in the first image giving the best correlation metric. - - References - ---------- - [1] : https://doi.org/10.1364/OE.418448 """ if cupywrapper.cupy_run: @@ -752,11 +743,11 @@ def find_center_pc( phase correlation in Fourier space. The `phase_cross_correlation` function uses cross-correlation in Fourier space, optionally employing an upsampled matrix-multiplication DFT to - achieve arbitrary subpixel precision. :cite:`Guizar:08`. + achieve arbitrary subpixel precision. See :cite:`guizar2008efficient`. Args: - proj1 (cp.ndarray): Projection from the 0th degree - proj2 (cp.ndarray): Projection from the 180th degree + proj1 (cp.ndarray): Projection from the 0th degree angle. + proj2 (cp.ndarray): Projection from the 180th degree angle. tol (float, optional): Subpixel accuracy. Defaults to 0.5. rotc_guess (float, optional): Initial guess value for the rotation center. Defaults to None. From ea09d85aafdfd60b3355ae1c2639e3c317006a31 Mon Sep 17 00:00:00 2001 From: dkazanc Date: Wed, 8 May 2024 14:46:40 +0100 Subject: [PATCH 2/3] adding nbsphinx dependency --- docs/source/doc-conda-requirements.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/doc-conda-requirements.yml b/docs/source/doc-conda-requirements.yml index c7517ff4..284b1026 100644 --- a/docs/source/doc-conda-requirements.yml +++ b/docs/source/doc-conda-requirements.yml @@ -10,5 +10,6 @@ dependencies: - sphinx-panels - sphinx-copybutton - sphinxcontrib-bibtex + - nbsphinx - pyyaml - ghp-import From 7d333f905f23890c93fdae067656f324e4a21420 Mon Sep 17 00:00:00 2001 From: dkazanc Date: Wed, 8 May 2024 15:08:03 +0100 Subject: [PATCH 3/3] adds to readme --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 5f73f0d8..2f7cfbf9 100644 --- a/README.rst +++ b/README.rst @@ -9,7 +9,7 @@ Some of the methods also have been optimised to ensure higher computational effi The purpose of HTTomolibGPU =========================== -**HTTomolibGPU** can be used as a stand-alone library, see `examples `_. +**HTTomolibGPU** can be used as a stand-alone library, see Examples section in `Documentation `_. However, it has been specifically developed to work together with the `HTTomo `_ package as its backend for data processing. HTTomo is a user interface (UI) written in Python for fast big tomographic data processing using MPI protocols.