diff options
Diffstat (limited to 'doc/source')
93 files changed, 1652 insertions, 392 deletions
diff --git a/doc/source/Tutorials/fitconfig.rst b/doc/source/Tutorials/fitconfig.rst index 1b5e8ae..225ef8f 100644 --- a/doc/source/Tutorials/fitconfig.rst +++ b/doc/source/Tutorials/fitconfig.rst @@ -122,7 +122,7 @@ used by our fit function to scale the *y* values. self.scalingFactorEdit.setToolTip( "Enter the scaling factor" ) - self.scalingFactorEdit.setValidator(qt.QDoubleValidator()) + self.scalingFactorEdit.setValidator(qt.QDoubleValidator(self)) self.ok = qt.QPushButton("ok", self) self.ok.clicked.connect(self.accept) diff --git a/doc/source/Tutorials/img/silx_view_edf.png b/doc/source/Tutorials/img/silx_view_edf.png Binary files differnew file mode 100644 index 0000000..424c165 --- /dev/null +++ b/doc/source/Tutorials/img/silx_view_edf.png diff --git a/doc/source/Tutorials/io.rst b/doc/source/Tutorials/io.rst new file mode 100644 index 0000000..139ad2d --- /dev/null +++ b/doc/source/Tutorials/io.rst @@ -0,0 +1,289 @@ + +Getting started with silx.io +============================ + +This tutorial explains how to read data files using the :meth:`silx.io.open` function. + +The target audience are developers without knowledge of the *h5py* library. + +If you are already familiar with *h5py*, you just need to know that +the :meth:`silx.io.open` function returns objects that mimic *h5py* file objects, +and that the main supported file formats are: + + - HDF5 + - all formats supported by the *FabIO* library + - SPEC data files + +Knowledge about the python *dictionary* type and the numpy *ndarray* type +are prerequisites for this tutorial. + + +Background +---------- + +In the past, it was necessary to learn how to use multiple libraries to read multiple +data formats. The library *FabIO* was designed to read images in many formats, but not to read +more heterogeneous formats, such as *HDF5* or *SPEC*. + +To read *SPEC* data files in Python, a common solution was to use the *PyMca* module +:mod:`PyMca5.PyMcaIO.specfilewrapper`. +Regarding HDF5 files, the de-facto standard for reading them in Python is to +use the *h5py* library. + +*silx* tries to address this situation by providing a unified way to read all +data formats supported at the ESRF. Today, HDF5 is the preffered format to store +data for many scientific institutions, including most synchrotrons. +So it was decided to provide tools for reading data that mimic the *h5py* library's API. + + +Definitions +----------- + +HDF5 +++++ + +The *HDF5* format is a *hierarchical data format*, designed to store and +organize large amounts of data. + +A HDF5 file contains a number of *datasets*, which are multidimensional arrays +of a homogeneous type. + +These datasets are stored in container structures +called *groups*. Groups can also be stored in other groups, allowing to +define a hierarchical tree structure. + +Both datasets and groups may have *attributes* attached to them. Attributes are +used to document the object. They are similar to datasets in several ways +(data container of homogeneous type), but they are typically much smaller. + +It is a common analogy to compare a HDF5 file to a filesystem. +Groups are analogous to directories, while datasets are analogous to files, +and attributes are analogous to file metadata (creation date, last modification...). + +.. image:: img/silx_view_edf.png + :width: 400px + + +h5py +++++ + +The *h5py* library is a Pythonic interface to the `HDF5`_ binary data format. + +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. + +API description +--------------- + +All main objects, File, Group and Dataset, share the following attributes: + + - :attr:`attrs`: Attributes, as a dictionary of metadata for the group or dataset. + - :attr:`basename`: String giving the basename of this group or dataset. + - :attr:`name`: String giving the full path to this group or dataset, relative + to the root group (file). + - :attr:`file`: File object at the root of the tree structure containing this + group or dataset. + - :attr:`parent`: Group object containing this group or dataset. + +File object ++++++++++++ + +The API of the file objects returned by the :meth:`silx.io.open` +function tries to be as close as possible to the API of the :class:`h5py.File` +objects used to read HDF5 data. + +A h5py file is a group with just a few extra attributes and methods. + +The objects defined in `silx.io` implement a subset of these attributes and methods: + + - :attr:`filename`: Name of the file on disk. + - :attr:`mode`: String indicating if the file is open in read mode ("r") + or write mode ("w"). :meth:`silx.io.open` always returns objects in read mode. + - :meth:`close`: Close this file. All open objects will become invalid. + +The :attr:`parent` of a file is `None`, and its :attr:`name` is an empty string. + +Group object +++++++++++++ + +Group objects behave like python dictionaries. + +You can iterate over a group's :meth:`keys`, which are the names of the objects +encapsulated by the group (datasets and sub-groups). The :meth:`values` method +returns an iterator over the encapsulated objects. The :meth:`items` method returns +an iterator over `(name, value)` pairs. + +Groups provide a :meth:`get` method that retrieves an item, or information about an item. +Like standard python dictionaries, a `default` parameter can be used to specify +a value to be returned if the given name is not a member of the group. + +Two methods are provided to visit recursively all members of a group, :meth:`visit` +and :meth:`visititems`. The former takes as argument a *callable* with the signature +``callable(name) -> None or return value``. The latter takes as argument a *callable* +with the signature ``callable(name, object) -> None or return value`` (``object`` being a +a group or dataset instance.) + +Example +------- + +Accessing data +++++++++++++++ + +In this first example, we open a Spec data file and we print some of its information. + +.. code-block:: python + + >>> import silx.io + >>> sf = silx.io.open("data/CuZnO_2.spec") + <silx.io.spech5.SpecH5 at 0x7f00d0760f90> + >>> print(sf.keys()) + ['1.1', '2.1', '3.1', '4.1', '5.1', '6.1', '7.1', ...] + >>> print(sf["1.1"]) + <silx.io.spech5.ScanGroup object at 0x7f00d0715b90> + + +We just opened a file, keeping a reference to the file object as ``sf``. +We then printed all items contained in this root group. We can see that all +these items are groups. Lets looks at what is inside these groups, and find +datasets: + + +.. code-block:: python + + >>> grp = sf["2.1"] + ... for name in grp: + ... item = grp[name] + ... print("Found item " + name) + ... if silx.io.is_dataset(item): + ... print("'%s' is a dataset.\n" % name) + ... elif silx.io.is_group(item): + ... print("'%s' is a group.\n" % name) + ... + Found item title + title is a dataset. + + Found item start_time + start_time is a dataset. + + Found item instrument + instrument is a group. + + Found item measurement + measurement is a group. + + Found item sample + sample is a group. + +We could have replaced the first three lines with this single line, +by iterating over the iterator returned by the group method :meth:`items`: + +.. code-block:: python + + >>> for name, item in sf["2.1"].items(): + ... + +In addition to :meth:`silx.io.is_group` and :meth:`silx.io.is_dataset`, +you can also use :meth:`silx.io.is_file` and :meth:`silx.io.is_softlink`. + + +Let's look at a dataset: + +.. code-block:: python + + >>> print(sf["2.1/title"]) + <HDF5-like dataset "title": shape (), type "|S29"> + +As you can see, printing a dataset does not print the data itself, it only print a +representation of the dataset object. The information printed tells us that the +object is similar to a numpy array, with a *shape* and a *type*. + +In this case, we are dealing with a scalar dataset, so we can use the same syntax as +in numpy to access the scalar value, ``result = dset[()]``: + +.. code-block:: python + + >>> print(sf["2.1/title"][()]) + 2 ascan phi 0.61 1.61 20 1 + +Similarly, you need to use numpy slicing to access values in numeric array: + +.. code-block:: python + + >>> print (sf["2.1/measurement/Phi"]) + <HDF5-like dataset "Phi": shape (21,), type "<f4"> + >>> print (sf["2.1/measurement/Phi"][0:10]) + [ 0.61000001 0.66000003 0.70999998 0.75999999 0.81 0.86000001 + 0.91000003 0.95999998 1.00999999 1.05999994] + >>> entire_phi_array = sf["2.1/measurement/Phi"][:] + +Here we could read the entire array by slicing it with ``[:]``, because we know +it is a 1D array. For a 2D array, the slicing argument would have been ``[:, :]``. + +For a dataset of unknown dimensionality (including scalar datasets), the +``Ellipsis`` object (represented by ``...``) can be used to slice the object. + +.. code-block:: python + + >>> print(sf["2.1/title"][...]) + 2 ascan phi 0.61 1.61 20 1 + >>> print (sf["2.1/measurement/Phi"][...]) + [ 0.61000001 0.66000003 0.70999998 0.75999999 0.81 0.86000001 + 0.91000003 0.95999998 1.00999999 1.05999994 1.11000001 1.15999997 + 1.21000004 1.25999999 1.30999994 1.36000001 1.40999997 1.46000004 + 1.50999999 1.55999994 1.61000001] + +To read more about the usage of ``Ellipsis`` to slice arrays, see +`Indexing numpy arrays <http://scipy-cookbook.readthedocs.io/items/Indexing.html?highlight=indexing#Multidimensional-slices>`_ +in the scipy documentation. + +Note that slicing a scalar dataset with ``[()]`` is not strictly equivalent to +slicing with ``[...]``. The former gives you the actual scalar value in +the dataset, while the latter always gives you an array object, which happens to +be 0D in the case of a scalar. + + >>> sf["2.1/instrument/positioners/Delta"][()] + 0.0 + >>> sf["2.1/instrument/positioners/Delta"][...] + array(0.0, dtype=float32) + +Closing the file +++++++++++++++++ + +You should always make sure to close the files that you opened. The simple way of +closing a file is to call its :meth:`close` method. + +.. code-block:: python + + import silx.io + sf = silx.io.open("data/CuZnO_2.spec") + + # read the information you need... + maxPhi = sf["2.1/measurement/Phi"][...].max() + + sf.close() + +The drawback of this method is that, if an error is raised while processing +the file, the program might never reach the ``sf.close()`` line. +Leaving files open can cause various issues for the rest of your program, +such as consuming memory, not being able to reopen the file when you need it... + +The best way to ensure the file is always properly closed is to use the file +inside its context manager: + +.. code-block:: python + + import silx.io + + with silx.io.open("data/CuZnO_2.spec") as sf: + # read the information you need... + maxPhi = sf["2.1/measurement/Phi"][...].max() + + +Additional resources +-------------------- + +- `h5py documentation <http://docs.h5py.org/en/latest/>`_ +- `Formats supported by FabIO <http://www.silx.org/doc/fabio/dev/getting_started.html#list-of-file-formats-that-fabio-can-read-and-write>`_ +- `Spec file h5py-like structure <http://www.silx.org/doc/silx/dev/modules/io/spech5.html#api-description>`_ +- `HDF5 format documentation <https://support.hdfgroup.org/HDF5/>`_ diff --git a/doc/source/Tutorials/specfile_to_hdf5.rst b/doc/source/Tutorials/specfile_to_hdf5.rst index 31f8383..32d942a 100644 --- a/doc/source/Tutorials/specfile_to_hdf5.rst +++ b/doc/source/Tutorials/specfile_to_hdf5.rst @@ -126,8 +126,7 @@ Example of scan and data block, without MCA:: 29.366004 45256 0.000343 734 419 248 229 236 343 178082 664 0.00372862 0.00765939 0.0041217 0.00235285 0.00185308 0.00139262 0.00128592 0.00132523 0.00192608 1364 330 29.36998 45258 0.00036 847 448 254 229 248 360 178342 668 0.00374561 0.00857342 0.0047493 0.00251203 0.00194009 0.00142423 0.00128405 0.00139059 0.00201859 1529 346 -Synthetic example of file with 3 scans. The last scan includes data of 3 multichannel analysers, sharing the -same MCA header. +Synthetic example of file with 3 scans. The last scan includes MCA data. :: @@ -198,8 +197,8 @@ The structure exposed is as follows:: start_time = "…" instrument/ specfile/ - file_header = ["…", "…", …] - scan_header = ["…", "…", …] + file_header = "…" + scan_header = "…" positioners/ motor_name = value … @@ -222,6 +221,11 @@ The structure exposed is as follows:: data -> /1.1/instrument/mca_0/data info -> /1.1/instrument/mca_0/ … + sample/ + ub_matrix = … + unit_cell = … + unit_cell_abc = … + unit_cell_alphabetagamma = … 2.1/ … @@ -292,12 +296,15 @@ Files and groups can be treated as iterators, which allows looping through them. Converting SPEC data to HDF5 ++++++++++++++++++++++++++++ -The *silx* module :mod:`silx.io.spectoh5` can be used to convert a SPEC file into a +Using the convert module +************************ + +The *silx* module :mod:`silx.io.convert` can be used to convert a SPEC file into a HDF5 file with the same structure as the one exposed by the :mod:`spech5` module. .. code-block:: python - from silx.io.spectoh5 import convert + from silx.io.convert import convert convert("/home/pierre/myspecfile.dat", "myfile.h5") @@ -305,10 +312,10 @@ HDF5 file with the same structure as the one exposed by the :mod:`spech5` module You can then read the file with any HDF5 reader. -In addition to the function :func:`silx.io.spectoh5.convert`, which is simplified -on purpose, you can use the more flexible :func:`silx.io.spectoh5.write_spec_to_h5`. +The function :func:`silx.io.convert.convert` is a simplified version of a +more flexible function :func:`silx.io.convert.write_to_h5`. -This way, you can choose to write scans into a specific HDF5 group in the output directory. +The latter allows you to write scans into a specific HDF5 group in the output directory. You can also decide whether you want to overwrite an existing file, or append data to it. You can specify whether existing data with the same name as input data should be overwritten or ignored. @@ -316,8 +323,34 @@ or ignored. This allows you to repeatedly transfer new content of a SPEC file to an existing HDF5 file, in between two scans. -The following script is an example of a command line interface to :func:`write_spec_to_h5`. +The following script is an example of a command line interface to :func:`write_to_h5`. + +.. literalinclude:: ../../../examples/writetoh5.py + :lines: 44- + +Using the convert application +***************************** + +.. versionadded:: 0.6 + +*silx* also provides a ``silx convert`` command line application, which allows you to +perform standard conversions without having to write your own program. + +Type ``silx convert --help`` in a terminal to see all available options. + +The simplest command to convert a single SPEC file to an HDF5 file would be:: + + silx convert myspecfile.dat + +As no output name is supplied, the input file name is reused but the extension is +modified from *.dat* to *.h5*. + +The following example allows you to append the content of a SPEC file to an +existing HDF5 file:: + + silx convert myspecfile.dat -m a -o myhdf5file.h5 -.. literalinclude:: ../../../examples/spectoh5.py - :lines: 42- +You could write the file into a specific group of the HDF5 file by providing +the complete URI in the format ``file_path::group_path``. For instance:: + silx convert myspecfile.dat -m a -o archive.h5::/2017-09-20/SPEC diff --git a/doc/source/conf.py b/doc/source/conf.py index 30abf54..e724d3c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,18 +1,40 @@ # -*- coding: utf-8 -*- +# /*########################################################################## +# Copyright (C) 2015-2017 European Synchrotron Radiation Facility # -# silx documentation build configuration file, created by -# sphinx-quickstart on Fri Nov 27 14:20:46 2015. +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: # -# This file is execfile()d with the current directory set to its containing dir. +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. # -# Note that not all possible configuration values are present in this -# autogenerated file. +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. # -# All configuration values have a default; values that are commented out -# serve to show the default. +# ############################################################################*/ +"""silx documentation build configuration file, created by +sphinx-quickstart on Fri Nov 27 14:20:46 2015. + +This file is execfile()d with the current directory set to its containing dir. + +Note that not all possible configuration values are present in this +autogenerated file. + +All configuration values have a default; values that are commented out +serve to show the default.""" import sys import os +import os.path import glob import subprocess @@ -20,11 +42,18 @@ import subprocess # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # sys.path.insert(0, os.path.abspath('.')) -dirname = os.path.dirname -root_dir = dirname(dirname(dirname(os.path.abspath(__file__)))) -import silx -source_dir = dirname(dirname(silx.__file__)) -os.environ["PYTHONPATH"] = source_dir + os.pathsep + os.environ.get("PYTHONPATH", "") +project = u'silx' +try: + import silx + project_dir = os.path.abspath(os.path.join(__file__, "..", "..", "..")) + build_dir = os.path.abspath(silx.__file__) + if not build_dir.startswith(project_dir): + raise RuntimeError("%s looks to come from the system. Fix your PYTHONPATH and restart sphinx." % project) +except ImportError: + raise RuntimeError("%s is not on the path. Fix your PYTHONPATH and restart sphinx." % project) + +# Add local sphinx extension directory +sys.path.append(os.path.join(os.path.dirname(os.path.abspath(__file__)), 'ext')) # -- General configuration ----------------------------------------------------- @@ -38,7 +67,8 @@ extensions = [ 'sphinx.ext.coverage', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode', - 'sphinx.ext.doctest' + 'sphinx.ext.doctest', + 'sphinxext-archive' ] autodoc_member_order = 'bysource' @@ -56,7 +86,6 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'silx' from silx._version import strictversion, version, __date__ as _date year = _date.split("/")[-1] copyright = u'2015-%s, Data analysis unit, European Synchrotron Radiation Facility, Grenoble' % year @@ -138,7 +167,7 @@ html_favicon = "img/silx.ico" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ['_static'] +# html_static_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/doc/source/description/img/sift_frame_ROI.png b/doc/source/description/img/sift_frame_ROI.png Binary files differnew file mode 100644 index 0000000..f722b35 --- /dev/null +++ b/doc/source/description/img/sift_frame_ROI.png diff --git a/doc/source/description/img/sift_match2.png b/doc/source/description/img/sift_match2.png Binary files differnew file mode 100644 index 0000000..a3beb3c --- /dev/null +++ b/doc/source/description/img/sift_match2.png diff --git a/doc/source/description/sift.rst b/doc/source/description/sift.rst index bd89dd0..d4a9fad 100644 --- a/doc/source/description/sift.rst +++ b/doc/source/description/sift.rst @@ -246,7 +246,7 @@ Matching is also explained in this tutorial, once the keypoints are :alt: Example of image matching for pattern recognition -.. figure:: img/sift_match2.jpg +.. figure:: img/sift_match2.png :align: center :alt: Another example of image matching for pattern recognition @@ -382,7 +382,7 @@ For instance, if a sample is centered on the image, the user can select the center of the image before processing. -.. figure:: img/sift_frame_ROI.jpg +.. figure:: img/sift_frame_ROI.png :align: center :alt: Sample with region of interest diff --git a/doc/source/ext/sphinxext-archive.py b/doc/source/ext/sphinxext-archive.py new file mode 100644 index 0000000..dc1c2c8 --- /dev/null +++ b/doc/source/ext/sphinxext-archive.py @@ -0,0 +1,184 @@ +# coding: utf-8 +# /*########################################################################## +# +# Copyright (c) 2017 European Synchrotron Radiation Facility +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. +# +# ###########################################################################*/ +"""Sphinx extension creating a link to an archive. + +This Sphinx extension adds the possibility to create a zip archive and +include it in the generated HTML documentation. + +This extension provides an *archive* directive. + +Usage: + +.. archive:: <relative_path/to/directory/to/compress> + :filename: <name_of_the_archive_file, default: last_folder_of_directory.zip> + :filter: <Space-separated list of included file patterns, default *.*> + :basedir: <Name of the base directory in the archive, default: filename> + +Examples: + +To create a example.zip archive of the ../../example/ folder: + +.. archive:: ../../examples/ + +To get more control on the name of the archive and its content: + +.. archive:: ../../examples/ + :filename: myproject_examples.zip + :filter: *.py *.png + :basedir: myproject_examples + +WARNING: The content of this directory is not checked for outdated documents. +""" +__authors__ = ["T. Vincent"] +__license__ = "MIT" +__date__ = "01/09/2017" + + +import fnmatch +import logging +import os +import os.path +import posixpath +import shutil +import tempfile + +from docutils.parsers.rst import directives, Directive +import docutils.nodes + + +_logger = logging.getLogger(__name__) + + +# docutils directive + +class ArchiveDirective(Directive): + """Add a link to download an archive + + This directive add an :class:`archive` node to the document tree. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'filename': directives.unchanged, + 'filter': directives.unchanged, + 'basedir': directives.unchanged, + } + + def run(self): + node = archive('') + + # Get rst source file containing this directive + source_file = self.state_machine.get_source_and_line()[0] + if source_file is None: + raise RuntimeError('Cannot get rst source file path') + + # Build input path from rst source file and directive argument + input_path = self.arguments[0] + if not input_path.startswith('/'): # Argument is a relative path + input_path = os.path.abspath( + os.path.join(os.path.dirname(source_file), input_path)) + node['input_path'] = input_path + + default_basedir = os.path.basename(input_path) + node['basedir'] = self.options.get('basedir', default_basedir) + node['filename'] = self.options.get('filename', + '.'.join((default_basedir, 'zip'))) + + node['filter'] = self.options.get('filter', '*.*') + + return [node] + + +# archive doctuils node + +class archive(docutils.nodes.General, docutils.nodes.Element, docutils.nodes.Inline): + """archive node created by :class:`ArchiveDirective`""" + pass + + +def visit_archive_html(self, node): + """Node visitor to translate :class:`archive` nodes to HTML. + + :param self: Sphinx HTML Writter + :param node: The :class:`archive` node to translate to HTML + :raise: SkipNode as depart is not implemented + """ + filename = node['filename'] + input_path = node['input_path'] + + # Create a temporary folder to create archive content + tmp_dir = tempfile.mkdtemp() + + # Copy selected content to temporary folder + base_dir = os.path.join(tmp_dir, node['basedir']) + + def ignore(src, names): + patterns = node['filter'].split() + ignored_names = [] + for name in names: + for pattern in patterns: + if fnmatch.fnmatch(name, pattern): + break + else: + ignored_names.append(name) + return ignored_names + + shutil.copytree(input_path, base_dir, ignore=ignore) + + # Compress temporary folder to zip + output_filename = os.path.join( + self.builder.outdir, '_downloads', filename) + root, ext = os.path.splitext(output_filename) + assert ext == '.zip' + shutil.make_archive(root, 'zip', tmp_dir, node['basedir']) + + # Clean-up temporary folder + shutil.rmtree(tmp_dir) + + # Generate HTML + relative_path = posixpath.join(self.builder.dlpath, filename) + self.body.append('<a href="%s">%s</a>' % (relative_path, filename)) + raise docutils.nodes.SkipNode + + +def visit_skip(self, node): + """No-op node visitor""" + raise docutils.nodes.SkipNode + + +# Extension setup + +def setup(app): + """Sphinx extension registration""" + app.add_node(archive, + html=(visit_archive_html, None), + latex=(visit_skip, None)) + + app.add_directive('archive', ArchiveDirective) + + return {'version': '0.1'} diff --git a/doc/source/index.rst b/doc/source/index.rst index 656f774..86a1395 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,10 +1,16 @@ silx |version| ============== -The silx project aims at providing a collection of Python packages to support the development of data assessment, reduction and analysis applications at synchrotron radiation facilities. -It aims at providing reading/writing different file formats, data reduction routines and a set of Qt widgets to browse and visualize data. +The silx project aims at providing a collection of Python packages to support the +development of data assessment, reduction and analysis applications at synchrotron +radiation facilities. +It aims at providing reading/writing different file formats, data reduction routines +and a set of Qt widgets to browse and visualize data. +Silx can be cited by its DOIs referenced on `Zenodo <https://doi.org/10.5281/zenodo.1000472>`_. -The current version provides reading `SPEC <https://certif.com/spec.html>`_ file format, histogramming, fitting, curves and image plot widget with a set of associated tools. +The current version provides reading `SPEC <https://certif.com/spec.html>`_ file +format, histogramming, fitting, curves and image plot widget with a set of +associated tools. .. toctree:: :hidden: @@ -33,6 +39,9 @@ The current version provides reading `SPEC <https://certif.com/spec.html>`_ file :doc:`modules/index` Documentation of the packages included in *silx* +:doc:`modules/gui/gallery` + Widgets gallery and screenshots + :doc:`changelog` List of changes between releases diff --git a/doc/source/license.rst b/doc/source/license.rst index 6b38b8e..760be91 100644 --- a/doc/source/license.rst +++ b/doc/source/license.rst @@ -1,7 +1,9 @@ License ======= -The source code of *silx* is mostly licensed under the `MIT <https://opensource.org/licenses/MIT>`_ and `LGPL 2.1 <https://opensource.org/licenses/LGPL-2.1>`_ licenses. +The source code of *silx* is licensed under the `MIT <https://opensource.org/licenses/MIT>`_ license: + +.. include:: ../../LICENSE The following list provides the copyright and license of the different source files of the project: diff --git a/doc/source/modules/gui/data/img/ArrayTableWidget.png b/doc/source/modules/gui/data/img/ArrayTableWidget.png Binary files differnew file mode 100644 index 0000000..7c81d02 --- /dev/null +++ b/doc/source/modules/gui/data/img/ArrayTableWidget.png diff --git a/doc/source/modules/gui/fit/backgroundwidget.rst b/doc/source/modules/gui/fit/backgroundwidget.rst index eea2052..a34c639 100644 --- a/doc/source/modules/gui/fit/backgroundwidget.rst +++ b/doc/source/modules/gui/fit/backgroundwidget.rst @@ -7,13 +7,6 @@ .. automodule:: silx.gui.fit.BackgroundWidget -.. |imgBGWidget| image:: ./img/bgwidget.png - :height: 300px - :align: middle - -|imgBGWidget| - - API --- diff --git a/doc/source/modules/gui/fit/img/BackgroundDialog.png b/doc/source/modules/gui/fit/img/BackgroundDialog.png Binary files differnew file mode 100644 index 0000000..c6b8c03 --- /dev/null +++ b/doc/source/modules/gui/fit/img/BackgroundDialog.png diff --git a/doc/source/modules/gui/fit/img/FitWidget.png b/doc/source/modules/gui/fit/img/FitWidget.png Binary files differnew file mode 100644 index 0000000..73a80b4 --- /dev/null +++ b/doc/source/modules/gui/fit/img/FitWidget.png diff --git a/doc/source/modules/gui/fit/img/bgwidget.png b/doc/source/modules/gui/fit/img/bgwidget.png Binary files differdeleted file mode 100644 index 724eadb..0000000 --- a/doc/source/modules/gui/fit/img/bgwidget.png +++ /dev/null diff --git a/doc/source/modules/gui/fit/index.rst b/doc/source/modules/gui/fit/index.rst index 67c22a1..d9581ed 100644 --- a/doc/source/modules/gui/fit/index.rst +++ b/doc/source/modules/gui/fit/index.rst @@ -9,11 +9,11 @@ Snapshot of the widgets: -.. |imgFitWidget| image:: ../../../Tutorials/img/fitwidget4.png +.. |imgFitWidget| image:: ./img/FitWidget.png :height: 150px :align: middle -.. |imgBGWidget| image:: ./img/bgwidget.png +.. |imgBGWidget| image:: ./img/BackgroundDialog.png :height: 150px :align: middle diff --git a/doc/source/modules/gui/gallery.rst b/doc/source/modules/gui/gallery.rst new file mode 100644 index 0000000..4ae83d6 --- /dev/null +++ b/doc/source/modules/gui/gallery.rst @@ -0,0 +1,273 @@ + +Widgets gallery +=============== + + +:mod:`silx.gui.console` Widgets ++++++++++++++++++++++++++++++++ + +.. currentmodule:: silx.gui.console + +.. list-table:: + :widths: 1 4 + :header-rows: 1 + + * - Widget + - Description + * - .. image:: img/IPythonWidget.png + :height: 150px + :align: center + - :class:`IPythonWidget` is an interactive console widget running a + :class`QtInProcessKernelManager`. This allows to push variables to the + interactive console, and interact with your application (e.g. adding + curves to a plot) + * - .. image:: img/IPythonDockWidget.png + :height: 150px + :align: center + - :class:`IPythonDockWidget` is an :class:`IPythonWidget` embedded in + a :class:`QDockWidget`. + + +:mod:`silx.gui.data` Widgets +++++++++++++++++++++++++++++ + +.. currentmodule:: silx.gui.data + +.. list-table:: + :widths: 1 4 + :header-rows: 1 + + * - Widget + - Description + * - .. image:: data/img/ArrayTableWidget.png + :height: 150px + :align: center + - :class:`ArrayTableWidget` is a table widget with browsers designed to + display the content of multi-dimensional data arrays. + * - .. image:: data/img/DataViewer.png + :height: 150px + :align: center + - :class:`DataViewer` is a widget designed to display data using the most + adapted view. + * - .. image:: data/img/DataViewerFrame.png + :height: 150px + :align: center + - :class:`DataViewerFrame` is a :class:`DataViewer` with a view selector + that lets you view the data using any compatible view. + * - .. image:: data/img/NumpyAxesSelector.png + :height: 50px + :align: center + - :class:`NumpyAxesSelector` is a widget designed to select a subarray in a + n-dimensional array, by fixing the index on some of the dimensions. + + +:mod:`silx.gui.fit` Widgets ++++++++++++++++++++++++++++ + +.. currentmodule:: silx.gui.fit + +.. list-table:: + :widths: 1 4 + :header-rows: 1 + + * - Widget + - Description + * - .. image:: fit/img/FitWidget.png + :height: 150px + :align: center + - :class:`FitWidget` is a widget designed to configure and run a fitting process, + with constraints on parameters. + * - .. image:: fit/img/BackgroundDialog.png + :height: 150px + :align: center + - :class:`BackgroundWidget.BackgroundDialog` is a widget designed to adjust + the parameters and preview the results of a *snip* or *strip* background + filter. + + +:mod:`silx.gui.hdf5` Widgets +++++++++++++++++++++++++++++ + +.. currentmodule:: silx.gui.hdf5 + +.. list-table:: + :widths: 1 4 + :header-rows: 1 + + * - Widget + - Description + * - .. image:: hdf5/img/Hdf5TreeView.png + :height: 150px + :align: center + - :class:`Hdf5TreeView` is a tree view desiged to browse an HDF5 + file structure. + +.. _plot-gallery: + +:mod:`silx.gui.plot` Widgets +++++++++++++++++++++++++++++ + +.. currentmodule:: silx.gui.plot + +Plotting widgets: + +.. list-table:: + :widths: 1 4 + :header-rows: 1 + + * - Widget + - Description + * - .. image:: plot/img/PlotWidget.png + :height: 150px + :align: center + - :class:`PlotWidget` is the base Qt widget providing a plot area. + Other plot widgets are based on this one and provides the same API. + * - .. image:: plot/img/PlotWindow.png + :height: 150px + :align: center + - :class:`PlotWindow` adds a toolbar to :class:`PlotWidget`. + The content of this toolbar can be configured from the + :class:`PlotWindow` constructor or by hiding its content afterward. + * - .. image:: plot/img/Plot1D.png + :height: 150px + :align: center + - :class:`.Plot1D` is a :class:`PlotWindow` configured with tools useful + for curves. + * - .. image:: plot/img/Plot2D.png + :height: 150px + :align: center + - :class:`.Plot2D` is a :class:`PlotWindow` configured with tools useful + for images. + * - .. image:: plot/img/ImageView.png + :height: 150px + :align: center + - :class:`ImageView` adds side histograms to a :class:`.Plot2D` widget. + * - .. image:: plot/img/StackView.png + :height: 150px + :align: center + - :class:`StackView` is a widget designed to display an image from a + stack of images in a :class:`PlotWindow` widget, with a frame browser + to navigate in the stack. The profile tool can do a 2D profile on the + stack of images. + * - .. image:: plot/img/ComplexImageView.png + :height: 150px + :align: center + - :class:`ComplexImageView` is a widget dedicated to visualize a single + 2D dataset of complex data. + It allows to switch between viewing amplitude, phase, real, imaginary, + colored phase with amplitude or log10(amplitude) as brightness. + + +Additional widgets: + +.. list-table:: + :widths: 1 4 + :header-rows: 1 + + * - Widget + - Description + * - .. image:: plot/img/PositionInfo.png + :width: 300px + :align: center + - :class:`.PlotTools.PositionInfo` is a widget displaying mouse position and + information of a :class:`PlotWidget` associated to the mouse position. + * - .. image:: plot/img/LimitsToolBar.png + :width: 300px + :align: center + - :class:`.PlotTools.LimitsToolBar` is a QToolBar displaying and + controlling the limits of a :class:`PlotWidget`. + * - .. image:: plot/img/logColorbar.png + :height: 150px + :align: center + - :class:`.ColorBar.ColorBarWidget` display colormap gradient and can be linked with a plot + to display the colormap + +.. _plot3d-gallery: + +:mod:`silx.gui.plot3d` Widgets +++++++++++++++++++++++++++++++ + +.. currentmodule:: silx.gui.plot3d + +.. list-table:: + :widths: 1 4 + :header-rows: 1 + + * - Widget + - Description + * - .. 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 + - :class:`Plot3DWindow` is a :class:`QMainWindow` with a :class:`Plot3DWidget` as central widget + and toolbars. + * - .. image:: plot3d/img/Plot3DWidget.png + :height: 150px + :align: center + - :class:`Plot3DWidget` is the base Qt widget providing an OpenGL 3D scene. + Other widgets are using this widget as the OpenGL scene canvas. + * - .. image:: plot3d/img/SFViewParamTree.png + :height: 150px + :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`. + + +:mod:`silx.gui.widgets` Widgets ++++++++++++++++++++++++++++++++ + +.. currentmodule:: silx.gui.widgets + +.. list-table:: + :widths: 1 4 + :header-rows: 1 + + * - Widget + - Description + * - .. image:: widgets/img/FrameBrowser.png + :width: 110px + :align: center + - :class:`FrameBrowser.FrameBrowser` is a browser widget designed to + browse through a sequence of integers (e.g. the indices of an array) + * - .. image:: widgets/img/HorizontalSliderWithBrowser.png + :width: 150px + :align: center + - :class:`FrameBrowser.HorizontalSliderWithBrowser` is a :class:`FrameBrowser` + with an additional slider. + * - .. image:: widgets/img/PeriodicCombo.png + :width: 150px + :align: center + - :class:`PeriodicTable.PeriodicCombo` is a :class:`QComboBox` widget designed to + select a single atomic element. + * - .. image:: widgets/img/PeriodicList.png + :height: 150px + :align: center + - :class:`PeriodicTable.PeriodicList` is a :class:`QTreeWidget` designed to select one + or more atomic elements. + * - .. image:: widgets/img/PeriodicTable.png + :height: 150px + :align: center + - :class:`PeriodicTable.PeriodicTable` is a periodic table widget designed to select one + or more atomic elements. + * - .. image:: widgets/img/TableWidget.png + :height: 150px + :align: center + - :class:`TableWidget.TableWidget` and :class:`TableWidget.TableView` inherit respectively + :class:`QTableWidget` and :class:`QTableView`, and add a context menu with *cut/copy/paste* + actions. + * - .. image:: widgets/img/WaitingPushButton.png + :width: 60px + :align: center + - :class:`WaitingPushButton` is a :class:`QPushButton` that can be graphically disabled, + for example to wait for a callback function to finish computing. + * - .. image:: widgets/img/ThreadPoolPushButton.png + :width: 100px + :align: center + - :class:`ThreadPoolPushButton` is a :class:`WaitingPushButton` that executes a + callback in a thread. diff --git a/doc/source/modules/gui/icons.rst b/doc/source/modules/gui/icons.rst index 61ea71d..c3fefd8 100644 --- a/doc/source/modules/gui/icons.rst +++ b/doc/source/modules/gui/icons.rst @@ -25,16 +25,22 @@ Available icons - 3d-plane-normal-y * - |3d-plane-normal-z| - 3d-plane-normal-z + * - |3d-plane-pan| + - 3d-plane-pan * - |3d-plane| - 3d-plane * - |arrow-keys| - arrow-keys + * - |axis| + - axis * - |camera| - camera * - |clipboard| - clipboard * - |close| - close + * - |colorbar| + - colorbar * - |colormap| - colormap * - |crop| @@ -97,10 +103,14 @@ Available icons - item-3dim * - |item-ndim| - item-ndim + * - |item-none| + - item-none * - |item-object| - item-object * - |last| - last + * - |math-amplitude| + - math-amplitude * - |math-average| - math-average * - |math-derive| @@ -109,6 +119,8 @@ Available icons - math-energy * - |math-fit| - math-fit + * - |math-imaginary| + - math-imaginary * - |math-normalize| - math-normalize * - |math-peak-reset| @@ -117,6 +129,14 @@ Available icons - math-peak-search * - |math-peak| - math-peak + * - |math-phase-color-log| + - math-phase-color-log + * - |math-phase-color| + - math-phase-color + * - |math-phase| + - math-phase + * - |math-real| + - math-real * - |math-sigma| - math-sigma * - |math-smooth| @@ -127,10 +147,14 @@ Available icons - math-swap-sign * - |math-ymin-to-zero| - math-ymin-to-zero + * - |median-filter| + - median-filter * - |next| - next * - |normal| - normal + * - |pan| + - pan * - |pixel-intensities| - pixel-intensities * - |plot-grid| @@ -167,12 +191,16 @@ Available icons - plot-yup * - |previous| - previous + * - |profile-clear| + - profile-clear * - |profile1D| - profile1D * - |profile2D| - profile2D * - |remove| - remove + * - |rotate-3d| + - rotate-3d * - |rudder| - rudder * - |selected| @@ -205,8 +233,6 @@ Available icons - sliders-on * - |spec| - spec - * - |test-png| - - test-png * - |view-1d| - view-1d * - |view-2d-stack| @@ -217,6 +243,10 @@ Available icons - view-3d * - |view-fullscreen| - view-fullscreen + * - |view-hdf5| + - view-hdf5 + * - |view-nexus| + - view-nexus * - |view-nofullscreen| - view-nofullscreen * - |view-raw| @@ -227,6 +257,8 @@ Available icons - view-text * - |window-new| - window-new + * - |zoom-back| + - zoom-back * - |zoom-in| - zoom-in * - |zoom-original| @@ -239,11 +271,14 @@ Available icons .. |3d-plane-normal-x| image:: ../../../../silx/resources/gui/icons/3d-plane-normal-x.png .. |3d-plane-normal-y| image:: ../../../../silx/resources/gui/icons/3d-plane-normal-y.png .. |3d-plane-normal-z| image:: ../../../../silx/resources/gui/icons/3d-plane-normal-z.png +.. |3d-plane-pan| image:: ../../../../silx/resources/gui/icons/3d-plane-pan.png .. |3d-plane| image:: ../../../../silx/resources/gui/icons/3d-plane.png .. |arrow-keys| image:: ../../../../silx/resources/gui/icons/arrow-keys.png +.. |axis| image:: ../../../../silx/resources/gui/icons/axis.png .. |camera| image:: ../../../../silx/resources/gui/icons/camera.png .. |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| image:: ../../../../silx/resources/gui/icons/colormap.png .. |crop| image:: ../../../../silx/resources/gui/icons/crop.png .. |crosshair| image:: ../../../../silx/resources/gui/icons/crosshair.png @@ -275,23 +310,32 @@ Available icons .. |item-2dim| image:: ../../../../silx/resources/gui/icons/item-2dim.png .. |item-3dim| image:: ../../../../silx/resources/gui/icons/item-3dim.png .. |item-ndim| image:: ../../../../silx/resources/gui/icons/item-ndim.png +.. |item-none| image:: ../../../../silx/resources/gui/icons/item-none.png .. |item-object| image:: ../../../../silx/resources/gui/icons/item-object.png .. |last| image:: ../../../../silx/resources/gui/icons/last.png +.. |math-amplitude| image:: ../../../../silx/resources/gui/icons/math-amplitude.png .. |math-average| image:: ../../../../silx/resources/gui/icons/math-average.png .. |math-derive| image:: ../../../../silx/resources/gui/icons/math-derive.png .. |math-energy| image:: ../../../../silx/resources/gui/icons/math-energy.png .. |math-fit| image:: ../../../../silx/resources/gui/icons/math-fit.png +.. |math-imaginary| image:: ../../../../silx/resources/gui/icons/math-imaginary.png .. |math-normalize| image:: ../../../../silx/resources/gui/icons/math-normalize.png .. |math-peak-reset| image:: ../../../../silx/resources/gui/icons/math-peak-reset.png .. |math-peak-search| image:: ../../../../silx/resources/gui/icons/math-peak-search.png .. |math-peak| image:: ../../../../silx/resources/gui/icons/math-peak.png +.. |math-phase-color-log| image:: ../../../../silx/resources/gui/icons/math-phase-color-log.png +.. |math-phase-color| image:: ../../../../silx/resources/gui/icons/math-phase-color.png +.. |math-phase| image:: ../../../../silx/resources/gui/icons/math-phase.png +.. |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-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 +.. |median-filter| image:: ../../../../silx/resources/gui/icons/median-filter.png .. |next| image:: ../../../../silx/resources/gui/icons/next.png .. |normal| image:: ../../../../silx/resources/gui/icons/normal.png +.. |pan| image:: ../../../../silx/resources/gui/icons/pan.png .. |pixel-intensities| image:: ../../../../silx/resources/gui/icons/pixel-intensities.png .. |plot-grid| image:: ../../../../silx/resources/gui/icons/plot-grid.png .. |plot-roi-above| image:: ../../../../silx/resources/gui/icons/plot-roi-above.png @@ -310,9 +354,11 @@ Available icons .. |plot-ylog| image:: ../../../../silx/resources/gui/icons/plot-ylog.png .. |plot-yup| image:: ../../../../silx/resources/gui/icons/plot-yup.png .. |previous| image:: ../../../../silx/resources/gui/icons/previous.png +.. |profile-clear| image:: ../../../../silx/resources/gui/icons/profile-clear.png .. |profile1D| image:: ../../../../silx/resources/gui/icons/profile1D.png .. |profile2D| image:: ../../../../silx/resources/gui/icons/profile2D.png .. |remove| image:: ../../../../silx/resources/gui/icons/remove.png +.. |rotate-3d| image:: ../../../../silx/resources/gui/icons/rotate-3d.png .. |rudder| image:: ../../../../silx/resources/gui/icons/rudder.png .. |selected| image:: ../../../../silx/resources/gui/icons/selected.png .. |shape-circle-solid| image:: ../../../../silx/resources/gui/icons/shape-circle-solid.png @@ -329,17 +375,19 @@ Available icons .. |sliders-off| image:: ../../../../silx/resources/gui/icons/sliders-off.png .. |sliders-on| image:: ../../../../silx/resources/gui/icons/sliders-on.png .. |spec| image:: ../../../../silx/resources/gui/icons/spec.png -.. |test-png| image:: ../../../../silx/resources/gui/icons/test-png.png .. |view-1d| image:: ../../../../silx/resources/gui/icons/view-1d.png .. |view-2d-stack| image:: ../../../../silx/resources/gui/icons/view-2d-stack.png .. |view-2d| image:: ../../../../silx/resources/gui/icons/view-2d.png .. |view-3d| image:: ../../../../silx/resources/gui/icons/view-3d.png .. |view-fullscreen| image:: ../../../../silx/resources/gui/icons/view-fullscreen.png +.. |view-hdf5| image:: ../../../../silx/resources/gui/icons/view-hdf5.png +.. |view-nexus| image:: ../../../../silx/resources/gui/icons/view-nexus.png .. |view-nofullscreen| image:: ../../../../silx/resources/gui/icons/view-nofullscreen.png .. |view-raw| image:: ../../../../silx/resources/gui/icons/view-raw.png .. |view-refresh| image:: ../../../../silx/resources/gui/icons/view-refresh.png .. |view-text| image:: ../../../../silx/resources/gui/icons/view-text.png .. |window-new| image:: ../../../../silx/resources/gui/icons/window-new.png +.. |zoom-back| image:: ../../../../silx/resources/gui/icons/zoom-back.png .. |zoom-in| image:: ../../../../silx/resources/gui/icons/zoom-in.png .. |zoom-original| image:: ../../../../silx/resources/gui/icons/zoom-original.png .. |zoom-out| image:: ../../../../silx/resources/gui/icons/zoom-out.png diff --git a/doc/source/modules/gui/img/IPythonDockWidget.png b/doc/source/modules/gui/img/IPythonDockWidget.png Binary files differnew file mode 100644 index 0000000..111a926 --- /dev/null +++ b/doc/source/modules/gui/img/IPythonDockWidget.png diff --git a/doc/source/modules/gui/img/IPythonWidget.png b/doc/source/modules/gui/img/IPythonWidget.png Binary files differnew file mode 100644 index 0000000..18b44e0 --- /dev/null +++ b/doc/source/modules/gui/img/IPythonWidget.png diff --git a/doc/source/modules/gui/index.rst b/doc/source/modules/gui/index.rst index eecd124..0b7f433 100644 --- a/doc/source/modules/gui/index.rst +++ b/doc/source/modules/gui/index.rst @@ -19,3 +19,11 @@ The ``silx.gui`` package provides a set of PyQt widgets. plot3d/index.rst qt.rst widgets/index.rst + + +.. toctree:: + :hidden: + + gallery.rst + +See the :doc:`gallery` page for an overview of all available widgets. diff --git a/doc/source/modules/gui/plot/actions/control.rst b/doc/source/modules/gui/plot/actions/control.rst new file mode 100644 index 0000000..b35986d --- /dev/null +++ b/doc/source/modules/gui/plot/actions/control.rst @@ -0,0 +1,5 @@ +:mod:`silx.gui.plot.actions.control` +```````````````````````````````````` + +.. automodule:: silx.gui.plot.actions.control + :members: diff --git a/doc/source/modules/gui/plot/plotactions_examples.rst b/doc/source/modules/gui/plot/actions/examples.rst index f14a42a..125e9c5 100644 --- a/doc/source/modules/gui/plot/plotactions_examples.rst +++ b/doc/source/modules/gui/plot/actions/examples.rst @@ -17,7 +17,7 @@ Simple example: Shift a curve The following script is a simplistic example to show the basic required steps: - - create a new class inheriting from :class:`silx.gui.plot.PlotActions.PlotAction` + - 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 @@ -27,7 +27,7 @@ The method implemented in this action interacts with the plot in a basic way. It 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. -.. literalinclude:: ../../../../../examples/shiftPlotAction.py +.. literalinclude:: ../../../../../../examples/shiftPlotAction.py :lines: 36- .. |imgShiftAction0| image:: img/shiftAction0.png @@ -66,7 +66,7 @@ the amplitude spectrum. However, the inverse FFT requires the complete FFT data We 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 +.. literalinclude:: ../../../../../../examples/fftPlotAction.py :lines: 44- .. |imgFftAction0| image:: img/fftAction0.png diff --git a/doc/source/modules/gui/plot/actions/fit.rst b/doc/source/modules/gui/plot/actions/fit.rst new file mode 100644 index 0000000..8b06908 --- /dev/null +++ b/doc/source/modules/gui/plot/actions/fit.rst @@ -0,0 +1,5 @@ +:mod:`silx.gui.plot.actions.fit` +```````````````````````````````` + +.. automodule:: silx.gui.plot.actions.fit + :members: diff --git a/doc/source/modules/gui/plot/actions/histogram.rst b/doc/source/modules/gui/plot/actions/histogram.rst new file mode 100644 index 0000000..6a31236 --- /dev/null +++ b/doc/source/modules/gui/plot/actions/histogram.rst @@ -0,0 +1,5 @@ +:mod:`silx.gui.plot.actions.histogram` +`````````````````````````````````````` + +.. automodule:: silx.gui.plot.actions.histogram + :members: diff --git a/doc/source/modules/gui/plot/img/fftAction0.png b/doc/source/modules/gui/plot/actions/img/fftAction0.png Binary files differindex 5bd8061..5bd8061 100644 --- a/doc/source/modules/gui/plot/img/fftAction0.png +++ b/doc/source/modules/gui/plot/actions/img/fftAction0.png diff --git a/doc/source/modules/gui/plot/img/fftAction1.png b/doc/source/modules/gui/plot/actions/img/fftAction1.png Binary files differindex e4b20d7..e4b20d7 100644 --- a/doc/source/modules/gui/plot/img/fftAction1.png +++ b/doc/source/modules/gui/plot/actions/img/fftAction1.png diff --git a/doc/source/modules/gui/plot/img/shiftAction0.png b/doc/source/modules/gui/plot/actions/img/shiftAction0.png Binary files differindex 2d5837a..2d5837a 100644 --- a/doc/source/modules/gui/plot/img/shiftAction0.png +++ b/doc/source/modules/gui/plot/actions/img/shiftAction0.png diff --git a/doc/source/modules/gui/plot/img/shiftAction3.png b/doc/source/modules/gui/plot/actions/img/shiftAction3.png Binary files differindex a2187b8..a2187b8 100644 --- a/doc/source/modules/gui/plot/img/shiftAction3.png +++ b/doc/source/modules/gui/plot/actions/img/shiftAction3.png diff --git a/doc/source/modules/gui/plot/actions/index.rst b/doc/source/modules/gui/plot/actions/index.rst new file mode 100644 index 0000000..f95b1f8 --- /dev/null +++ b/doc/source/modules/gui/plot/actions/index.rst @@ -0,0 +1,30 @@ +.. currentmodule:: silx.gui.plot + +:mod:`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`. + +For an introduction to creating custom plot actions, see :doc:`examples`. + +actions API +----------- + +Actions are divided into the following sub-modules: + + +.. toctree:: + :maxdepth: 1 + + control.rst + medfilt.rst + fit.rst + histogram.rst + io.rst + +.. autoclass:: silx.gui.plot.actions.PlotAction diff --git a/doc/source/modules/gui/plot/actions/io.rst b/doc/source/modules/gui/plot/actions/io.rst new file mode 100644 index 0000000..98f1808 --- /dev/null +++ b/doc/source/modules/gui/plot/actions/io.rst @@ -0,0 +1,6 @@ +:mod:`silx.gui.plot.actions.io` +``````````````````````````````` + +.. automodule:: silx.gui.plot.actions.io + :members: + diff --git a/doc/source/modules/gui/plot/actions/medfilt.rst b/doc/source/modules/gui/plot/actions/medfilt.rst new file mode 100644 index 0000000..25f5af1 --- /dev/null +++ b/doc/source/modules/gui/plot/actions/medfilt.rst @@ -0,0 +1,5 @@ +:mod:`silx.gui.plot.actions.medfilt` +```````````````````````````````````` + +.. automodule:: silx.gui.plot.actions.medfilt + :members: diff --git a/doc/source/modules/gui/plot/colormap.rst b/doc/source/modules/gui/plot/colormap.rst new file mode 100644 index 0000000..a492605 --- /dev/null +++ b/doc/source/modules/gui/plot/colormap.rst @@ -0,0 +1,16 @@ + +.. currentmodule:: silx.gui.plot.Colormap + +:mod:`Colormap`: Colormap API +============================= + +.. automodule:: silx.gui.plot.Colormap + +.. currentmodule:: silx.gui.plot.Colormap + +:class:`Colormap` class +----------------------- + +.. autoclass:: Colormap + :show-inheritance: + :members: diff --git a/doc/source/modules/gui/plot/compleximageview.rst b/doc/source/modules/gui/plot/compleximageview.rst new file mode 100644 index 0000000..d9009eb --- /dev/null +++ b/doc/source/modules/gui/plot/compleximageview.rst @@ -0,0 +1,19 @@ + +.. currentmodule:: silx.gui.plot + +:mod:`ComplexImageView`: Plot a 2D array of complex +=================================================== + +.. automodule:: silx.gui.plot.ComplexImageView + +.. currentmodule:: silx.gui.plot.ComplexImageView + +.. image:: img/ComplexImageView.png + :height: 400px + :align: center + +:class:`ComplexImageView` class +------------------------------- + +.. autoclass:: ComplexImageView + :members: diff --git a/doc/source/modules/gui/plot/dev.rst b/doc/source/modules/gui/plot/dev.rst index 707d215..b793b01 100644 --- a/doc/source/modules/gui/plot/dev.rst +++ b/doc/source/modules/gui/plot/dev.rst @@ -10,7 +10,7 @@ This package is structured as follows. :class:`PlotWidget` is a Qt widget (actually a :class:`QMainWindow`) displaying a 1D, 2D plot area. It provides different interaction modes. :class:`PlotWindow` is a Qt widget (actually a :class:`QMainWindow`) which adds a set of toolbar buttons and associated functionalities to :class:`PlotWidget`. -The toolbar QActions are implemented in :mod:`.PlotActions`. +The toolbar QActions are implemented in :mod:`.actions`. :mod:`.Plot`, :mod:`.PlotEvents` and :mod:`.PlotInteraction` implement the plotting API regardless of the rendering backend and regardless of its integration in Qt. The plotting API in defined in :mod:`.Plot`. @@ -40,7 +40,6 @@ The :class:`PlotWindow` uses additional widgets: The widgets also use the following miscellaneous modules: - :mod:`.Colors` to convert colors from name to RGB(A) -- :mod:`.MPLColormap` to embed recent matplotlib colormaps: 'magma', 'inferno', 'plasma' and 'viridis'. - :mod:`._utils`: utility functions The :mod:`backends` package provide the implementation of the rendering used by the :class:`Plot`. @@ -89,15 +88,6 @@ The following modules are the modules used internally by the plot package. .. automodule:: silx.gui.plot.backends.BackendMatplotlib :members: -:mod:`backends.ModestImage` -+++++++++++++++++++++++++++ - -.. currentmodule:: silx.gui.plot.backends.ModestImage - -.. automodule:: silx.gui.plot.backends.ModestImage - :members: - :undoc-members: - :mod:`ColormapDialog` +++++++++++++++++++++ @@ -164,14 +154,6 @@ The following modules are the modules used internally by the plot package. :members: :show-inheritance: -:mod:`MPLColormap` -++++++++++++++++++ - -.. currentmodule:: silx.gui.plot.MPLColormap - -.. automodule:: silx.gui.plot.MPLColormap - :members: - :mod:`PlotEvents` +++++++++++++++++ diff --git a/doc/source/modules/gui/plot/getting_started.rst b/doc/source/modules/gui/plot/getting_started.rst index 9e45b70..484d3f7 100644 --- a/doc/source/modules/gui/plot/getting_started.rst +++ b/doc/source/modules/gui/plot/getting_started.rst @@ -157,6 +157,7 @@ a module from :mod:`silx.gui`: .. 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. @@ -342,17 +343,15 @@ When updating an image, if ``origin`` and ``scale`` are not provided, the previo Colormap ++++++++ -A ``colormap`` is described with a :class:`dict` as follows (See :mod:`silx.gui.plot.Plot` for full documentation of the colormap): +A ``colormap`` is described with a :class:`.Colormap` class as follows: .. code-block:: python - colormap = { - 'name': 'gray', # Name of the colormap - 'normalization': 'linear', # Either 'linear' or 'log' - 'autoscale': True, # True to autoscale colormap to data range, False to use [vmin, vmax] - 'vmin': 0.0, # If not autoscale, data value to bind to min of colormap - 'vmax': 1.0 # If not autoscale, data value to bind to max of 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 + vmax=1.0 # If not autoscale, data value to bind to max of colormap + ) 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: @@ -372,19 +371,23 @@ It is possible to change the default colormap of :meth:`.PlotWidget.addImage` fo .. code-block:: python - colormap = {'name': 'viridis', 'normalization': 'linear', - 'autoscale': True, 'vmin': 0.0, 'vmax': 1.0} + colormap = Colormap(name='viridis', + normalization='linear', + vmin=0.0, + vmax=1.0) plot.setDefaultColormap(colormap) data = numpy.arange(512 * 512.).reshape(512, -1) plot.addImage(data) # Rendered with the default colormap set before -It is also possible to provide a ``colormap`` to :meth:`.PlotWidget.addImage` to override this default for an image: +It is also possible to provide a :class:`.Colormap` to :meth:`.PlotWidget.addImage` to override this default for an image: .. code-block:: python - colormap = {'name': 'magma', 'normalization': 'log', - 'autoscale': False, 'vmin': 1.2, 'vmax': 1.8} + colormap = Colormap(name='magma', + normalization='log', + vmin=1.2, + vmax=1.8) data = numpy.random.random(512 * 512).reshape(512, -1) + 1. plot.addImage(data, colormap=colormap) @@ -432,18 +435,19 @@ Control 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. Labels and title ++++++++++++++++ Use :meth:`.PlotWidget.setGraphTitle` to set the plot main title. -Use :meth:`.PlotWidget.setGraphXLabel` and :meth:`.PlotWidget.setGraphYLabel` to set the axes text labels: +Use :meth:`.PlotWidget.getXAxis` and :meth:`.PlotWidget.getYAxis` to get the axes and set their text label with :meth:`.items.Axis.setLabel`: .. code-block:: python plot.setGraphTitle('My plot') - plot.setGraphXLabel('X') - plot.setGraphYLabel('Y') + plot.getXAxis().setLabel('X') + plot.getYAxis().setLabel('Y') Axes limits @@ -455,9 +459,9 @@ The following code moves the visible plot area to the right: .. code-block:: python - xmin, xmax = plot.getGraphXLimits() + xmin, xmax = plot.getXAxis().getLimits() offset = 0.1 * (xmax - xmin) - plot.setGraphXLimits(xmin + offset, xmax + offset) + plot.getXAxis().setLimits(xmin + offset, xmax + offset) :meth:`.PlotWidget.resetZoom` set the plot limits to the bounds of the data: @@ -465,7 +469,7 @@ The following code moves the visible plot area to the right: plot.resetZoom() -See :meth:`.PlotWidget.resetZoom`, :meth:`.PlotWidget.setLimits`, :meth:`.PlotWidget.getGraphXLimits`, :meth:`.PlotWidget.setGraphXLimits`, :meth:`.PlotWidget.getGraphYLimits`, :meth:`.PlotWidget.setGraphYLimits` for details. +See :meth:`.PlotWidget.resetZoom`, :meth:`.PlotWidget.setLimits`, :meth:`.PlotWidget.getXAxis`, :meth:`.PlotWidget.getYAxis` and :class:`.items.Axis` for details. Axes @@ -475,17 +479,17 @@ Different methods allow plot axes modifications: .. code-block:: python - plot.setYAxisInverted(True) # Makes the Y axis pointing downward + plot.getYAxis().setInverted(True) # Makes the Y axis pointing downward plot.setKeepDataAspectRatio(True) # To keep aspect ratio between X and Y axes -See :meth:`.PlotWidget.setYAxisInverted`, :meth:`.PlotWidget.setKeepDataAspectRatio` for details. +See :meth:`.PlotWidget.getYAxis`, :meth:`.PlotWidget.setKeepDataAspectRatio` for details. .. code-block:: python plot.setGraphGrid(which='both') # To show a grid for both minor and major axes ticks # Use logarithmic axes - plot.setXAxisLogarithmic(True) - plot.setYAxisLogarithmic(True) + plot.getXAxis().setScale("log") + plot.getYAxis().setScale("log") -See :meth:`.PlotWidget.setGraphGrid`, :meth:`.PlotWidget.setXAxisLogarithmic`, :meth:`.PlotWidget.setYAxisLogarithmic` for details. +See :meth:`.PlotWidget.setGraphGrid`, :meth:`.PlotWidget.getXAxis`, :meth:`.PlotWidget.getXAxis` and :class:`.items.Axis` for details. diff --git a/doc/source/modules/gui/plot/imageview.rst b/doc/source/modules/gui/plot/imageview.rst index c2663c7..f03868b 100644 --- a/doc/source/modules/gui/plot/imageview.rst +++ b/doc/source/modules/gui/plot/imageview.rst @@ -6,10 +6,12 @@ .. automodule:: silx.gui.plot.ImageView -.. currentmodule:: silx.gui.plot.ImageView +.. image:: img/ImageView.png + :height: 400 + :align: center :class:`ImageView` class ------------------------ .. autoclass:: ImageView - :members: valueChanged, profile, setImage, getColormap, setColormap, getHistogram, setGraphTitle, setGraphXLabel, setGraphYLabel + :members: valueChanged, setImage, getColormap, setColormap, getHistogram, setGraphTitle, getXAxis, getYAxis diff --git a/doc/source/modules/gui/plot/img/ComplexImageView.png b/doc/source/modules/gui/plot/img/ComplexImageView.png Binary files differnew file mode 100644 index 0000000..3f8b502 --- /dev/null +++ b/doc/source/modules/gui/plot/img/ComplexImageView.png diff --git a/doc/source/modules/gui/plot/img/printPreviewMultiPlot.png b/doc/source/modules/gui/plot/img/printPreviewMultiPlot.png Binary files differnew file mode 100644 index 0000000..4ce42b3 --- /dev/null +++ b/doc/source/modules/gui/plot/img/printPreviewMultiPlot.png diff --git a/doc/source/modules/gui/plot/index.rst b/doc/source/modules/gui/plot/index.rst index 143b85b..b77bbcc 100644 --- a/doc/source/modules/gui/plot/index.rst +++ b/doc/source/modules/gui/plot/index.rst @@ -15,94 +15,12 @@ For an introduction to the widgets of this package, see :doc:`getting_started`. -For examples of custom plot actions, see :doc:`plotactions_examples`. +For examples of custom plot actions, see :doc:`actions/examples`. Widgets gallery --------------- -The :mod:`silx.gui.plot` package provides the following plotting widgets: - -.. |imgPlotWidget| image:: img/PlotWidget.png - :height: 150px - :align: middle - -.. |imgPlotWindow| image:: img/PlotWindow.png - :height: 150px - :align: middle - -.. |imgPlot1D| image:: img/Plot1D.png - :height: 150px - :align: middle - -.. |imgPlot2D| image:: img/Plot2D.png - :height: 150px - :align: middle - -.. |imgImageView| image:: img/ImageView.png - :height: 150px - :align: middle - -.. |imgStackView| image:: img/StackView.png - :height: 150px - :align: middle - -.. list-table:: - :widths: 1 4 - :header-rows: 1 - - * - Widget - - Description - * - |imgPlotWidget| - - :class:`PlotWidget` is the base Qt widget providing a plot area. - Other plot widgets are based on this one and provides the same API. - * - |imgPlotWindow| - - :class:`PlotWindow` adds a toolbar to :class:`PlotWidget`. - The content of this toolbar can be configured from the - :class:`PlotWindow` constructor or by hiding its content afterward. - * - |imgPlot1D| - - :class:`.Plot1D` is a :class:`PlotWindow` configured with tools useful - for curves. - * - |imgPlot2D| - - :class:`.Plot2D` is a :class:`PlotWindow` configured with tools useful - for images. - * - |imgImageView| - - :class:`ImageView` adds side histograms to a :class:`.Plot2D` widget. - * - |imgStackView| - - :class:`StackView` is a widget designed to display an image from a - stack of images in a :class:`PlotWindow` widget, with a frame browser - to navigate in the stack. The profile tool can do a 2D profile on the - stack of images. - -It also provides (and uses) widgets that can be attached to a :class:`PlotWidget`: - -.. |imgPositionInfo| image:: img/PositionInfo.png - :width: 300px - :align: middle - -.. |imgLimitsToolBar| image:: img/LimitsToolBar.png - :width: 300px - :align: middle - -.. |imgColorbar| image:: img/logColorbar.png - :height: 150px - :align: middle - - -.. list-table:: - :widths: 1 4 - :header-rows: 1 - - * - Widget - - Description - * - |imgPositionInfo| - - :class:`.PlotTools.PositionInfo` is a widget displaying mouse position and - information of a :class:`PlotWidget` associated to the mouse position. - * - |imgLimitsToolBar| - - :class:`.PlotTools.LimitsToolBar` is a QToolBar displaying and - controlling the limits of a :class:`PlotWidget`. - * - |imgColorbar| - - :class:`.ColorBar.ColorBarWidget` display colormap gradient and can be linked with a plot - to display the colormap +See :ref:`plot-gallery` gallery. Public modules -------------- @@ -114,12 +32,14 @@ Public modules plotwindow.rst imageview.rst stackview.rst - plot.rst + compleximageview.rst + colormap.rst items.rst - plotactions.rst + actions/index.rst plottools.rst profile.rst roi.rst + printpreviewtoolbutton.rst Internals --------- diff --git a/doc/source/modules/gui/plot/items.rst b/doc/source/modules/gui/plot/items.rst index beba3a1..3cdcf17 100644 --- a/doc/source/modules/gui/plot/items.rst +++ b/doc/source/modules/gui/plot/items.rst @@ -8,56 +8,103 @@ .. currentmodule:: silx.gui.plot.items +Item +---- + +All plot primitives inherits from :class:`Item` as a common ground: + +.. autoclass:: Item + :show-inheritance: + :members: + Curve ----- .. autoclass:: Curve - :members: - :inherited-members: + :members: getData, getXData, getYData, getXErrorData, getYErrorData, setData, + getSymbol, setSymbol, getSymbolSize, setSymbolSize, + getAlpha, setAlpha, + getColor, setColor, + getYAxis, setYAxis, + isFill, setFill, + getXLabel, getYLabel, + getLineWidth, setLineWidth, getLineStyle, setLineStyle, + isHighlighted, setHighlighted, getHighlightedColor, setHighlightedColor, + getCurrentColor Images ------ .. autoclass:: ImageData - :members: - :inherited-members: + :members: getData, getRgbaImageData, + getOrigin, setOrigin, + getScale, setScale, + isDraggable, + getAlpha, setAlpha, + getColormap, setColormap, + getAlternativeImageData .. autoclass:: ImageRgba - :members: - :inherited-members: + :members: getData, getRgbaImageData, + getOrigin, setOrigin, + getScale, setScale, + isDraggable, + getAlpha, setAlpha Scatter ------- .. autoclass:: Scatter - :members: - :inherited-members: + :members: getValueData, + getData, getXData, getYData, getXErrorData, getYErrorData, setData, + getSymbol, setSymbol, getSymbolSize, setSymbolSize, + getAlpha, setAlpha, + getColormap, setColormap Histogram --------- .. autoclass:: Histogram - :members: - :inherited-members: + :members: getValueData, getBinEdgesData, getData, setData, + getAlpha, setAlpha, + getColor, setColor, + getYAxis, setYAxis, + isFill, setFill, + getLineWidth, setLineWidth, getLineStyle, setLineStyle Markers ------- .. autoclass:: Marker - :members: - :inherited-members: + :members: getText, setText, getXPosition, getYPosition, getPosition, setPosition, getConstraint, + getSymbol, setSymbol, getSymbolSize, setSymbolSize .. autoclass:: XMarker - :members: - :inherited-members: + :members: getText, setText, getXPosition, getYPosition, getPosition, setPosition, getConstraint .. autoclass:: YMarker + :members: getText, setText, getXPosition, getYPosition, getPosition, setPosition, getConstraint + +Shapes +------ + +.. autoclass:: Shape + :members: setOverlay, + getColor, setColor, + isFill, setFill, + getType, getPoints, setPoints + +Item changed signal +------------------- + +Plot items emit a :attr:`Item.sigItemChanged` signal when their values are updated. +This signal provides a flag in the following enumeration describing the modified value: + +.. autoclass:: ItemChangedType :members: - :inherited-members: -Item +Axis ---- -.. autoclass:: Shape +.. autoclass:: Axis :members: - :inherited-members: diff --git a/doc/source/modules/gui/plot/plot.rst b/doc/source/modules/gui/plot/plot.rst deleted file mode 100644 index 2b8e096..0000000 --- a/doc/source/modules/gui/plot/plot.rst +++ /dev/null @@ -1,16 +0,0 @@ - -.. currentmodule:: silx.gui.plot - -:mod:`Plot`: Full plot API -========================== - -.. automodule:: silx.gui.plot.Plot - -.. currentmodule:: silx.gui.plot.Plot - -:class:`Plot` class -------------------- - -.. autoclass:: Plot - :show-inheritance: - :members: diff --git a/doc/source/modules/gui/plot/plotactions.rst b/doc/source/modules/gui/plot/plotactions.rst deleted file mode 100644 index 29a3656..0000000 --- a/doc/source/modules/gui/plot/plotactions.rst +++ /dev/null @@ -1,20 +0,0 @@ - -.. currentmodule:: silx.gui.plot - -:mod:`PlotActions`: Actions for PlotWidget -=========================================== - -.. currentmodule:: silx.gui.plot.PlotActions - -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`. - -For an introduction to creating custom plot actions, see :doc:`plotactions_examples`. - -PlotActions API ---------------- - -.. automodule:: silx.gui.plot.PlotActions - :members: diff --git a/doc/source/modules/gui/plot/plotwidget.rst b/doc/source/modules/gui/plot/plotwidget.rst index df576fc..a8e7831 100644 --- a/doc/source/modules/gui/plot/plotwidget.rst +++ b/doc/source/modules/gui/plot/plotwidget.rst @@ -14,13 +14,8 @@ It is the basis of other plot widget, thus all plot widgets share the same API. For an introduction and examples of the plot API, see :doc:`getting_started`. -Plot API --------- - -.. currentmodule:: silx.gui.plot.Plot - -This is a choosen subset of the complete plot API, the full API is -documented in :class:`silx.gui.plot.Plot`. +:class:`PlotWidget` +------------------- .. currentmodule:: silx.gui.plot.PlotWidget @@ -37,6 +32,20 @@ Those methods allow to add and update plotted data: .. automethod:: PlotWidget.addScatter .. automethod:: PlotWidget.addHistogram +Get data +........ + +Those methods return objects providing access to plotted data: + +.. automethod:: PlotWidget.getCurve +.. automethod:: PlotWidget.getImage +.. automethod:: PlotWidget.getScatter +.. automethod:: PlotWidget.getHistogram + +.. automethod:: PlotWidget.getAllCurves +.. automethod:: PlotWidget.getAllImages + + Plot markers ............ @@ -52,59 +61,40 @@ Remove data from the plot .. automethod:: PlotWidget.clear .. automethod:: PlotWidget.remove -Title and labels -................ +Title +..... -Those methods handle the text labels of the axes and the plot title: +Those methods handle the plot title: .. automethod:: PlotWidget.getGraphTitle .. automethod:: PlotWidget.setGraphTitle -.. automethod:: PlotWidget.getGraphXLabel -.. automethod:: PlotWidget.setGraphXLabel -.. automethod:: PlotWidget.getGraphYLabel -.. automethod:: PlotWidget.setGraphYLabel - -Axes limits -........... - -Those methods change the range of data values displayed on each axis. - -.. automethod:: PlotWidget.getGraphXLimits -.. automethod:: PlotWidget.setGraphXLimits -.. automethod:: PlotWidget.getGraphYLimits -.. automethod:: PlotWidget.setGraphYLimits -.. automethod:: PlotWidget.setLimits Axes .... -The following methods handle the display properties of the axes: +Those two methods give access to :class:`.items.Axis` which handle the limits, scales and labels of axis: -.. automethod:: PlotWidget.isXAxisLogarithmic -.. automethod:: PlotWidget.setXAxisLogarithmic -.. automethod:: PlotWidget.isYAxisLogarithmic -.. automethod:: PlotWidget.setYAxisLogarithmic +.. automethod:: PlotWidget.getXAxis +.. automethod:: PlotWidget.getYAxis -.. automethod:: PlotWidget.isYAxisInverted -.. automethod:: PlotWidget.setYAxisInverted +The following methods handle plot limits, aspect ratio, grid and axes display: + +.. automethod:: PlotWidget.setLimits .. automethod:: PlotWidget.isKeepDataAspectRatio .. automethod:: PlotWidget.setKeepDataAspectRatio .. automethod:: PlotWidget.getGraphGrid .. automethod:: PlotWidget.setGraphGrid +.. automethod:: PlotWidget.setAxesDisplayed Reset zoom .......... .. automethod:: PlotWidget.resetZoom -Those methods change the behavior of :meth:`PlotWidget.resetZoom`. +The following methods allow to add margins around the data when performing a zoom reset: .. automethod:: PlotWidget.getDataMargins .. automethod:: PlotWidget.setDataMargins -.. automethod:: PlotWidget.isXAxisAutoScale -.. automethod:: PlotWidget.setXAxisAutoScale -.. automethod:: PlotWidget.isYAxisAutoScale -.. automethod:: PlotWidget.setYAxisAutoScale Defaults ........ @@ -130,10 +120,35 @@ of the plot and to toggle the use of a crosshair cursor: .. automethod:: PlotWidget.getGraphCursor .. automethod:: PlotWidget.setGraphCursor +.. automethod:: PlotWidget.isPanWithArrowKeys +.. automethod:: PlotWidget.setPanWithArrowKeys + +Coordinates conversion +...................... + +.. automethod:: PlotWidget.getDataRange +.. automethod:: PlotWidget.getPlotBoundsInPixels +.. automethod:: PlotWidget.dataToPixel +.. automethod:: PlotWidget.pixelToData + +Active Item +........... + +.. automethod:: PlotWidget.isActiveCurveHandling +.. automethod:: PlotWidget.setActiveCurveHandling +.. automethod:: PlotWidget.getActiveCurveColor +.. automethod:: PlotWidget.setActiveCurveColor +.. automethod:: PlotWidget.getActiveCurve +.. automethod:: PlotWidget.setActiveCurve +.. automethod:: PlotWidget.getActiveImage +.. automethod:: PlotWidget.setActiveImage + Misc. ..... +.. automethod:: PlotWidget.getWidgetHandle .. automethod:: PlotWidget.saveGraph +.. automethod:: PlotWidget.setDefaultBackend Signals ....... @@ -141,11 +156,6 @@ Signals The :class:`PlotWidget` provides the following Qt signals: .. autoattribute:: PlotWidget.sigPlotSignal -.. autoattribute:: PlotWidget.sigSetYAxisInverted -.. autoattribute:: PlotWidget.sigSetXAxisLogarithmic -.. autoattribute:: PlotWidget.sigSetYAxisLogarithmic -.. autoattribute:: PlotWidget.sigSetXAxisAutoScale -.. autoattribute:: PlotWidget.sigSetYAxisAutoScale .. autoattribute:: PlotWidget.sigSetKeepDataAspectRatio .. autoattribute:: PlotWidget.sigSetGraphGrid .. autoattribute:: PlotWidget.sigSetGraphCursor @@ -153,21 +163,33 @@ The :class:`PlotWidget` provides the following Qt signals: .. autoattribute:: PlotWidget.sigContentChanged .. autoattribute:: PlotWidget.sigActiveCurveChanged .. autoattribute:: PlotWidget.sigActiveImageChanged +.. autoattribute:: PlotWidget.sigActiveScatterChanged .. autoattribute:: PlotWidget.sigInteractiveModeChanged -.. Not documented: - addItem, removeItem, clearItems - isActiveCurveHandling, enableActiveCurveHandling, - getActiveCurveColor, setActiveCurveColor, - getActiveCurve, setActiveCurve, - isCurveHidden, hideCurve, - getActiveImage, setActiveImage, - getAllCurves, getCurve, getImage, getAllImages, - getScatter, getHistogram, - setDefaultPlotPoints, setDefaultPlotLines, - getWidgetHandle, notify, setCallback, graphCallback, - dataToPixel, pixelToData, getPlotBoundsInPixels, - setGraphCursorShape, pickMarker, moveMarker, pickImageOrCurve, moveImage, - onMousePress, onMouseMove, onMouseRelease, onMouseWheel, - isDrawModeEnabled, setDrawModeEnabled, getDrawMode, - isZoomModeEnabled, setZoomModeEnabled, +.. PlotWidget public API that is not documented: + Could be added: + - addItem + - pan + - getLimitsHistory + - isDefaultPlotPoints + - isDefaultPlotLines + - setGraphCursorShape + - getAutoReplot, setAutoReplot, replot + Should not be added: + * Should be private: + - notify, setCallback, graphCallback + * Use remove instead: + - removeCurve, removeImage, removeItem, removeMarker + - clearCurves, clearImages, clearItems, clearMarkers + * Use items instead: + - isCurveHidden, hideCurve + * Use items.axis instead: + - getGraphXLimits, setGraphXLimits + - getGraphYLimits, setGraphYLimits + - getGraphXLabel, setGraphXLabel + - getGraphYLabel, setGraphYLabel + - isXAxisLogarithmic, setXAxisLogarithmic + - isYAxisLogarithmic, setXAxisLogarithmic + - isXAxisAutoScale, setXAxisAutoScale + - isYAxisAutoScale, setYAxisAutoScale + - setYAxisInverted, isYAxisInverted diff --git a/doc/source/modules/gui/plot/printpreviewtoolbutton.rst b/doc/source/modules/gui/plot/printpreviewtoolbutton.rst new file mode 100644 index 0000000..42b3832 --- /dev/null +++ b/doc/source/modules/gui/plot/printpreviewtoolbutton.rst @@ -0,0 +1,8 @@ + +.. currentmodule:: silx.gui.plot + +:mod:`PrintPreviewToolButton`: Print preview buttons +==================================================== + +.. automodule:: silx.gui.plot.PrintPreviewToolButton + :members: diff --git a/doc/source/modules/gui/plot/stackview.rst b/doc/source/modules/gui/plot/stackview.rst index 7f2442a..11c7828 100644 --- a/doc/source/modules/gui/plot/stackview.rst +++ b/doc/source/modules/gui/plot/stackview.rst @@ -13,7 +13,9 @@ .. autoclass:: StackView :members: - :exclude-members: remove, setInteractiveMode, addItem + :exclude-members: remove, setInteractiveMode, addItem, getActiveImage, + resetZoom, setYAxisInverted, isYAxisInverted, getSupportedColormaps, + isKeepDataAspectRatio, setKeepDataAspectRatio :class:`StackViewMainWindow` class ---------------------------------- diff --git a/doc/source/modules/gui/plot3d/actions.rst b/doc/source/modules/gui/plot3d/actions.rst index a2fde68..c9e3af2 100644 --- a/doc/source/modules/gui/plot3d/actions.rst +++ b/doc/source/modules/gui/plot3d/actions.rst @@ -1,10 +1,15 @@ -Actions -======= +:mod:`actions` +============== -:mod:`Plot3DActions` --------------------- +.. currentmodule:: silx.gui.plot3d.actions -.. currentmodule:: silx.gui.plot3d.Plot3DActions +.. automodule:: silx.gui.plot3d.actions + :members: + +.. automodule:: silx.gui.plot3d.actions.io + :members: -.. automodule:: silx.gui.plot3d.Plot3DActions +.. automodule:: silx.gui.plot3d.actions.mode :members: + +.. autoclass:: Plot3DAction diff --git a/doc/source/modules/gui/plot3d/dev.rst b/doc/source/modules/gui/plot3d/dev.rst index 757240e..96704f8 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 -and toolbars: :class:`ViewpointToolBar` and :class:`Plot3DToolBar`. -:class:`QAction` that can be associated with a :class:`Plot3DWidget` are defined in the :mod:`.Plot3DActions` module. -Those actions are used by the :class:`Plot3DToolBar` toolbar. +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:`.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/index.rst b/doc/source/modules/gui/plot3d/index.rst index 8941403..38b8f02 100644 --- a/doc/source/modules/gui/plot3d/index.rst +++ b/doc/source/modules/gui/plot3d/index.rst @@ -11,42 +11,7 @@ Widgets gallery --------------- -.. |imgPlot3DWidget| image:: img/Plot3DWidget.png - :height: 150px - :align: middle - -.. |imgPlot3DWindow| image:: img/Plot3DWindow.png - :height: 150px - :align: middle - -.. |imgScalarFieldView| image:: img/ScalarFieldView.png - :height: 150px - :align: middle - -.. |imgSFViewParamTree| image:: img/SFViewParamTree.png - :height: 150px - :align: middle - -.. list-table:: - :widths: 1 4 - :header-rows: 1 - - * - Widget - - Description - * - |imgScalarFieldView| - - :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:`viewer3dvolume_example`. - * - |imgPlot3DWindow| - - :class:`Plot3DWindow` is a :class:`QMainWindow` with a :class:`Plot3DWidget` as central widget - and toolbars. - * - |imgPlot3DWidget| - - :class:`Plot3DWidget` is the base Qt widget providing an OpenGL 3D scene. - Other widgets are using this widget as the OpenGL scene canvas. - * - |imgSFViewParamTree| - - :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:`viewer3dvolume_example`. +See :ref:`plot3d-gallery` gallery. Public modules -------------- @@ -60,7 +25,7 @@ The following sub-modules are available: plot3dwindow.rst scalarfieldview.rst sfviewparamtree.rst - toolbars.rst + tools.rst actions.rst diff --git a/doc/source/modules/gui/plot3d/scalarfieldview.rst b/doc/source/modules/gui/plot3d/scalarfieldview.rst index 763c18e..80127ea 100644 --- a/doc/source/modules/gui/plot3d/scalarfieldview.rst +++ b/doc/source/modules/gui/plot3d/scalarfieldview.rst @@ -21,13 +21,6 @@ Helper classes Those classes are used by :class:`ScalarFieldView`. -:class:`Colormap` -+++++++++++++++++ - -.. autoclass:: Colormap - :show-inheritance: - :members: - :class:`CutPlane` +++++++++++++++++ diff --git a/doc/source/modules/gui/plot3d/toolbars.rst b/doc/source/modules/gui/plot3d/toolbars.rst deleted file mode 100644 index df4b4ef..0000000 --- a/doc/source/modules/gui/plot3d/toolbars.rst +++ /dev/null @@ -1,29 +0,0 @@ -Toolbars -======== - - -:mod:`ViewpointToolbar` ------------------------ - -.. currentmodule:: silx.gui.plot3d.ViewpointToolBar - -.. automodule:: silx.gui.plot3d.ViewpointToolBar - -.. autoclass:: ViewpointActionGroup - :show-inheritance: - :members: - -.. autoclass:: ViewpointToolBar - :show-inheritance: - :members: - -:mod:`Plot3DToolbar` --------------------- - -.. currentmodule:: silx.gui.plot3d.Plot3DToolBar - -.. automodule:: silx.gui.plot3d.Plot3DToolBar - -.. autoclass:: Plot3DToolBar - :show-inheritance: - :members: diff --git a/doc/source/modules/gui/plot3d/tools.rst b/doc/source/modules/gui/plot3d/tools.rst new file mode 100644 index 0000000..6cd433b --- /dev/null +++ b/doc/source/modules/gui/plot3d/tools.rst @@ -0,0 +1,40 @@ +:mod:`tools` +============ + +.. currentmodule:: silx.gui.plot3d.tools + +.. automodule:: silx.gui.plot3d.tools + +Toolbars +-------- + +:class:`InteractiveModeToolbar` ++++++++++++++++++++++++++++++++ + +.. autoclass:: InteractiveModeToolBar + :show-inheritance: + :members: + +:class:`OutputToolBar` +++++++++++++++++++++++ + +.. autoclass:: OutputToolBar + :show-inheritance: + :members: + +:class:`ViewpointToolbar` ++++++++++++++++++++++++++ + +.. autoclass:: ViewpointToolBar + :show-inheritance: + :members: + +Tool Buttons +------------ + +:class:`ViewpointToolButton` +++++++++++++++++++++++++++++ + +.. autoclass:: ViewpointToolButton + :show-inheritance: + :members: diff --git a/doc/source/modules/gui/widgets/img/FrameBrowser.png b/doc/source/modules/gui/widgets/img/FrameBrowser.png Binary files differnew file mode 100644 index 0000000..c5624f7 --- /dev/null +++ b/doc/source/modules/gui/widgets/img/FrameBrowser.png diff --git a/doc/source/modules/gui/widgets/img/HorizontalSliderWithBrowser.png b/doc/source/modules/gui/widgets/img/HorizontalSliderWithBrowser.png Binary files differnew file mode 100644 index 0000000..d64b2df --- /dev/null +++ b/doc/source/modules/gui/widgets/img/HorizontalSliderWithBrowser.png diff --git a/doc/source/modules/gui/widgets/img/PeriodicCombo.png b/doc/source/modules/gui/widgets/img/PeriodicCombo.png Binary files differnew file mode 100644 index 0000000..e0b40c2 --- /dev/null +++ b/doc/source/modules/gui/widgets/img/PeriodicCombo.png diff --git a/doc/source/modules/gui/widgets/img/PeriodicList.png b/doc/source/modules/gui/widgets/img/PeriodicList.png Binary files differnew file mode 100644 index 0000000..d1e540b --- /dev/null +++ b/doc/source/modules/gui/widgets/img/PeriodicList.png diff --git a/doc/source/modules/gui/widgets/img/PeriodicTable.png b/doc/source/modules/gui/widgets/img/PeriodicTable.png Binary files differnew file mode 100644 index 0000000..c06dded --- /dev/null +++ b/doc/source/modules/gui/widgets/img/PeriodicTable.png diff --git a/doc/source/modules/gui/widgets/img/TableWidget.png b/doc/source/modules/gui/widgets/img/TableWidget.png Binary files differnew file mode 100644 index 0000000..a0f819f --- /dev/null +++ b/doc/source/modules/gui/widgets/img/TableWidget.png diff --git a/doc/source/modules/gui/widgets/img/ThreadPoolPushButton.png b/doc/source/modules/gui/widgets/img/ThreadPoolPushButton.png Binary files differnew file mode 100644 index 0000000..4710d16 --- /dev/null +++ b/doc/source/modules/gui/widgets/img/ThreadPoolPushButton.png diff --git a/doc/source/modules/gui/widgets/img/WaitingPushButton.png b/doc/source/modules/gui/widgets/img/WaitingPushButton.png Binary files differnew file mode 100644 index 0000000..fa1d51a --- /dev/null +++ b/doc/source/modules/gui/widgets/img/WaitingPushButton.png diff --git a/doc/source/modules/gui/widgets/index.rst b/doc/source/modules/gui/widgets/index.rst index 2284f22..72f89a8 100644 --- a/doc/source/modules/gui/widgets/index.rst +++ b/doc/source/modules/gui/widgets/index.rst @@ -14,6 +14,7 @@ Public modules: framebrowser.rst periodictable.rst + printpreview.rst tablewidget.rst threadpoolpushbutton.rst waitingpushbutton.rst diff --git a/doc/source/modules/gui/widgets/printpreview.rst b/doc/source/modules/gui/widgets/printpreview.rst new file mode 100644 index 0000000..d0b7999 --- /dev/null +++ b/doc/source/modules/gui/widgets/printpreview.rst @@ -0,0 +1,60 @@ + +.. currentmodule:: silx.gui.widgets + +:mod:`PrintPreview`: Print preview dialog +----------------------------------------- + +.. automodule:: silx.gui.widgets.PrintPreview + +Widgets ++++++++ + +.. autoclass:: silx.gui.widgets.PrintPreview.PrintPreviewDialog + :members: + :exclude-members: printDialog, showEvent + :show-inheritance: + + +.. autoclass:: silx.gui.widgets.PrintPreview.SingletonPrintPreviewDialog + :show-inheritance: + +Example ++++++++ + +.. code-block:: python + + import sys + from silx.gui import qt + from silx.gui.widgets import PrintPreviewDialog + + a = qt.QApplication(sys.argv) + + if len(sys.argv) < 2: + print("give an image file as parameter please.") + sys.exit(1) + + if len(sys.argv) > 2: + print("only one parameter please.") + sys.exit(1) + + filename = sys.argv[1] + w = PrintPreviewDialog() + w.resize(400, 500) + + comment = "" + for i in range(20): + comment += "Line number %d: En un lugar de La Mancha de cuyo nombre ...\n" + + if filename[-3:] == "svg": + item = qt.QSvgRenderer(filename, w.page) + w.addSvgItem(item, title=filename, + comment=comment, commentPosition="CENTER") + else: + w.addPixmap(qt.QPixmap.fromImage(qt.QImage(filename)), + title=filename, + comment=comment, + commentPosition="CENTER") + w.addImage(qt.QImage(filename), comment=comment, commentPosition="LEFT") + + w.exec_() + a.exec_() diff --git a/doc/source/modules/image/backprojection.rst b/doc/source/modules/image/backprojection.rst new file mode 100644 index 0000000..c45f670 --- /dev/null +++ b/doc/source/modules/image/backprojection.rst @@ -0,0 +1,8 @@ + +.. currentmodule:: silx.image + +:mod:`backprojection`: backprojection algorithm +----------------------------------------------- + +.. automodule:: silx.image.backprojection + :members: Backprojection diff --git a/doc/source/modules/image/index.rst b/doc/source/modules/image/index.rst index abdeb64..89c5642 100644 --- a/doc/source/modules/image/index.rst +++ b/doc/source/modules/image/index.rst @@ -11,3 +11,4 @@ medianfilter.rst shapes.rst sift.rst + backprojection.rst diff --git a/doc/source/modules/image/projection.rst b/doc/source/modules/image/projection.rst new file mode 100644 index 0000000..f5f4815 --- /dev/null +++ b/doc/source/modules/image/projection.rst @@ -0,0 +1,15 @@ + +.. currentmodule:: silx.image + +:mod:`projection`: projection algorithm +--------------------------------------- + +.. warning:: + + This module is known to be buggy in version 0.6: + Do NOT use it without having checked it provides + proper results + +.. automodule:: silx.image.projection + :members: Projection + diff --git a/doc/source/modules/image/reconstruction.rst b/doc/source/modules/image/reconstruction.rst new file mode 100644 index 0000000..d288581 --- /dev/null +++ b/doc/source/modules/image/reconstruction.rst @@ -0,0 +1,14 @@ + +.. currentmodule:: silx.image + +:mod:`reconstruction`: reconstruction algorithm +----------------------------------------------- + +.. warning:: + + This module is known to be buggy in version 0.6: + Do NOT use it without having checked it provides + proper results + +.. automodule:: silx.image.reconstruction + :members: ReconstructionAlgorithm, SIRT, TV diff --git a/doc/source/modules/io/convert.rst b/doc/source/modules/io/convert.rst new file mode 100644 index 0000000..4d3abdc --- /dev/null +++ b/doc/source/modules/io/convert.rst @@ -0,0 +1,8 @@ + +.. currentmodule:: silx.io + +:mod:`convert`: HDF5 conversion +------------------------------- + +.. automodule:: silx.io.convert + :members: write_to_h5, convert diff --git a/doc/source/modules/io/index.rst b/doc/source/modules/io/index.rst index 1538a74..815a094 100644 --- a/doc/source/modules/io/index.rst +++ b/doc/source/modules/io/index.rst @@ -9,13 +9,13 @@ :maxdepth: 1 configdict.rst + convert.rst dictdump.rst nxdata.rst octaveh5.rst specfile.rst specfilewrapper.rst spech5.rst - spectoh5.rst utils.rst Top-level functions @@ -23,3 +23,8 @@ Top-level functions .. autofunction:: silx.io.open .. autofunction:: silx.io.save1D + +.. autofunction:: silx.io.is_dataset +.. autofunction:: silx.io.is_group +.. autofunction:: silx.io.is_file +.. autofunction:: silx.io.is_softlink diff --git a/doc/source/modules/io/spech5.rst b/doc/source/modules/io/spech5.rst index 143d3bb..61e0083 100644 --- a/doc/source/modules/io/spech5.rst +++ b/doc/source/modules/io/spech5.rst @@ -5,7 +5,41 @@ ----------------------------------------- .. automodule:: silx.io.spech5 + + +Classes ++++++++ + +- :class:`SpecH5` +- :class:`SpecH5Group` +- :class:`SpecH5Dataset` + +.. autoclass:: SpecH5 + :members: + :show-inheritance: + :undoc-members: + :inherited-members: name, basename, attrs, h5py_class, parent, + get, keys, values, items, + :special-members: __getitem__, __len__, __contains__, __enter__, __exit__, __iter__ + :exclude-members: add_node + +.. autoclass:: SpecH5Group + :show-inheritance: + +.. autoclass:: silx.io.commonh5.Group + :show-inheritance: + :undoc-members: + :members: name, basename, file, attrs, h5py_class, parent, + get, keys, values, items, visit, visititems + :special-members: __getitem__, __len__, __contains__, __iter__ + :exclude-members: add_node + +.. autoclass:: SpecH5Dataset + :show-inheritance: + +.. autoclass:: SpecH5NodeDataset :members: :show-inheritance: :undoc-members: - :special-members: __getitem__, __len__, __contains__ + :inherited-members: + :special-members: __getitem__, __len__, __iter__, __getattr__ diff --git a/doc/source/modules/io/spectoh5.rst b/doc/source/modules/io/spectoh5.rst deleted file mode 100644 index 05fc768..0000000 --- a/doc/source/modules/io/spectoh5.rst +++ /dev/null @@ -1,8 +0,0 @@ - -.. currentmodule:: silx.io - -:mod:`spectoh5`: SpecFile to HDF5 conversion ---------------------------------------------- - -.. automodule:: silx.io.spectoh5 - :members: write_spec_to_h5, convert diff --git a/doc/source/modules/utils/decorators.rst b/doc/source/modules/utils/decorators.rst index 1da0f44..c181220 100644 --- a/doc/source/modules/utils/decorators.rst +++ b/doc/source/modules/utils/decorators.rst @@ -1,7 +1,7 @@ .. currentmodule:: silx.utils -:mod:`decorators` +:mod:`deprecation` ------------------ -.. automodule:: silx.utils.decorators - :members: +.. automodule:: silx.utils.deprecation + :members: deprecated diff --git a/doc/source/sample_code/img/animatedicons.png b/doc/source/sample_code/img/animatedicons.png Binary files differnew file mode 100644 index 0000000..c6f02d8 --- /dev/null +++ b/doc/source/sample_code/img/animatedicons.png diff --git a/doc/source/sample_code/img/customHdf5TreeModel.png b/doc/source/sample_code/img/customHdf5TreeModel.png Binary files differnew file mode 100644 index 0000000..fff6db5 --- /dev/null +++ b/doc/source/sample_code/img/customHdf5TreeModel.png diff --git a/doc/source/sample_code/img/fftPlotAction.png b/doc/source/sample_code/img/fftPlotAction.png Binary files differnew file mode 100644 index 0000000..beb3ae3 --- /dev/null +++ b/doc/source/sample_code/img/fftPlotAction.png diff --git a/doc/source/sample_code/img/hdf5widget.png b/doc/source/sample_code/img/hdf5widget.png Binary files differnew file mode 100644 index 0000000..90ef758 --- /dev/null +++ b/doc/source/sample_code/img/hdf5widget.png diff --git a/doc/source/sample_code/img/icons.png b/doc/source/sample_code/img/icons.png Binary files differnew file mode 100644 index 0000000..927184e --- /dev/null +++ b/doc/source/sample_code/img/icons.png diff --git a/doc/source/sample_code/img/imageview.png b/doc/source/sample_code/img/imageview.png Binary files differnew file mode 100644 index 0000000..b46cd97 --- /dev/null +++ b/doc/source/sample_code/img/imageview.png diff --git a/doc/source/sample_code/img/periodicTable.png b/doc/source/sample_code/img/periodicTable.png Binary files differnew file mode 100644 index 0000000..85aea6c --- /dev/null +++ b/doc/source/sample_code/img/periodicTable.png diff --git a/doc/source/sample_code/img/plotContextMenu.png b/doc/source/sample_code/img/plotContextMenu.png Binary files differnew file mode 100644 index 0000000..2ca7386 --- /dev/null +++ b/doc/source/sample_code/img/plotContextMenu.png diff --git a/doc/source/sample_code/img/plotItemsSelector.png b/doc/source/sample_code/img/plotItemsSelector.png Binary files differnew file mode 100644 index 0000000..f040472 --- /dev/null +++ b/doc/source/sample_code/img/plotItemsSelector.png diff --git a/doc/source/sample_code/img/plotLimits.png b/doc/source/sample_code/img/plotLimits.png Binary files differnew file mode 100644 index 0000000..4ca3d29 --- /dev/null +++ b/doc/source/sample_code/img/plotLimits.png diff --git a/doc/source/sample_code/img/plotUpdateFromThread.png b/doc/source/sample_code/img/plotUpdateFromThread.png Binary files differnew file mode 100644 index 0000000..ac97ccd --- /dev/null +++ b/doc/source/sample_code/img/plotUpdateFromThread.png diff --git a/doc/source/sample_code/img/plotWidget.png b/doc/source/sample_code/img/plotWidget.png Binary files differnew file mode 100644 index 0000000..7385ee5 --- /dev/null +++ b/doc/source/sample_code/img/plotWidget.png diff --git a/doc/source/sample_code/img/printPreview.png b/doc/source/sample_code/img/printPreview.png Binary files differnew file mode 100644 index 0000000..fb75025 --- /dev/null +++ b/doc/source/sample_code/img/printPreview.png diff --git a/doc/source/sample_code/img/scatterMask.png b/doc/source/sample_code/img/scatterMask.png Binary files differnew file mode 100644 index 0000000..b2028a1 --- /dev/null +++ b/doc/source/sample_code/img/scatterMask.png diff --git a/doc/source/sample_code/img/shiftPlotAction.png b/doc/source/sample_code/img/shiftPlotAction.png Binary files differnew file mode 100644 index 0000000..afa51eb --- /dev/null +++ b/doc/source/sample_code/img/shiftPlotAction.png diff --git a/doc/source/sample_code/img/simplewidget.png b/doc/source/sample_code/img/simplewidget.png Binary files differnew file mode 100644 index 0000000..b4ed9dd --- /dev/null +++ b/doc/source/sample_code/img/simplewidget.png diff --git a/doc/source/sample_code/img/stackView.png b/doc/source/sample_code/img/stackView.png Binary files differnew file mode 100644 index 0000000..6003f0a --- /dev/null +++ b/doc/source/sample_code/img/stackView.png diff --git a/doc/source/sample_code/img/syncaxis.png b/doc/source/sample_code/img/syncaxis.png Binary files differnew file mode 100644 index 0000000..fd15353 --- /dev/null +++ b/doc/source/sample_code/img/syncaxis.png diff --git a/doc/source/sample_code/img/viewer3DVolume.png b/doc/source/sample_code/img/viewer3DVolume.png Binary files differnew file mode 100644 index 0000000..69abf26 --- /dev/null +++ b/doc/source/sample_code/img/viewer3DVolume.png diff --git a/doc/source/sample_code/index.rst b/doc/source/sample_code/index.rst new file mode 100644 index 0000000..6c826b7 --- /dev/null +++ b/doc/source/sample_code/index.rst @@ -0,0 +1,232 @@ +.. _sample-code: + +Sample Code +=========== + +All sample codes can be downloaded as a zip file: |sample_code_archive|. + +.. |sample_code_archive| archive:: ../../../examples/ + :filename: silx_examples.zip + :basedir: silx_examples + :filter: *.py *.png + +:mod:`silx.gui` sample code ++++++++++++++++++++++++++++ + +.. list-table:: + :widths: 1 1 4 + :header-rows: 1 + + * - Source + - Screenshot + - Description + * - :download:`animatedicons.py <../../../examples/animatedicons.py>` + - .. image:: img/animatedicons.png + :height: 150px + :align: center + - Display available project icons using Qt. + * - :download:`customHdf5TreeModel.py <../../../examples/customHdf5TreeModel.py>` + - .. image:: img/customHdf5TreeModel.png + :height: 150px + :align: center + - Qt Hdf5 widget examples + * - :download:`hdf5widget.py <../../../examples/hdf5widget.py>` + - .. image:: img/hdf5widget.png + :height: 150px + :align: center + - Qt Hdf5 widget examples + + .. note:: This module has a dependency on the `h5py <http://www.h5py.org/>`_ + library, which is not a mandatory dependency for `silx`. You might need + to install it if you don't already have it. + * - :download:`icons.py <../../../examples/icons.py>` + - .. image:: img/icons.png + :height: 150px + :align: center + - Display available project icons using Qt. + * - :download:`periodicTable.py <../../../examples/periodicTable.py>` + - .. image:: img/periodicTable.png + :height: 150px + :align: center + - This script is a simple example of how to use the periodic table widgets, + select elements and connect signals. + * - :download:`simplewidget.py <../../../examples/simplewidget.py>` + - .. image:: img/simplewidget.png + :height: 150px + :align: center + - This script shows a gallery of simple widgets provided by silx. + + It shows the following widgets: + + - :class:WaitingPushButton: A button with a progress-like waiting animated icon + * - :download:`viewer3DVolume.py <../../../examples/viewer3DVolume.py>` + - .. image:: img/viewer3DVolume.png + :height: 150px + :align: center + - This script illustrates the use of silx.gui.plot3d.ScalarFieldView. + + It loads a 3D scalar data set from a file and displays iso-surfaces and + an interactive cutting plane. + It can also be started without providing a file. + +:mod:`silx.gui.plot` sample code +++++++++++++++++++++++++++++++++ + +.. list-table:: + :widths: 1 1 4 + :header-rows: 1 + + * - Source + - Screenshot + - Description + * - :download:`fftPlotAction.py <../../../examples/fftPlotAction.py>`, + :download:`fft.png <../../../examples/fft.png>` + - .. image:: img/fftPlotAction.png + :height: 150px + :align: center + - This script is a simple example of how to create a PlotWindow with a custom + PlotAction added to the toolbar. + + The action computes the FFT of all curves and plots their amplitude spectrum. + It also performs the reverse transform. + + This example illustrates: + - how to create a checkable action + - how to store user info with a curve in a PlotWindow + - how to modify the graph title and axes labels + - how to add your own icon as a PNG file + + See shiftPlotAction.py for a simpler example with more basic comments. + * - :download:`imageview.py <../../../examples/imageview.py>` + - .. image:: img/imageview.png + :height: 150px + :align: center + - Example to show the use of `ImageView` widget. It can be used to open an EDF + or TIFF file from the shell command line. + + To view an image file with the current installed silx library: + ``python examples/imageview.py <file to open>`` + To get help: + ``python examples/imageview.py -h`` + + For developers with a git clone you can use it with the bootstrap + To view an image file with the current installed silx library: + + ``./bootstrap.py python examples/imageview.py <file to open>`` + * - :download:`plotContextMenu.py <../../../examples/plotContextMenu.py>` + - .. image:: img/plotContextMenu.png + :height: 150px + :align: center + - This script illustrates the addition of a context menu to a PlotWidget. + + This is done by adding a custom context menu to the plot area of PlotWidget: + - set the context menu policy of the plot area to Qt.CustomContextMenu. + - connect to the plot area customContextMenuRequested signal. + + The same method works with PlotWindow, Plot1D and Plot2D widgets as they + inherit from PlotWidget. + + For more information on context menus, see Qt documentation. + * - :download:`plotItemsSelector.py <../../../examples/plotItemsSelector.py>` + - .. image:: img/plotItemsSelector.png + :height: 150px + :align: center + - This example illustrates how to use a :class:`ItemsSelectionDialog` widget + associated with a :class:`PlotWidget`. + * - :download:`plotLimits.py <../../../examples/plotLimits.py>` + - .. image:: img/plotLimits.png + :height: 150px + :align: center + - This script is an example to illustrate how to use axis synchronization + tool. + * - :download:`plotUpdateFromThread.py <../../../examples/plotUpdateFromThread.py>` + - .. image:: img/plotUpdateFromThread.png + :height: 150px + :align: center + - This script illustrates the update of a silx.gui.plot widget from a thread. + + The problem is that plot and GUI methods should be called from the main thread. + To safely update the plot from another thread, one need to make the update + asynchronously from the main thread. + In this example, this is achieved through a Qt signal. + + In this example we create a subclass of :class:`silx.gui.plot.Plot1D` + that adds a thread-safe method to add curves: + :meth:`ThreadSafePlot1D.addCurveThreadSafe`. + This thread-safe method is then called from a thread to update the plot. + * - :download:`plotWidget.py <../../../examples/plotWidget.py>` + - .. image:: img/plotWidget.png + :height: 150px + :align: center + - This script shows how to subclass :class:`PlotWidget` to tune its tools. + + It subclasses a :class:`silx.gui.plot.PlotWidget` and adds toolbars and + a colorbar by using pluggable widgets: + + - QAction from :mod:`silx.gui.plot.actions` + - QToolButton from :mod:`silx.gui.plot.PlotToolButtons` + - QToolBar from :mod:`silx.gui.plot.PlotTools` + - :class:`ColorBarWidget` from :mod:`silx.gui.plot.ColorBar`. + * - :download:`printPreview.py <../../../examples/printPreview.py>` + - .. image:: img/printPreview.png + :height: 150px + :align: center + - This script illustrates how to add a print preview tool button to any plot + widget inheriting :class:`PlotWidget`. + + Three plot widgets are instantiated. One of them uses a standalone + :class:`PrintPreviewToolButton`, while the other two use a + :class:`SingletonPrintPreviewToolButton` which allows them to send their content + to the same print preview page. + * - :download:`scatterMask.py <../../../examples/scatterMask.py>` + - .. image:: img/scatterMask.png + :height: 150px + :align: center + - This example demonstrates how to use ScatterMaskToolsWidget + and NamedScatterAlphaSlider with a PlotWidget. + * - :download:`shiftPlotAction.py <../../../examples/shiftPlotAction.py>` + - .. image:: img/shiftPlotAction.png + :height: 150px + :align: center + - This script is a simple (trivial) example of how to create a PlotWindow, + create a custom :class:`PlotAction` and add it to the toolbar. + + The action simply shifts the selected curve up by 1 unit by adding 1 to each + value of y. + * - :download:`stackView.py <../../../examples/stackView.py>` + - .. image:: img/stackView.png + :height: 150px + :align: center + - This script is a simple example to illustrate how to use the StackView + widget. + * - :download:`syncaxis.py <../../../examples/syncaxis.py>` + - .. image:: img/syncaxis.png + :height: 150px + :align: center + - This script is an example to illustrate how to use axis synchronization + tool. + +:mod:`silx.io` sample code +++++++++++++++++++++++++++ + +.. list-table:: + :widths: 1 1 4 + :header-rows: 1 + + * - Source + - Screenshot + - Description + * - :download:`writetoh5.py <../../../examples/writetoh5.py>` + - + - This script converts a supported data file (SPEC, EDF...) to a HDF5 file. + + By default, it creates a new output file or fails if the output file given + on the command line already exist, but the user can choose to overwrite + an existing file, or append data to an existing HDF5 file. + + In case of appending data to HDF5 files, the user can choose between ignoring + input data if a corresponding dataset already exists in the output file, or + overwriting the existing dataset. + + By default, new scans are written to the root (/) of the HDF5 file, but it is + possible to specify a different target path. diff --git a/doc/source/tutorials.rst b/doc/source/tutorials.rst index 8ea536b..97698cd 100644 --- a/doc/source/tutorials.rst +++ b/doc/source/tutorials.rst @@ -1,5 +1,5 @@ -Tutorials -========= +Tutorials and sample code +========================= Tutorials and cookbooks: @@ -7,11 +7,17 @@ Tutorials and cookbooks: :maxdepth: 1 modules/gui/plot/getting_started.rst - modules/gui/plot/plotactions_examples.rst + modules/gui/plot/actions/examples.rst modules/gui/designer.rst Tutorials/Sift/sift.rst + Tutorials/io.rst Tutorials/specfile_to_hdf5.rst modules/gui/hdf5/getting_started.rst Tutorials/fit.rst Tutorials/fitconfig.rst Tutorials/array_widget.rst + +.. toctree:: + :maxdepth: 2 + + sample_code/index.rst |
