diff options
Diffstat (limited to 'doc/source')
| -rw-r--r-- | doc/source/Tutorials/io.rst | 46 | ||||
| -rw-r--r-- | doc/source/install.rst | 68 | ||||
| -rw-r--r-- | doc/source/modules/gui/plot3d/items.rst | 23 | ||||
| -rw-r--r-- | doc/source/modules/io/h5py_utils.rst | 8 | ||||
| -rw-r--r-- | doc/source/modules/io/index.rst | 1 | ||||
| -rw-r--r-- | doc/source/modules/utils/index.rst | 1 | ||||
| -rw-r--r-- | doc/source/modules/utils/retry.rst | 7 | ||||
| -rw-r--r-- | doc/source/overview.rst | 16 |
8 files changed, 114 insertions, 56 deletions
diff --git a/doc/source/Tutorials/io.rst b/doc/source/Tutorials/io.rst index 8b70e83..41a0dd3 100644 --- a/doc/source/Tutorials/io.rst +++ b/doc/source/Tutorials/io.rst @@ -72,6 +72,19 @@ It exposes an HDF5 group as a python object that resembles a python dictionary and an HDF5 dataset or attribute as an object that resembles a numpy array. + +silx.io.h5py_utils +++++++++++++++++++ + +The *h5py* library does not support concurrent HDF5 reading and writing in +different processes in a convenient way. SWMR does not allow adding groups, +datasets and attributes during writing. In addition SWMR does not work on +network file systems. + +The module :mod:`silx.io.h5py_utils` provides utility methods for reading +an HDF5 file that is being modified by another process without SWMR. + + API description --------------- @@ -279,6 +292,39 @@ inside its context manager: maxPhi = sf["2.1/measurement/Phi"][...].max() +Concurrent HDF5 ++++++++++++++++ + +When reading an HDF5 file that is being written to, exceptions +can be raised when opening the file or reading data. The only +solution is to retry opening and reading until it succeeds. + +For example to process all top-level groups of an HDF5 file: + +.. code-block:: python + + import silx.io.h5py_utils + + @silx.io.h5py_utils.retry() + def process_scan(filename, name): + """The method will be executed again if + any HDF5 IO fails. + """ + with silx.io.h5py_utils.File(filename) as h5file: + scan = h5file[name] + I0 = scan["measurement/I0"][()] + It = scan["measurement/It"][()] + return It/I0 + + scans = silx.io.h5py_utils.safe_top_level_names("myfile.h5") + + for name in scans: + result = process_scan("myfile.h5", name) + +Note that the method with the `retry` decorator has to be idempotent +as it can be executed several times for one call. + + Additional resources -------------------- diff --git a/doc/source/install.rst b/doc/source/install.rst index 8ed5136..b0d6b4f 100644 --- a/doc/source/install.rst +++ b/doc/source/install.rst @@ -10,11 +10,11 @@ This table summarizes the support matrix of silx: +------------+--------------+---------------------+ | System | Python vers. | Qt and its bindings | +------------+--------------+---------------------+ -| `Windows`_ | 3.5-3.8 | PyQt5.6+, PySide2 | +| `Windows`_ | 3.6-3.9 | PyQt5.6+, PySide2 | +------------+--------------+---------------------+ -| `MacOS`_ | 3.5-3.8 | PyQt5.6+, PySide2 | +| `MacOS`_ | 3.6-3.9 | PyQt5.6+, PySide2 | +------------+--------------+---------------------+ -| `Linux`_ | 3.5-3.8 | PyQt5.3+, PySide2 | +| `Linux`_ | 3.6-3.9 | PyQt5.3+, PySide2 | +------------+--------------+---------------------+ For the description of *silx* dependencies, see the Dependencies_ section. @@ -69,39 +69,28 @@ The GUI widgets depend on the following extra packages: or `PySide2 <https://wiki.qt.io/Qt_for_Python>`_ * `matplotlib <http://matplotlib.org/>`_ * `PyOpenGL <http://pyopengl.sourceforge.net/>`_ -* `qt_console <https://pypi.python.org/pypi/qtconsole>`_ +* `qt_console <https://pypi.org/project/qtconsole>`_ for the ``silx.gui.console`` widget. * `dateutil <https://pypi.org/project/python-dateutil/>`_ -Tools for reading and writing files depend on the following packages: - -* `h5py <http://docs.h5py.org/en/latest/build.html>`_ for HDF5 files -* `fabio <https://github.com/silx-kit/fabio>`_ for multiple image formats - *silx.opencl* further depends on OpenCL and the following packages too : * `pyopencl <https://mathema.tician.de/software/pyopencl/>`_ * `Mako <http://www.makotemplates.org/>`_ The complete list of dependencies with the minimal version is described in the -`requirement.txt <https://github.com/silx-kit/silx/blob/0.8/requirements.txt>`_ +`requirement.txt <https://github.com/silx-kit/silx/blob/master/requirements.txt>`_ at the top level of the source package. Build dependencies ++++++++++++++++++ In addition to run-time dependencies, building *silx* requires a C/C++ compiler, -`numpy <http://www.numpy.org/>`_ and `cython <http://cython.org>`_ (optional). - -On Windows it is recommended to use Python 3.5, because with previous versions -of Python, it might be difficult to compile extensions (i.e. binary modules). - -This project uses Cython (version > 0.21) to generate C files. -Cython is mandatory to build *silx* from the development branch. +`numpy <http://www.numpy.org/>`_ and `cython <http://cython.org>`_. The complete list of dependencies for building the package, including its documentation, is described in the -`requirement-dev.txt <https://github.com/silx-kit/silx/blob/0.8/requirements-dev.txt>`_ +`requirement-dev.txt <https://github.com/silx-kit/silx/blob/master/requirements-dev.txt>`_ at the top level of the source package. @@ -110,7 +99,7 @@ Linux Packages are available for a few distributions: -- Debian 9: see `Installing a Debian package`_. +- Debian/Ubuntu: see `Installing a Debian package`_. - `CentOS 7 RPM packages <http://pubrepo.maxiv.lu.se/rpm/el7/x86_64/>`_ provided by the Max IV institute at Lund, Sweden. - `Fedora 23 rpm packages <http://pubrepo.maxiv.lu.se/rpm/fc23/x86_64/>`_ provided by the Max IV institute at Lund, Sweden. - `Arch Linux (AUR) package <https://aur.archlinux.org/packages/python-silx>`_ provided by Leonid Bloch. @@ -125,35 +114,24 @@ You can also follow one of those installation procedures: Installing a Debian package +++++++++++++++++++++++++++ -Debian 9 (Stretch) packages are available on http://www.silx.org/pub/debian/ for amd64 computers. -To install it, you need to download this file : - -.. code-block:: bash +silx is officially packaged in `Debian <https://packages.debian.org/search?searchon=names&keywords=silx>`_ +and `Ubuntu <https://packages.ubuntu.com/search?keywords=silx&searchon=names&suite=all§ion=all>`_. - http://www.silx.org/pub/debian/silx.list +To install it, run `apt-get install silx` as root. +The `python3-silx` package provides the library, while the `silx` package provides the executable (`silx view`, `silx convert`, ...). -and copy it into the /etc/apt/sources.list.d folder. -Then run ``apt-get update`` and ``apt-get install python-silx`` - -.. code-block:: bash - - wget http://www.silx.org/pub/debian/silx.list - sudo cp silx.list /etc/apt/sources.list.d - sudo apt-get update - sudo apt-get install python-silx python3-silx silx - -The `python-silx` and `python3-silx` packages provide the library, -while the `silx` package provides the executable (`silx view`, `silx convert` ...). +Unofficial (possibly more recent) packages are available for Debian 10 (Buster, amd64) and Ubuntu 20.04 (Focal, amd64 and ppc64le) in this repository: http://www.silx.org/pub/linux-repo/. +See information on `how-to use this repository <http://www.silx.org/pub/linux-repo/>`_ before running `apt-get install silx`. .. note:: - The packages are built automatically, hence not signed. - You have to accept the installation of non-signed packages. + Those packages are built automatically, hence not signed. + You have to accept the installation of non-signed packages. If the packages are not installed, it might be due to the priority list. -You can display the priority list using `apt-cache policy python-silx`. -If the Pin-number of silx.org is too low compared to other sources: -download http://www.silx.org/pub/debian/silx.pref into /etc/apt/preferences.d +You can display the priority list using `apt-cache policy silx`. +If the Pin-number of silx.org is too low compared to other sources, +see the "Information/Troubleshooting" section `here <http://www.silx.org/pub/linux-repo/>`_, and start the update/install procedure again. @@ -184,9 +162,6 @@ binary wheel for it. This means that you would have to install *silx* from its sources, which requires you to install a C compiler first. -We also encourage you to use Python 3.5 or newer as former versions are no longer -officially supported. - Configure Python as explained on `docs.python.org <https://docs.python.org/3/using/windows.html#configuring-python>`_ to add the python installation directory to your PATH environment variable. @@ -211,8 +186,7 @@ prompt. MacOS ----- -Apple ships Python 2.7 by default on their operating systems. -You must install Python 3.5 or newer to install silx. +Make sure to use python3 to install silx (you might need to install python3). Then, install *silx* with ``pip``, see `Installing with pip`_:: @@ -278,7 +252,7 @@ Building from source ++++++++++++++++++++ Source package of *silx* releases can be downloaded from -`the pypi project page <https://pypi.python.org/pypi/silx>`_. +`the pypi project page <https://pypi.org/project/silx>`_. After downloading the `silx-x.y.z.tar.gz` archive, extract its content:: diff --git a/doc/source/modules/gui/plot3d/items.rst b/doc/source/modules/gui/plot3d/items.rst index 5c4884f..ba39336 100644 --- a/doc/source/modules/gui/plot3d/items.rst +++ b/doc/source/modules/gui/plot3d/items.rst @@ -112,6 +112,29 @@ The following classes allows to configure :class:`ScalarField3D` visualization: getParameters, setParameters, getDisplayValuesBelowMin, setDisplayValuesBelowMin +Height map +---------- + +.. currentmodule:: silx.gui.plot3d.items.image + +:class:`HeightMapData` +++++++++++++++++++++++ + +:class:`HeightMapData` inherits from :class:`.DataItem3D` and also provides its API. + +.. autoclass:: HeightMapData + :members: getData, setData, + getColormappedData, setColormappedData + +:class:`HeightMapRGBA` +++++++++++++++++++++++ + +:class:`HeightMapRGBA` inherits from :class:`.DataItem3D` and also provides its API. + +.. autoclass:: HeightMapRGBA + :members: getData, setData, + getColorData, setColorData + Clipping plane -------------- diff --git a/doc/source/modules/io/h5py_utils.rst b/doc/source/modules/io/h5py_utils.rst new file mode 100644 index 0000000..b6461b1 --- /dev/null +++ b/doc/source/modules/io/h5py_utils.rst @@ -0,0 +1,8 @@ + +.. currentmodule:: silx.io + +:mod:`h5py_utils`: HDF5 I/O utilities +------------------------------------- + +.. automodule:: silx.io.h5py_utils + :members: diff --git a/doc/source/modules/io/index.rst b/doc/source/modules/io/index.rst index b504695..581f763 100644 --- a/doc/source/modules/io/index.rst +++ b/doc/source/modules/io/index.rst @@ -18,6 +18,7 @@ spech5.rst url.rst utils.rst + h5py_utils.rst Top-level functions ------------------- diff --git a/doc/source/modules/utils/index.rst b/doc/source/modules/utils/index.rst index 7dd10dd..db18422 100644 --- a/doc/source/modules/utils/index.rst +++ b/doc/source/modules/utils/index.rst @@ -9,3 +9,4 @@ html.rst testutils.rst weakref.rst + retry.rst diff --git a/doc/source/modules/utils/retry.rst b/doc/source/modules/utils/retry.rst new file mode 100644 index 0000000..e176bc0 --- /dev/null +++ b/doc/source/modules/utils/retry.rst @@ -0,0 +1,7 @@ +.. currentmodule:: silx.utils + +:mod:`weakref` +--------------- + +.. automodule:: silx.utils.retry + :members:
\ No newline at end of file diff --git a/doc/source/overview.rst b/doc/source/overview.rst index 93db23a..e65c163 100644 --- a/doc/source/overview.rst +++ b/doc/source/overview.rst @@ -5,21 +5,19 @@ Releases -------- Source code, pre-built binaries (aka Python wheels) for Windows, MacOS and -ManyLinux1. -Debian packages of released versions are made available in the following places: +ManyLinux, Debian/Ubuntu packages of released versions are made available in the following places: -- `Wheels and source code on PyPi <https://pypi.python.org/pypi/silx>`_ -- `Debian 9 packages <http://www.silx.org/pub/debian/>`_ +- `Wheels and source code on PyPi <https://pypi.org/project/silx/>`_ - `Documentation on silx.org <http://www.silx.org/doc/silx/latest/>`_ +- `Unofficial Debian/Ubuntu packages <https://github.com/silx-kit/silx/releases>`_ - :doc:`changelog` Nightly builds -------------- -Debian 9 packages and documentation are automatically generated from the tip of -the project's repository on a daily basis: +Linux packages and documentation are automatically generated from the tip of the project's repository on a regular basis: -- `Debian 9 packages <http://www.silx.org/pub/debian/>`_ +- `Debian 10 and Ubuntu20.04 packages <http://www.silx.org/pub/linux-repo/>`_ - `Documentation <http://www.silx.org/doc/silx/dev/>`_ Project @@ -36,12 +34,12 @@ Project - Continuous integration: *silx* is continuously tested on all three major operating systems: - - Linux and MacOS X: `Travis <https://travis-ci.org/silx-kit/silx>`_ + - Linux, MacOS, Windows: `GitHub Actions <https://github.com/silx-kit/silx/actions>`_ - Windows: `AppVeyor <https://ci.appveyor.com/project/ESRF/silx>`_ Additional Material ------------------- -- Code Camp Talks. *silx* follows a quarterly release cycle. Prior to each release, a code camp takes place in which the novelties are presented and interested users make use of the development version in order to spot bugs or missing features. The `PDFs of the talks are available for download <http://ftp.esrf.fr/pub/scisoft/silx/talks/>`_ +- Code Camp held before releases: `The PDFs of the talks are available for download <http://ftp.esrf.fr/pub/scisoft/silx/talks/>`_ |