Funplot Users Manual

Funplot - 2D data plotting environment, version 1.0


Contents



Introduction

This document describes the users interface to the 2d-graphics visualization environment 'Funplot'.

Funplot's aim is to visualize 2 dimensional data in one or many plots and give the user the possibility to analyze, store, print and copy the plots in many ways.

You can directly start using Funplot when you have an ASCII data file, where your numeric data is stored column-wise. Drag & Drop this data file on the Funplot icon and you got your data immediately visualised. But before continue using Funplot intuitively, follow-on reading a little bit more.

The program was designed to be user-friendly, therefore advanced users should be able to use it without reading any instructions. However, it is recommended that even they go through the following chapters: General Terms, File Types and Properties Inheritance for a better understanding of basic ideas and philosophy behind.

Overall, this description first defines the general terms, which are clearly used and which help you to understand the anatomy of a plot. Then by explaining you the file types which are handled by Funplot you got a deeper knowledge about the data I/O and so about the data flow. Further you're guided through the individual menu items and functions. At the end of this document additional items are explained, as the Status-Line, the Distance-Mode, keyboard and mouse support, ...

Get familiar with Funplot practically, loading and manipulating the examples of the 'examples' directory. You find data files in the directory 'dataOnly', which you should open from the Graphs menu. Plot files can be found in the 'plots' directory, open this from the Plot menu. And one Session example is provided in the 'session' directory, which should be opened from the Session menu.

Note, that every function or menu item is also accessible from the Programmers Interface.


General Terms

The following terms describe the anatomy of a plot. The terms are reused within the further description (please note the capitalized starting letter).

Graph

A Graph is the aggregation of lines and points. These have a common color, line width, line style, marker, .... A graph does not necessarily need to be uninterrupted. Graphs are explicitly assigned to Axes-Systems. The Graphs properties are set in the 'Graphs' menu.

Axes-System

The Axes-System is the axes coordinate frame, where Graphs are visualized. The Axes-System includes the border, ticks, drawing region and axes titles. Axes-Systems are explicitly assigned to Plots.

Plot

The Plot is the window where Axes-Systems are displayed. Thus it includes the menu, the status bar, and the border. For instance there is exactly one Axes-System per Plot. The Plot and the Axes-Systems properties are set in the 'Plot' menu.

Session

A multiple number of Plots can coexist. All Plots belonging to one Funplot executable are building a Session. The Session is mastered by the 'Session' menu of any Plot. There is no session master window, all Plots are equal.


File Types and Handling

File Types

Funplot handles the following files:

File Type Description
<data file> Funplot reads column-oriented ASCII data files with arbitrary extension for generation of Graphs. The data for x and y is expected to be column oriented. Anyway, data in data files can be interpreted in different ways from your plot window. A data file can contain more than one graph. The data for the further graphs can be placed in additional columns respecting the following read mode possibilities or by appending the data pair columns at the end of the file, separated by the keyword 'New'. This gives the possibilities to add data pairs with different number of points. Respecting the chosen read mode Funplot has the built-in capability to recognize the number of graphs and the number of values automatically.
Note, that you can add an unlimited number of comment lines staring with #.
*.dat When Funplot writes data (ASCII readable) to file it uses the extension '.dat'. Further the same conventions as <data file> are applied.
Note, that the data is always stored with full numerical precision.
*.plt Funplot writes or reads the Plot configuration to/from file with this file extension.
When opening a Plot file in Funplot, it is assumed that a data file with the same name and the extension '.dat' is located in the same directory.
*.ses Funplot writes or reads the top-level Session configuration to/from file with this file extension.
When opening a Session file in Funplot, it is assumed that the referenced Plot files with their data files are all located in the same directory.
*.emf Upon request Funplot writes the plot current view as enhanced meta file to file. Enhanced metafiles are vector graphics which assure a small file size, and which allow an enlargement of the figure without losses.
Funplot.ini Funplot initialization file, carrying as well Funplot options and default values. Have a look at the delivered Funplot.ini.

Funplot.ini, *.plt and *.ses files follow the conventions for windows © initialization file format. These are simple to understand, ASCII readable and modifyable by normal text editors. Note, that you can add an unlimited number of comment lines starting with ' to these files. See examples of these files:

Read Mode

The following read mode (readMode) possibilities exist for data files:

Menu Item Description
X Y Y .. The first column contains the x-value and all following columns are taken as the y-values. The x-value and the respective y-value are building one pair. If you have three y-values you obtain three graphs.
X Y X Y .. 2 consecutive values are taken as data pairs.
X Y A Y A .. In addition to mode XYY this mode understands the third, fifth, seventh, ... value as an attribute value to the y value. If the attribute has the value 1 a new line begins here (a graph can consist of multiple lines), the value 0 means connection to the value pair before. Saving of plot data is done in this mode. Note, if you want to figure out points and not lines, set all attribute values to one.
X Y A X Y A .. In addition to mode XYXY this mode adds an attribute value to the x-y pair before. See XYAYA for the definition of an attribute value.
Y Y .. This mode understands all columns as y-values, the x-value is the index of the y value. So e.g. the second data line gives x = 2.

Menu Items and Functions

Session Menu

Session | File | Open / Add ...

You can replace the current Session with an already existing session, or you can add a Session to the current. Adding a Session means that all the plots of the selected Session are appended.

Session | File | Save ...

Save the current Session to File.
Note, that a Session consists of one Session file (*.ses) and of the referenced Plot files (*.plt) with their data files (*.dat).

Session | Print >

Print directly (without any dialog box) all the Plots of the Session black & white or couloured with the default printer and the printer's default settings. For the print the complete page width (or length, depending if the printer's orientation is set to 'portrait' or 'landscape') is used. The actual width-to-height ratio of the Plots is considered.

Session | Exit

Closes all windows belonging to the Session asking the user for confirmation when more than one window exists.


Plot Menu

Plot | File | Open / Add ...

You can replace the current Plot with an already existing Plot, or you can add a Plot to the current Session. Adding a Plot means that an additional Plot is generated, while the current Plot remains unchanged.

Plot | File | Save ...

Saves the current Plot to File.
Note, that a Plot consists of the Plot file (*.ses) and of a data file with the same and the extension (*.dat).

Plot | Edit Lables ...

Gives the possibility to give the plot a title, to name the x- and the y-axis and to give the window a name.

Plot | Show | Grid >

Add a grid to your plot. You can decide whether you want a grid for the x-values, the y-values or for both. The grid is always positioned at the main tick marks.

Plot | Show | Legend >

Draw a legend at the specified location, using the same style (color, width, points, marker) as in the current Plot. Graph names are automatically assigned for each Graph and can be changed in the Graphs | Edit ... dialog box.

Plot | Show | Coordinate System >

Usually you want to see the complete coordinate system, including the frame, the tickmarks and the lables. You can also choose to view just half a coordinate system, such that the upper right corner is not visible. Sometimes it makes sense not to display the coordinate system at all, e.g. if you want to draw something. This option has a second advantage, that the complete plot window is used for visualization of your plot.

Plot | Color | Color Set ...

Colors are assigned to Graphs using color numbers which than are visualised on screen by use of the color sets. Depending on the chosen color set and the number of colors chosen for this set the Graph is displayed, using its color number as index for the color set entry. By default color numbers are assigned automatically starting with number 1 and are incremented with each graph. Color numbers can be changed in the Graphs | Edit ... dialog box.

Plot | Color | Color Scheme >

The color scheme configures the layout of the Plot. It sets the background color and style of the Plot and the legend, the background color of the Axes-System and the grid.

Plot | Zoom Mode >

The default zoom mode is 'X-Y'. Clicking the left mouse button and dragging in this mode let's you select your viewing range in x and y direction. The modes 'X, Autorange Y' and 'Y, Autorange X' let you select the x- or y-range you want to see, the respective y- or x-range is calculated automatically. 'X, Keep Ratio' holds the actual ratio of the x- and y-range, finally 'X' and 'Y' let you select the x- or y-range maintaining the actual y- or x-range.

Plot | Auto Range >

When choosing 'X & Y' this feature selects the actual range of the plot such that all points are inside. It goes through all the graphs and calculates the boundary box. When choosing 'X' it maintains the actual y-range and displays all points in that range. The vice versa is valid for 'Y'.

Plot | Range | Set ...

With this dialog box you can set the viewing range manually. Additionally you can set the main tickmarks and the sub-tickmarks distances. This is often helpful when you want a 'nice' plot, for pasting them into other tools or for printing.

Plot | Range | Last

Restore the last viewing range, for e.g. after auto range or mouse zoom.

Plot | Range | Original >

Restore the original viewing range. The original range is set, when a file is opened.

Plot | Range | Store / Restore

Have you found an interesting viewing range which you want to compare with another range. So store the range, find the second interesting range and restore the old range. To toggle between the two ranges use then 'view last' option or the 'End' key.

Plot | Range | Redraw >

Redraw the plot, starting by displaying the grid and frame, then drawing one graph after the other, finally redrawing the grid and frame. You can choose to redraw all or only parts of them.

Plot | Range | Move >

Zoom into or out of the plot, while the midpoint remains. 'Left','Right', 'Up' and 'Down' shifts the plot in the corresponding direction. The shifting value is taken from the actual main tick distance. Usually you will use the cursor keys and the 'PgUp' and 'PgDn' keys instead of these menu items. Refer to chapter Keyboard Input for more information.

Plot | Axes Equal

Axes Equal is specially designed for purposes where you want equal sized x- and y-axis. This means the aspect ratio is set such that equal tick mark increments on the x- and y-axis are equal in size. Mostly used, when the two axes have the same unit as e.g. architectural drawings.

Plot | Auto Screen Position >

Place the Plot at specified locations on screen.

Plot | Copy (to Clipboard) >

Copy the Plot, black & white or colored, as metafile to the Windows © clipboard, using a maximum resolution of 800x600 taking care of the plots actual width-to-height ratio. You can paste the clipboard content to any Windows © application that handles metafiles as e.g. Word ©, Visio © or CorelDraw ©.

Plot | Save Figure >

Save the Plot, black & white or colored, as enhanced metafile (.emf) to file, using the current resolution or a full screen resolution taking care of the plots actual width-to-height ratio.

Plot | Print >

Print directly (without any dialog box) the Plot black & white or couloured with the default printer and the printer's default settings. For the print the complete page width (or length, depending if the printer's orientation is set to 'portrait' or 'landscape') is used. The actual width-to-height ratio of the Plot is considered.

Plot | New

Generate a new Plot, using the default Funplot settings.

Plot | Clone

Copy the actual Plot into a new Plot. Use this e.g. to compare different views of the same Plot or to keep your "latest" Plot before adding another data file. The new Plot inherites all properties of the one from which it is generated.

Plot | Close Plot

Close the window without saving the plot and without asking the user for confirmation.


Graphs Menu

Graphs | Data File | Open / Add ...

Replace or add data files (and so Graphs) to your plot.

Graphs | Data File | Save ...

Save the data from the plot to file. See *.dat files details.

Graphs | Data File | Read Mode

Set the Read Mode for the file that has to be opened.

Graphs | Edit ...

The edit dialog box allows to edit all properties idividually for every single graph.
These are its:

Additionally you have the possibility to reorder the colors of the Graphs, so the color number will be set to the same value as the Graph No. The 'Delete Unused' button will delete all Graphs which are empty and contain no data.

Note, that you have to press the 'Accept Changes' button to have taken over the changes. You will see the changes after confirming with 'OK'.

Graphs | Show | Points >

Show the points from which the plot is generated. In the menu Graphs | Points Draw Rate you can set the draw-rate, which default is 1 (show every point). An additional entry is for purposes where it is convenient to see the beginning and end points of each individual graph.

Graphs | Show | Marker >

Show markers assigned to the Graphs. Markers (style and size) are automatically assigned for each Graph and can be changed in the Graphs | Edit ... dialog box. In the menu Graphs | Marker Draw Rate you can set the draw-rate, which default is 1 (show every point). See also Graphs | Marker Size.

Graphs | Show | Lines >

Hide or show the Graph lines. Hiding lines make only sense if the points or marker are set to be shown.

Graphs | Line Width

Set the line width of all Graphs to the same value. Note, you will see the 'Diverse' menu item checked if the values are not equal.

Graphs | Marker Size

Set the size of the marker of all Graphs to the same value. Note, you will see the 'Diverse' menu item checked if the values are not equal.

Graphs | Lines Draw Rate

Set the draw rate of all lines to the same value. As default every line of a graph is drawn. If you have too many data let's say more than 100000 points you possibly want to reduce the data output on screen e.g. to have a faster response (even if Funplot handles 100000 points very fast) so increase the 'Lines Draw-Rate'. Note, you will see the 'Diverse' menu item checked if the values are not equal.

Graphs | Points Draw Rate

Set the draw rate of all points to the same value. The 'Points Draw-Rate' item changes only the drawing rate of the points holding the actual line draw rates and so the actual line curvature. Useful e.g. for displaying equal distances or equal time stamps. Note, you will see the 'Diverse' menu item checked if the values are not equal.

Graphs | Marker Draw Rate

Set the draw rate of all marker to the same value. The 'Marker Draw-Rate' item changes only the drawing rate of the marker holding the actual line draw rates and so the actual line curvature. Note, you will see the 'Diverse' menu item checked if the values are not equal.

Graphs | Graph Type

Set the Graph type of all Graphs at the same, with these options:

Graphs | Handle ...

This dialog box allows to copy selected Graphs from and to the Graphs clipboard. Via this clipboard you can pass Graphs from one Plot to another or duplicate Graphs. Further you can delete Graphs as well in the Plot as in the clipboard.
Please note, that this clipboard has no relation with the Windows © clipboard.

Graphs | Copy All

Add all Graphs of the current Plot to the Graphs clipboard.

Graphs | Paste All

Add all Graphs (with all their properties) of the Graphs clipboard to the current Plot. Note, that this does not change the current view ranges.

Graphs | Empty Clipboard

Delete the content (and so all the Graphs) in the Graphs clipboard.


Extras Menu

Extras | Statistics ...

Compute and plot statistics of the Graphs. Minimum and maximum values, mean value, standard deviation and range are numerically displayed for x- and y-axes. All these values can be checked to be plot into the current plot or in another window. A further option allows to use the same color as the selected Graph itself.

Extras | Distribution ...

Plots the distribution of the Graphs points. The distribution is displayed in another Plot with bars. You can select the number of bins (and so bars) that are used to distribute the complete y-range or you can select the bin width directly as y-value.

Extras | Plot Info ...

Tells you how many graphs are in the plot and how many points contain these graphs.

Extras | Break

This special item is reserved for programmers using the Funplot C++ graphics library. When the user selects this item, the programmer (or better his program) gets a feedback that the user wants to break something, e.g. a simulation loop. It is not activated in the normal Funplot use.


Help Menu

Help | Register ...

This is the registration dialog box. Enter your registration message exactly, which you will receive, when you purchase Funplot. See here, how to register Funplot.

Help | About ...

Inform you about the actual Funplot version, the web address where you can get more information about it and where you can contact the developer and administrator of 'Funplot'. You will also see the name to whom it is registered.


Keyboard and Mouse

Status Line and Distance Mode

As default the status line shows you the actual position of the cursor in world (and not screen) coordinates. Pressing the 'Ctrl' key and clicking the left mouse button transfers you to 'Distance Mode'. In this mode you can measure the distance and the gradient between two points (one being the position where you pressed the mouse button, the other one being the actual mouse position). If you view your data in 'Axes Equal Mode' your gradient is measured in degrees otherwise you obtain the ratio between dy and dx. Leave this mode by simply clicking the left mouse button again.

Keyboard Input

The cursor keys and the 'PgUp', 'PgDn', 'Pos 1' and 'End' keys let you shift the view range, zoom into or out of your plot, to switch to your first view range or to toggle between the last two viewing ranges. The shifting value related to the cursor keys is taken from the actual main tick distance. If you press the 'Ctrl' key together with the cursor keys your viewing range will shift one complete viewing window, while pressing the 'Shift' key will shift your viewing range for about one sub-tickmark distance.

Mouse Actions

Holding down the left mouse button and dragging let you choose your desired viewing range depending on your actual Zoom Mode. Note, that you can drag the viewing range also outside your actual plot window. A double click with the left mouse button performs an Auto Range in XY. You can switch to Distance Mode by pressing the 'Ctrl' key and clicking the left mouse button (details, see above). A single click with the right mouse button zooms out. The mouse wheel is used to zoom in and out of the plot. Holding down the 'Ctrl' key while turning the wheel let's you zoom in and out at the position of the cursor.

Drag & Drop

Drag & Drop any kind of handled files into an already opened Plot or on the Funplot icon to display data, a Plot or a Session directly. Holding the 'Ctrl' key pressed while dropping, 'adds' the file to the current plot instead of replacing it. The drop of multiple files is supported.


Properties and Options

Properties Inheritance

The property values of the Plot and Graphs follow an inheritance philosophy. To assign a value, Funplot performs the following steps:

  1. Reads default values hard-coded in the Funplot source code.
  2. Looks for the initialization file Funplot.ini. Every property value found here overwrites the hard-coded value. The values now are used for newly generated plots.
  3. When an already existing Plot file is opened, the property values specified here are used for the data file belonging to this plot.
    And note, that even in the Plot file itself a further hierarchy exists: First the chapter [Graphs] is read, where specified property values are taken as default values for every single graph. Then the chapter for every single graph [Graph<X>] is read which obviously overwrites these values.

It's up to the user to modify the existing files for their dedicated purpose. Always taking in mind, that if a property value isn't specified or the property is missing, the property value of the 'level' above is used, up to the hard-coded values.

Options

The term "Options" does not really make sense in Funplot, since all properties are treated in the same way, following the properties inheritance philosophy. Anyway the properties which influence the default behaviour are called "Options" and are described hereafter together with their possible values. The default value, which reflects the hard-coded value, is underlined. Some options have slightly other values in the Funplot.ini file. You can easily modify the values in this file to your favorite default behaviour and style.

Plots

Option Description Values
xWinPos, yWinPos, xWinSize, yWinSize Position and size of the Plot in Pixel. The specified position refers to the upper left corner of the window. Integer value >= 1,
60, 60, 640, 520
dxWinPos, dyWinPos Relative position of the succeeding Plot to the current Plot. Integer value,
20, 20
printFactor Multiplication factor when printing. Used for increasing/decreasing the line width of the graphs and the coordinate frame, for the text size of titles and values and indentation from the border. The value 1.0 is suited for most purposes. Floating value > 0.0,
1.0

Axes-Systems

Option Description Values
showGrid See Plot | Show | Grid SHOW, shows the grid for both x- and y-axis
SHOW_XAXIS, shows the grid for the x-axis
SHOW_YAXIS, shows the grid for the y-axis
HIDE, does not show the grid at all.
showCoorSystem See Plot | Show | Coordinate System SHOW, to see the complete coordinate system (as default)
SHOW_HALF, to see only the left lower part of the border and the tickmarks
HIDE, in this case the complete window is used for displaying the actual range. No border, ticks and values are displayed.
showLegend See Plot | Show | Legend HIDE, the legend is hidden
SHOW_UPRIGHT, displays the legend inside the axes coordinate frame at the upper right corner
SHOW_DOWNRIGHT, ... at lower right corner
SHOW_UPLEFT, ... at upper left corner
SHOW_DOWNLEFT, ... at lower left corner
SHOW_OUTRIGHT, displays the legend outside the axes coordinate frame at the right.
aspectRatio See Plot | Axes Equal AXES_EQUAL, for equal sized axes
AXES_SCALED, in the other case.
colorScheme See Plot | Color | Color Scheme LIGHT, DARK, PAPER, SCOPE, FANCY
colorPalette See Plot | Color | Color Set MIXED_COLORS_I, set with 7 cyclic used colors (Blue, Green, Red, Cyan, Magenta, Yellow, Black. These are Matlab used default colors and order)
MIXED_COLORS_II, set with 15 cyclic used colors (Red, Green, Blue, Dark Red, Dark Green, Dark Blue, Light Red, Light Green, Light Blue, Yellow, Magenta, Cyan, Black, Gray, Light Gray)
GRAY_SCALE, scale from black via gray to white
RED_SCALE, scale from black via red to white
GREEN_SCALE, scale from black via green to white
BLUE_SCALE, scale from black via blue to white
HEAT_SCALE, scale from black via blue, cyan, green, yellow, orange, red to black again
BLACK_ONLY, uses the black color only (good for printing or including into documentation).
numColors Number of colors specified is used for subdividing the color set (see above). The color sets MIXED_COLORS_I and MIXED_COLORS_II ignore the number of colors. Integer value >= 1,
6
zoomMode See Plot | Zoom Mode ZOOM_XY, zoom in x and y direction, when the user clicks and drags the left mouse button in this mode he selects his viewing range in x and y direction.
ZOOM_XARY, zoom in x and auto range in y, let the user select the x-range, the respective y-range is calculated automatically
ZOOM_YARX, zoom in y and auto range in x, let the user select the y-range, the respective x-range is calculated automatically
ZOOM_XKR, maintain the ratio of the actual visible x- and y-range.
ZOOM_X, let the user select the x-range maintaining the actual y-range.
ZOOM_Y, let the user select the y-range maintaining the actual x-range.
zoomFactor Factor used when zooming in and out. The viewing range changes with this factor. A value of 2 doubles the range when zooming out, and halves the range when zooming in. Floating value > 1.0,
1.5
autoRangeExcess Number for excess of the viewing range when the auto range feature is used. Setting the number to 0 means no excess, the viewing range matches then exactly the smallest and biggest values of the data points. A value of 1 doubles the range. Floating value >= 0.0,
0.05
numTicks, numSubTicks Set number of ticks and number of subticks. Since every tick is accompanied by a displayed axes value, the number of ticks is also a measure of the number of displayed values. Integer value >= 1,
6, 2
maxDigits Maximum number of digits for the axes value. The number of digits is automatically calculated, but will not exceed the specified value. Integer value >= 1,
6
indentUp, indentDown, indentLeft, indentRight Sets the indentation values of the coordinate frame from the border in pixel. Note, that the indentation values are not used if the coordinate frame appearance is set to HIDE. Integer value >= 1,
40, 75, 85, 35
xLableDistance, yLableDistance Distance of the x- and y-lables from the Axes-System border in pixel. Integer value >= 1,
50, 60
axesTitleDistance Distance of the title from the Axes-System border in pixel. Integer value >= 1,
10
valueDistance Distance of the displayed axes values from the Axes-System border in pixel. Integer value >= 1,
7
legendBorderDistance Distance of the legend border from the Axes-System border in pixel. Integer value >= 1,
12
legendInnerDistance Distance of the legend internals from the legend border in pixel. Integer value >= 1,
6
legendLineSampleLength Length of the line sample in the legend in pixel. Integer value >= 1,
30
fontSize Set the size of the main font in pixel. The smaller font will be set accordingly (hard-coded at 83% of the main font). Integer value >= 1,
17
ticksSize, subTicksSize Set the length of the ticks and the subticks. A positive value causes that the ticks are going inside the Axes-System while a negative value effects that the ticks are going towards the Plot border. Integer value,
7, 4

Graphs

Option Description Values
readMode See Read Mode XYY, XYXY, XYAYA, XYAXYA, YY
type See Graphs | Graph Type LINES, lines are drawn from one point to the next
STAIRS, lines are drawn in stairs from one point to the next, holding constant the y-coordinate of the last point
BARS, similar to stairs, but the bars are drawn as columns down or up to the x-axis
STEMS, for each point lines are drawn from the x-axis to the respective point
lineWidth Width of a Graph line in pixel. Integer value >= 1,
1
pointsSize Size of a point in pixel, when these are displayed. Integer value >= 1,
3
markerSize Size of a marker in pixel, when these are displayed. Integer value >= 1,
7
linesDrawRate See Graphs | Lines Draw Rate Integer value >= 1,
1
pointsDrawRate See Graphs | Points Draw Rate Integer value >= 1,
1
markerDrawRate See Graphs | Marker Draw Rate Integer value >= 1,
1
showLines See Graphs | Show Lines SHOW, show the lines
HIDE, hide the lines
showPoints See Graphs | Show Points SHOW, show all the points
SHOW_BEGIN_END, show only the begin and end points of the graph
HIDE, does not show the points
showMarker See Graphs | Show Marker SHOW, show the marker
HIDE, hide the marker

Funplot is not free software! Please read carefully the License Agreement!

e-mail:   support@VanillaWare.de
www:   http://www.VanillaWare.de

Copyright © 1998-2006 Domenico Reggio, Software-Engineering.