Commit 55a0d7b2 authored by Valentin Valls's avatar Valentin Valls
Browse files

Update the documentation

parent d4bdecbe
......@@ -16,37 +16,10 @@ This Qt application is started automatically when a new plot is created.
This interface supports several types of plot:
- **curve plot**:
* plotting one or several 1D data as curves
* Optional x-axis data can be provided
* the plot is created using ``plot_curve``
- **scatter plot**:
* plotting one or several scattered data
* each scatter is a group of three 1D data of same length
* the plot is created using ``plot_scatter``
- **image plot**:
* plot one or several image on top of each other
* the image order can be controlled using a depth parameter
* the plot is created using ``plot_image``
- **image + histogram plot**:
* plot a single 2D image (greyscale or colormap)
* two histograms along the X and Y dimensions are displayed
* the plot is created using ``plot_image_with_histogram``
- **image stack plot**:
* plot a single stack of image
* a slider is provided to browse the images
* the plot is created using ``plot_image_stack``
An extra helper called ``plot`` is provided to automatically infer
a suitable type of plot from the data provided.
- And few others
Basic interface
---------------
......@@ -59,80 +32,14 @@ as an argument and return a plot:
>>> plot(mydata, name="My plot")
ImagePlot(plot_id=1, flint_pid=17450)
Extra keyword arguments are forwarded to silx:
>>> p = plot(mydata, xlabel='A', ylabel='b')
From then on, all the interaction with the corresponding plot window goes
through the plot object. For instance, it provides a ``plot`` method
to add and display extra data:
>>> p.plot(some_extra_data, yaxis='right')
Advanced interface
------------------
For a finer control over the plotted data, the data management is
separated from the plot management. In order to add more data to
the plot, use the following interface:
>>> p.add_data(cos_data, field='cos')
This data is now identified using its field, ``'cos'``. A dict or
a structured numpy array can also be provided. In this case,
the fields of the provided data structure are used as identifiers:
>>> p.add_data({'cos': cos_data, 'sin': sin_data})
The plot selection is then done through the ``select_data`` method.
For a curve plot, the expected arguments are the names of the data
to use for X and Y:
>>> p.select_data('sin', 'cos')
Again, the extra keyword arguments will be forwarded to silx:
>>> p.select_data('sin', 'cos', color='green', symbol='x')
The curve can then be deselected:
>>> p.deselect_data('sin', 'cos')
And the data can be cleared:
>>> p.clear_data()
Plot interaction
----------------
In order to interact with a given plot, several methods are provided.
The ``select_points`` method allows the user to select a given number of point
on the corresponding plot using their mouse.
>>> a, b, c = p.select_points(3)
# Blocks until the user selects the 3 points
>>> a
(1.2, 3.4)
The ``select_shape`` methods allows the user to select a given shape on the
corresponding plot using their mouse. The available shapes are:
- ``'rectangle'``: rectangle selection
- ``'line'``: line selection
- ``'hline'``: horizontal line selection
- ``'vline'``: vertical line selection
- ``'polygon'``: polygon selection
The return values are shown in the following example:
There is way to have finer control of the plot content, especially to create
plot containing many curves.
>>> topleft, bottomright = p.select_shape('rectangle')
>>> start, stop = p.select_shape('line')
>>> left, right = p.select_shape('hline')
>>> bottom, top = p.select_shape('vline')
>>> points = p.select_shape('polygon')
See the `online BLISS documentation <https://bliss.gitlab-pages.esrf.fr/bliss/master/flint/flint_data_plotting.html>`
for detailed explanation and examples.
"""
from typing import List
......
......@@ -104,6 +104,63 @@ p = f.get_plot("curve", name="My heart")
p.add_curve(x, y, legend="heart")
```
## Descriptive 1D plot
The 1D plot also provides a descriptive mode. In this mode, there is a separation
between the data and the way it is rendered.
The description of the rendering is done by a layer of items. First this
description have to be provided, then the data can be set.
When data for axis are shared, it's also a convenient way to only transfer data
once.
```python
import numpy
# Create the plot
f = flint()
p = f.get_plot("curve", name="My plot")
# Create the data
t = numpy.linspace(0, 10 * numpy.pi, 100)
s1 = numpy.sin(t)
s2 = numpy.sin(t + numpy.pi * 0.5)
s3 = numpy.sin(t + numpy.pi * 1.0)
s4 = numpy.sin(t + numpy.pi * 1.5)
# Describe the plot
p.add_curve_item("t", "s1")
p.add_curve_item("t", "s2")
p.add_curve_item("t", "s3")
p.add_curve_item("t", "s4")
# Transfer the data / and update the plot
p.set_data(t=t, s1=s1, s2=s2, s3=s3, s4=s4)
# As the plot description is already known
# Theplot can be updated the same way again
p.set_data(t=t+1, s1=s1+1, s2=s2+1, s3=s3+1, s4=s4+1)
# Clean up the plot
p.clean_data()
```
For complex plot, if you want to handle properly the refresh of the plot
a transaction can be used. It will enforce a signle update of the plot at the
end of the transaction.
```python
with p.transaction():
p.clear_items()
p.add_curve_item("x", "y", legend="item1")
p.add_curve_item("x", "w", legend="item2")
p.remove_item(legend="item2")
p.set_data(x=[1])
p.append_data(x=[2, 3, 4, 5])
p.set_data(y=[6, 5, 6, 5, 6])
```
## Scatter plot
A 2D scatter plot is provided.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment