Commit 8ce9c2f0 authored by payno's avatar payno
Browse files

[doc] rework documentation

- add an example file to present a quick start documentation
- group API in a dedicated place
- several small fix on doc (types, param name not specify for :type: ...)
parent 40af0014
Pipeline #30947 failed with stages
in 2 minutes and 6 seconds
......@@ -34,7 +34,7 @@ project = u'tomoscan'
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# Add any Sphinx extension modules names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
......@@ -93,7 +93,7 @@ exclude_patterns = ['build', '**.ipynb_checkpoints']
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# If true, the current modules name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
......@@ -104,7 +104,7 @@ exclude_patterns = ['build', '**.ipynb_checkpoints']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# A list of ignored prefixes for modules index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
......@@ -169,7 +169,7 @@ html_logo = "img/tomoscan.png"
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
# If false, no modules index is generated.
#html_domain_indices = True
# If false, no index is generated.
......@@ -253,7 +253,7 @@ latex_elements = {
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
# If false, no modules index is generated.
#latex_domain_indices = True
......@@ -289,7 +289,7 @@ texinfo_documents = [
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
# If false, no modules index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
......
Examples
========
Quick Start
-----------
The goal is to have an unified API to access data from an EDF acquisition or an HDF5 acquisition.
EDF scan
''''''''
To create a 'Scan' object from EDF you have to use the :class:`EDFTomoScan` class and provide the path to the acquisition:
.. code-block:: python
scan = EDFTomoScan(scan=folder_path)
.. warning:: Browsing EDF files is based on several convention at ESRF.
The most important one is that the acquisition 'identification' - which is the folder name is repeated in the file names.
For example if we have an acquisition names 'acq_0005' we expect edf file prefix to be 'acq_0005' too.
.. warning:: The :class:`EDFTomoScan` as been tested on EDF single frame files. It wouldn't be surprising if it fails on EDF multiple frames files.
HDF5 scan
'''''''''
.. warning:: The HDF5 managed by tomoscan should be NXTomo compliant. So if your files come directly from bliss you should first convert them using `nxtomomill <https://gitlab.esrf.fr/tomotools/nxtomomill>`_.
See `tomoh52nx tutorial <https://tomotools.gitlab-pages.esrf.fr/nxtomomill/tutorials/tomoh52nx.html>`_.
For HDF5 you have to provide the file you want to tread (.hdf5, .h5, .nx...) and an entry as HDF5 files can contains several acquisition.
.. code-block:: python
scan = HDF5TomoScan(scan=hdf5_files, entry='entry0000')
TomoScanBase API
''''''''''''''''
Both :class:`EDFTomoScan` and :class:`HDF5TomoScan` are implementing the TomoScanBase interface.
This allow you to access flattely data from EDF or HDF5 regardless of the type of acquisition.
You can access:
* projections:
.. code-block:: python
scan.projections
* flats:
.. code-block:: python
scan.flats
* darks:
.. code-block:: python
scan.darks
* incoming beam energy:
.. code-block:: python
scan.energy
* detector pixel size:
.. code-block:: python
scan.pixel_size
* ...
\ No newline at end of file
......@@ -3,10 +3,20 @@ tomoscan
tomoscan aims to provide an unified interface to read tomography data from .edf or .hdf5 (NXtomo) acquisitions.
This one tool to get an unified API from EDF or HDF5 acquisitions.
You can also convert EDF dataset to obtain an HDF5 - NXTomo compliant file by using `nxtomomill <https://gitlab.esrf.fr/tomotools/nxtomomill>`_.
See the `tomoedf2nx tutorial <https://tomotools.gitlab-pages.esrf.fr/nxtomomill/tutorials/tomoedf2nx.html>`_.
tomoscan will not produce any other file.
.. toctree::
:maxdepth: 4
:hidden:
modules/index.rst
examples
:doc:`examples`
esrf
scanbase
scanfactory
unitsystem
:doc:`modules/index`
API
===
.. toctree::
:maxdepth: 4
esrf.rst
scanbase.rst
scanfactory.rst
unitsystem.rst
\ No newline at end of file
{
"cells": [
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.7.3"
}
},
"nbformat": 4,
"nbformat_minor": 4
}
%% Cell type:code id: tags:
``` python
```
......@@ -52,11 +52,11 @@ class EDFTomoScan(TomoScanBase):
TomoScanBase instanciation for scan defined from .edf files
:param scan: path to the root folder containing the scan.
:type: Union[str,None]
:type scan: Union[str,None]
:param n_frames: Number of frames in each EDF file.
If not provided, it will be inferred by reading the files.
In this case, the frame number is guessed from the file name.
:type: Union[int, None]=None
:type n_frames: Union[int, None]=None
"""
_TYPE = 'edf'
......@@ -264,10 +264,10 @@ class EDFTomoScan(TomoScanBase):
ending by .edf
:param scan: is the path to the folder of acquisition
:type: str
:type scan: str
:param n_frames: Number of frames in each EDF file.
If not provided, it is inferred by reading each file.
:type: int
:type n_frames: int
:return: dict of radios files with radio index as key and file as value
:rtype: dict
"""
......@@ -480,11 +480,11 @@ class EDFTomoScan(TomoScanBase):
"""
:param scan_path:
:type: str
:type scan_path: str
:param prefix: ref / flat field file prefix
:type: str
:type prefix: str
:param file_ext: ref / flat field file extension
:type: str
:type file_ext: str
:return: list of refs as silx's `DataUrl`
"""
res = {}
......@@ -514,11 +514,11 @@ class EDFTomoScan(TomoScanBase):
"""
:param scan_path:
:type: str
:type scan_path: str
:param prefix: ref / flat field file prefix
:type: str
:type prefix: str
:param file_ext: ref / flat field file extension
:type: str
:type file_ext: str
:return: list of refs as silx's `DataUrl`
"""
res = {}
......@@ -575,11 +575,11 @@ class EDFTomoScan(TomoScanBase):
:param ref_file: the refXXXX_YYYY which should contain information
about the scan.
:param key: the key (information) we are looking for
:type: str
:type key: str
:param type_: requestde out type if the information is found
:type type_: return type if the information is found.
:param key_aliases: aliases of the key in the different file
:type: list
:type key_aliases: list
:return: the requested information or None if not found
"""
info_aliases = [key]
......
......@@ -651,11 +651,9 @@ class HDF5TomoScan(TomoScanBase):
"""
Return a compacted view of projection frames.
Returns
--------
merged_projections: dict
Dictionary where the key is a list of indices, and the value
:return: Dictionary where the key is a list of indices, and the value
is the corresponding `silx.io.url.DataUrl` with merged data_slice
:rtype: dict
"""
if self._projections_compacted is None:
self._projections_compacted = get_compacted_dataslices(self.projections)
......
......@@ -41,7 +41,7 @@ def get_parameters_frm_par_or_info(file_: str) -> dict:
their values as values
:param file_: path to the file to parse
:type:str
:type file_: str
:raises: ValueError when fail to parse some line.
"""
assert os.path.exists(file_) and os.path.isfile(file_)
......@@ -67,15 +67,17 @@ def get_parameters_frm_par_or_info(file_: str) -> dict:
return ddict
def extract_urls_from_edf(file_: str, start_index: Union[None, int], n_frames: Union[int, None]=None) -> dict:
"""return one DataUrl for each frame contain in the file_
def extract_urls_from_edf(file_: str, start_index: Union[None, int],
n_frames: Union[int, None]=None) -> dict:
"""
return one DataUrl for each frame contain in the file_
:param file_: path to the file to parse
:type:str
:type file_: str
:param n_frames: Number of frames in each edf file (inferred if not told)
:type: Union[int, None]
:type n_frames: Union[int, None]
:param start_index:
:type: Union[None,start_index]
:type start_index: Union[None,start_index]
"""
res = {}
index = 0 if start_index is None else start_index
......@@ -96,17 +98,12 @@ def get_compacted_dataslices(urls):
how to load the data: `{indices_set: data_location}`
where `data_location` contains contiguous indices.
Parameters
-----------
urls: dict
Dictionary where the key is an integer and the value is a silx `DataUrl`.
Returns
--------
merged_urls: dict
Dictionary where the key is a list of indices, and the value
is the corresponding `silx.io.url.DataUrl` with merged data_slice
:param dict urls: Dictionary where the key is an integer and the value is
a silx `DataUrl`.
:return: Dictionary where the key is a list of indices, and the value is
the corresponding `silx.io.url.DataUrl` with merged data_slice
:rtype: dict
"""
def _convert_to_slice(idx):
if numpy.isscalar(idx):
......
......@@ -21,7 +21,7 @@
# THE SOFTWARE.
#
#############################################################################*/
"""This module contains base class for TomoScanBase"""
"""This modules contains base class for TomoScanBase"""
__authors__ = ["H.Payno"]
__license__ = "MIT"
......@@ -51,7 +51,7 @@ class TomoScanBase:
projections, dark and flat field...
:param scan: path to the root folder containing the scan.
:type: Union[str,None]
:type scan: Union[str,None]
"""
DICT_TYPE_KEY = 'type'
......@@ -236,7 +236,7 @@ class TomoScanBase:
Load properties contained in the dictionnary.
:param _dict: dictionary to load
:type: dict
:type _dict: dict
:return: self
:raises: ValueError if dict is invalid
"""
......@@ -247,8 +247,9 @@ class TomoScanBase:
:param :class:`.ScanBase` other: instance to compare with
:return: True if instance are equivalent
:note: we cannot use the __eq__ function because this object need to be
pickable
..note:: we cannot use the __eq__ function because this object need to be
pickable
"""
return (
isinstance(other, self.__class__) or isinstance(self, other.__class__) and
......@@ -274,23 +275,29 @@ class TomoScanBase:
map given urls to an angle regarding scan_range and number of projection.
We take the hypothesis that 'extra projection' are taken regarding the
'id19' policy:
* If the acquisition has a scan range of 360 then:
* if 4 extra projection, the angles are (270, 180, 90, 0)
* if 5 extra projection, the angles are (360, 270, 180, 90, 0)
* If the acquisition has a scan range of 180 then:
* if 2 extra projections: the angles are (90, 0)
* if 3 extra projections: the angles are (180, 90, 0)
:warning: each url should contain only one radio.
..warning:: each url should contain only one radio.
:param urls: dict with all the urls. First url should be
the first radio acquire, last url should match the last
radio acquire.
:type: dict
:type urls: dict
:param n_projection: number of projection for the sample.
:type: int
:type n_projection: int
:param scan_range: acquisition range (usually 180 or 360)
:type: float
:type scan_range: float
:return: angle in degree as key and url as value
:rtype: dict
......
......@@ -27,7 +27,7 @@
# THE SOFTWARE.
__doc__ = """test module for pyFAI."""
__doc__ = """test modules for pyFAI."""
__authors__ = ["Jérôme Kieffer", "Valentin Valls", "Henri Payno"]
__license__ = "MIT"
__copyright__ = "European Synchrotron Radiation Facility, Grenoble, France"
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment