Funplot - 2D data plotting environment, version 1.0
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.
The following terms describe the anatomy of a plot. The terms are reused within the further description (please note the capitalized starting letter).
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.
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.
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.
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.
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:
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. |
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.
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).
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.
Closes all windows belonging to the Session asking the user for confirmation when more than one window exists.
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.
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).
Gives the possibility to give the plot a title, to name the x- and the y-axis and to give the window a name.
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.
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.
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.
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.
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.
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.
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'.
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.
Restore the last viewing range, for e.g. after auto range or mouse zoom.
Restore the original viewing range. The original range is set, when a file is opened.
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.
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.
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.
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.
Place the Plot at specified locations on screen.
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 ©.
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.
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.
Generate a new Plot, using the default Funplot settings.
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.
Close the window without saving the plot and without asking the user for confirmation.
Replace or add data files (and so Graphs) to your plot.
Save the data from the plot to file. See *.dat files details.
Set the Read Mode for the file that has to be opened.
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'.
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.
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.
Hide or show the Graph lines. Hiding lines make only sense if the points or marker are set to be shown.
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.
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.
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.
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.
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.
Set the Graph type of all Graphs at the same, with these options:
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.
Add all Graphs of the current Plot to the Graphs clipboard.
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.
Delete the content (and so all the Graphs) in the Graphs clipboard.
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.
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.
Tells you how many graphs are in the plot and how many points contain these graphs.
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.
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.
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.
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.
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.
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 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.
The property values of the Plot and Graphs follow an inheritance philosophy. To assign a value, Funplot performs the following steps:
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.
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.
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, |
dxWinPos, dyWinPos | Relative position of the succeeding Plot to the current Plot. | Integer value, |
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, |
Option | Description | Values |
showGrid | See |
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 |
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 |
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 |
AXES_EQUAL, for equal sized axes AXES_SCALED, in the other case. |
colorScheme | See |
LIGHT, DARK, PAPER, SCOPE, FANCY |
colorPalette | See |
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 |
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, |
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 |
Option | Description | Values |
readMode | See |
XYY, XYXY, XYAYA, XYAXYA, YY |
type | See |
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 |
Integer value >= 1, 1 |
pointsDrawRate | See |
Integer value >= 1, 1 |
markerDrawRate | See |
Integer value >= 1, 1 |
showLines | See |
SHOW, show the lines HIDE, hide the lines |
showPoints | See |
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 |
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.