feat: added command-line entry point 'qpinfo' and updated docs

CHANGELOG

@@ -1,5 +1,7 @@
 0.7.0
+ - feat: added command-line entry point "qpinfo"
  - feat: support subjoined QPSeries file format
+ - docs: minor update
 0.6.4
  - fix: ignore None or nan values in given meta data
 0.6.3

docs/conf.py

@@ -76,6 +76,7 @@
               'sphinxcontrib.bibtex',
               'fancy_include',
               'qpformat_readers',
+              'github_changelog',
               ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/index.rst

@@ -1,20 +1,24 @@
 .. _index:
 
-qpformat documentation
-======================
-
 Qpformat is a Python3 library for opening quantitative
 phase imaging data file formats. This is the
 documentation of qpformat version |release|.
 
+Documentation
+=============
+
 .. toctree::
    :maxdepth: 4
-   :caption: Contents:
 
    sec_introduction
    sec_getting_started
    sec_examples
    sec_code_reference
+
+.. toctree::
+   :maxdepth: 1
+
+   sec_changelog
    sec_z_bib
 
 

docs/sec_getting_started.rst

@@ -2,8 +2,74 @@
 Getting started
 ===============
 
-.. toctree::
-  :maxdepth: 2
 
-  sec_installation
-  sec_userapi
+Installing qpformat
+===================
+
+qpformat is written in pure Python and supports Python version 3.5
+and higher. qpformat depends on several other scientific Python packages,
+including:
+
+ - `numpy <https://docs.scipy.org/doc/numpy/>`_,
+ - `scipy <https://docs.scipy.org/doc/scipy/reference/>`_,
+ - `qpimage <https://qpimage.readthedocs.io/en/stable/>`_ (phase data manipulation),
+
+To install qpformat, use one of the following methods
+(package dependencies will be installed automatically):
+
+* from `PyPI <https://pypi.python.org/pypi/qpformat>`_:
+    ``pip install qpformat``
+* from `sources <https://github.com/RI-imaging/qpformat>`_:
+    ``pip install -e .`` or
+    ``python setup.py install``
+
+
+User API
+========
+Qpformat supports :ref:`several file formats <supported_formats>` that are
+categorized into :class:`qpformat.file_formats.SingleData`
+(the experimental data file format contains only one phase image)
+and :class:`qpformat.file_formats.SeriesData` (the experimental
+data file format supports multiple phase images).
+From these base classes, all data file formats are derived. The idea
+is that experimental data is not loaded into memory until the
+`get_qpimage` method is called which returns a
+:class:`qpimage.QPImage <qpimage.core.QPImage>` object.
+
+
+Basic Usage
+-----------
+To extract the (unwrapped) phase from a DHM image, use the
+:func:`qpformat.load_data` method. The file format type is
+determined automatically by qpformat.
+
+.. code:: python
+
+    import qpformat
+    # The data are not loaded into memory, only the meta data is read
+    dataset = qpformat.load_data("/path/to/hologram_image.tif")
+    # Get the quantitative phase data (a qpimage.QPImage is returned)
+    qpi = dataset.get_qpimage()
+    # Get the 2D phase image data as a numpy array
+    phase = qpi.pha
+
+The object ``qpi`` is an instance of
+:class:`qpimage.QPImage <qpimage.core.QPImage>` which
+comes with an elaborate set of background correction methods. Note
+that :func:`qpformat.load_data` accepts keyword arguments that allow
+to define the setup metadata as well as the hologram reconstruction
+parameters.
+
+
+Command-line program "qpinfo"
+=============================
+This command-line program allows checking whether a file (or directory)
+contains quantitative phase data with a file format supported by qpformat.
+
+.. code::
+
+  usage: qpinfo [-h] path
+
+The command yields the type of the format, the corresponding class name
+in qpformat, as well as the meta data associated with the dataset
+(e.g. wavelength, pixel size).

qpformat/cli.py

@@ -0,0 +1,32 @@
+"""command line interface"""
+import argparse
+import pathlib
+
+from .core import load_data
+from .file_formats import UnknownFileFormatError
+
+
+def qpinfo():
+    """Print information of a quantitative phase imaging dataset"""
+    parser = qpinfo_parser()
+    args = parser.parse_args()
+
+    path = pathlib.Path(args.path).resolve()
+    try:
+        ds = load_data(path)
+    except UnknownFileFormatError:
+        print("Unknown file format: {}".format(path))
+        return
+
+    print("{} ({})".format(ds.__class__.__doc__, ds.__class__.__name__))
+    print("- number of images: {}".format(len(ds)))
+    for key in ds.meta_data:
+        print("- {}: {}".format(key, ds.meta_data[key]))
+
+
+def qpinfo_parser():
+    descr = "Show information about a quantitative phase imaging dataset"
+    parser = argparse.ArgumentParser(description=descr)
+    parser.add_argument('path', metavar='path', type=str,
+                        help='Data path')
+    return parser

qpformat/file_formats/dataset.py

@@ -57,7 +57,7 @@ def __init__(self, path, meta_data={}, holo_kw={}, as_type="float32"):
 
     def __repr__(self):
         rep = "QPFormat '{}'".format(self.__class__.__name__) \
-              + ", {} event(s)".format(len(self)) \
+              + ", {} image(s)".format(len(self)) \
               + "\nfile: {}".format(self.path)
 
         meta = []

setup.py

@@ -33,6 +33,11 @@
     setup_requires=['pytest-runner'],
     tests_require=["pytest"],
     python_requires='>=3.6, <4',
+    entry_points={
+       "console_scripts": [
+           "qpinfo = qpformat.cli:qpinfo",
+            ],
+       },
     keywords=["data file format",
               "digital holographic microscopy",
               "quantitative phase imaging",