"Fossies" - the Fresh Open Source Software Archive

Member "veusz-3.1/Documents/manual/html/introduction.html" (26 Oct 2019, 46843 Bytes) of package /linux/privat/veusz-3.1.tar.gz:

The requested HTML page contains a <FORM> tag that is unusable on "Fossies" in "automatic" (rendered) mode so that page is shown as HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4
5 <html xmlns="http://www.w3.org/1999/xhtml">
7     <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
8     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
9     <title>Introduction &#8212; Veusz 3.1 documentation</title>
10     <link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
11     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
12     <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
13     <script type="text/javascript" src="_static/jquery.js"></script>
14     <script type="text/javascript" src="_static/underscore.js"></script>
15     <script type="text/javascript" src="_static/doctools.js"></script>
16     <script type="text/javascript" src="_static/language_data.js"></script>
17     <link rel="index" title="Index" href="genindex.html" />
18     <link rel="search" title="Search" href="search.html" />
20     <link rel="prev" title="Veusz documentation" href="index.html" />
21
22   <link rel="stylesheet" href="_static/custom.css" type="text/css" />
23
24   <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
25
27
28
29     <div class="document">
30       <div class="documentwrapper">
31         <div class="bodywrapper">
32           <div class="body" role="main">
33
34   <div class="section" id="introduction">
36 <div class="section" id="veusz">
38 <p>Veusz is a 2D and 3D scientific plotting package. It is designed to be
39 easy to use, easily extensible, but powerful. The program features a
40 graphical user interface (GUI), which works under Unix/Linux, Windows
41 or Mac OS. It can also be easily scripted (the saved file formats are
42 similar to Python scripts) or used as module inside Python. Veusz
43 reads data from a number of different types of data file, it can be
44 manually entered, or constructed from other datasets.</p>
45 <p>In Veusz the document is built in an object-oriented fashion, where a
46 document is built up by a number of widgets in a hierarchy. For
47 example, multiple function or xy widgets can be placed inside a graph
48 widget, and many graphs can be placed in a grid widget. The program
49 also supports a variety of 3D plots, including 3D point and surface
50 plots. The program produces vector rather than rastered 3D output.</p>
51 <p>Veusz can be extended by the user easily by adding plugins. Support
52 for different data file types can be added with import
53 plugins. Dataset plugins automate the manipulation of datasets. Tools
54 plugins automate the manipulation of the document.</p>
55 </div>
56 <div class="section" id="installation">
59 program. Links to binaries, distribution packages and the source
61 see the package INSTALL.</p>
62 </div>
63 <div class="section" id="getting-started">
65 <p>Veusz includes a built-in tutorial which starts the first time the
66 program is run. You can rerun it later from the Help menu. It also
67 includes many <a class="reference external" href="https://veusz.github.io/examples/">examples</a>, to show how certain kinds of plots are
68 produced. For more help and link to a video tutorial, see <a class="reference external" href="https://veusz.github.io/help-support/">help</a>.</p>
69 </div>
70 <div class="section" id="terminology">
72 <p>Here we define some terminology for future use.</p>
73 <div class="section" id="widget">
75 <p>A document and its graphs are built up from widgets.  These widgets
76 can often by placed within each other, depending on the type of the
77 widget. A widget has children (those widgets placed within it) and its
78 parent. The widgets have a number of different settings which modify
79 their behaviour. These settings are divided into properties, which
80 affect what is plotted and how it is plotted. These would include the
81 dataset being plotted or whether an axis is logarithmic.  There are
82 also formatting settings, including the font to be used and the line
83 thickness. In addition they have actions, which perform some sort of
84 activity on the widget or its children, like “fit” for a fit widget.</p>
85 <p>As an aside, using the scripting interface, widgets are
86 specified with a “path”, like a file in Unix or Windows. These
87 can be relative to the current widget (do not start with a
89 paths include, <cite>/page1/graph1/x</cite>, <cite>x</cite> and <cite>.</cite>.</p>
90 <p>The widget types include</p>
91 <ol class="arabic">
92 <li><p class="first"><strong class="command">document</strong> - representing a complete document. A document
93 can contain pages. In addition it contains a setting giving the
94 page size for the document.</p>
95 </li>
96 <li><p class="first"><strong class="command">page</strong> - representing a page in a document. One or more
97 graphs can be placed on a page, or a grid.</p>
98 </li>
99 <li><p class="first"><strong class="command">graph</strong> - defining an actual graph. A graph can be placed
100 on a page or within a grid. Contained within the graph are its axes
101 and plotters. A graph can be given a background fill and a border
102 if required. It also has a margin, which specifies how far away
103 from the edge of its parent widget to plot the body of the graph.
104 A graph can contain several axes, at any position on the plot. In
105 addition a graph can use axes defined in parent widgets, shared
106 with other graphs.  More than one graph can be placed within in a
107 page. The margins can be adjusted so that they lie within or
108 besides each other.</p>
109 </li>
110 <li><p class="first"><strong class="command">grid</strong> - containing one or more graphs. A grid plots
111 graphs in a gridlike fashion. You can specify the number of rows
112 and columns, and the plots are automatically replotted in the
113 chosen arrangement. A grid can contain graphs or axes. If an axis
114 is placed in a grid, it can be shared by the graphs in the grid.</p>
115 </li>
116 <li><p class="first"><strong class="command">axis</strong> - giving the scale for plotting data. An axis
117 translates the coordinates of the data to the screen. An axis can
118 be linear or logarithmic, it can have fixed endpoints, or can
119 automatically get them from the plotted data. It also has settings
120 for the axis labels and lines, tick labels, and major and minor
121 tick marks.  An axis may be “horizontal” or “vertical” and can
122 appear anywhere on its parent graph or grid.  If an axis appears
123 within a grid, then it can be shared by all the graphs which are
124 contained within the grid.  The <strong class="command">axis-broken</strong> widget is an
125 axis sub-type. It is an axis type where there are jumps in the
126 scale of the axis.  The <strong class="command">axis-function</strong> widget allows the
127 user to create an axis where the values are scaled by a monotonic
128 function, allowing non-linear and non-logarithmic axis scales. The
129 widget can also be linked to a different axis via the function.</p>
130 </li>
131 <li><p class="first">plotters - types of widgets which plot data or add other things on
132 a graph. There is no actual plotter widget which can be added, but
133 several types of plotters listed below. Plotters typically take an
134 axis as a setting, which is the axis used to plot the data on the
135 graph (default x and y).</p>
136 <ol class="arabic simple">
137 <li><strong class="command">function</strong> - a plotter which plots a function on the
138 graph. Functions can be functions of x or y (parametric
139 functions are not done yet!), and are defined in Python
140 expression syntax, which is very close to most other
141 languages. For example <cite>3*x**2 + 2*x - 4</cite>. A number of functions
142 are available (e.g. sin, cos, tan, exp, log…). Technically,
143 Veusz imports the numpy package when evaluating, so numpy
144 functions are available.  As well as the function setting, also
145 settable is the line type to plot the function, and the number
146 of steps to evaluate the function when plotting. Filling is
147 supported above/below/left/right of the function.</li>
148 <li><strong class="command">xy</strong> - a plotter which plots scatter, line, or stepped
149 plots. This versatile plotter takes an x and y dataset, and
150 plots (optional) points, in a chosen marker and colour,
151 connecting them with (optional) lines, and plotting (optional)
152 error bars. An xy plotter can also plot a stepped line, allowing
153 histograms to be plotted (note that it doesn’t yet do the
154 binning of the data).  The settings for the xy widget are the
155 various attributes for the points, line and error bars, the
156 datasets to plot, and the axes to plot on.  The xy plotter can
157 plot a label next to each dataset, which is either the same for
158 each point or taken from a text dataset.  If you wish to leave
159 gaps in a plot, the input value <cite>nan</cite> can be specified in the
160 numeric dataset.</li>
161 <li><strong class="command">fit</strong> - fit a function to data. This plotter is a like
162 the function plotter, but allows fitting of the function to
163 data. This is achieved by clicking on a “fit” button, or using
164 the “fit” action of the widget. The fitter takes a function to
165 fit containing the unknowns, e.g. <cite>a*x**2 + b*x + c</cite>, and
166 initial values for the variables (here a, b and c). It then fits
167 the data (note that at the moment, the fit plotter fits all the
168 data, not just the data that can be seen on the graph) by
169 minimising the chi-squared.  In order to fit properly, the y
170 data (or x, if fitting as a function of x) must have a properly
171 defined, preferably symmetric error. If there is none, Veusz
172 assumes the same fractional error everywhere, or symmetrises
173 asymmetric errors.  Note that more work is required in this
174 widget, as if a parameter is not well defined by the data, the
175 matrix inversion in the fit will fail. In addition Veusz does
176 not supply estimates for the errors or the final chi-squared in
177 a machine readable way.  If the fitting parameters vary
178 significantly from 1, then it is worth “normalizing” them by
179 adding in a factor in the fit equation to bring them to of the
180 order of 1.</li>
181 <li><strong class="command">bar</strong> - a bar chart which plots sets of data as
182 horizontal or vertical bars. Multiple datasets are supported. In
183 “grouped” mode the bars are placed side-by-side for each
184 dataset. In “stacked” mode the bars are placed on top of each
185 other (in the appropriate direction according to the sign of the
186 dataset). Bars are placed on coordinates given, or in integer
187 values from 1 upward if none are given. Error bars are plotted
188 for each of the datasets.  Different fill styles can be given
189 for each dataset given. A separate key value can be given for
190 each dataset.</li>
191 <li><strong class="command">key</strong> - a box which describes the data plotted. If a
192 key is added to a plot, the key looks for “key” settings of the
193 other data plotted within a graph. If there any it builds up a
194 box containing the symbol and line for the plotter, and the text
195 in the “key” setting of the widget. This allows a key to be very
196 easily added to a plot.  The key may be placed in any of the
197 corners of the plot, in the centre, or manually
198 placed. Depending on the ordering of the widgets, the key will
199 be placed behind or on top of the widget. The key can be filled
200 and surrounded by a box, or not filled or surrounded.</li>
201 <li><strong class="command">label</strong> - a text label places on a graph. The alignment
202 can be adjusted and the font changed. The position of the label
203 can be specified in fractional terms of the current graph, or
204 using axis coordinates.</li>
205 <li><strong class="command">rect, ellipse</strong> - these draw a rectangle or ellipse,
206 respectively, of size and rotation given. These widgets can be
207 placed directly on the page or on a graph. The centre can be
208 given in axis coordinates or fractional coordinates.</li>
209 <li><strong class="command">imagefile</strong> - draw an external graphs file on the graph
210 or page, with size and rotation given. The centre can be given
211 in axis coordinates or fractional coordinates.</li>
212 <li><strong class="command">line</strong> - draw a line with optional arrowheads on the
213 graph or page. One end can be given in axis coordinates or
214 fractional coordinates.</li>
215 <li><strong class="command">contour</strong> - plot contours of a 2D dataset on the
216 graph. Contours are automatically calculated between the minimum
217 and maximum values of the graph or chosen manually. The line
218 style of the contours can be chosen individually and the region
219 between contours can be filled with shading or color.  2D
220 datasets currently consist of a regular grid of values between
221 minimum and maximum positions in x and y. They can be
222 constructed from three 1D datasets of x, y and z if they form a
223 regular x, y grid.</li>
224 <li><strong class="command">image</strong> - plot a 2D dataset as a colored
225 image. Different color schemes can be chosen. The scaling
226 between the values and the image can be specified as linear,
227 logarithmic, square-root or square.</li>
228 <li><strong class="command">polygon</strong> - plot x and y points from datasets as a
229 polygon. The polygon can be placed directly on the page or
230 within a graph. Coordinates are either plotted using the axis or
231 as fractions of the width and height of the containing widget.</li>
232 <li><strong class="command">boxplot</strong> - plot distribution of points in a dataset.</li>
233 <li><strong class="command">polar</strong> - plot polar data or functions. This is a
234 non-orthogonal plot and is placed directly on the page rather
235 than in a graph.</li>
236 <li><strong class="command">ternary</strong> - plot data of three variables which add up
237 to 100 per cent.This is a non-orthogonal plot and is placed
238 directly on the page rather than in a graph.</li>
239 </ol>
240 </li>
241 <li><p class="first">3D widgets - 3D graphs can be created by adding a 3D scene widget
242 (<strong class="command">scene3d</strong>) to a blank page, or by creating a new 3D
243 document. The 3D scene has settings which control the angle the
244 rotation angle of the plot, the position and color of lighting and
245 the rendering method.</p>
246 <p>To build up a 3D plot the following widgets can be placed inside
247 it:</p>
248 <ol class="arabic simple">
249 <li><strong class="command">graph3d</strong> - this is an analogous widget to the 2D graph
250 widget, plotting a 3D plot with cartesian axes. It contains
251 three or more axis3d widgets, and plotting widgets. The graph
252 contains settings for the graph size (the default is 1 in each
253 direction) and the 3D position of the graph in the same
254 units. Multiple graph widgets can be added to a scene, though
255 the position and sizes may need to be adjusted.</li>
256 <li><strong class="command">axis3d</strong> - normally a 3D graph has three axes (X, Y and
257 Z), but more axes can be added to plot multiple things on a single
258 axis direction. This works in a similar way to the 2D axis
259 widget. The widget has options for the axis label, tick labels,
260 tick marks and grid lines (which appear on the outside of the 3D
261 cube). An axis can be swiched between linear and logorithmic
262 mode. Scalings can be applied to the data values plotted in that
263 dimension or to the axis labels.</li>
264 <li><strong class="command">point3d</strong> - for plotting points, and optionally
265 connecting lines, in 3D. This, and the other plotting widgets
266 are placed in a graph3d widget. The user provides three 1D
267 datasets for the x, y and z values. The markers can be scaled in
268 size by another optional dataset. The markers can also be
269 colored according to another optional dataset, according to a
270 color map, minimum and maximum. Error bars can be provided for
271 each of the x, y and z datasets. The connecting line can also be
272 colored if a color dataset is provided and a colormap chosen.</li>
273 <li><strong class="command">function3d</strong> - for plotting either a functional line in
274 3D space or a functional surface. The type of plot is given by
275 the mode parameter. In the case of the line, the x,y,z
276 coordinates can be specified as a function of t, where t goes
277 from 0 to 1, or by giving functions for two of the coordinates
278 as a function of the other. For a surface, the value for x, y or
279 z is given as a function of the other two. In addition, a
280 function returning 0 to 1 can be provided for the color, which
281 specifies the color map value for the surface at each position
282 or the line color. For a 2D surface, the grid lines or surface
283 fill can be hidden or shown. There are also settings giving the
284 number of function evaluations to compute in each direction for
285 a surface, or in one direction for a line.</li>
286 <li><strong class="command">surface3d</strong> - for plotting a two dimensional surface
287 from data values. The user should provide a 2D dataset for the
288 height of a surface. The x, y or z axis for the height and other
289 directions can be chosen. A second 2D dataset can be provided
290 for the color of the surface at each point. Note that the
291 coordinate of the 2D dataset lies at the center of each 2D grid
292 point. The height of the grid at the edge is calculated by
293 linear interpolation. Normally the grid is surrounded by four
294 lines and the surface by two triangles. If a high resolution
295 option is enabled, the each grid point is surrounded by eight
296 lines and the surface drawn by eight triangles.</li>
297 <li><strong class="command">volume3d</strong> - for plotting 3D volumes. In this widget,
298 for a volume described by A×B×C values, then the user should
299 provide four datasets, each containing up to A×B×C values (there
300 can be holes in the representation). Three of the datasets give
301 coordinates of the centers of the 3D cells and the fourth the
302 color of the cell. An example set of datasets would be
303 X=(0,0,0,0,1,1,1,1), Y=(0,0,1,1,0,0,1,1), Z=(0,1,0,1,0,1,0,1),
305 can provide a transparency dataset, which can be useful for
306 showing or hiding parts of the 3D space.</li>
307 </ol>
308 </li>
309 </ol>
310 </div>
311 <div class="section" id="settings-properties-and-formatting">
313 <p>The various settings of the widgets come in a number of types,
314 including integers (e.g. 10), floats (e.g. 3.14), dataset names
315 (<cite>mydata</cite>), expressions (<cite>x+y</cite>), text (<cite>hi there!</cite>), distances (see
316 above), options (<cite>horizontal</cite> or <cite>vertical</cite> for axes).</p>
317 <p>Veusz performs type checks on these parameters. If they
318 are in the wrong format the control to edit the setting will
319 turn red. In the command line, a TypeError exception is
320 thrown.</p>
321 <p>In the GUI, the current page is replotted if a setting
322 is changed when enter is pressed or the user moves to another
323 setting.</p>
324 <p>The settings are split up into formatting settings,
325 controlling the appearance of the plot, or properties,
326 controlling what is plotted and how it is plotted.</p>
327 <p>Default settings, including the default font and line
328 style, and the default settings for any graph widget, can be
329 modified in the “Default styles” dialog box under the “Edit”
330 menu. Default settings are set on a per-document basis, but
331 can be saved into a separate file and loaded. A default
332 default settings file can be given to use for new documents
333 (set in the preferences dialog).</p>
334 </div>
335 <div class="section" id="datasets">
337 <p>Data are imported into Veusz as a dataset. A dataset is
338 imported from a file, entered manually, set via the command
339 line, or linked to other datasets via an expression or
340 dataset plugin. Each dataset has a unique name in the
341 document. They can be seen in the dataset browser panel, or
342 in the Data, Edit dialog box.  To choose the data to be
343 plotted, the user usually selects the dataset in the
344 appropriate setting of a widget.</p>
345 <p>Veusz supports one-dimensional (1D) datasets, which are a
346 list of values with optional error bars. Error bars can
347 either be symmetric or asymmetric. Veusz also supports
348 two-dimensional (2D) data. A 2D dataset is a grid of values,
349 with either a fixed spacing in coordinates, or with
350 arbitrary pixel sizes. An n-dimensional (nD) dataset is an
351 arbitrary matrix of values. These cannot be plotted
352 directly, but subsets can be plotted using python slice
353 syntax to convert to 1D or 2D datasets.</p>
354 <p>In addition to simple numeric datasets, Veusz also supports
355 date-time datasets. For details see the sections on reading
356 data. Also supported are text datasets, which are lists of
357 text strings.</p>
358 <p>Datasets can either be plain lists of values which are
359 stored within the document, or they can be linked to a file,
360 so that the values update if the file is reloaded, or they
361 can be linked to other datasets via expressions or dataset
362 plugins.</p>
363 </div>
364 <div class="section" id="text">
366 <p>Veusz understands a limited set of LaTeX-like formatting
367 for text. There are some differences (for example, <cite>10^23</cite>
368 puts the 2 and 3 into superscript), but it is fairly
369 similar. You should also leave out the dollar signs. Veusz
370 supports superscripts (<cite>^</cite>), subscripts (<cite>_</cite>), brackets for
371 grouping attributes are <cite>{</cite> and <cite>}</cite>.</p>
372 <p>Supported LaTeX symbols include: \AA, \Alpha, \Beta,
373 \Chi, \Delta, \Epsilon, \Eta, \Gamma, \Iota, \Kappa, \Lambda, \Mu,
374 \Nu, \Omega, \Omicron, \Phi, \Pi, \Psi, \Rho, \Sigma, \Tau, \Theta,
375 \Upsilon, \Xi, \Zeta, \alpha, \approx, \ast, \asymp, \beta, \bowtie,
376 \bullet, \cap, \chi, \circ, \cup, \dagger, \dashv, \ddagger, \deg,
377 \delta, \diamond, \divide, \doteq, \downarrow, \epsilon, \equiv,
378 \eta, \gamma, \ge, \gg, \hat, \in, \infty, \int, \iota, \kappa, \lambda,
379 \le, \leftarrow, \lhd, \ll, \models, \mp, \mu, \neq, \ni, \nu, \odot,
380 \omega, \omicron, \ominus, \oplus, \oslash, \otimes, \parallel,
381 \perp, \phi, \pi, \pm, \prec, \preceq, \propto, \psi, \rhd, \rho,
382 \rightarrow, \sigma, \sim, \simeq, \sqrt, \sqsubset, \sqsubseteq,
383 \sqsupset, \sqsupseteq, \star, \stigma, \subset, \subseteq, \succ,
384 \succeq, \supset, \supseteq, \tau, \theta, \times, \umid, \unlhd,
385 \unrhd, \uparrow, \uplus, \upsilon, \vdash, \vee, \wedge, \xi, \zeta.
387 in the unicode character set). Special symbols can be included
388 directly from a character map.</p>
389 <p>Other LaTeX commands are supported. <cite>\</cite> breaks a
390 line. This can be used for simple tables. For example <cite>{a\b}
391 {c\d}</cite> shows <cite>a c</cite> over <cite>b d</cite>. The command <cite>\frac{a}{b}</cite>
392 shows a vertical fraction a/b.</p>
393 <p>Also supported are commands to change font. The command
394 <cite>\font{name}{text}</cite> changes the font text is written in to
395 name. This may be useful if a symbol is missing from the
396 current font, e.g. <cite>\font{symbol}{g}</cite> should produce a
397 gamma. You can increase, decrease, or set the size of the font
398 with <cite>\size{+2}{text}</cite>, <cite>\size{-2}{text}</cite>, or
399 <cite>\size{20}{text}</cite>. Numbers are in points.</p>
400 <p>Various font attributes can be changed: for example,
401 <cite>\italic{some italic text}</cite> (or use <cite>\textit</cite> or <cite>\emph</cite>),
402 <cite>\bold{some bold text}</cite> (or use <cite>\textbf</cite>) and <cite>\underline{some
403 underlined text}</cite>.</p>
404 <p>Example text could include <cite>Area / \pi (10^{-23}
405 cm^{-2})</cite>, or <cite>\pi\bold{g}</cite>.</p>
406 <p>Veusz plots these symbols with Qt’s unicode support. You
407 can also include special characters directly, by copying and
408 pasting from a character map application. If your current font
409 does not contain these symbols then you may get a box
410 character.</p>
411 <p>Veusz also supports the evaluation of a Python
412 expression when text is written to the page. Python code is
413 written inside the brackets <strong class="command">%{{ }}%</strong>. Note
414 that the Python evaluation happens before the LaTeX expansion
415 is done. The return value of the expression is converted to
416 text using the Python <strong class="command">str()</strong> function. For
417 example, the expression <strong class="command">%{{2+2}}%</strong> would
418 write <strong class="command">4</strong>. Custom functions and constants are
419 supported when evaluation, in addition to the usual numpy
420 functions. In addition, Veusz defines the following useful
421 functions and values.</p>
422 <ol class="arabic simple">
423 <li><strong class="command">ENVIRON</strong> is the
424 <strong class="command">os.environ</strong> dict of environment
425 variables. <strong class="command">%{{ENVIRON['USER']}}%</strong>
426 would show the current user in unix.</li>
427 <li><strong class="command">DATE([fmt])</strong> returns the current
428 date, by default in ISO format. fmt is an optional
429 format specifier using
430 <strong class="command">datetime.date.strftime</strong> format
431 specifiers.</li>
432 <li><strong class="command">TIME([fmt])</strong> returns the current
433 date/time, by default in ISO format. fmt is an optional
434 format specifier using
435 <strong class="command">datetime.datetime.strftime</strong> format
436 specifiers.</li>
437 <li><strong class="command">DATA(name[, part])</strong> returns the Veusz
438 dataset with given name. For numeric datasets this is a
439 numpy array. For numeric datasets with errors, part
440 specifies the dataset part to return, i.e. ‘data’,
441 ‘serr’, ‘perr’, ‘nerr’. For example, the mean value of
442 a dataset could be shown using
443 <strong class="command">%{{mean(DATA('x'))}}%</strong>.</li>
444 <li><strong class="command">FILENAME()</strong> - returns the current
445 document filename. This can include the
446 directory/folder of the file. Note that the filename is
447 escaped with ESCAPE() so that LaTeX symbols are not
448 expanded when shown.</li>
449 <li><strong class="command">BASENAME()</strong> - returns the current
450 document filename, removing the directory or folder
451 name Note that the filename is escaped with ESCAPE() so
452 that LaTeX symbols are not expanded when shown.</li>
453 <li><strong class="command">ESCAPE(x)</strong> - escapes any LaTeX
454 symbols in x so that they are not interpreted as
455 LaTeX.</li>
456 <li><strong class="command">SETTING(path)</strong> - return the value of
457 the Veusz setting given by the full path,
458 e.g. <strong class="command">%{{SETTING('/page1/width')}}%</strong>.</li>
459 <li><strong class="command">LANG(mapping)</strong> - mapping is a dictionary which maps
460 language names to strings. This returns the string corresponding to
461 the current language. The keys come from the locale names which are
462 the two-letter language codes (e.g. <cite>en</cite> or <cite>fr</cite>), or the full code
463 (e.g. <cite>en_GB</cite> or <cite>de_AT</cite>). The <cite>default</cite> key is used if the
465 LANG({'de':'Druck','default':'Pressure'}) }}%</strong>.</li>
466 </ol>
467 </div>
468 <div class="section" id="measurements">
470 <p>Distances, widths and lengths in Veusz can be specified in a number of
471 different ways. These include absolute distances specified in physical
472 units, e.g. 1cm, 0.05m, 10mm, 5in and 10pt, and relative units, which
473 are relative to the largest dimension of the page, including 5%, 1/20,
474 0.05.</p>
475 </div>
476 <div class="section" id="color-theme">
478 <p>From version 1.26, widgets are colored automatically using the color
479 theme. This theme is specified in the main document widget
480 settings. Widgets are given the colors in order given the order in a
481 graph widget. The default theme can be specified in the preferences
482 dialog box.</p>
483 <p>To override a theme, the user can manually specify the individual
484 colors in the custom definitions dialog box. Color <cite>theme1</cite> is used as
485 the first theme color, then <cite>theme2</cite>, etc.</p>
486 </div>
487 <div class="section" id="axis-numeric-scales">
489 <p>The way in which numbers are formatted in axis scales is chosen
490 automatically. For standard numerical axes, values are shown with the
491 <cite>%Vg</cite> formatting (see below). For date axes, an appropriate date
492 formatting is used so that the interval shown is correct. A format can
493 be given for an axis in the axis number formatting panel can be given
494 to explicitly choose a format. Some examples are given in the drop
495 down axis menu. Hold the mouse over the example for detail.</p>
496 <p>C-style number formatting is used with a few Veusz specific
497 extensions. Text can be mixed with format specifiers, which start with
498 a <cite>%</cite> sign. Examples of C-style formatting include: <cite>%.2f</cite> (decimal
499 number with two decimal places, e.g. 2.01), <cite>%.3e</cite> (scientific
500 formatting with three decimal places, e.g. 2.123e-02), <cite>%g</cite> (general
501 formatting, switching between <cite>%f</cite> and <cite>%e</cite> as appropriate). See
502 <a class="reference external" href="http://opengroup.org/onlinepubs/007908799/xsh/fprintf.html">http://opengroup.org/onlinepubs/007908799/xsh/fprintf.html</a> for
503 details.</p>
504 <p>Veusz extensions include <cite>%Ve</cite>, which is like <cite>%e</cite> except it displays
505 scientific notation as written, e.g. 1.2x10^23, rather than
506 1.2e+23. <cite>%Vg</cite> switches between standard numbers and Veusz scientific
507 notation for large and small numbers. <cite>%VE</cite> using engineering SI
508 suffixes to represent large or small numbers (e.g. 1000 is 1k).</p>
509 <p>Veusz allows dates and times to be formatted using <cite>%VDX</cite> where <cite>X</cite> is
510 one of the formatting characters for strftime (see
511 <a class="reference external" href="http://opengroup.org/onlinepubs/007908799/xsh/strftime.html">http://opengroup.org/onlinepubs/007908799/xsh/strftime.html</a> for
512 details). These include <cite>a</cite> for an abbreviated weekday name, <cite>A</cite> for
513 full weekday name, <cite>b</cite> for abbreviated month name, <cite>B</cite> for full month
514 name, <cite>c</cite> date and time representation, <cite>d</cite> day of month 01..31, <cite>H</cite>
515 hour as 00..23, <cite>I</cite> hour as 01..12, <cite>j</cite> as day of year 001..366, <cite>m</cite>
516 as month 01..12, <cite>M</cite> minute as 00..59, <cite>p</cite> AM/PM, <cite>S</cite> second 00..61,
517 <cite>U</cite> week number of year 00..53 (Sunday as first day of week), <cite>w</cite>
518 weekday as decimal number 0..6, <cite>W</cite> week number of year (Monday as
519 first day of week), <cite>x</cite> date representation, <cite>X</cite> time representation,
520 <cite>y</cite> year without century 00..99 and <cite>Y</cite> year. <cite>%VDVS</cite> is a special
521 Veusz addon format which shows seconds and fractions of seconds
522 (e.g. 12.2).</p>
523 </div>
524 <div class="section" id="three-dimensional-3d-plots">
526 <p>When drawing in three dimensions, Veusz builds up a 3D “scene” for the
527 graph from the various plotting widgets, made up of triangles, line
528 segments, points and text. Veusz does not use a standard (e.g. OpenGL)
529 drawing method, but renders the scene itself. The advantage of this is
530 that it can produce vector rather than bitmap or raster
531 output. OpenGL, for example, is based around bitmaps.</p>
532 <p>Veusz applies lighting to the scene. The lighting depends on enabled
533 light sources, which are set in the scene3d widget. Light sources have
534 a color, intensity and position. Note that only the angle of the light
535 to a surface affects its lighting, not its distance. The position of
536 the light is relative to the viewer (camera), not the graph. Positive
537 light coordinates are towards the graph (z), upwards (y) and
538 rightwards (x). Normally each solid surface has an intrinsic color,
539 which can be seen without any lighting. If a light source is enabled,
540 the color of the light is added to the surface color, depending on the
541 reflectivity of the surface. Each surface also has a transparency
542 setting.</p>
543 <p>By default, Veusz uses a naive Painter’s Algorithm to draw the
544 scene. It draws from the back of scene to the front. The main problem
545 with this algorithm is that shapes and lines overlapping in depth can
546 be confused as the depth of each object is calculated at only one
547 point. In addition objects may intersect, which is not properly
548 treated. In the scene3d object, the user can switch to a different
549 rendering mode called BSP. In this accurate BSP mode, the objects are
550 split so that they never overlap from any viewing angle. The
551 disadvantage of this mode is that it is slow, uses a lot of memory and
552 produces large output files. We plan in future to add another mode
553 which handles overlaps better and does not unnecessarily split
554 objects.</p>
555 <p>The plot is affected by the viewing angle, which is specified in the
556 scene3d widget settings. The rotation is given be three rotations
557 around lines in X, Y and Z directions (note that these are not the
558 same directions as the X, Y and Z axes!). The X axis runs horizontally
559 on the screen, the Y axis runs vertically, and the Z axis runs along
560 the line of sight.</p>
561 <p>There is also a distance setting, which moves graphs closer to or away
562 from the viewer. At larger distances the effect of perspective
563 reduces, meaning that parts of the plot closer to the viewer are not
564 larger than if they were at the farthest side. At large distances, a
565 plot tends towards being isometric. At small distances, shapes are
566 more distorted (note by default the size of the graph is 1 in these
567 distance units). It is currently possible to place graphs inside the
568 camera leading to strange output.</p>
569 <p>By default, Veusz enlarges the 3D rendered scene to fill the bounds of
570 the 3D scene widget, so distance has no effect on the size of the
571 plot. This scaling can be switched off by modifying the Size setting
572 from “Auto” to a fixed number. A fixed size is useful if the user
573 wants a graph to be the same size for any rotation. With this setting
574 the size of the plot is affected by their distance.</p>
575 <p>By default, a 3D graph has dimensions of 1 along the X, Y and Z
576 axes. The size can be adjusted using the size settings in the graph3d
577 widget. Care should be taken that the graph size does not lead to
578 points being at negative viewing distances. The default position of
579 the plot is at the origin 0,0,0. If the user wants to plot multiple
580 graph3d widgets, the positions should be adjusted to prevent overlap.</p>
581 <p>Normally in Veusz, sizes of objects (e.g. plot markers) are given in
582 physical units. This makes less sense for a 3D plot as sizes can
583 depend on distance. In a 3D graph sizes of plotting markers and line
584 widths are given in 1/1000 of the graph bounding box maximum
585 dimension.</p>
586 </div>
587 </div>
588 <div class="section" id="the-main-window">
590 <p>You should see the main window when you run Veusz (you can just type
591 the veusz command in Unix).</p>
592 <img alt="_images/mainwindow.png" src="_images/mainwindow.png" />
593 <p>The Veusz window is split into several sections. At the top is the
594 menu bar and tool bar. These work in the usual way to other
595 applications. Sometimes options are disabled (greyed out) if they do
596 not make sense to be used. If you hold your mouse over a button for a
597 few seconds, you will usually get an explanation for what it does
598 called a “tool tip”.</p>
599 <p>Below the main toolbar is a second toolbar for constructing the graph
600 by adding widgets (on the left), and some editing buttons. The add
601 widget buttons add the request widget to the currently selected widget
602 in the selection window. The widgets are arranged in a tree-like
603 structure.</p>
604 <p>Below these toolbars and to the right is the plot window. This is
605 where the current page of the current document is shown. You can
606 adjust the size of the plot on the screen (the zoom factor) using the
607 “View” menu or the zoom tool bar button (the magnifying
608 glass). Initially you will not see a plot in the plot window, but you
609 will see the Veusz logo. At the moment you cannot do much else with
610 the window. In the future you will be able to click on items in the
611 plot to modify them.</p>
612 <p>To the left of the plot window is the selection window, and the
613 properties and formatting windows. The properties window lets you edit
614 various aspects of the selected widget (such as the minimum and
615 maximum values on an axis). Changing these values should update the
616 plot. The formatting lets you modify the appearance of the selected
617 widget. There are a series of tabs for choosing what aspect to modify.</p>
618 <p>The various windows can be “dragged” from the main window to “float”
619 by themselves on the screen.</p>
620 <p>To the bottom of the window is the console. This window is not shown
621 by default, but can be enabled in the View menu. The console is a
622 Veusz and Python command line console. To read about the commands
623 available see <a class="reference internal" href="api.html#commands"><span class="std std-ref">Commands</span></a>. As this is a Python console,
624 you can enter mathematical expressions (e.g. <cite>1+2.0*cos(pi/4)</cite>) here
625 and they will be evaluated when you press Enter. The usual special
626 functions and the operators are supported. You can also assign results
627 to variables (e.g. <cite>a=1+2</cite>) for use later. The console also supports
628 command history like many Unix shells. Press the up and down cursor
629 keys to browse through the history. Command line completion is not
630 available yet!</p>
631 <p>There also exists a dataset browsing window, by default to the right
632 of the screen. This window allows you to view the datasets currently
633 loaded, their dimensions and type. Hovering a mouse over the size of
634 the dataset will give you a preview of the data.</p>
635 </div>
636 <div class="section" id="my-first-plot">
638 <p>After opening Veusz, on the left of the main window, you will see a
639 Document, containing a Page, which contains a Graph with its axes. The
640 Graph is selected in the selection window. The toolbar above adds a
641 new widget to the selected widget. If a widget cannot be added to a
642 selected widget it is disabled. On opening a new document Veusz
643 automatically adds a new Page and Graph (with axes) to the document.</p>
644 <p>You will see something like this:</p>
645 <img alt="_images/winwithgraph.png" src="_images/winwithgraph.png" />
646 <p>Select the x axis which has been added to the document (click on <cite>x</cite>
647 in the selection window). In the properties window you will see a
648 variety of different properties you can modify. For instance you can
649 enter a label for the axis by writing <cite>Area (cm^{2})</cite> in the box next
650 to label and pressing enter. Veusz supports text in LaTeX-like form
651 (without the dollar signs). Other important parameters is the <cite>log</cite>
652 switch which switches between linear and logarithmic axes, and <cite>min</cite>
653 and <cite>max</cite> which allow the user to specify the minimum and maximum
654 values on the axes.</p>
655 <p>The formatting dialog lets you edit various aspects of the graph
656 appearance. For instance the “Line” tab allows you to edit the line of
657 the axis. Click on “Line”, then you can then modify its colour. Enter
658 “green” instead of “black” and press enter. Try making the axis label
659 bold.</p>
660 <p>Now you can try plotting a function on the graph. If the graph, or its
661 children are selected, you will then be able to click the “function”
662 button at the top (a red curve on a graph). You will see a straight
663 line (y=x) added to the plot. If you select “function1”, you will be
664 able to edit the functional form plotted and the style of its
665 line. Change the function to <cite>x**2</cite> (x-squared).</p>
666 <p>We will now try plotting data on the graph. Go to your
667 favourite text editor and save the following data as
668 test.dat:</p>
669 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">1</span>     <span class="mf">0.1</span>   <span class="o">-</span><span class="mf">0.12</span>   <span class="mf">1.1</span>    <span class="mf">0.1</span>
670 <span class="mf">2.05</span>  <span class="mf">0.12</span>  <span class="o">-</span><span class="mf">0.14</span>   <span class="mf">4.08</span>   <span class="mf">0.12</span>
671 <span class="mf">2.98</span>  <span class="mf">0.08</span>  <span class="o">-</span><span class="mf">0.1</span>    <span class="mf">2.9</span>    <span class="mf">0.11</span>
672 <span class="mf">4.02</span>  <span class="mf">0.04</span>  <span class="o">-</span><span class="mf">0.1</span>    <span class="mf">15.3</span>   <span class="mf">1.0</span>
673 </pre></div>
674 </div>
675 <p>The first three columns are the x data to plot plus its asymmetric
676 errors. The final two columns are the y data plus its symmetric
677 errors. In Veusz, go to the “Data” menu and select “Import”. Type the
678 filename into the filename box, or use the “Browse…” button to
679 search for the file. You will see a preview of the data pop up in the
680 box below. Enter <cite>x,+,- y,+-</cite> into the descriptors edit box (note that
681 commas and spaces in the descriptor are almost interchangeable in
682 Veusz 1.6 or newer). This describes the format of the data which
683 describes dataset “x” plus its asymmetric errors, and “y” with its
684 symmetric errors. If you now click “Import”, you will see it has
685 imported datasets <cite>x</cite> and <cite>y</cite>.</p>
686 <p>To plot the data you should now click on <cite>graph1</cite> in the tree
687 window. You are now able to click on the “xy” button (which looks like
688 points plotted on a graph). You will see your data plotted on the
689 graph. Veusz plots datasets <cite>x</cite> and <cite>y</cite> by default, but you can change
690 these in the properties of the “xy” plotter.</p>
691 <p>You are able to choose from a variety of markers to plot. You can
692 remove the plot line by choosing the “Plot Line” subsetting, and
693 clicking on the “hide” option. You can change the colour of the marker
694 by going to the “Marker Fill” subsetting, and entering a new colour
695 (e.g. red), into the colour property.</p>
696 </div>
697 </div>
698
699
700           </div>
701         </div>
702       </div>
704         <div class="sphinxsidebarwrapper">
705 <h1 class="logo"><a href="index.html">Veusz</a></h1>
706
707
708
709
710
711
712
713
715 <ul class="current">
716 <li class="toctree-l1 current"><a class="current reference internal" href="#">Introduction</a><ul>
717 <li class="toctree-l2"><a class="reference internal" href="#veusz">Veusz</a></li>
718 <li class="toctree-l2"><a class="reference internal" href="#installation">Installation</a></li>
719 <li class="toctree-l2"><a class="reference internal" href="#getting-started">Getting started</a></li>
720 <li class="toctree-l2"><a class="reference internal" href="#terminology">Terminology</a><ul>
721 <li class="toctree-l3"><a class="reference internal" href="#widget">Widget</a></li>
722 <li class="toctree-l3"><a class="reference internal" href="#settings-properties-and-formatting">Settings: properties and formatting</a></li>
723 <li class="toctree-l3"><a class="reference internal" href="#datasets">Datasets</a></li>
724 <li class="toctree-l3"><a class="reference internal" href="#text">Text</a></li>
725 <li class="toctree-l3"><a class="reference internal" href="#measurements">Measurements</a></li>
726 <li class="toctree-l3"><a class="reference internal" href="#color-theme">Color theme</a></li>
727 <li class="toctree-l3"><a class="reference internal" href="#axis-numeric-scales">Axis numeric scales</a></li>
728 <li class="toctree-l3"><a class="reference internal" href="#three-dimensional-3d-plots">Three dimensional (3D) plots</a></li>
729 </ul>
730 </li>
731 <li class="toctree-l2"><a class="reference internal" href="#the-main-window">The main window</a></li>
732 <li class="toctree-l2"><a class="reference internal" href="#my-first-plot">My first plot</a></li>
733 </ul>
734 </li>
735 <li class="toctree-l1"><a class="reference internal" href="datasets.html">Reading data</a></li>
736 <li class="toctree-l1"><a class="reference internal" href="datasets.html#manipulating-datasets">Manipulating datasets</a></li>
737 <li class="toctree-l1"><a class="reference internal" href="datasets.html#capturing-data">Capturing data</a></li>
738 <li class="toctree-l1"><a class="reference internal" href="api.html">Veusz command line and embedding interface (API)</a></li>
739 </ul>
740
741 <div class="relations">
742 <h3>Related Topics</h3>
743 <ul>
744   <li><a href="index.html">Documentation overview</a><ul>
745       <li>Previous: <a href="index.html" title="previous chapter">Veusz documentation</a></li>
746       <li>Next: <a href="datasets.html" title="next chapter">Reading data</a></li>
747   </ul></li>
748 </ul>
749 </div>
750 <div id="searchbox" style="display: none" role="search">
751   <h3>Quick search</h3>
752     <div class="searchformwrapper">
753     <form class="search" action="search.html" method="get">
754       <input type="text" name="q" />
755       <input type="submit" value="Go" />
756       <input type="hidden" name="check_keywords" value="yes" />
757       <input type="hidden" name="area" value="default" />
758     </form>
759     </div>
760 </div>
761 <script type="text/javascript">\$('#searchbox').show(0);</script>
762         </div>
763       </div>
764       <div class="clearer"></div>
765     </div>
766     <div class="footer">
767       &copy;2003-2019, Jeremy Sanders.
768
769       |
771       &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
772
773       |
774       <a href="_sources/introduction.rst.txt"
775           rel="nofollow">Page source</a>
776     </div>
777
778
779
780
781   </body>
782 </html>