File: introduction.html

package info (click to toggle)
veusz 3.6.2-1.1
links: PTS, VCS
area: main
in suites: trixie
size: 13,820 kB
sloc: python: 41,892; cpp: 11,272; javascript: 9,202; ansic: 1,256; makefile: 247; xml: 79
file content (789 lines) | stat: -rw-r--r-- 46,825 bytes
parent folder | download | duplicates (2)

<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />

    <title>Introduction &#8212; Veusz 3.6.2 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/doctools.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Reading data" href="datasets.html" />
    <link rel="prev" title="Veusz documentation" href="index.html" />
   
  <link rel="stylesheet" href="_static/custom.css" type="text/css" />
  
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />

  </head><body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          

          <div class="body" role="main">
            
  <section id="introduction">
<h1>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h1>
<section id="veusz">
<h2>Veusz<a class="headerlink" href="#veusz" title="Permalink to this headline">¶</a></h2>
<p>Veusz is a 2D and 3D scientific plotting package. It is designed to be
easy to use, easily extensible, but powerful. The program features a
graphical user interface (GUI), which works under Unix/Linux, Windows
or Mac OS. It can also be easily scripted (the saved file formats are
similar to Python scripts) or used as module inside Python. Veusz
reads data from a number of different types of data file, it can be
manually entered, or constructed from other datasets.</p>
<p>In Veusz the document is built in an object-oriented fashion, where a
document is built up by a number of widgets in a hierarchy. For
example, multiple function or xy widgets can be placed inside a graph
widget, and many graphs can be placed in a grid widget. The program
also supports a variety of 3D plots, including 3D point and surface
plots. The program produces vector rather than rastered 3D output.</p>
<p>Veusz can be extended by the user easily by adding plugins. Support
for different data file types can be added with import
plugins. Dataset plugins automate the manipulation of datasets. Tools
plugins automate the manipulation of the document.</p>
</section>
<section id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2>
<p>Please go to the <a class="reference external" href="https://veusz.github.io/">website</a> of Veusz to learn more about the
program. Links to binaries, distribution packages and the source
package can be found in <a class="reference external" href="https://veusz.github.io/download/">downloads</a>. For source installation, please
see the package INSTALL.</p>
</section>
<section id="getting-started">
<h2>Getting started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2>
<p>Veusz includes a built-in tutorial which starts the first time the
program is run. You can rerun it later from the Help menu. It also
includes many <a class="reference external" href="https://veusz.github.io/examples/">examples</a>, to show how certain kinds of plots are
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>
</section>
<section id="terminology">
<h2>Terminology<a class="headerlink" href="#terminology" title="Permalink to this headline">¶</a></h2>
<p>Here we define some terminology for future use.</p>
<section id="widget">
<h3>Widget<a class="headerlink" href="#widget" title="Permalink to this headline">¶</a></h3>
<p>A document and its graphs are built up from widgets.  These widgets
can often by placed within each other, depending on the type of the
widget. A widget has children (those widgets placed within it) and its
parent. The widgets have a number of different settings which modify
their behaviour. These settings are divided into properties, which
affect what is plotted and how it is plotted. These would include the
dataset being plotted or whether an axis is logarithmic.  There are
also formatting settings, including the font to be used and the line
thickness. In addition they have actions, which perform some sort of
activity on the widget or its children, like “fit” for a fit widget.</p>
<p>As an aside, using the scripting interface, widgets are
specified with a “path”, like a file in Unix or Windows. These
can be relative to the current widget (do not start with a
slash), or absolute (start with a slash). Examples of
paths include, <cite>/page1/graph1/x</cite>, <cite>x</cite> and <cite>.</cite>.</p>
<p>The widget types include</p>
<ol class="arabic">
<li><p><strong class="command">document</strong> - representing a complete document. A document
can contain pages. In addition it contains a setting giving the
page size for the document.</p></li>
<li><p><strong class="command">page</strong> - representing a page in a document. One or more
graphs can be placed on a page, or a grid.</p></li>
<li><p><strong class="command">graph</strong> - defining an actual graph. A graph can be placed
on a page or within a grid. Contained within the graph are its axes
and plotters. A graph can be given a background fill and a border
if required. It also has a margin, which specifies how far away
from the edge of its parent widget to plot the body of the graph.
A graph can contain several axes, at any position on the plot. In
addition a graph can use axes defined in parent widgets, shared
with other graphs.  More than one graph can be placed within in a
page. The margins can be adjusted so that they lie within or
besides each other.</p></li>
<li><p><strong class="command">grid</strong> - containing one or more graphs. A grid plots
graphs in a gridlike fashion. You can specify the number of rows
and columns, and the plots are automatically replotted in the
chosen arrangement. A grid can contain graphs or axes. If an axis
is placed in a grid, it can be shared by the graphs in the grid.</p></li>
<li><p><strong class="command">axis</strong> - giving the scale for plotting data. An axis
translates the coordinates of the data to the screen. An axis can
be linear or logarithmic, it can have fixed endpoints, or can
automatically get them from the plotted data. It also has settings
for the axis labels and lines, tick labels, and major and minor
tick marks.  An axis may be “horizontal” or “vertical” and can
appear anywhere on its parent graph or grid.  If an axis appears
within a grid, then it can be shared by all the graphs which are
contained within the grid.  The <strong class="command">axis-broken</strong> widget is an
axis sub-type. It is an axis type where there are jumps in the
scale of the axis.  The <strong class="command">axis-function</strong> widget allows the
user to create an axis where the values are scaled by a monotonic
function, allowing non-linear and non-logarithmic axis scales. The
widget can also be linked to a different axis via the function.</p></li>
<li><p>plotters - types of widgets which plot data or add other things on
a graph. There is no actual plotter widget which can be added, but
several types of plotters listed below. Plotters typically take an
axis as a setting, which is the axis used to plot the data on the
graph (default x and y).</p>
<ol class="arabic simple">
<li><p><strong class="command">function</strong> - a plotter which plots a function on the
graph. Functions can be functions of x or y (parametric
functions are not done yet!), and are defined in Python
expression syntax, which is very close to most other
languages. For example <cite>3*x**2 + 2*x - 4</cite>. A number of functions
are available (e.g. sin, cos, tan, exp, log…). Technically,
Veusz imports the numpy package when evaluating, so numpy
functions are available.  As well as the function setting, also
settable is the line type to plot the function, and the number
of steps to evaluate the function when plotting. Filling is
supported above/below/left/right of the function.</p></li>
<li><p><strong class="command">xy</strong> - a plotter which plots scatter, line, or stepped
plots. This versatile plotter takes an x and y dataset, and
plots (optional) points, in a chosen marker and colour,
connecting them with (optional) lines, and plotting (optional)
error bars. An xy plotter can also plot a stepped line, allowing
histograms to be plotted (note that it doesn’t yet do the
binning of the data).  The settings for the xy widget are the
various attributes for the points, line and error bars, the
datasets to plot, and the axes to plot on.  The xy plotter can
plot a label next to each dataset, which is either the same for
each point or taken from a text dataset.  If you wish to leave
gaps in a plot, the input value <cite>nan</cite> can be specified in the
numeric dataset.</p></li>
<li><p><strong class="command">fit</strong> - fit a function to data. This plotter is a like
the function plotter, but allows fitting of the function to
data. This is achieved by clicking on a “fit” button, or using
the “fit” action of the widget. The fitter takes a function to
fit containing the unknowns, e.g. <cite>a*x**2 + b*x + c</cite>, and
initial values for the variables (here a, b and c). It then fits
the data (note that at the moment, the fit plotter fits all the
data, not just the data that can be seen on the graph) by
minimising the chi-squared.  In order to fit properly, the y
data (or x, if fitting as a function of x) must have a properly
defined, preferably symmetric error. If there is none, Veusz
assumes the same fractional error everywhere, or symmetrises
asymmetric errors.  Note that more work is required in this
widget, as if a parameter is not well defined by the data, the
matrix inversion in the fit will fail. In addition Veusz does
not supply estimates for the errors or the final chi-squared in
a machine readable way.  If the fitting parameters vary
significantly from 1, then it is worth “normalizing” them by
adding in a factor in the fit equation to bring them to of the
order of 1.</p></li>
<li><p><strong class="command">bar</strong> - a bar chart which plots sets of data as
horizontal or vertical bars. Multiple datasets are supported. In
“grouped” mode the bars are placed side-by-side for each
dataset. In “stacked” mode the bars are placed on top of each
other (in the appropriate direction according to the sign of the
dataset). Bars are placed on coordinates given, or in integer
values from 1 upward if none are given. Error bars are plotted
for each of the datasets.  Different fill styles can be given
for each dataset given. A separate key value can be given for
each dataset.</p></li>
<li><p><strong class="command">key</strong> - a box which describes the data plotted. If a
key is added to a plot, the key looks for “key” settings of the
other data plotted within a graph. If there any it builds up a
box containing the symbol and line for the plotter, and the text
in the “key” setting of the widget. This allows a key to be very
easily added to a plot.  The key may be placed in any of the
corners of the plot, in the centre, or manually
placed. Depending on the ordering of the widgets, the key will
be placed behind or on top of the widget. The key can be filled
and surrounded by a box, or not filled or surrounded.</p></li>
<li><p><strong class="command">label</strong> - a text label places on a graph. The alignment
can be adjusted and the font changed. The position of the label
can be specified in fractional terms of the current graph, or
using axis coordinates.</p></li>
<li><p><strong class="command">rect, ellipse</strong> - these draw a rectangle or ellipse,
respectively, of size and rotation given. These widgets can be
placed directly on the page or on a graph. The centre can be
given in axis coordinates or fractional coordinates.</p></li>
<li><p><strong class="command">imagefile</strong> - draw an external graphs file on the graph
or page, with size and rotation given. The centre can be given
in axis coordinates or fractional coordinates.</p></li>
<li><p><strong class="command">svgfile</strong> - draw an external scalable vector graphic on the graph
or page, with size and rotation given. The centre can be given
in axis coordinates or fractional coordinates.</p></li>
<li><p><strong class="command">line</strong> - draw a line with optional arrowheads on the
graph or page. One end can be given in axis coordinates or
fractional coordinates.</p></li>
<li><p><strong class="command">contour</strong> - plot contours of a 2D dataset on the
graph. Contours are automatically calculated between the minimum
and maximum values of the graph or chosen manually. The line
style of the contours can be chosen individually and the region
between contours can be filled with shading or color.  2D
datasets currently consist of a regular grid of values between
minimum and maximum positions in x and y. They can be
constructed from three 1D datasets of x, y and z if they form a
regular x, y grid.</p></li>
<li><p><strong class="command">image</strong> - plot a 2D dataset as a colored
image. Different color schemes can be chosen. The scaling
between the values and the image can be specified as linear,
logarithmic, square-root or square.</p></li>
<li><p><strong class="command">polygon</strong> - plot x and y points from datasets as a
polygon. The polygon can be placed directly on the page or
within a graph. Coordinates are either plotted using the axis or
as fractions of the width and height of the containing widget.</p></li>
<li><p><strong class="command">boxplot</strong> - plot distribution of points in a dataset.</p></li>
<li><p><strong class="command">polar</strong> - plot polar data or functions. This is a
non-orthogonal plot and is placed directly on the page rather
than in a graph.</p></li>
<li><p><strong class="command">ternary</strong> - plot data of three variables which add up
to 100 per cent.This is a non-orthogonal plot and is placed
directly on the page rather than in a graph.</p></li>
</ol>
</li>
<li><p>3D widgets - 3D graphs can be created by adding a 3D scene widget
(<strong class="command">scene3d</strong>) to a blank page, or by creating a new 3D
document. The 3D scene has settings which control the angle the
rotation angle of the plot, the position and color of lighting and
the rendering method.</p>
<p>To build up a 3D plot the following widgets can be placed inside
it:</p>
<ol class="arabic simple">
<li><p><strong class="command">graph3d</strong> - this is an analogous widget to the 2D graph
widget, plotting a 3D plot with cartesian axes. It contains
three or more axis3d widgets, and plotting widgets. The graph
contains settings for the graph size (the default is 1 in each
direction) and the 3D position of the graph in the same
units. Multiple graph widgets can be added to a scene, though
the position and sizes may need to be adjusted.</p></li>
<li><p><strong class="command">axis3d</strong> - normally a 3D graph has three axes (X, Y and
Z), but more axes can be added to plot multiple things on a single
axis direction. This works in a similar way to the 2D axis
widget. The widget has options for the axis label, tick labels,
tick marks and grid lines (which appear on the outside of the 3D
cube). An axis can be swiched between linear and logorithmic
mode. Scalings can be applied to the data values plotted in that
dimension or to the axis labels.</p></li>
<li><p><strong class="command">point3d</strong> - for plotting points, and optionally
connecting lines, in 3D. This, and the other plotting widgets
are placed in a graph3d widget. The user provides three 1D
datasets for the x, y and z values. The markers can be scaled in
size by another optional dataset. The markers can also be
colored according to another optional dataset, according to a
color map, minimum and maximum. Error bars can be provided for
each of the x, y and z datasets. The connecting line can also be
colored if a color dataset is provided and a colormap chosen.</p></li>
<li><p><strong class="command">function3d</strong> - for plotting either a functional line in
3D space or a functional surface. The type of plot is given by
the mode parameter. In the case of the line, the x,y,z
coordinates can be specified as a function of t, where t goes
from 0 to 1, or by giving functions for two of the coordinates
as a function of the other. For a surface, the value for x, y or
z is given as a function of the other two. In addition, a
function returning 0 to 1 can be provided for the color, which
specifies the color map value for the surface at each position
or the line color. For a 2D surface, the grid lines or surface
fill can be hidden or shown. There are also settings giving the
number of function evaluations to compute in each direction for
a surface, or in one direction for a line.</p></li>
<li><p><strong class="command">surface3d</strong> - for plotting a two dimensional surface
from data values. The user should provide a 2D dataset for the
height of a surface. The x, y or z axis for the height and other
directions can be chosen. A second 2D dataset can be provided
for the color of the surface at each point. Note that the
coordinate of the 2D dataset lies at the center of each 2D grid
point. The height of the grid at the edge is calculated by
linear interpolation. Normally the grid is surrounded by four
lines and the surface by two triangles. If a high resolution
option is enabled, the each grid point is surrounded by eight
lines and the surface drawn by eight triangles.</p></li>
<li><p><strong class="command">volume3d</strong> - for plotting 3D volumes. In this widget,
for a volume described by A×B×C values, then the user should
provide four datasets, each containing up to A×B×C values (there
can be holes in the representation). Three of the datasets give
coordinates of the centers of the 3D cells and the fourth the
color of the cell. An example set of datasets would be
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),
color=(0.1,0.2,0.3,0.4,0.3,0.2,0.1,0). Additionally, the user
can provide a transparency dataset, which can be useful for
showing or hiding parts of the 3D space.</p></li>
</ol>
</li>
</ol>
</section>
<section id="settings-properties-and-formatting">
<h3>Settings: properties and formatting<a class="headerlink" href="#settings-properties-and-formatting" title="Permalink to this headline">¶</a></h3>
<p>The various settings of the widgets come in a number of types,
including integers (e.g. 10), floats (e.g. 3.14), dataset names
(<cite>mydata</cite>), expressions (<cite>x+y</cite>), text (<cite>hi there!</cite>), distances (see
above), options (<cite>horizontal</cite> or <cite>vertical</cite> for axes).</p>
<p>Veusz performs type checks on these parameters. If they
are in the wrong format the control to edit the setting will
turn red. In the command line, a TypeError exception is
thrown.</p>
<p>In the GUI, the current page is replotted if a setting
is changed when enter is pressed or the user moves to another
setting.</p>
<p>The settings are split up into formatting settings,
controlling the appearance of the plot, or properties,
controlling what is plotted and how it is plotted.</p>
<p>Default settings, including the default font and line
style, and the default settings for any graph widget, can be
modified in the “Default styles” dialog box under the “Edit”
menu. Default settings are set on a per-document basis, but
can be saved into a separate file and loaded. A default
default settings file can be given to use for new documents
(set in the preferences dialog).</p>
</section>
<section id="datasets">
<h3>Datasets<a class="headerlink" href="#datasets" title="Permalink to this headline">¶</a></h3>
<p>Data are imported into Veusz as a dataset. A dataset is
imported from a file, entered manually, set via the command
line, or linked to other datasets via an expression or
dataset plugin. Each dataset has a unique name in the
document. They can be seen in the dataset browser panel, or
in the Data, Edit dialog box.  To choose the data to be
plotted, the user usually selects the dataset in the
appropriate setting of a widget.</p>
<p>Veusz supports one-dimensional (1D) datasets, which are a
list of values with optional error bars. Error bars can
either be symmetric or asymmetric. Veusz also supports
two-dimensional (2D) data. A 2D dataset is a grid of values,
with either a fixed spacing in coordinates, or with
arbitrary pixel sizes. An n-dimensional (nD) dataset is an
arbitrary matrix of values. These cannot be plotted
directly, but subsets can be plotted using python slice
syntax to convert to 1D or 2D datasets.</p>
<p>In addition to simple numeric datasets, Veusz also supports
date-time datasets. For details see the sections on reading
data. Also supported are text datasets, which are lists of
text strings.</p>
<p>Datasets can either be plain lists of values which are
stored within the document, or they can be linked to a file,
so that the values update if the file is reloaded, or they
can be linked to other datasets via expressions or dataset
plugins.</p>
</section>
<section id="text">
<span id="textfonts"></span><h3>Text<a class="headerlink" href="#text" title="Permalink to this headline">¶</a></h3>
<p>Veusz understands a limited set of LaTeX-like formatting
for text. There are some differences (for example, <cite>10^23</cite>
puts the 2 and 3 into superscript), but it is fairly
similar. You should also leave out the dollar signs. Veusz
supports superscripts (<cite>^</cite>), subscripts (<cite>_</cite>), brackets for
grouping attributes are <cite>{</cite> and <cite>}</cite>.</p>
<p>Supported LaTeX symbols include: \AA, \Alpha, \Beta,
\Chi, \Delta, \Epsilon, \Eta, \Gamma, \Iota, \Kappa, \Lambda, \Mu,
\Nu, \Omega, \Omicron, \Phi, \Pi, \Psi, \Rho, \Sigma, \Tau, \Theta,
\Upsilon, \Xi, \Zeta, \alpha, \approx, \ast, \asymp, \beta, \bowtie,
\bullet, \cap, \chi, \circ, \cup, \dagger, \dashv, \ddagger, \deg,
\delta, \diamond, \divide, \doteq, \downarrow, \epsilon, \equiv,
\eta, \gamma, \ge, \gg, \hat, \in, \infty, \int, \iota, \kappa, \lambda,
\le, \leftarrow, \lhd, \ll, \models, \mp, \mu, \neq, \ni, \nu, \odot,
\omega, \omicron, \ominus, \oplus, \oslash, \otimes, \parallel,
\perp, \phi, \pi, \pm, \prec, \preceq, \propto, \psi, \rhd, \rho,
\rightarrow, \sigma, \sim, \simeq, \sqrt, \sqsubset, \sqsubseteq,
\sqsupset, \sqsupseteq, \star, \stigma, \subset, \subseteq, \succ,
\succeq, \supset, \supseteq, \tau, \theta, \times, \umid, \unlhd,
\unrhd, \uparrow, \uplus, \upsilon, \vdash, \vee, \wedge, \wtilde, \xi, \zeta.
Please request additional characters if they are required (and exist
in the unicode character set). Special symbols can be included
directly from a character map.</p>
<p>Other LaTeX commands are supported. <cite>\\</cite> breaks a
line. This can be used for simple tables. For example <cite>{a\\b}
{c\\d}</cite> shows <cite>a c</cite> over <cite>b d</cite>. The command <cite>\frac{a}{b}</cite>
shows a vertical fraction a/b.</p>
<p>Also supported are commands to change font. The command
<cite>\font{name}{text}</cite> changes the font text is written in to
name. This may be useful if a symbol is missing from the
current font, e.g. <cite>\font{symbol}{g}</cite> should produce a
gamma. You can increase, decrease, or set the size of the font
with <cite>\size{+2}{text}</cite>, <cite>\size{-2}{text}</cite>, or
<cite>\size{20}{text}</cite>. Numbers are in points.</p>
<p>Various font attributes can be changed: for example,
<cite>\italic{some italic text}</cite> (or use <cite>\textit</cite> or <cite>\emph</cite>),
<cite>\bold{some bold text}</cite> (or use <cite>\textbf</cite>) and <cite>\underline{some
underlined text}</cite>.</p>
<p>Example text could include <cite>Area / \pi (10^{-23}
cm^{-2})</cite>, or <cite>\pi\bold{g}</cite>.</p>
<p>Veusz plots these symbols with Qt’s unicode support. You
can also include special characters directly, by copying and
pasting from a character map application. If your current font
does not contain these symbols then you may get a box
character.</p>
<p>Veusz also supports the evaluation of a Python
expression when text is written to the page. Python code is
written inside the brackets <strong class="command">%{{ }}%</strong>. Note
that the Python evaluation happens before the LaTeX expansion
is done. The return value of the expression is converted to
text using the Python <strong class="command">str()</strong> function. For
example, the expression <strong class="command">%{{2+2}}%</strong> would
write <strong class="command">4</strong>. Custom functions and constants are
supported when evaluation, in addition to the usual numpy
functions. In addition, Veusz defines the following useful
functions and values.</p>
<ol class="arabic simple">
<li><p><strong class="command">ENVIRON</strong> is the
<strong class="command">os.environ</strong> dict of environment
variables. <strong class="command">%{{ENVIRON['USER']}}%</strong>
would show the current user in unix.</p></li>
<li><p><strong class="command">DATE([fmt])</strong> returns the current
date, by default in ISO format. fmt is an optional
format specifier using
<strong class="command">datetime.date.strftime</strong> format
specifiers.</p></li>
<li><p><strong class="command">TIME([fmt])</strong> returns the current
date/time, by default in ISO format. fmt is an optional
format specifier using
<strong class="command">datetime.datetime.strftime</strong> format
specifiers.</p></li>
<li><p><strong class="command">DATA(name[, part])</strong> returns the Veusz
dataset with given name. For numeric datasets this is a
numpy array. For numeric datasets with errors, part
specifies the dataset part to return, i.e. ‘data’,
‘serr’, ‘perr’, ‘nerr’. For example, the mean value of
a dataset could be shown using
<strong class="command">%{{mean(DATA('x'))}}%</strong>.</p></li>
<li><p><strong class="command">FILENAME()</strong> - returns the current
document filename. This can include the
directory/folder of the file. Note that the filename is
escaped with ESCAPE() so that LaTeX symbols are not
expanded when shown.</p></li>
<li><p><strong class="command">BASENAME()</strong> - returns the current
document filename, removing the directory or folder
name Note that the filename is escaped with ESCAPE() so
that LaTeX symbols are not expanded when shown.</p></li>
<li><p><strong class="command">ESCAPE(x)</strong> - escapes any LaTeX
symbols in x so that they are not interpreted as
LaTeX.</p></li>
<li><p><strong class="command">SETTING(path)</strong> - return the value of
the Veusz setting given by the full path,
e.g. <strong class="command">%{{SETTING('/page1/width')}}%</strong>.</p></li>
<li><p><strong class="command">LANG(mapping)</strong> - mapping is a dictionary which maps
language names to strings. This returns the string corresponding to
the current language. The keys come from the locale names which are
the two-letter language codes (e.g. <cite>en</cite> or <cite>fr</cite>), or the full code
(e.g. <cite>en_GB</cite> or <cite>de_AT</cite>). The <cite>default</cite> key is used if the
language code is not found. An example is <strong class="command">%{{
LANG({'de':'Druck','default':'Pressure'}) }}%</strong>.</p></li>
</ol>
</section>
<section id="measurements">
<h3>Measurements<a class="headerlink" href="#measurements" title="Permalink to this headline">¶</a></h3>
<p>Distances, widths and lengths in Veusz can be specified in a number of
different ways. These include absolute distances specified in physical
units, e.g. 1cm, 0.05m, 10mm, 5in and 10pt, and relative units, which
are relative to the largest dimension of the page, including 5%, 1/20,
0.05.</p>
</section>
<section id="color-theme">
<h3>Color theme<a class="headerlink" href="#color-theme" title="Permalink to this headline">¶</a></h3>
<p>From version 1.26, widgets are colored automatically using the color
theme. This theme is specified in the main document widget
settings. Widgets are given the colors in order given the order in a
graph widget. The default theme can be specified in the preferences
dialog box.</p>
<p>To override a theme, the user can manually specify the individual
colors in the custom definitions dialog box. Color <cite>theme1</cite> is used as
the first theme color, then <cite>theme2</cite>, etc.</p>
</section>
<section id="axis-numeric-scales">
<h3>Axis numeric scales<a class="headerlink" href="#axis-numeric-scales" title="Permalink to this headline">¶</a></h3>
<p>The way in which numbers are formatted in axis scales is chosen
automatically. For standard numerical axes, values are shown with the
<cite>%Vg</cite> formatting (see below). For date axes, an appropriate date
formatting is used so that the interval shown is correct. A format can
be given for an axis in the axis number formatting panel can be given
to explicitly choose a format. Some examples are given in the drop
down axis menu. Hold the mouse over the example for detail.</p>
<p>C-style number formatting is used with a few Veusz specific
extensions. Text can be mixed with format specifiers, which start with
a <cite>%</cite> sign. Examples of C-style formatting include: <cite>%.2f</cite> (decimal
number with two decimal places, e.g. 2.01), <cite>%.3e</cite> (scientific
formatting with three decimal places, e.g. 2.123e-02), <cite>%g</cite> (general
formatting, switching between <cite>%f</cite> and <cite>%e</cite> as appropriate). See
<a class="reference external" href="http://opengroup.org/onlinepubs/007908799/xsh/fprintf.html">http://opengroup.org/onlinepubs/007908799/xsh/fprintf.html</a> for
details.</p>
<p>Veusz extensions include <cite>%Ve</cite>, which is like <cite>%e</cite> except it displays
scientific notation as written, e.g. 1.2x10^23, rather than
1.2e+23. <cite>%Vg</cite> switches between standard numbers and Veusz scientific
notation for large and small numbers. <cite>%VE</cite> using engineering SI
suffixes to represent large or small numbers (e.g. 1000 is 1k).</p>
<p>Veusz allows dates and times to be formatted using <cite>%VDX</cite> where <cite>X</cite> is
one of the formatting characters for strftime (see
<a class="reference external" href="http://opengroup.org/onlinepubs/007908799/xsh/strftime.html">http://opengroup.org/onlinepubs/007908799/xsh/strftime.html</a> for
details). These include <cite>a</cite> for an abbreviated weekday name, <cite>A</cite> for
full weekday name, <cite>b</cite> for abbreviated month name, <cite>B</cite> for full month
name, <cite>c</cite> date and time representation, <cite>d</cite> day of month 01..31, <cite>H</cite>
hour as 00..23, <cite>I</cite> hour as 01..12, <cite>j</cite> as day of year 001..366, <cite>m</cite>
as month 01..12, <cite>M</cite> minute as 00..59, <cite>p</cite> AM/PM, <cite>S</cite> second 00..61,
<cite>U</cite> week number of year 00..53 (Sunday as first day of week), <cite>w</cite>
weekday as decimal number 0..6, <cite>W</cite> week number of year (Monday as
first day of week), <cite>x</cite> date representation, <cite>X</cite> time representation,
<cite>y</cite> year without century 00..99 and <cite>Y</cite> year. <cite>%VDVS</cite> is a special
Veusz addon format which shows seconds and fractions of seconds
(e.g. 12.2).</p>
</section>
<section id="three-dimensional-3d-plots">
<h3>Three dimensional (3D) plots<a class="headerlink" href="#three-dimensional-3d-plots" title="Permalink to this headline">¶</a></h3>
<p>When drawing in three dimensions, Veusz builds up a 3D “scene” for the
graph from the various plotting widgets, made up of triangles, line
segments, points and text. Veusz does not use a standard (e.g. OpenGL)
drawing method, but renders the scene itself. The advantage of this is
that it can produce vector rather than bitmap or raster
output. OpenGL, for example, is based around bitmaps.</p>
<p>Veusz applies lighting to the scene. The lighting depends on enabled
light sources, which are set in the scene3d widget. Light sources have
a color, intensity and position. Note that only the angle of the light
to a surface affects its lighting, not its distance. The position of
the light is relative to the viewer (camera), not the graph. Positive
light coordinates are towards the graph (z), upwards (y) and
rightwards (x). Normally each solid surface has an intrinsic color,
which can be seen without any lighting. If a light source is enabled,
the color of the light is added to the surface color, depending on the
reflectivity of the surface. Each surface also has a transparency
setting.</p>
<p>By default, Veusz uses a naive Painter’s Algorithm to draw the
scene. It draws from the back of scene to the front. The main problem
with this algorithm is that shapes and lines overlapping in depth can
be confused as the depth of each object is calculated at only one
point. In addition objects may intersect, which is not properly
treated. In the scene3d object, the user can switch to a different
rendering mode called BSP. In this accurate BSP mode, the objects are
split so that they never overlap from any viewing angle. The
disadvantage of this mode is that it is slow, uses a lot of memory and
produces large output files. We plan in future to add another mode
which handles overlaps better and does not unnecessarily split
objects.</p>
<p>The plot is affected by the viewing angle, which is specified in the
scene3d widget settings. The rotation is given be three rotations
around lines in X, Y and Z directions (note that these are not the
same directions as the X, Y and Z axes!). The X axis runs horizontally
on the screen, the Y axis runs vertically, and the Z axis runs along
the line of sight.</p>
<p>There is also a distance setting, which moves graphs closer to or away
from the viewer. At larger distances the effect of perspective
reduces, meaning that parts of the plot closer to the viewer are not
larger than if they were at the farthest side. At large distances, a
plot tends towards being isometric. At small distances, shapes are
more distorted (note by default the size of the graph is 1 in these
distance units). It is currently possible to place graphs inside the
camera leading to strange output.</p>
<p>By default, Veusz enlarges the 3D rendered scene to fill the bounds of
the 3D scene widget, so distance has no effect on the size of the
plot. This scaling can be switched off by modifying the Size setting
from “Auto” to a fixed number. A fixed size is useful if the user
wants a graph to be the same size for any rotation. With this setting
the size of the plot is affected by their distance.</p>
<p>By default, a 3D graph has dimensions of 1 along the X, Y and Z
axes. The size can be adjusted using the size settings in the graph3d
widget. Care should be taken that the graph size does not lead to
points being at negative viewing distances. The default position of
the plot is at the origin 0,0,0. If the user wants to plot multiple
graph3d widgets, the positions should be adjusted to prevent overlap.</p>
<p>Normally in Veusz, sizes of objects (e.g. plot markers) are given in
physical units. This makes less sense for a 3D plot as sizes can
depend on distance. In a 3D graph sizes of plotting markers and line
widths are given in 1/1000 of the graph bounding box maximum
dimension.</p>
</section>
</section>
<section id="the-main-window">
<h2>The main window<a class="headerlink" href="#the-main-window" title="Permalink to this headline">¶</a></h2>
<p>You should see the main window when you run Veusz (you can just type
the veusz command in Unix).</p>
<img alt="_images/mainwindow.png" src="_images/mainwindow.png" />
<p>The Veusz window is split into several sections. At the top is the
menu bar and tool bar. These work in the usual way to other
applications. Sometimes options are disabled (greyed out) if they do
not make sense to be used. If you hold your mouse over a button for a
few seconds, you will usually get an explanation for what it does
called a “tool tip”.</p>
<p>Below the main toolbar is a second toolbar for constructing the graph
by adding widgets (on the left), and some editing buttons. The add
widget buttons add the request widget to the currently selected widget
in the selection window. The widgets are arranged in a tree-like
structure.</p>
<p>Below these toolbars and to the right is the plot window. This is
where the current page of the current document is shown. You can
adjust the size of the plot on the screen (the zoom factor) using the
“View” menu or the zoom tool bar button (the magnifying
glass). Initially you will not see a plot in the plot window, but you
will see the Veusz logo. At the moment you cannot do much else with
the window. In the future you will be able to click on items in the
plot to modify them.</p>
<p>To the left of the plot window is the selection window, and the
properties and formatting windows. The properties window lets you edit
various aspects of the selected widget (such as the minimum and
maximum values on an axis). Changing these values should update the
plot. The formatting lets you modify the appearance of the selected
widget. There are a series of tabs for choosing what aspect to modify.</p>
<p>The various windows can be “dragged” from the main window to “float”
by themselves on the screen.</p>
<p>To the bottom of the window is the console. This window is not shown
by default, but can be enabled in the View menu. The console is a
Veusz and Python command line console. To read about the commands
available see <a class="reference internal" href="api.html#commands"><span class="std std-ref">Commands</span></a>. As this is a Python console,
you can enter mathematical expressions (e.g. <cite>1+2.0*cos(pi/4)</cite>) here
and they will be evaluated when you press Enter. The usual special
functions and the operators are supported. You can also assign results
to variables (e.g. <cite>a=1+2</cite>) for use later. The console also supports
command history like many Unix shells. Press the up and down cursor
keys to browse through the history. Command line completion is not
available yet!</p>
<p>There also exists a dataset browsing window, by default to the right
of the screen. This window allows you to view the datasets currently
loaded, their dimensions and type. Hovering a mouse over the size of
the dataset will give you a preview of the data.</p>
</section>
<section id="my-first-plot">
<h2>My first plot<a class="headerlink" href="#my-first-plot" title="Permalink to this headline">¶</a></h2>
<p>After opening Veusz, on the left of the main window, you will see a
Document, containing a Page, which contains a Graph with its axes. The
Graph is selected in the selection window. The toolbar above adds a
new widget to the selected widget. If a widget cannot be added to a
selected widget it is disabled. On opening a new document Veusz
automatically adds a new Page and Graph (with axes) to the document.</p>
<p>You will see something like this:</p>
<img alt="_images/winwithgraph.png" src="_images/winwithgraph.png" />
<p>Select the x axis which has been added to the document (click on <cite>x</cite>
in the selection window). In the properties window you will see a
variety of different properties you can modify. For instance you can
enter a label for the axis by writing <cite>Area (cm^{2})</cite> in the box next
to label and pressing enter. Veusz supports text in LaTeX-like form
(without the dollar signs). Other important parameters is the <cite>log</cite>
switch which switches between linear and logarithmic axes, and <cite>min</cite>
and <cite>max</cite> which allow the user to specify the minimum and maximum
values on the axes.</p>
<p>The formatting dialog lets you edit various aspects of the graph
appearance. For instance the “Line” tab allows you to edit the line of
the axis. Click on “Line”, then you can then modify its colour. Enter
“green” instead of “black” and press enter. Try making the axis label
bold.</p>
<p>Now you can try plotting a function on the graph. If the graph, or its
children are selected, you will then be able to click the “function”
button at the top (a red curve on a graph). You will see a straight
line (y=x) added to the plot. If you select “function1”, you will be
able to edit the functional form plotted and the style of its
line. Change the function to <cite>x**2</cite> (x-squared).</p>
<p>We will now try plotting data on the graph. Go to your
favourite text editor and save the following data as
test.dat:</p>
<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>
<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>
<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>
<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>
</pre></div>
</div>
<p>The first three columns are the x data to plot plus its asymmetric
errors. The final two columns are the y data plus its symmetric
errors. In Veusz, go to the “Data” menu and select “Import”. Type the
filename into the filename box, or use the “Browse…” button to
search for the file. You will see a preview of the data pop up in the
box below. Enter <cite>x,+,- y,+-</cite> into the descriptors edit box (note that
commas and spaces in the descriptor are almost interchangeable in
Veusz 1.6 or newer). This describes the format of the data which
describes dataset “x” plus its asymmetric errors, and “y” with its
symmetric errors. If you now click “Import”, you will see it has
imported datasets <cite>x</cite> and <cite>y</cite>.</p>
<p>To plot the data you should now click on <cite>graph1</cite> in the tree
window. You are now able to click on the “xy” button (which looks like
points plotted on a graph). You will see your data plotted on the
graph. Veusz plots datasets <cite>x</cite> and <cite>y</cite> by default, but you can change
these in the properties of the “xy” plotter.</p>
<p>You are able to choose from a variety of markers to plot. You can
remove the plot line by choosing the “Plot Line” subsetting, and
clicking on the “hide” option. You can change the colour of the marker
by going to the “Marker Fill” subsetting, and entering a new colour
(e.g. red), into the colour property.</p>
</section>
</section>


          </div>
          
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="index.html">Veusz</a></h1>








<h3>Navigation</h3>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Introduction</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#veusz">Veusz</a></li>
<li class="toctree-l2"><a class="reference internal" href="#installation">Installation</a></li>
<li class="toctree-l2"><a class="reference internal" href="#getting-started">Getting started</a></li>
<li class="toctree-l2"><a class="reference internal" href="#terminology">Terminology</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#widget">Widget</a></li>
<li class="toctree-l3"><a class="reference internal" href="#settings-properties-and-formatting">Settings: properties and formatting</a></li>
<li class="toctree-l3"><a class="reference internal" href="#datasets">Datasets</a></li>
<li class="toctree-l3"><a class="reference internal" href="#text">Text</a></li>
<li class="toctree-l3"><a class="reference internal" href="#measurements">Measurements</a></li>
<li class="toctree-l3"><a class="reference internal" href="#color-theme">Color theme</a></li>
<li class="toctree-l3"><a class="reference internal" href="#axis-numeric-scales">Axis numeric scales</a></li>
<li class="toctree-l3"><a class="reference internal" href="#three-dimensional-3d-plots">Three dimensional (3D) plots</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#the-main-window">The main window</a></li>
<li class="toctree-l2"><a class="reference internal" href="#my-first-plot">My first plot</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="datasets.html">Reading data</a></li>
<li class="toctree-l1"><a class="reference internal" href="datasets.html#manipulating-datasets">Manipulating datasets</a></li>
<li class="toctree-l1"><a class="reference internal" href="datasets.html#capturing-data">Capturing data</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">Veusz command line and embedding interface (API)</a></li>
</ul>

<div class="relations">
<h3>Related Topics</h3>
<ul>
  <li><a href="index.html">Documentation overview</a><ul>
      <li>Previous: <a href="index.html" title="previous chapter">Veusz documentation</a></li>
      <li>Next: <a href="datasets.html" title="next chapter">Reading data</a></li>
  </ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>$('#searchbox').show(0);</script>








        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy;2003-2021, Jeremy Sanders.
      
      |
      Powered by <a href="http://sphinx-doc.org/">Sphinx 4.3.2</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
      
      |
      <a href="_sources/introduction.rst.txt"
          rel="nofollow">Page source</a>
    </div>

    

    
  </body>
</html>