summaryrefslogtreecommitdiff
path: root/doc/source/modules
diff options
context:
space:
mode:
authorPicca Frédéric-Emmanuel <picca@debian.org>2018-03-04 10:20:27 +0100
committerPicca Frédéric-Emmanuel <picca@debian.org>2018-03-04 10:20:27 +0100
commit270d5ddc31c26b62379e3caa9044dd75ccc71847 (patch)
tree55c5bfc851dfce7172d335cd2405b214323e3caf /doc/source/modules
parente19c96eff0c310c06c4f268c8b80cb33bd08996f (diff)
New upstream version 0.7.0+dfsg
Diffstat (limited to 'doc/source/modules')
-rw-r--r--doc/source/modules/gui/dialog/abstractdatafiledialog.rst13
-rw-r--r--doc/source/modules/gui/dialog/datafiledialog.rst13
-rw-r--r--doc/source/modules/gui/dialog/imagefiledialog.rst13
-rw-r--r--doc/source/modules/gui/dialog/img/datafiledialog.pngbin0 -> 31843 bytes
-rw-r--r--doc/source/modules/gui/dialog/img/imagefiledialog_edf.pngbin0 -> 109562 bytes
-rw-r--r--doc/source/modules/gui/dialog/img/imagefiledialog_h5.pngbin0 -> 46649 bytes
-rw-r--r--doc/source/modules/gui/dialog/index.rst33
-rw-r--r--doc/source/modules/gui/gallery.rst39
-rw-r--r--doc/source/modules/gui/icons.rst12
-rw-r--r--doc/source/modules/gui/index.rst1
-rw-r--r--doc/source/modules/gui/plot/actions/examples.rst46
-rw-r--r--doc/source/modules/gui/plot/actions/index.rst12
-rw-r--r--doc/source/modules/gui/plot/getting_started.rst259
-rw-r--r--doc/source/modules/gui/plot/index.rst1
-rw-r--r--doc/source/modules/gui/plot/plotsignal.rst166
-rw-r--r--doc/source/modules/gui/plot/plottoolbuttons.rst7
-rw-r--r--doc/source/modules/gui/plot/plotwidget.rst5
-rw-r--r--doc/source/modules/gui/plot3d/actions.rst3
-rw-r--r--doc/source/modules/gui/plot3d/dev.rst8
-rw-r--r--doc/source/modules/gui/plot3d/img/Plot3DWindow.pngbin20571 -> 21207 bytes
-rw-r--r--doc/source/modules/gui/plot3d/img/ScalarFieldView.pngbin42407 -> 55012 bytes
-rw-r--r--doc/source/modules/gui/plot3d/img/SceneWidget.pngbin0 -> 349485 bytes
-rw-r--r--doc/source/modules/gui/plot3d/img/SceneWindow.pngbin0 -> 363783 bytes
-rw-r--r--doc/source/modules/gui/plot3d/index.rst9
-rw-r--r--doc/source/modules/gui/plot3d/items.rst173
-rw-r--r--doc/source/modules/gui/plot3d/scalarfieldview.rst2
-rw-r--r--doc/source/modules/gui/plot3d/scenewidget.rst29
-rw-r--r--doc/source/modules/gui/plot3d/scenewindow.rst22
-rw-r--r--doc/source/modules/gui/plot3d/viewer3dvolume_example.rst7
-rw-r--r--doc/source/modules/index.rst3
-rw-r--r--doc/source/modules/io/index.rst2
-rw-r--r--doc/source/modules/io/url.rst8
-rw-r--r--doc/source/modules/opencl/codec_cbf.rst9
-rw-r--r--doc/source/modules/opencl/fbp.rst10
-rw-r--r--doc/source/modules/opencl/index.rst15
-rw-r--r--doc/source/modules/opencl/medfilt.rst7
-rw-r--r--doc/source/modules/opencl/sift/align.rst7
-rw-r--r--doc/source/modules/opencl/sift/index.rst11
-rw-r--r--doc/source/modules/opencl/sift/match.rst7
-rw-r--r--doc/source/modules/opencl/sift/plan.rst7
-rw-r--r--doc/source/modules/sx.rst77
-rw-r--r--doc/source/modules/utils/index.rst2
-rw-r--r--doc/source/modules/utils/testutils.rst7
43 files changed, 833 insertions, 212 deletions
diff --git a/doc/source/modules/gui/dialog/abstractdatafiledialog.rst b/doc/source/modules/gui/dialog/abstractdatafiledialog.rst
new file mode 100644
index 0000000..ac395ae
--- /dev/null
+++ b/doc/source/modules/gui/dialog/abstractdatafiledialog.rst
@@ -0,0 +1,13 @@
+
+.. currentmodule:: silx.gui.dialog
+
+:mod:`AbstractDataFileDialog`
+=============================
+
+.. automodule:: silx.gui.dialog.AbstractDataFileDialog
+
+.. currentmodule:: silx.gui.dialog.AbstractDataFileDialog
+
+.. autoclass:: AbstractDataFileDialog
+ :members:
+ :show-inheritance:
diff --git a/doc/source/modules/gui/dialog/datafiledialog.rst b/doc/source/modules/gui/dialog/datafiledialog.rst
new file mode 100644
index 0000000..d815a0b
--- /dev/null
+++ b/doc/source/modules/gui/dialog/datafiledialog.rst
@@ -0,0 +1,13 @@
+
+.. currentmodule:: silx.gui.dialog
+
+:mod:`DataFileDialog`
+=====================
+
+.. automodule:: silx.gui.dialog.DataFileDialog
+
+.. currentmodule:: silx.gui.dialog.DataFileDialog
+
+.. autoclass:: DataFileDialog
+ :members:
+ :show-inheritance:
diff --git a/doc/source/modules/gui/dialog/imagefiledialog.rst b/doc/source/modules/gui/dialog/imagefiledialog.rst
new file mode 100644
index 0000000..cebd6e7
--- /dev/null
+++ b/doc/source/modules/gui/dialog/imagefiledialog.rst
@@ -0,0 +1,13 @@
+
+.. currentmodule:: silx.gui.dialog
+
+:mod:`ImageFileDialog`
+======================
+
+.. automodule:: silx.gui.dialog.ImageFileDialog
+
+.. currentmodule:: silx.gui.dialog.ImageFileDialog
+
+.. autoclass:: ImageFileDialog
+ :members:
+ :show-inheritance:
diff --git a/doc/source/modules/gui/dialog/img/datafiledialog.png b/doc/source/modules/gui/dialog/img/datafiledialog.png
new file mode 100644
index 0000000..f7c7fd5
--- /dev/null
+++ b/doc/source/modules/gui/dialog/img/datafiledialog.png
Binary files differ
diff --git a/doc/source/modules/gui/dialog/img/imagefiledialog_edf.png b/doc/source/modules/gui/dialog/img/imagefiledialog_edf.png
new file mode 100644
index 0000000..ed715b4
--- /dev/null
+++ b/doc/source/modules/gui/dialog/img/imagefiledialog_edf.png
Binary files differ
diff --git a/doc/source/modules/gui/dialog/img/imagefiledialog_h5.png b/doc/source/modules/gui/dialog/img/imagefiledialog_h5.png
new file mode 100644
index 0000000..33da51e
--- /dev/null
+++ b/doc/source/modules/gui/dialog/img/imagefiledialog_h5.png
Binary files differ
diff --git a/doc/source/modules/gui/dialog/index.rst b/doc/source/modules/gui/dialog/index.rst
new file mode 100644
index 0000000..a13ad31
--- /dev/null
+++ b/doc/source/modules/gui/dialog/index.rst
@@ -0,0 +1,33 @@
+
+.. currentmodule:: silx.gui
+
+:mod:`dialog`: Dialog widgets
+-----------------------------
+
+.. automodule:: silx.gui.dialog
+
+Snapshot of the widgets:
+
+
+.. |imgImageFileDialog| image:: ./img/imagefiledialog_h5.png
+ :height: 150px
+ :align: middle
+
+.. |imgDataFileDialog| image:: ./img/datafiledialog.png
+ :height: 150px
+ :align: middle
+
+======================== ==========================
+|imgImageFileDialog| |imgDataFileDialog|
+:class:`ImageFileDialog` :class:`DataFileDialog`
+======================== ==========================
+
+Public modules:
+
+.. toctree::
+ :maxdepth: 2
+
+ imagefiledialog.rst
+ datafiledialog.rst
+ abstractdatafiledialog.rst
+
diff --git a/doc/source/modules/gui/gallery.rst b/doc/source/modules/gui/gallery.rst
index 4ae83d6..40d8648 100644
--- a/doc/source/modules/gui/gallery.rst
+++ b/doc/source/modules/gui/gallery.rst
@@ -61,6 +61,29 @@ Widgets gallery
n-dimensional array, by fixing the index on some of the dimensions.
+:mod:`silx.gui.dialog` Widgets
+++++++++++++++++++++++++++++++
+
+.. currentmodule:: silx.gui.dialog
+
+.. list-table::
+ :widths: 1 4
+ :header-rows: 1
+
+ * - Widget
+ - Description
+ * - .. image:: dialog/img/datafiledialog.png
+ :height: 150px
+ :align: center
+ - :class:`DataFileDialog` is a dialog that allow users to select
+ any datasets or groups from an HDF5-like file.
+ * - .. image:: dialog/img/imagefiledialog_h5.png
+ :height: 150px
+ :align: center
+ - :class:`ImageFileDialog` is a dialog that allow users to select
+ an image from an HDF5-like file.
+
+
:mod:`silx.gui.fit` Widgets
+++++++++++++++++++++++++++
@@ -195,12 +218,24 @@ Additional widgets:
* - Widget
- Description
+ * - .. image:: plot3d/img/SceneWindow.png
+ :height: 150px
+ :align: center
+ - :class:`SceneWindow` is a :class:`QMainWindow` embedding a 3D data visualization :class:`SceneWidget`
+ and associated toolbars.
+ It can display 2D images, 2D scatter data, 3D scatter data and 3D volumes with different visualizations.
+ See ``plot3dSceneWindow.py`` in :ref:`plot3d-sample-code`.
+ * - .. image:: plot3d/img/SceneWidget.png
+ :height: 150px
+ :align: center
+ - :class:`SceneWidget` is a :class:`Plot3DWidget` providing a 3D scene for visualizing different kind of data.
+ It can display 2D images, 2D scatter data, 3D scatter data and 3D volumes with different visualizations.
+ See ``plot3dSceneWindow.py`` in :ref:`plot3d-sample-code`.
* - .. image:: plot3d/img/ScalarFieldView.png
:height: 150px
:align: center
- :class:`ScalarFieldView` is a :class:`Plot3DWindow` dedicated to display 3D scalar field.
It can display iso-surfaces and an interactive cutting plane.
- Sample code: :doc:`plot3d/viewer3dvolume_example`.
* - .. image:: plot3d/img/Plot3DWindow.png
:height: 150px
:align: center
@@ -216,7 +251,7 @@ Additional widgets:
:align: center
- :class:`SFViewParamTree` is a :class:`QTreeView` widget that can be attached to a :class:`ScalarFieldView`.
It displays current parameters of the :class:`ScalarFieldView` and allows to modify it.
- Sample code: :doc:`plot3d/viewer3dvolume_example`.
+ See :ref:`plot3d-sample-code`.
:mod:`silx.gui.widgets` Widgets
diff --git a/doc/source/modules/gui/icons.rst b/doc/source/modules/gui/icons.rst
index a1cd3d7..48fe95c 100644
--- a/doc/source/modules/gui/icons.rst
+++ b/doc/source/modules/gui/icons.rst
@@ -41,6 +41,12 @@ Available icons
- close
* - |colorbar|
- colorbar
+ * - |colormap-histogram|
+ - colormap-histogram
+ * - |colormap-none|
+ - colormap-none
+ * - |colormap-range|
+ - colormap-range
* - |colormap|
- colormap
* - |crop|
@@ -143,6 +149,8 @@ Available icons
- math-sigma
* - |math-smooth|
- math-smooth
+ * - |math-square-amplitude|
+ - math-square-amplitude
* - |math-substract|
- math-substract
* - |math-swap-sign|
@@ -281,6 +289,9 @@ Available icons
.. |clipboard| image:: ../../../../silx/resources/gui/icons/clipboard.png
.. |close| image:: ../../../../silx/resources/gui/icons/close.png
.. |colorbar| image:: ../../../../silx/resources/gui/icons/colorbar.png
+.. |colormap-histogram| image:: ../../../../silx/resources/gui/icons/colormap-histogram.png
+.. |colormap-none| image:: ../../../../silx/resources/gui/icons/colormap-none.png
+.. |colormap-range| image:: ../../../../silx/resources/gui/icons/colormap-range.png
.. |colormap| image:: ../../../../silx/resources/gui/icons/colormap.png
.. |crop| image:: ../../../../silx/resources/gui/icons/crop.png
.. |crosshair| image:: ../../../../silx/resources/gui/icons/crosshair.png
@@ -332,6 +343,7 @@ Available icons
.. |math-real| image:: ../../../../silx/resources/gui/icons/math-real.png
.. |math-sigma| image:: ../../../../silx/resources/gui/icons/math-sigma.png
.. |math-smooth| image:: ../../../../silx/resources/gui/icons/math-smooth.png
+.. |math-square-amplitude| image:: ../../../../silx/resources/gui/icons/math-square-amplitude.png
.. |math-substract| image:: ../../../../silx/resources/gui/icons/math-substract.png
.. |math-swap-sign| image:: ../../../../silx/resources/gui/icons/math-swap-sign.png
.. |math-ymin-to-zero| image:: ../../../../silx/resources/gui/icons/math-ymin-to-zero.png
diff --git a/doc/source/modules/gui/index.rst b/doc/source/modules/gui/index.rst
index 0b7f433..1f7ee4a 100644
--- a/doc/source/modules/gui/index.rst
+++ b/doc/source/modules/gui/index.rst
@@ -13,6 +13,7 @@ The ``silx.gui`` package provides a set of PyQt widgets.
console.rst
data/index.rst
fit/index.rst
+ dialog/index.rst
hdf5/index.rst
icons.rst
plot/index.rst
diff --git a/doc/source/modules/gui/plot/actions/examples.rst b/doc/source/modules/gui/plot/actions/examples.rst
index 125e9c5..f4679ba 100644
--- a/doc/source/modules/gui/plot/actions/examples.rst
+++ b/doc/source/modules/gui/plot/actions/examples.rst
@@ -3,29 +3,29 @@
Adding custom plot actions
==========================
-A :class:`PlotWindow` defines a number of standard plot actions that can be executed
+:class:`PlotWindow` defines a number of standard plot actions that can be executed
by clicking on toolbar icons.
Developers can design additional plot actions to be added as toolbar icons or as menu entries,
to be added to a :class:`PlotWindow` or to design their own plot window based on
:class:`PlotWidget`.
-This documentation pages provides examples on how to do this.
+This documentation pages provide examples on how to do this.
Simple example: Shift a curve
-----------------------------
-The following script is a simplistic example to show the basic required steps:
+The following script is a simplistic example to show the required basic steps:
- create a new class inheriting from :class:`silx.gui.plot.actions.PlotAction`
- define basic parameters such as the icon, the tooltip...
- - write a method that will be triggered by the action
- - initialize the new plot action by passing a reference to a plot window
- - add the action to a toolbar or a menu
+ - write a method that will be triggered by the plot action
+ - initialise the new plot action by passing a reference to a plot window
+ - add the plot action to a toolbar or a menu
The method implemented in this action interacts with the plot in a basic way. It gets the active curve,
-then it creates a new data array based on the curve data, and finally it replaces the original curve
-with a new one using the modified data array.
+then it creates a new data array based on the curve points, and finally it replaces the original curve
+by a new one using the modified data array.
.. literalinclude:: ../../../../../../examples/shiftPlotAction.py
:lines: 36-
@@ -47,23 +47,23 @@ with a new one using the modified data array.
- After triggering the action 3 times, the selected triangle shaped curve
is shifted up by 3 units
-Advanced example: Display amplitude spectrum
---------------------------------------------
+Advanced example: Display an amplitude spectrum
+-----------------------------------------------
-This more advanced example shows additional ways of interacting with the plot, by changing
-labels, storing additional data array along with the curve data.
+This more advanced example (see `figure below`_) shows additional ways of interacting with the plot, by changing
+labels, storing additional data arrays along with the curve coordinates.
This action is *checkable*, meaning that is has two states. When clicking the toolbar icon
-or the menu item, it remains in a *pushed* state until it is clicked again.
+or the menu item, this remains in a *pushed* state until it is clicked again.
In one state (*un-checked*), the original data is displayed. In the other state, the amplitude
spectrum of the original signal is displayed. When the state is changed, the triggered action
computes either the Fast Fourier Transform (FFT), or the reverse FFT.
-This example also illustrates how to store additional data, along with a curve.
-The FFT computation returns complex values, but we want to display real data, so we compute
-the amplitude spectrum. However, the inverse FFT requires the complete FFT data as input.
-We are therefore required to store the complex array of FFT data as curve metadata,
+This example also illustrates how to store additional data along with a curve.
+The FFT computation returns complex values, but you want to display real data, so you compute
+the spectrum of amplitudes. However, the inverse FFT requires the complete FFT data as input.
+You are therefore required to store the complex array of FFT data as curve metadata,
in order to be able to reverse the process when the action is unchecked.
.. literalinclude:: ../../../../../../examples/fftPlotAction.py
@@ -77,17 +77,19 @@ in order to be able to reverse the process when the action is unchecked.
:height: 300px
:align: middle
+.. _`figure below`:
+
.. list-table::
:widths: 1 2
* - |imgFftAction0|
- - Original signals (zoom applied). In red, a cosine wave at 7 Hz.
+ - Original signals (zoomed in). In red, a cosine wave at 7 Hz.
In black, a sum of sines with frequencies of 3, 20 and 42 Hz.
In green, a square wave with a fundamental frequency of 0.5 Hz
- (wavelength of 2 seconds).
+ (period of 2 seconds).
* - |imgFftAction1|
- - Amplitude spectra (zoom applied), with peaks visible at
+ - Amplitude spectra (zoomed in), with peaks visible at
the expected frequencies of 3, 7, 20 and 42 Hz for the sine and cosine
- signals. In green, we see the complete series of peaks related to the square wave,
+ signals, respectively. In green, one sees the complete series of peaks related to the square wave,
with a fundamental frequency at 0.5 Hz and harmonic frequencies at every
- odd multiple of the fundamental.
+ odd multiple of the fundamental frequency.
diff --git a/doc/source/modules/gui/plot/actions/index.rst b/doc/source/modules/gui/plot/actions/index.rst
index f95b1f8..b8b345b 100644
--- a/doc/source/modules/gui/plot/actions/index.rst
+++ b/doc/source/modules/gui/plot/actions/index.rst
@@ -1,14 +1,8 @@
-.. currentmodule:: silx.gui.plot
-:mod:`actions`: Actions for PlotWidget
-===========================================
+:mod:`~silx.gui.plot.actions`: Actions for PlotWidget
+=====================================================
-.. currentmodule:: silx.gui.plot.actions
-
-The :class:`PlotAction` is a base class used to define plot actions.
-
-Plot actions serve to add menu items or toolbar items that are associated with a method
-that can interact with the associated :class:`.PlotWidget`.
+.. automodule:: silx.gui.plot.actions
For an introduction to creating custom plot actions, see :doc:`examples`.
diff --git a/doc/source/modules/gui/plot/getting_started.rst b/doc/source/modules/gui/plot/getting_started.rst
index 484d3f7..bfea8f2 100644
--- a/doc/source/modules/gui/plot/getting_started.rst
+++ b/doc/source/modules/gui/plot/getting_started.rst
@@ -1,3 +1,7 @@
+
+.. role:: python(code)
+ :language: python
+
.. currentmodule:: silx.gui
Getting started with plot widgets
@@ -5,30 +9,40 @@ Getting started with plot widgets
This introduction to :mod:`silx.gui.plot` covers the following topics:
-- `Use silx.gui.plot from the console`_
+- `Use silx.gui.plot from (I)Python console`_
- `Use silx.gui.plot from a script`_
- `Plot curves in a widget`_
- `Plot images in a widget`_
-- `Control plot axes`_
+- `Configure plot axes`_
For a complete description of the API, see :mod:`silx.gui.plot`.
-Use :mod:`silx.gui.plot` from the console
------------------------------------------
+Use :mod:`silx.gui.plot` from (I)Python console
+-----------------------------------------------
+
+The simplest way is to import the :mod:`silx.sx` module:
+
+>>> from silx import sx
-From IPython
-++++++++++++
+The :mod:`silx.sx` module initialises Qt and provides access to :mod:`silx.gui.plot` widgets and extra plot functions.
-To run :mod:`silx.gui.plot` widgets from `IPython <http://ipython.org/>`_, IPython must be set to use Qt (and in case of using PyQt4 and Python 2.7, PyQt must be set ti use API version 2, see Explanation_ below).
+.. note:: The :mod:`silx.sx` module does NOT initialise Qt and does NOT expose silx widget in a notebook.
-As *silx* is performing some configuration of the Qt binding and `matplotlib <http://matplotlib.org/>`_, the safest way to use *silx* from IPython is to import :mod:`silx.gui.plot` first and then run either `%gui <http://ipython.org/ipython-doc/stable/interactive/magics.html#magic-gui>`_ qt or `%pylab <http://ipython.org/ipython-doc/stable/interactive/magics.html#magic-pylab>`_ qt::
+Compatibility with IPython
+++++++++++++++++++++++++++
+
+To run :mod:`silx.gui` widgets from `IPython <http://ipython.org/>`_,
+IPython must be set to use Qt (and in case of using PyQt4 and Python 2.7,
+PyQt must be set to use API version 2, see note below for explanation).
+
+As *silx* is configuring the Qt binding and `matplotlib <http://matplotlib.org/>`_, the safest way to use *silx* from IPython is to import :mod:`silx.gui.plot` first and then run either `%gui <http://ipython.org/ipython-doc/stable/interactive/magics.html#magic-gui>`_ qt or `%pylab <http://ipython.org/ipython-doc/stable/interactive/magics.html#magic-pylab>`_ qt::
In [1]: from silx.gui.plot import *
In [2]: %pylab qt
Alternatively, when using Python 2.7 and PyQt4, you can start IPython with the ``QT_API`` environment variable set to ``pyqt``.
-On Linux and MacOS X, run::
+On Linux and MacOS X, run from the command line::
QT_API=pyqt ipython
@@ -37,100 +51,33 @@ On Windows, run from the command line::
set QT_API=pyqt&&ipython
-Explanation
-...........
-
-PyQt4 used from Python 2.x provides 2 incompatible versions of QString and QVariant:
-
-- version 1, the legacy which is the default, and
-- version 2, a more pythonic one, which is the only one supported by *silx*.
+.. note:: PyQt4 used from Python 2.x provides 2 incompatible versions of QString and QVariant:
-All other configurations (i.e., PyQt4 on Python 3.x, PySide, PyQt5, IPython QtConsole widget) uses version 2 only or as the default.
+ - version 1, the legacy version which is also the default, and
+ - version 2, a more pythonic one, which is the only one supported by *silx*.
-For more information, see `IPython, PyQt and PySide <http://ipython.org/ipython-doc/stable/interactive/reference.html#pyqt-and-pyside>`_.
+ All other configurations (i.e., PyQt4 on Python 3.x, PySide, PyQt5, IPython QtConsole widget) uses version 2.
+ For more information, see `IPython, PyQt and PySide <http://ipython.org/ipython-doc/stable/interactive/reference.html#pyqt-and-pyside>`_.
-From Python
-+++++++++++
-
-The :mod:`silx.sx` package is a convenient module to use silx from the console.
-It sets-up Qt and provides functions for the main features of silx.
-
->>> from silx import sx
-
-Alternatively, you can create a QApplication before using silx widgets:
-
->>> from silx.gui import qt # Import Qt binding and do some set-up
->>> qapp = qt.QApplication([])
-
->>> from silx.gui.plot import * # Import plot widgets and set-up matplotlib
-
-.. currentmodule:: silx.sx
Plot functions
++++++++++++++
-The :mod:`silx.sx` package provides 2 functions to plot curves and images from the (I)Python console in a widget with a set of tools:
-
-- :func:`plot`, and
-- :func:`imshow`.
-
-For more features, use widgets directly (see `Plot curves in a widget`_ and `Plot images in a widget`_).
-
-
-Curve: :func:`plot`
-...................
-
-The following examples must run with a Qt QApplication initialized (see `Use silx.gui.plot from the console`_).
-
-First import :mod:`sx` function:
-
->>> from silx import sx
->>> import numpy
-
-Plot a single curve given some values:
-
->>> values = numpy.random.random(100)
->>> plot_1curve = sx.plot(values, title='Random data')
-
-Plot a single curve given the x and y values:
-
->>> angles = numpy.linspace(0, numpy.pi, 100)
->>> sin_a = numpy.sin(angles)
->>> plot_sinus = sx.plot(angles, sin_a,
-... xlabel='angle (radian)', ylabel='sin(a)')
-
-Plot many curves by giving a 2D array, provided xn, yn arrays:
-
->>> plot_curves = sx.plot(x0, y0, x1, y1, x2, y2, ...)
-
-Plot curve with style giving a style string:
-
->>> plot_styled = sx.plot(x0, y0, 'ro-', x1, y1, 'b.')
-
-See :func:`plot` for details.
+The :mod:`silx.sx` module provides functions to plot curves and images with :mod:`silx.gui.plot` widgets:
+- :func:`~silx.sx.plot` for curves, e.g., :python:`sx.plot(y)` or :python:`sx.plot(x, y)`
+- :func:`~silx.sx.imshow` for images, e.g., :python:`sx.imshow(image)`
-Image: :func:`imshow`
-.....................
+See :mod:`silx.sx` for documentation and how to use it.
-This example plot a single image.
-
-First, import :mod:`silx.sx`:
-
->>> from silx import sx
->>> import numpy
-
->>> data = numpy.random.random(1024 * 1024).reshape(1024, 1024)
->>> plt = sx.imshow(data, title='Random data')
-
-See :func:`imshow` for more details.
+For more features, use widgets directly (see `Plot curves in a widget`_ and `Plot images in a widget`_).
Use :mod:`silx.gui.plot` from a script
--------------------------------------
-A Qt GUI script must have a QApplication initialized before creating widgets:
+A Qt GUI script must have a QApplication initialised before creating widgets:
.. code-block:: python
@@ -146,27 +93,22 @@ A Qt GUI script must have a QApplication initialized before creating widgets:
[...]
qapp.exec_()
-Unless a Qt binding has already been loaded, :mod:`silx.gui.qt` uses the first Qt binding it founds by probing in the following order: PyQt5, PyQt4 and finally PySide.
+Unless a Qt binding has already been loaded, :mod:`silx.gui.qt` uses one of the supported Qt bindings (PyQt4, PySide or PyQt5).
If you prefer to choose the Qt binding yourself, import it before importing
a module from :mod:`silx.gui`:
.. code-block:: python
- import PySide # Importing PySide will force silx to use it
+ import PyQt5.QtCore # Importing PyQt5 will force silx to use it
from silx.gui import qt
-.. warning::
-
- :mod:`silx.gui.plot` widgets are not thread-safe.
- All calls to :mod:`silx.gui.plot` widgets must be made from the main thread.
-
Plot curves in a widget
-----------------------
-The :class:`Plot1D` widget provides a plotting area and a toolbar with tools useful for curves such as setting logarithmic scale or defining region of interest.
+The :class:`~silx.gui.plot.PlotWindow.Plot1D` widget provides a plotting area and a toolbar with tools useful for curves such as setting a logarithmic scale or defining a region of interest.
-First, create a :class:`Plot1D` widget:
+First, create a :class:`~silx.gui.plot.PlotWindow.Plot1D` widget:
.. code-block:: python
@@ -183,15 +125,17 @@ To display a single curve, use the :meth:`.PlotWidget.addCurve` method:
.. code-block:: python
- plot.addCurve(x=(1, 2, 3), y=(3, 2, 1)) # Add a curve with default style
+ plot.addCurve(x=(1, 2, 3), y=(3, 2, 1), legend='curve') # Add a curve named 'curve'
-When you need to update this curve, call :meth:`.PlotWidget.addCurve` again with the new values to display:
+When you need to update this curve, first get the curve invoking :meth:`.PlotWidget.getCurve` and
+update its points invoking the curve's :meth:`~silx.gui.plot.items.Curve.setData` method:
.. code-block:: python
- plot.addCurve(x=(1, 2, 3), y=(1, 2, 3)) # Replace the existing curve
+ mycurve = plot.getCurve('curve') # Retrieve the curve
+ mycurve.setData(x=(1, 2, 3), y=(1, 2, 3)) # Update its data
-To clear the plotting area, call :meth:`.PlotWidget.clear`:
+To clear the plot, call :meth:`.PlotWidget.clear`:
.. code-block:: python
@@ -201,7 +145,7 @@ To clear the plotting area, call :meth:`.PlotWidget.clear`:
Multiple curves
+++++++++++++++
-In order to display multiple curves at the same time, you need to provide a different ``legend`` string for each of them:
+In order to display multiple curves in a frame, you need to provide a different ``legend`` string for each of them:
.. code-block:: python
@@ -213,14 +157,15 @@ In order to display multiple curves at the same time, you need to provide a diff
plot.addCurve(x, numpy.random.random(len(x)), legend='random')
-To update a curve, call :meth:`.PlotWidget.addCurve` with the ``legend`` of the curve you want to udpdate.
-By default, the new curve will keep the same color (and style) as the curve it is updating:
+To update a curve, call :meth:`.PlotWidget.getCurve` with the ``legend`` of the curve you want to update,
+and update its data through :meth:`~silx.gui.plot.items.Curve.setData`:
.. code-block:: python
- plot.addCurve(x, numpy.random.random(len(x)) - 1., legend='random')
+ curve = plot.getCurve('random')
+ curve.setData(x, numpy.random.random(len(x)) - 1.)
-To remove a curve from the plot, call :meth:`.PlotWidget.remove` with the ``legend`` of the curve you want to remove from the plot:
+To remove a curve from the plot, call :meth:`.PlotWidget.remove` with the ``legend`` of the curve you want to remove:
.. code-block:: python
@@ -235,9 +180,9 @@ To clear the plotting area, call :meth:`.PlotWidget.clear`:
Curve style
+++++++++++
-By default, different curves will automatically use different styles to render, and keep the same style when updated.
+By default, different curves will automatically be displayed using different styles, and keep the same style when updating the plot.
-It is possible to specify the ``color`` of the curve, its ``linewidth`` and ``linestyle`` as well as the ``symbol`` to use as markers for data points (See :meth:`.PlotWidget.addCurve` for more details):
+It is possible to specify the ``color`` of the curve, its ``linewidth`` and ``linestyle`` as well as the ``symbol`` to use as marker for data points (See :meth:`.PlotWidget.addCurve` for more details):
.. code-block:: python
@@ -262,24 +207,32 @@ It is possible to specify the ``color`` of the curve, its ``linewidth`` and ``li
Histogram
+++++++++
-Data can be displayed as an histogram. This must be specified when calling the the addCurve function. (using ``histogram``, See :meth:`.PlotWidget.addCurve` for more details ).
+To display histograms, use :meth:`.PlotWidget.addHistogram`:
-Histogram steps can be centered on x values or set at the left or the right of the given x values.
+.. code-block:: python
+
+ import numpy
+ values = numpy.arange(20) # Values of the histogram
+ edges = numpy.arange(21) # Edges of the bins (number of values + 1)
+ plot.addHistogram(values, edges, legend='histo1', fill=True, color='green')
+
+Alternatively, :meth:`.PlotWidget.addCurve` can be used to display histograms with the ``histogram`` argument.
+(See :meth:`.PlotWidget.addCurve` for more details).
.. code-block:: python
import numpy
x = numpy.arange(0, 20, 1)
- plot.addCurve(x, x+1, histogram='center', fill=True, color='green')
+ plot.addCurve(x, x+1, legend='histo2', histogram='center', fill=False, color='black')
-.. note:: You can also give x as edges. For this you must have len(x) = len(y) + 1
+Histogram bins can be centred on x values or set on the left hand side or the right hand side of the given x values.
Plot images in a widget
-----------------------
-The :class:`Plot2D` widget provides a plotting area and a toolbar with tools useful for images, such as keeping aspect ratio, changing the colormap or defining a mask.
+The :class:`~silx.gui.plot.PlotWindow.Plot2D` widget provides a plotting area and a toolbar with tools useful for images, such as keeping the aspect ratio, changing the colormap or defining a mask.
-First, create a :class:`Plot2D` widget:
+First, create a :class:`~silx.gui.plot.PlotWindow.Plot2D` widget:
.. code-block:: python
@@ -288,7 +241,6 @@ First, create a :class:`Plot2D` widget:
plot = Plot2D() # Create the plot widget
plot.show() # Make the plot widget visible
-
One image
+++++++++
@@ -299,46 +251,36 @@ To display a single image, use the :meth:`.PlotWidget.addImage` method:
import numpy
data = numpy.random.random(512 * 512).reshape(512, -1) # Create 2D image
- plot.addImage(data) # Plot the 2D data set with default colormap
-
+ plot.addImage(data, legend='image') # Plot the 2D data set with default colormap
-To update this image, call :meth:`.PlotWidget.addImage` again with the new image to display:
+To update this image, call :meth:`.PlotWidget.getImage` with its ``legend`` and
+update its data with :meth:`~silx.gui.plot.items.Image.setData`:
.. code-block:: python
- # Create a RGB image
- rgb_image = (numpy.random.random(512*512*3) * 255).astype(numpy.uint8)
- rgb_image.shape = 512, 512, 3
+ data2 = numpy.arange(512*512).reshape(512, 512)
- plot.addImage(rgb_image) # Plot the RGB image instead of the previous data
+ image = plot.getImage('image') # Retrieve the image
+ image.setData(data2) # Update the displayed data
+:meth:`.PlotWidget.addImage` supports both 2D arrays of data displayed with a colormap and RGB(A) images as 3D arrays of shape (height, width, color channels).
-To clear the plotting area, call :meth:`.PlotWidget.clear`:
+To clear the plot area, call :meth:`.PlotWidget.clear`:
.. code-block:: python
plot.clear()
-
Origin and scale
++++++++++++++++
-:meth:`.PlotWidget.addImage` supports both 2D arrays of data displayed with a colormap and RGB(A) images as 3D arrays of shape (height, width, color channels).
-When displaying an image, it is possible to specify the ``origin`` and the ``scale`` of the image array in the plot area coordinates:
+When displaying an image, it is possible to define the ``origin`` and the ``scale`` of the image array in the plot area coordinates:
.. code-block:: python
data = numpy.random.random(512 * 512).reshape(512, -1)
- plot.addImage(data, origin=(100, 100), scale=(0.1, 0.1))
-
-When updating an image, if ``origin`` and ``scale`` are not provided, the previous values will be used:
-
-.. code-block:: python
-
- data = numpy.random.random(512 * 512).reshape(512, -1)
- plot.addImage(data) # Keep previous origin and scale
-
+ plot.addImage(data, legend='image', origin=(100, 100), scale=(0.1, 0.1))
Colormap
++++++++
@@ -347,6 +289,8 @@ A ``colormap`` is described with a :class:`.Colormap` class as follows:
.. code-block:: python
+ from silx.gui.plot.Colormap import Colormap
+
colormap = Colormap(name='gray', # Name of the colormap
normalization='linear', # Either 'linear' or 'log'
vmin=0.0, # If not autoscale, data value to bind to min of colormap
@@ -354,7 +298,7 @@ A ``colormap`` is described with a :class:`.Colormap` class as follows:
)
-At least the following colormap names are guaranteed to be available, but any colormap name from `matplotlib <http://matplotlib.org/>`_ (see `Choosing Colormaps <http://matplotlib.org/users/colormaps.html>`_) should work:
+The following colormap names are guaranteed to be available:
- gray
- reversed gray
@@ -367,14 +311,18 @@ At least the following colormap names are guaranteed to be available, but any co
- inferno
- plasma
-It is possible to change the default colormap of :meth:`.PlotWidget.addImage` for the plot widget with :meth:`.PlotWidget.setDefaultColormap` (and to get it with :meth:`.PlotWidget.getDefaultColormap`):
+Yet, any colormap name from `matplotlib <http://matplotlib.org/>`_ (see `Choosing Colormaps <http://matplotlib.org/users/colormaps.html>`_) should work.
+
+It is possible to change the default colormap of the plot widget by :meth:`.PlotWidget.setDefaultColormap` (and to get it with :meth:`.PlotWidget.getDefaultColormap`):
.. code-block:: python
+ from silx.gui.plot.Colormap import Colormap
+
colormap = Colormap(name='viridis',
normalization='linear',
vmin=0.0,
- vmax=1.0)
+ vmax=10000.0)
plot.setDefaultColormap(colormap)
data = numpy.arange(512 * 512.).reshape(512, -1)
@@ -386,25 +334,18 @@ It is also possible to provide a :class:`.Colormap` to :meth:`.PlotWidget.addIma
colormap = Colormap(name='magma',
normalization='log',
- vmin=1.2,
- vmax=1.8)
+ vmin=1.8,
+ vmax=2.2)
data = numpy.random.random(512 * 512).reshape(512, -1) + 1.
plot.addImage(data, colormap=colormap)
-As for `Origin and scale`_, when updating an image, if ``colormap`` is not provided, the previous colormap will be used:
-
-.. code-block:: python
-
- data = numpy.random.random(512 * 512).reshape(512, -1) + 1.
- plot.addImage(data) # Keep previous colormap
-
The colormap can be changed by the user from the widget's toolbar.
Multiple images
+++++++++++++++
-In order to display multiple images at the same time, you need to provide a different ``legend`` string for each of them and to set the ``replace`` argument to ``False``:
+In order to display multiple images in a frame, you need to provide a different ``legend`` string for each of them and to set the ``replace`` argument to ``False``:
.. code-block:: python
@@ -415,27 +356,27 @@ In order to display multiple images at the same time, you need to provide a diff
plot.addImage(data, legend='arange', replace=False, origin=(512, 512))
-To update an image, call :meth:`.PlotWidget.addImage` with the ``legend`` of the curve you want to udpdate.
-By default, the new image will keep the same colormap, origin and scale as the image it is updating:
+To update an image, call :meth:`.PlotWidget.getImage` with the ``legend`` to get the corresponding curve.
+Update its data values using :meth:`~silx.gui.plot.items.setData`.
.. code-block:: python
data = (512 * 512. - numpy.arange(512 * 512.)).reshape(512, -1)
- plot.addImage(data, legend='arange', replace=False) # Beware of replace=False
-
+ arange_image = plot.getImage('arange')
+ arange_image.setData(data)
-To remove an image from the plot, call :meth:`.PlotWidget.remove` with the ``legend`` of the image you want to remove:
+To remove an image from a plot, call :meth:`.PlotWidget.remove` with the ``legend`` of the image you want to remove:
.. code-block:: python
plot.remove('random')
-Control plot axes
------------------
+Configure plot axes
+-------------------
-The following examples illustrate the API to control the plot axes.
-:meth:`.PlotWidget.getXAxis` and :meth:`.PlotWidget.getYAxis` give access to each plot axis (:class:`.items.Axis`) in order to control them.
+The following examples illustrate the API to configure the plot axes.
+:meth:`.PlotWidget.getXAxis` and :meth:`.PlotWidget.getYAxis` give access to each plot axis (:class:`.items.Axis`) in order to configure them.
Labels and title
++++++++++++++++
@@ -453,7 +394,7 @@ Use :meth:`.PlotWidget.getXAxis` and :meth:`.PlotWidget.getYAxis` to get the axe
Axes limits
+++++++++++
-Different methods allows to get and set the data limits displayed on each axis.
+Different methods allow to retrieve and set the data limits displayed on each axis.
The following code moves the visible plot area to the right:
@@ -463,7 +404,7 @@ The following code moves the visible plot area to the right:
offset = 0.1 * (xmax - xmin)
plot.getXAxis().setLimits(xmin + offset, xmax + offset)
-:meth:`.PlotWidget.resetZoom` set the plot limits to the bounds of the data:
+:meth:`.PlotWidget.resetZoom` set the plot limits to the upper and lower bounds of the data:
.. code-block:: python
@@ -475,7 +416,7 @@ See :meth:`.PlotWidget.resetZoom`, :meth:`.PlotWidget.setLimits`, :meth:`.PlotWi
Axes
++++
-Different methods allow plot axes modifications:
+The axes of a plot can be modified via different methods:
.. code-block:: python
diff --git a/doc/source/modules/gui/plot/index.rst b/doc/source/modules/gui/plot/index.rst
index b77bbcc..ab1c7df 100644
--- a/doc/source/modules/gui/plot/index.rst
+++ b/doc/source/modules/gui/plot/index.rst
@@ -36,6 +36,7 @@ Public modules
colormap.rst
items.rst
actions/index.rst
+ plottoolbuttons.rst
plottools.rst
profile.rst
roi.rst
diff --git a/doc/source/modules/gui/plot/plotsignal.rst b/doc/source/modules/gui/plot/plotsignal.rst
new file mode 100644
index 0000000..c4cb003
--- /dev/null
+++ b/doc/source/modules/gui/plot/plotsignal.rst
@@ -0,0 +1,166 @@
+
+.. currentmodule:: silx.gui.plot.PlotWidget
+
+.. _plot_signal:
+
+Plot signal
+-----------
+
+The :class:`PlotWidget` sends events through its :attr:`PlotWidget.sigPlotSignal`
+signal.
+Those events are sent as a dictionary with a key 'event' describing the kind
+of event.
+
+.. note::
+
+ These dictionary events will be replaced by objects in the future.
+
+
+Drawing events
+..............
+
+'drawingProgress' and 'drawingFinished' events are sent during drawing
+interaction (See :meth:`PlotWidget.setInteractiveMode`).
+
+- 'event': 'drawingProgress' or 'drawingFinished'
+- 'parameters': dict of parameters used by the drawing mode.
+ It has the following keys: 'shape', 'label', 'color'.
+ See :meth:`PlotWidget.setInteractiveMode`.
+- 'points': Points (x, y) in data coordinates of the drawn shape.
+ For 'hline' and 'vline', it is the 2 points defining the line.
+ For 'line' and 'rectangle', it is the coordinates of the start
+ drawing point and the latest drawing point.
+ For 'polygon', it is the coordinates of all points of the shape.
+- 'type': The type of drawing in 'line', 'hline', 'polygon', 'rectangle',
+ 'vline'.
+- 'xdata' and 'ydata': X coords and Y coords of shape points in data
+ coordinates (as in 'points').
+
+When the type is 'rectangle', the following additional keys are provided:
+
+- 'x' and 'y': The origin of the rectangle in data coordinates
+- 'widht' and 'height': The size of the rectangle in data coordinates
+
+
+Mouse events
+............
+
+'mouseMoved', 'mouseClicked' and 'mouseDoubleClicked' events are sent for
+mouse events.
+
+They provide the following keys:
+
+- 'event': 'mouseMoved', 'mouseClicked' or 'mouseDoubleClicked'
+- 'button': the mouse button that was pressed in 'left', 'middle', 'right'
+- 'x' and 'y': The mouse position in data coordinates
+- 'xpixel' and 'ypixel': The mouse position in pixels
+
+
+Marker events
+.............
+
+'hover', 'markerClicked', 'markerMoving' and 'markerMoved' events are
+sent during interaction with markers.
+
+'hover' is sent when the mouse cursor is over a marker.
+'markerClicker' is sent when the user click on a selectable marker.
+'markerMoving' and 'markerMoved' are sent when a draggable marker is moved.
+
+They provide the following keys:
+
+- 'event': 'hover', 'markerClicked', 'markerMoving' or 'markerMoved'
+- 'button': the mouse button that is pressed in 'left', 'middle', 'right'
+- 'draggable': True if the marker is draggable, False otherwise
+- 'label': The legend associated with the clicked image or curve
+- 'selectable': True if the marker is selectable, False otherwise
+- 'type': 'marker'
+- 'x' and 'y': The mouse position in data coordinates
+- 'xdata' and 'ydata': The marker position in data coordinates
+
+'markerClicked' and 'markerMoving' events have a 'xpixel' and a 'ypixel'
+additional keys, that provide the mouse position in pixels.
+
+
+Image and curve events
+......................
+
+'curveClicked' and 'imageClicked' events are sent when a selectable curve
+or image is clicked.
+
+Both share the following keys:
+
+- 'event': 'curveClicked' or 'imageClicked'
+- 'button': the mouse button that was pressed in 'left', 'middle', 'right'
+- 'label': The legend associated with the clicked image or curve
+- 'type': The type of item in 'curve', 'image'
+- 'x' and 'y': The clicked position in data coordinates
+- 'xpixel' and 'ypixel': The clicked position in pixels
+
+'curveClicked' events have a 'xdata' and a 'ydata' additional keys, that
+provide the coordinates of the picked points of the curve.
+There can be more than one point of the curve being picked, and if a line of
+the curve is picked, only the first point of the line is included in the list.
+
+'imageClicked' have a 'col' and a 'row' additional keys, that provide
+the column and row index in the image array that was clicked.
+
+
+Limits changed events
+.....................
+
+.. warning::
+
+ This event is deprecated. Use :attr:`silx.gui.plot.items.axis.Axis.sigLimitsChanged`
+ instead. See :meth:`PlotWidget.getXAxis` and :meth:`PlotWidget.getYAxis`.
+
+'limitsChanged' events are sent when the limits of the plot are changed.
+This can results from user interaction or API calls.
+
+It provides the following keys:
+
+- 'event': 'limitsChanged'
+- 'source': id of the widget that emitted this event.
+- 'xdata': Range of X in graph coordinates: (xMin, xMax).
+- 'ydata': Range of Y in graph coordinates: (yMin, yMax).
+- 'y2data': Range of right axis in graph coordinates (y2Min, y2Max) or None.
+
+Plot state change events
+........................
+
+.. warning::
+
+ These events are deprecated.  
+ Use :attr:`PlotWidget.sigSetKeepDataAspectRatio`,
+ :attr:`PlotWidget.sigSetGraphGrid`, :attr:`PlotWidget.sigSetGraphCursor`,
+ :attr:`PlotWidget.sigContentChanged`, :attr:`PlotWidget.sigActiveCurveChanged`,
+ :attr:`PlotWidget.sigActiveImageChanged` and
+ :attr:`PlotWidget.sigInteractiveModeChanged` instead.
+
+
+The following events are emitted when the plot is modified.
+They provide the new state:
+
+- 'setGraphCursor' event with a 'state' key (bool)
+- 'setGraphGrid' event with a 'which' key (str), see :meth:`setGraphGrid`
+- 'setKeepDataAspectRatio' event with a 'state' key (bool)
+
+A 'contentChanged' event is triggered when the content of the plot is updated.
+It provides the following keys:
+
+- 'action': The change of the plot: 'add' or 'remove'
+- 'kind': The kind of primitive changed: 'curve', 'image', 'item' or 'marker'
+- 'legend': The legend of the primitive changed.
+
+'activeCurveChanged' and 'activeImageChanged' events with the following keys:
+
+- 'legend': Name (str) of the current active item or None if no active item.
+- 'previous': Name (str) of the previous active item or None if no item was
+ active. It is the same as 'legend' if 'updated' == True
+- 'updated': (bool) True if active item name did not changed,
+ but active item data or style was updated.
+
+'interactiveModeChanged' event with a 'source' key identifying the object
+setting the interactive mode.
+
+'defaultColormapChanged' event is triggered when the default colormap of
+the plot is updated.
diff --git a/doc/source/modules/gui/plot/plottoolbuttons.rst b/doc/source/modules/gui/plot/plottoolbuttons.rst
new file mode 100644
index 0000000..e1e1626
--- /dev/null
+++ b/doc/source/modules/gui/plot/plottoolbuttons.rst
@@ -0,0 +1,7 @@
+:mod:`~silx.gui.plot.PlotToolButtons`: QToolButtons for plot widgets
+====================================================================
+
+.. currentmodule:: silx.gui.plot.PlotToolButtons
+
+.. automodule:: silx.gui.plot.PlotToolButtons
+ :members:
diff --git a/doc/source/modules/gui/plot/plotwidget.rst b/doc/source/modules/gui/plot/plotwidget.rst
index a8e7831..d045f92 100644
--- a/doc/source/modules/gui/plot/plotwidget.rst
+++ b/doc/source/modules/gui/plot/plotwidget.rst
@@ -166,6 +166,11 @@ The :class:`PlotWidget` provides the following Qt signals:
.. autoattribute:: PlotWidget.sigActiveScatterChanged
.. autoattribute:: PlotWidget.sigInteractiveModeChanged
+.. toctree::
+ :hidden:
+
+ plotsignal.rst
+
.. PlotWidget public API that is not documented:
Could be added:
- addItem
diff --git a/doc/source/modules/gui/plot3d/actions.rst b/doc/source/modules/gui/plot3d/actions.rst
index c9e3af2..66086bc 100644
--- a/doc/source/modules/gui/plot3d/actions.rst
+++ b/doc/source/modules/gui/plot3d/actions.rst
@@ -12,4 +12,7 @@
.. automodule:: silx.gui.plot3d.actions.mode
:members:
+.. automodule:: silx.gui.plot3d.actions.viewpoint
+ :members:
+
.. autoclass:: Plot3DAction
diff --git a/doc/source/modules/gui/plot3d/dev.rst b/doc/source/modules/gui/plot3d/dev.rst
index 96704f8..f135767 100644
--- a/doc/source/modules/gui/plot3d/dev.rst
+++ b/doc/source/modules/gui/plot3d/dev.rst
@@ -12,10 +12,10 @@ Widget-level API
Widgets are available as modules of the :mod:`silx.gui.plot3d` packages.
The :mod:`.Plot3DWidget` module provides the OpenGL canvas where the scene is rendered.
-The :mod:`.Plot3DWindow` module provides a :class:`QMainWindow` with a :class:`Plot3DWindow` as its central widget,
-toolbars (:class:`InteractiveModeToolBar` and :class:`OutputToolBar`) and a :class:`ViewpointToolButton` in a toolbar.
-:class:`QAction` that can be associated with a :class:`Plot3DWidget` are defined in the :mod:`.actions` module.
-Those actions are used by the :class:`OutputToolBar` and the :class:`InteractiveModeToolBar` toolbars.
+The :mod:`.Plot3DWindow` module provides a :class:`QMainWindow` with a :class:`Plot3DWindow` as its central widget
+and toolbars: :class:`InteractiveModeToolBar`, :class:`ViewpointToolBar` and :class:`OutputToolBar`.
+:class:`QAction` that can be associated with a :class:`Plot3DWidget` are defined in the :mod:`.actions` package.
+Toolbars and tool buttons are available in :mod:`.tools` package.
The :mod:`.ScalarFieldView` module defines the :class:`ScalarFieldView` widget that displays iso-surfaces of a 3D scalar data set and the associated classes.
The :mod:`.SFViewParamTree` module defines a :class:`SFViewParamTree.TreeView` widget that can be attached to a :class:`ScalarFieldView` to control the display.
diff --git a/doc/source/modules/gui/plot3d/img/Plot3DWindow.png b/doc/source/modules/gui/plot3d/img/Plot3DWindow.png
index 0e562f5..6066d2a 100644
--- a/doc/source/modules/gui/plot3d/img/Plot3DWindow.png
+++ b/doc/source/modules/gui/plot3d/img/Plot3DWindow.png
Binary files differ
diff --git a/doc/source/modules/gui/plot3d/img/ScalarFieldView.png b/doc/source/modules/gui/plot3d/img/ScalarFieldView.png
index f40fdac..f8f61da 100644
--- a/doc/source/modules/gui/plot3d/img/ScalarFieldView.png
+++ b/doc/source/modules/gui/plot3d/img/ScalarFieldView.png
Binary files differ
diff --git a/doc/source/modules/gui/plot3d/img/SceneWidget.png b/doc/source/modules/gui/plot3d/img/SceneWidget.png
new file mode 100644
index 0000000..610c41a
--- /dev/null
+++ b/doc/source/modules/gui/plot3d/img/SceneWidget.png
Binary files differ
diff --git a/doc/source/modules/gui/plot3d/img/SceneWindow.png b/doc/source/modules/gui/plot3d/img/SceneWindow.png
new file mode 100644
index 0000000..c3c48af
--- /dev/null
+++ b/doc/source/modules/gui/plot3d/img/SceneWindow.png
Binary files differ
diff --git a/doc/source/modules/gui/plot3d/index.rst b/doc/source/modules/gui/plot3d/index.rst
index 38b8f02..e0a14f6 100644
--- a/doc/source/modules/gui/plot3d/index.rst
+++ b/doc/source/modules/gui/plot3d/index.rst
@@ -23,6 +23,8 @@ The following sub-modules are available:
plot3dwidget.rst
plot3dwindow.rst
+ scenewidget.rst
+ scenewindow.rst
scalarfieldview.rst
sfviewparamtree.rst
tools.rst
@@ -32,7 +34,7 @@ The following sub-modules are available:
Sample code
-----------
-- :doc:`viewer3dvolume_example`: Sample code using :class:`ScalarFieldView`
+See :ref:`plot3d-sample-code`
Internals
---------
@@ -41,8 +43,3 @@ Internals
:maxdepth: 2
dev.rst
-
-.. toctree::
- :hidden:
-
- viewer3dvolume_example.rst
diff --git a/doc/source/modules/gui/plot3d/items.rst b/doc/source/modules/gui/plot3d/items.rst
new file mode 100644
index 0000000..1162cb9
--- /dev/null
+++ b/doc/source/modules/gui/plot3d/items.rst
@@ -0,0 +1,173 @@
+.. currentmodule:: silx.gui.plot3d
+
+:mod:`items`: SceneWidget items
+===============================
+
+The following classes are items that describes the content of a :class:`SceneWidget`:
+
+.. currentmodule:: silx.gui.plot3d.items
+
+- :class:`~silx.gui.plot3d.items.image.ImageData`
+- :class:`~silx.gui.plot3d.items.image.ImageRgba`
+- :class:`~silx.gui.plot3d.items.scatter.Scatter2D`
+- :class:`~silx.gui.plot3d.items.scatter.Scatter3D`
+- :class:`~silx.gui.plot3d.items.volume.ScalarField3D`
+- :class:`~silx.gui.plot3d.items.clipplane.ClipPlane`
+- :class:`~silx.gui.plot3d.items.mesh.Mesh`
+- :class:`~silx.gui.plot3d.items.core.GroupItem`
+
+2D images
+---------
+
+.. currentmodule:: silx.gui.plot3d.core
+
+.. currentmodule:: silx.gui.plot3d.items.image
+
+:class:`ImageData`
+++++++++++++++++++
+
+:class:`ImageData` inherits from :class:`.DataItem3D` and also provides its API.
+
+.. autoclass:: ImageData
+ :members: getData, setData,
+ getColormap, setColormap,
+ getInterpolation, setInterpolation
+
+:class:`ImageRgba`
+++++++++++++++++++
+
+:class:`ImageRgba` inherits from :class:`.DataItem3D` and also provides its API.
+
+.. autoclass:: ImageRgba
+ :members: getData, setData,
+ getInterpolation, setInterpolation
+
+2D/3D scatter data
+------------------
+
+.. currentmodule:: silx.gui.plot3d.items.scatter
+
+:class:`Scatter2D`
+++++++++++++++++++
+
+:class:`Scatter2D` inherits from :class:`.DataItem3D` and also provides its API.
+
+.. autoclass:: Scatter2D
+ :members: getData, setData, getXData, getYData, getValues,
+ supportedVisualizations, isPropertyEnabled,
+ getVisualization, setVisualization,
+ isHeightMap, setHeightMap,
+ getLineWidth, setLineWidth,
+ getColormap, setColormap,
+ getSupportedSymbols, getSymbol, setSymbol
+
+:class:`Scatter3D`
+++++++++++++++++++
+
+:class:`Scatter3D` inherits from :class:`.DataItem3D` and also provides its API.
+
+.. autoclass:: Scatter3D
+ :members: getData, setData, getXData, getYData, getZData, getValues,
+ getColormap, setColormap,
+ getSupportedSymbols, getSymbol, setSymbol
+
+3D volume
+---------
+
+.. currentmodule:: silx.gui.plot3d.items.volume
+
+:class:`ScalarField3D`
+++++++++++++++++++++++
+
+:class:`ScalarField3D` inherits from :class:`.DataItem3D` and also provides its API.
+
+.. autoclass:: ScalarField3D
+ :members: getData, setData,
+ getCutPlanes,
+ sigIsosurfaceAdded, sigIsosurfaceRemoved,
+ addIsosurface, getIsosurfaces, removeIsosurface, clearIsosurfaces
+
+The following classes allows to configure :class:`ScalarField3D` visualization:
+
+:class:`IsoSurface`
++++++++++++++++++++
+
+:class:`IsoSurface` inherits from :class:`.Item3D` and also provides its API.
+
+.. autoclass:: Isosurface
+ :show-inheritance:
+ :members:
+
+:class:`CutPlane`
++++++++++++++++++
+
+:class:`CutPlane` inherits from :class:`.Item3D` and also provides its API.
+
+.. autoclass:: CutPlane
+ :members: getColormap, setColormap,
+ getInterpolation, setInterpolation,
+ moveToCenter, isValid,
+ getNormal, setNormal,
+ getPoint, setPoint,
+ getParameters, setParameters,
+ getDisplayValuesBelowMin, setDisplayValuesBelowMin
+
+Clipping plane
+--------------
+
+.. currentmodule:: silx.gui.plot3d.items.clipplane
+
+:class:`ClipPlane`
+++++++++++++++++++
+
+:class:`ClipPlane` inherits from :class:`.Item3D` and also provides its API.
+
+.. autoclass:: ClipPlane
+ :show-inheritance:
+ :members:
+
+3D mesh
+-------
+
+.. currentmodule:: silx.gui.plot3d.items.mesh
+
+:class:`Mesh`
++++++++++++++
+
+:class:`Mesh` inherits from :class:`.DataItem3D` and also provides its API.
+
+.. autoclass:: Mesh
+ :show-inheritance:
+ :members:
+
+Item base classes
+-----------------
+
+The following classes provides the base classes for other items.
+
+.. currentmodule:: silx.gui.plot3d.items.core
+
+:class:`Item3D`
++++++++++++++++
+
+.. autoclass:: Item3D
+ :show-inheritance:
+ :members:
+
+:class:`DataItem3D`
++++++++++++++++++++
+
+:class:`DataItem3D` inherits from :class:`.Item3D` and also provides its API.
+
+.. autoclass:: DataItem3D
+ :show-inheritance:
+ :members:
+
+:class:`GroupItem`
+++++++++++++++++++
+
+:class:`GroupItem` inherits from :class:`.DataItem3D` and also provides its API.
+
+.. autoclass:: GroupItem
+ :show-inheritance:
+ :members:
diff --git a/doc/source/modules/gui/plot3d/scalarfieldview.rst b/doc/source/modules/gui/plot3d/scalarfieldview.rst
index 80127ea..b2e1e67 100644
--- a/doc/source/modules/gui/plot3d/scalarfieldview.rst
+++ b/doc/source/modules/gui/plot3d/scalarfieldview.rst
@@ -5,7 +5,7 @@
.. automodule:: silx.gui.plot3d.ScalarFieldView
-For sample code using ScalarFieldView, see :doc:`viewer3dvolume_example`
+For sample code using ScalarFieldView, see :ref:`plot3d-sample-code`
.. currentmodule:: silx.gui.plot3d.ScalarFieldView
diff --git a/doc/source/modules/gui/plot3d/scenewidget.rst b/doc/source/modules/gui/plot3d/scenewidget.rst
new file mode 100644
index 0000000..5c6f411
--- /dev/null
+++ b/doc/source/modules/gui/plot3d/scenewidget.rst
@@ -0,0 +1,29 @@
+.. currentmodule:: silx.gui.plot3d
+
+:mod:`SceneWidget`: 3D data viewer widget
+=========================================
+
+.. automodule:: silx.gui.plot3d.SceneWidget
+
+.. image:: img/SceneWidget.png
+ :height: 150px
+ :align: center
+
+For sample code using :class:`SceneWidget`, see ``plot3dSceneWindow.py`` in :ref:`plot3d-sample-code`.
+
+.. currentmodule:: silx.gui.plot3d.SceneWidget
+
+:class:`SceneWidget`
+--------------------
+
+.. autoclass:: SceneWidget
+ :show-inheritance:
+ :members:
+
+:class:`SceneWidget` items
+--------------------------
+
+.. toctree::
+ :maxdepth: 2
+
+ items.rst \ No newline at end of file
diff --git a/doc/source/modules/gui/plot3d/scenewindow.rst b/doc/source/modules/gui/plot3d/scenewindow.rst
new file mode 100644
index 0000000..ee6a59b
--- /dev/null
+++ b/doc/source/modules/gui/plot3d/scenewindow.rst
@@ -0,0 +1,22 @@
+.. currentmodule:: silx.gui.plot3d.SceneWindow
+
+
+:mod:`SceneWindow`: 3D data viewer window
+=========================================
+
+.. automodule:: silx.gui.plot3d.SceneWindow
+
+.. image:: img/SceneWindow.png
+ :height: 150px
+ :align: center
+
+For sample code using :class:`SceneWindow`, see ``plot3dSceneWindow.py`` in :ref:`plot3d-sample-code`.
+
+See :class:`~silx.gui.plot3d.SceneWidget.SceneWidget` for the API to manage the visualized 3D data.
+
+:class:`SceneWindow`
+--------------------
+
+.. autoclass:: SceneWindow
+ :show-inheritance:
+ :members:
diff --git a/doc/source/modules/gui/plot3d/viewer3dvolume_example.rst b/doc/source/modules/gui/plot3d/viewer3dvolume_example.rst
deleted file mode 100644
index 5368e05..0000000
--- a/doc/source/modules/gui/plot3d/viewer3dvolume_example.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-viewer3DVolume.py
-=================
-
-Sample code demonstrating :mod:`silx.gui.plot3d.ScalarFieldView` widget:
-
-.. literalinclude:: ../../../../../examples/viewer3DVolume.py
- :lines: 38- \ No newline at end of file
diff --git a/doc/source/modules/index.rst b/doc/source/modules/index.rst
index b9a4753..b6e0036 100644
--- a/doc/source/modules/index.rst
+++ b/doc/source/modules/index.rst
@@ -8,7 +8,8 @@ API Reference
io/index.rst
image/index.rst
math/index.rst
+ opencl/index.rst
resources.rst
+ sx.rst
utils/index.rst
test/index.rst
-
diff --git a/doc/source/modules/io/index.rst b/doc/source/modules/io/index.rst
index 815a094..b504695 100644
--- a/doc/source/modules/io/index.rst
+++ b/doc/source/modules/io/index.rst
@@ -16,6 +16,7 @@
specfile.rst
specfilewrapper.rst
spech5.rst
+ url.rst
utils.rst
Top-level functions
@@ -23,6 +24,7 @@ Top-level functions
.. autofunction:: silx.io.open
.. autofunction:: silx.io.save1D
+.. autofunction:: silx.io.get_data
.. autofunction:: silx.io.is_dataset
.. autofunction:: silx.io.is_group
diff --git a/doc/source/modules/io/url.rst b/doc/source/modules/io/url.rst
new file mode 100644
index 0000000..6184904
--- /dev/null
+++ b/doc/source/modules/io/url.rst
@@ -0,0 +1,8 @@
+
+.. currentmodule:: silx.io
+
+:mod:`url`: Utils for data locators
+-----------------------------------
+
+.. automodule:: silx.io.url
+ :members:
diff --git a/doc/source/modules/opencl/codec_cbf.rst b/doc/source/modules/opencl/codec_cbf.rst
new file mode 100644
index 0000000..f39a484
--- /dev/null
+++ b/doc/source/modules/opencl/codec_cbf.rst
@@ -0,0 +1,9 @@
+
+.. currentmodule:: silx.opencl.codec
+
+:mod:`byte_offset`: Byte Offset compression/decompression
+---------------------------------------------------------
+
+.. automodule:: silx.opencl.codec.byte_offset
+ :members: ByteOffset
+ :show-inheritance:
diff --git a/doc/source/modules/opencl/fbp.rst b/doc/source/modules/opencl/fbp.rst
new file mode 100644
index 0000000..3c8c465
--- /dev/null
+++ b/doc/source/modules/opencl/fbp.rst
@@ -0,0 +1,10 @@
+
+.. currentmodule:: silx.opencl
+
+:mod:`backprojection`: (Filtered) Back-Projection
+--------------------------------------------------
+
+.. automodule:: silx.opencl.backprojection
+ :members: Backprojection
+ :show-inheritance:
+ :undoc-members:
diff --git a/doc/source/modules/opencl/index.rst b/doc/source/modules/opencl/index.rst
new file mode 100644
index 0000000..e17eecb
--- /dev/null
+++ b/doc/source/modules/opencl/index.rst
@@ -0,0 +1,15 @@
+
+.. py:module:: silx.opencl
+
+:mod:`silx.opencl`: OpenCL-based features
+=========================================
+
+
+.. toctree::
+ :maxdepth: 1
+
+ sift/index.rst
+ fbp.rst
+ medfilt.rst
+ codec_cbf.rst
+
diff --git a/doc/source/modules/opencl/medfilt.rst b/doc/source/modules/opencl/medfilt.rst
new file mode 100644
index 0000000..b1379f7
--- /dev/null
+++ b/doc/source/modules/opencl/medfilt.rst
@@ -0,0 +1,7 @@
+.. currentmodule:: silx.opencl
+
+:mod:`medianfilter`: OpenCL median filter
+------------------------------------------
+
+.. automodule:: silx.opencl.medfilt
+ :members: MedianFilter2D, medfilt2d
diff --git a/doc/source/modules/opencl/sift/align.rst b/doc/source/modules/opencl/sift/align.rst
new file mode 100644
index 0000000..01b9fd6
--- /dev/null
+++ b/doc/source/modules/opencl/sift/align.rst
@@ -0,0 +1,7 @@
+.. currentmodule:: silx.opencl.sift
+
+:mod:`alignment`: SIFT Plan for linear alignment
+-------------------------------------------------
+
+.. automodule:: silx.opencl.sift.alignment
+ :members: LinearAlign
diff --git a/doc/source/modules/opencl/sift/index.rst b/doc/source/modules/opencl/sift/index.rst
new file mode 100644
index 0000000..9ae0d6f
--- /dev/null
+++ b/doc/source/modules/opencl/sift/index.rst
@@ -0,0 +1,11 @@
+.. currentmodule:: silx.opencl.sift
+
+:mod:`sift`: SIFT image alignment
+==================================
+
+.. toctree::
+ :maxdepth: 1
+
+ plan.rst
+ match.rst
+ align.rst
diff --git a/doc/source/modules/opencl/sift/match.rst b/doc/source/modules/opencl/sift/match.rst
new file mode 100644
index 0000000..c64c7d3
--- /dev/null
+++ b/doc/source/modules/opencl/sift/match.rst
@@ -0,0 +1,7 @@
+.. currentmodule:: silx.opencl.sift
+
+:mod:`match`: SIFT Plan for keypoints matching
+------------------------------------------------------
+
+.. automodule:: silx.opencl.sift.match
+ :members: MatchPlan, match_py
diff --git a/doc/source/modules/opencl/sift/plan.rst b/doc/source/modules/opencl/sift/plan.rst
new file mode 100644
index 0000000..135495d
--- /dev/null
+++ b/doc/source/modules/opencl/sift/plan.rst
@@ -0,0 +1,7 @@
+.. currentmodule:: silx.opencl.sift
+
+:mod:`plan`: SIFT Plan
+-----------------------
+
+.. automodule:: silx.opencl.sift.plan
+ :members: SiftPlan
diff --git a/doc/source/modules/sx.rst b/doc/source/modules/sx.rst
new file mode 100644
index 0000000..d5e0288
--- /dev/null
+++ b/doc/source/modules/sx.rst
@@ -0,0 +1,77 @@
+
+:mod:`silx.sx`: Using silx from Python Interpreter
+==================================================
+
+.. currentmodule:: silx.sx
+
+.. automodule:: silx.sx
+
+Plot functions
+--------------
+
+The following functions plot curves and images with silx widgets:
+
+- :func:`plot` for curves
+- :func:`imshow` for images
+
+The :func:`ginput` function handles user selection on those widgets.
+
+
+.. note:: Those functions are not available from a notebook.
+
+:func:`plot`
+++++++++++++
+
+.. autofunction:: plot
+
+:func:`imshow`
+++++++++++++++
+
+.. autofunction:: imshow
+
+
+:func:`ginput`
+++++++++++++++
+
+.. autofunction:: ginput
+
+3D plot functions
+-----------------
+
+The following functions plot 3D data with silx widgets (it requires OpenGL):
+
+- :func:`contour3d` for isosurfaces (and cut plane) in a 3D scalar field
+- :func:`points3d` for 2D/3D scatter plots
+
+.. note:: Those functions are not available from a notebook.
+
+:func:`contour3d`
++++++++++++++++++
+
+.. autofunction:: contour3d
+
+:func:`points3d`
+++++++++++++++++
+
+.. autofunction:: points3d
+
+Widgets
+-------
+
+The widgets of the :mod:`silx.gui.plot` package are also exposed in this package.
+See :mod:`silx.gui.plot` for documentation.
+
+Input/Output
+------------
+
+The content of the :mod:`silx.io` package is also exposed in this package.
+See :mod:`silx.io` for documentation.
+
+Math
+----
+
+The following classes from :mod:`silx.math` are exposed in this package:
+
+- :class:`~silx.math.histogram.Histogramnd`
+- :class:`~silx.math.histogram.HistogramndLut`
+- :class:`~silx.math.fit.leastsq`
diff --git a/doc/source/modules/utils/index.rst b/doc/source/modules/utils/index.rst
index 4eac097..7dd10dd 100644
--- a/doc/source/modules/utils/index.rst
+++ b/doc/source/modules/utils/index.rst
@@ -7,5 +7,5 @@
array_like.rst
decorators.rst
html.rst
+ testutils.rst
weakref.rst
-
diff --git a/doc/source/modules/utils/testutils.rst b/doc/source/modules/utils/testutils.rst
new file mode 100644
index 0000000..854f4be
--- /dev/null
+++ b/doc/source/modules/utils/testutils.rst
@@ -0,0 +1,7 @@
+.. currentmodule:: silx.utils
+
+:mod:`testutils`
+----------------
+
+.. automodule:: silx.utils.testutils
+ :members: