diff --git a/src/doc/plotting_framework.dox b/src/doc/plotting_framework.dox index 7606feb9f..c667432c9 100644 --- a/src/doc/plotting_framework.dox +++ b/src/doc/plotting_framework.dox @@ -1,146 +1,146 @@ /**\page plotting_framework Plotting Framework \section fundamental Fundamental terms (Italic words are actual/proposed class names in this section) - Aspect: An aspect is an object of a class derived from 'AbstractAspect'. It is placed as one node in the project aspect tree, which has a 'Project' object as root node. This tree is the central data structure which contains all data related to the currently opened project in the application. The implementation of each aspect follows the 5 layer paradigm (http://scidavis.sourceforge.net/contributing/aspect-framework.html). Each aspect has a name, a comment, one parent, and zero or more child aspects. Being a child aspect of another aspect can mean different things depending on the type of the parent and child aspect. Typically, child aspects are the contents of its parent aspect, e.g., a 'Folder'. Children of a 'Table' (probably to be renamed to 'Spreadsheet') are its columns. Sometimes, the child aspects have special roles such as data<->string filters of 'Column's. - Part: A part is an aspect which inherits 'AbstractPart'. As a first approximation, a part is everything that gets displayed in its own MDI subwindow, although in principle Parts could be displayed differently, e.g. in their own main windows. - Worksheet: the plotting part. Top-level container for 'WorksheetElement's. - Plot: second level container in a 'Worksheet' for logical grouping, equivalent (kind of) to a folder in a project. - WorksheetElement: base class for basically all children of a 'Worksheet' object, sort of equivalent to 'Column' if 'Worksheet' is compared with 'Table'. - WorksheetView: view class (layer 4) for 'Worksheet'. Includes a 'QGraphicsView'. - WorksheetModel: model class (layer 3) for 'Worksheet'. Includes a 'QGraphicScene'. Basically an adapter between the API of 'Worksheet' and Qt's model/view API. - WorksheetElementGroup: generic 'WorksheetElement' container, similar to object groups in a vector drawing program. - Zooming: changing the size in which the 'Worksheet' contents are displayed on screen. Does not change any project data. Completely independent of undo/redo. - Scaling: changing the actual size of a 'WorksheetElement'. This does change project data and triggers generation of undo commands. \section arch Architecture (The contents of this section are still subject to discussion. Everyone is encouraged to provide suggestions and ideas to improve the architecture.) Focus The main goal of the implementation of a new plotting framework for LabPlot/SciDAVis is to combine the following: - superior quality plot export fully scalable to any output resolution - interactive plot editing comparable to a vector graphics drawing program \section Basics The plotting framework (currently codenamed LithoGraph; the name is supposed to express that we want: high-quality, professional output (as in offset lithography), while also containing a reference to plotting (graph of a function)) will follow the aspect framework in the following manner: The core and top-level container is a 'Worksheet' object with its associated 'WorksheetView' and 'WorksheetModel'. The 'WorksheetView' is composed of a 'QGraphicsView' and possibly additional GUI elements. 'WorksheetModel' inherits from 'QGraphicsScene' and contains 'QGraphicsItem's. The 'QGraphicsItem's are representations of the child aspects (i.e., contents) of the 'Worksheet' and are managed by one 'WorksheetElement' each. This means that every 'WorksheetElement' is responsible for changing its 'QGraphicsItem' (within its undo commands) according to the changes made to the 'WorksheetElement'. The 'WorksheetElement's are organized in an aspect tree as children and grandchildren of the 'Worksheet'. They can represent for example axes, curves, or decoration objects (such as arrows, circles, rectangles, '). Most of the 'WorksheetElement's will show up in the project explorer to facilitate selecting them for an editing operation. The plotting framework shall be independent of the origin of the data. I.e., it shall be irrelevant whether the data is entered by hand, generated by a formula, imported from an ASCII file, or read from an external command. For this, a data source abstraction is needed, see [[Data Set]]. Another important topic closely related to the plotting framework is [[aspect styles|styles]] (or themes, templates). The goal of this concept is to allow reusing visualization properties/layouts (think of line colors, decoration objects, multi-plot arrangements, and similar here) with different data. The current state of the discussion however uses a concept which may be used for all aspects and thus goes beyond the plotting framework. Bits and pieces - Plotting order (which object is on top of which) can be easily done by using 'QGraphicsItem::zValue()'/'setZValue()'. - A custom QGraphicsItem implementation (with an optimized paint() method) could be better for some 'WorksheetElement's than a QGraphicsItemGroup for efficiency reasons. - We need a generic concept for tools like zoom, select, data reader, multi-peak fitting etc.. KOffice's Flakes could provide some inspiration. - The MDI window size and aspect ratio should be independent of the actual export page size/aspect ratio (contrary to QtiPlot/current SciDAVis). A page-oriented approach like Inkscape or OpenOffice Draw is intended. - The role of coordinate systems (those who transform logical coordinates into graphics scene coordinates) and their relation to plots is still undecided. The definition may be 'Plot := one or more coordinate systems drawn on top of each other', so that anything displayed side-by-side would be multiple plots. Another criterion could be 'Plot := one or more coordinate systems linked by mathematical or physical relations' (think linked energy/frequency/wavelength axes or linked cartesian/polar plots here). By this definition, both plots with insets and side-by-side displays would involve different Plots, because their relative placement is a matter of layout choice, not of fixed relations. Also, putting the coordinate transform into the plot class or the worksheet element class has been discussed. - Data sets shouldn't be attached to worksheets (e.g., copying a worksheet should not duplicate the data, deleting a plot should not delete the data). Data sets should be contained in an appropriate container aspect, e.g., a Spreadsheet for columns or a DataFile(-part) for data sets read from an external file. The 'Folder' functionality then offers the user the possibility to decide whether the data is placed in the same folder or in a separate data sources folder. - The possibility for every aspect (and thereby every worksheet element) is already implemented in the aspect framework and is usable through the project explorer. - Tools for worksheet element editing will require extra 'QGraphicsItem's (such as handles for scaling) which are not included in exports. \section Class hierarchy (incomplete, only examples given) AbstractAspect | +- AbstractPart | | | `- Worksheet | `- AbstractWorksheetElement | +- LineElement | +- TextElement | +- AbstractPlot | | | +- CurvePlot | | | `- PieChartPlot | +- AbstractCoordinateSystem | | | +- CartesianCoordinateSystem | | | +- PolarCoordinateSystem | | | `- TernaryCoordinateSystem | +- AbstractCurve | | | +- LineSymbolCurve | | | +- AreaCurve | | | `- BarCurve | `- AbstractAxis | +- LinearAxis | +- LogAxis | `- SqrtAxis A sample object (aspect) hierarchy (as displayed by the project explorer) MyProject | `- Worksheet1 | + Title (a TextElement) | `- Plot1 (a CurvePlot) | + Coords1 (a CartesianCoordinateSystem) | | | +- XAxis (a LinearAxis) | | | | | `- Title (a TextElement) | | | +- YAxis (a LogAxis) | | | | | `- Title (a TextElement) | | | `- Curve1 (a LineSymbolCurve) | `- Legend (possibly multiple child elements) \section Features -See this [https://sourceforge.net/tracker2/'limit=10&group_id=199120&atid=968217&status=1&category=1166914 Feature tracker] +See this Feature tracker \section Related Projects A lot of information to related projects is gathered in Wikipedia, so if -somebody needs inspirations' http://en.wikipedia.org/wiki/List_of_graphing_software +somebody needs inspirations' https://en.wikipedia.org/wiki/List_of_graphing_software - LabPlot 1.x - Qtiplot aims to be a free clone of Microcal Origin®. - Grace is a widely used WYSIWYG application for making two-dimensional plots of numerical data. It's based on Motif and somewhat moldy. Relatively active though; improved GUIs based on GTK and Qt are under development. - gnuplot is THE tool for command-line driven interactive data and function plotting. The license is a bit restrictive. - Veusz is designed to produce publication-ready Postscript/PDF output. It is written in Python and actively maintained. - DISLIN is a data display library with an imperative interface. Actively maintained. - kst claims to be the fastest real-time large-dataset viewing and plotting tool. May be at some stage it is worth to look into the code of this project. - ROOT is used a lot by experimentalists in hight energy physics, although several attributes of its design are generally considered less than ideal - matplotlib is an object-oriented plotting framework with a matlab-style interface on top. Written in Python. - Descartes seems to have been maintained only for a few months in 2005, but may provide some inspiration. Being able to superimpose images and plots (with manually tuned parameters) as in the screenshot on the home page would be nice. - KMatplot describes itself as 'gnuplot-like', but is really quite close to what we're trying to do (even with 2D and 3D plots integrated on one worksheet). Last version from 2002, so probably dead. Definitely worth a look, though. - HippoDraw is an 'interactive data analysis environment' built on top of Qt, which appears to have a thought-out architecture (makes use of design patterns). Not very active these days either, last release made early in 2008 (Windows installer only' latest source release older still). - MathGL is a library for scientific graphics in two, three and four dimensions (although MathGL itself doesn't seem to count the codomain; the homepage talks about 1D, 2D and 3D graphics). Written in C++, GPL licensed, actively maintained and with an emphasis on output quality => definitely interesting. Lacks good object-oriented architecture though (huge classes!), so using/extending for our needs could get tricky. - Altaxo is an 'Alternative to plotting programs like MathSoft Axum® or Microcal Origin®' written in C#. Like most other projects in this area, development is slow to stalled (latest release dated February 2007). -- JAS3 'is a general purpose, open-source, data analysis tool' geared towards high-energy physics. Based on [http://aida.freehep.org/ AIDA] conventions. +- JAS3 'is a general purpose, open-source, data analysis tool' geared towards high-energy physics. Based on AIDA conventions. - MCDfit is a Qt/Qwt/Qwtplot3D based application for spectroscopic analyses with emphasis on on-screen display. Seems to have been inactive for more than a year now, CVS is even older. - SciGraphica is 'a scientific application for data analysis and technical graphics' written in C/Gtk. Looks pretty dead (last release in 2005, last post to devel list in 2008 remained unanswered). - GumTree ' An integrated scientific workbench based on Eclipse. */