Plot2D

by Glenn D. MacGougan

Introduction

Plot multiple data series from ASCII text files directly to a compressed BITMAP file. The core code is ANSI C with C++ code provided for ease of use and encapsulation. The source code can be compiled across many operating systems and platforms. OS independant and platform independant. Windows exectuable and linux binaries available.

The 'BSD-style' license allows non-restrictive use for commercial and open source development.

I wanted a 2D plotting program with the following characteristics:

Easy to learn. Get started in 5 minutes or less.

BSD license, so my friends in industry can use it without restriction.

No requirements to learn complicated command line syntax.

Configure from an easy to use ASCII option file. (e.g. option file)

Configure from the command line with options.

Standalone, it has it's own font and graphics (all wrtten in C).

Platform independant AND very easy for most Windows users.

Supports plotting of multiple series without having to think much about it.

Supports almost all delimiters, e.g. ',', whitespace, ';', ':'

Allows a header comment line (but otherwise no non-numeric data).

Plots that include the statistics.

Quick.

Runs from the console/terminal.

Configure and run from a GUI to test options and get the desired output. (win32 for now).

Download It!

Getting Started

Windows uses can download the application and a GUI to configure the options directly.
For other systems, download the source and compile it for your system (../apps/plot2d/unix/make release).
(Sourceforge Download Page)
Get your ASCII data file, e.g. data.txt, (data must be column aligned).
Open a command prompt or terminal where your data is.
Run: plot2d data.txt // The program will plot the first column vs the second or the only column vs its index (or only row vector vs its index).
Run: plot2d -h // All the options for running the program are listed.
Run: plot2d data.txt 1 3 // Plot column 1 vs column 3.
Run: plot2d data.txt 1 2 1 3 1 4 // Plot column 1 vs 2, 1 vs 3, and 1 vs 4.
Run: plot2d -c plot2d_options.txt // Generate a default options file.
Run: plot2d -f plot2d_options.txt // Generate the plot using the easy to use option file.
Run: plot2d --stdin 1 2 1 3 // Plot columns 1 vs 2 and 1 vs 3 from standard input. An empty line will terminate input.
Run: plot2d data.txt 1 2 1 3 --xmin -10 --xmax 10 --ymin -1 --ymax 1 --title "The Title" --xlabel "Time (s)" --ylabel "Voltage (V) // Plot with lots of options.

PLOT2D HELP

Since     2007-12-19 
Author    Glenn D. MacGougan (GDM) 
Copyright 2008, all rights reserved 
License: 'BSD license' 
THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS ``AS IS'' AND ANY EXPRESS 
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
DISCLAIMED. IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 
SUCH DAMAGE. 
 
USAGE: Plot2D <ascii data.txt> 
   plot 1st vs 2nd column of data.txt 
 
USAGE: Plot2D <ascii data.txt> N M 
   plot N'th vs M'th column of data.txt 
 
USAGE: Plot2D data.txt --option <args> A B C D ... 
   plot A'th vs B'th and C'th vs D'th columsn of data.txt with options. 
 
USAGE: Plot2D --stdin --option <args> A B C D ... 
   plot A'th vs B'th and C'th vs D'th columsn from standard input data with options. 
 
USAGE: Plot2D -f <option file name> 
-f specifies that the name of the ASCII option file is to follow. 
 
USAGE: Plot2D -c <option file name> 
-c specifies that a default option file is to be created with the name specified. 
 
ALL OPTIONS: 
-short version, --long version, <parameter(s)>, description 
-f  --optfile    <option file to use>, all other options ignored 
-c  --create     <filename>, create opt file, all other options ignored 
-i  --stdin      <N> <M>, plot N vs M columns from the standard input 
                 (N & M are optional 1 vs 2 or 1 vs index are default) 
                 reads data line by line columnwise, 
                 empty line or end of file will stop input 
-o  --out        <the output bitmap file path> 
-T  --title      "the title in quotes" 
-x  --xlim       <lower_limit> <upper_limit> 
    --xmin       <lower_limit> 
    --xmax       <upper_limit> 
-X  --xtick      <tick_start> <tick_size> <tick_end> 
-m  --xlabel     "the label in quotes" 
-g  --xgrid      <0 is off, 1 is on> 
-y  --ylim       <lower_limit> <upper_limit> 
    --ymin       <lower_limit> 
    --ymax       <upper_limit> 
-Y  --ytick      <tick_start> <tick_size> <tick_end> 
-r  --ylabel     "the label in quotes" 
-v  --ygrid      <0 is off, 1 is on> 
-s  --stats      <0 is off, 1 is on> 
-G  --gpslabel   <0 is off, 1 is on> <utc_offset_always_positive> 
-B  --bcolor     <color> // the figure background color, default is white 
-L  --slabel     <series_index_1_to_N> "the label in quotes" 
-P  --sprecision <series_index_1_to_N> precision (0 integer, 1 tenths, etc) 
-C  --scolor     <series_index_1_to_N> color 
 
color is one of: white, black, blue, green, purple, magenta, darkblue, 
indianred, babyblue, paislyblue, lightpurple, darkpurple, greypurple, brown 
red, pink, yellow, orange, cyan, limegreen, grey, lightgrey

Examples

Run: plot2d data.txt // The program will plot the first column vs the second column.

Run: plot2d data.csv 1 2 1 3 1 4 // Plot column 1 vs 2, 1 vs 3, and 1 vs 4.

Run: plot2d data.csv 2 3 --xlim -2 2 --ylim -2 2 --xtick -2 0.5 2 --ytick -2 0.5 2 --scolor 1 orange --xlabel "Cosine" --ylabel "Sine" --slabel 1 "cosine vs sine" --title "A circle" --stats 0 --out orange.bmp // Plot with lots of command line options.

Run: plot2d -f plot2d_options.txt // Generate the plot using the easy to use option file

Options for the plot below | sine.txt | cosine.txt | sinc.txt

The interface for Windows.

SourceForge

The project is developed via http://sourceforge.net/projects/plot2d

Download

View all the files

Sourceforge Download Page

Options File

Plotting options are set using a simple ASCII options file.

View Example Options

Subversion

To become a developer email glenn_macgougan at sourceforge.net.

Example subversion checkout: svn co https://plot2d.svn.sourceforge.net/svnroot/plot2d/trunk plot2d

Try it Online

Upload one data file from which you can plot up to 12 series.

Upload file

Edit Options

; PLOT2D OPTIONS FILE
;______________________________________________________________________________
; FORMAT
; 
; OPTIONFIELD, COMMENT = VALUE ; POST_VALUE_COMMENT
; OPTIONFIELD        - a valid identifier, no spaces
; COMMENT            - a good place to put the units
; VALUE              - the option value, a number, a string, an 
;                      array, a boolean (yes/no, 1/0)
; POST_VALUE_COMMENT - a comment following the value
; 
; Anything after a ';' is a comment.
;______________________________________________________________________________
; PLOT2D COLOR CHOICES
; White; Black; Blue; Green; Purple; Magenta; DarkBlue; IndianRed; BabyBlue
; PaislyBlue; LightPurple; DarkPurple; GreyPurple; Brown; Red; Pink; Yellow
; Orange; Cyan; LimeGreen; Grey; LightGrey
;______________________________________________________________________________
;
; GENERAL PLOT2D OPTIONS
;______________________________________________________________________________

OutputFileName,  (the bitmap file, do not change this)        = result.bmp
NumberOfSeries,  (number of active series as specified below) = 1  ; up to 12
PlotSize_Width,  (cm, 15 is a good value)                     = 11
PlotSize_Height, (cm, 13 is a good value)                     = 9
Title,           (a string, or empty if none)                 = Test Plot

X_IsGridOn,      (enable/disable horizontal gridlines)        = yes
X_Label,         (a string, or empty if none)                 = Time (s)
; LowerLimit, UpperLimit, TickStart, TickSize, and Tickend
; values can be determined automatically, by the data values
; in the first series, by specifying 'default'.
X_LowerLimit,    (lower plotting limit or 'default')          = default
X_UpperLimit,    (upper plotting limit or 'default')          = default
X_TickStart,     (start xtick label value or 'default')       = default
X_TickSize,      (xtick size value or 'default')              = default
X_TickEnd,       (end xtick label value or 'default')         = default

Y_IsGridOn,      (enable/disable horizontal gridlines)        = yes
Y_Label,         (a string, or empty if none)                 = Data (units)
; LowerLimit, UpperLimit, TickStart, TickSize, and Tickend
; values can be determined automatically, by the data values
; in the first series, by specifying 'default'.
Y_LowerLimit,    (lower plotting limit or 'default')          = default
Y_UpperLimit,    (upper plotting limit or 'default')          = default
Y_TickStart,     (start xtick label value or 'default')       = default
Y_TickSize,      (xtick size value or 'default')              = default
Y_TickEnd,       (end xtick label value or 'default')         = default
  
; ADVANCED PLOT2D OPTIONS
;______________________________________________________________________________
; Enabling PlotStatistics add a small table to the right of 
; plot including min, max, mean, rms, and standard deviation.
PlotStatistics,  (include statistics)                         = yes  ;yes/no
PlaceLabelBelowThePlot, (usually on the right)                = no  ;yes/no
FigureBackgroundColor,  (see above)                           = White

; Enabling X_UseGPSLabel assumes that the X part of the 
; series is a GPS time of week, (0-604800 s), and will
; compute the corresponding UTC time and include it 
; below each xtick.
X_UseGPSLabel,   (include UTC time below GPS time of week)    = no  ;yes/no
X_GPSUTCOffset,  (specify the GPS/UTC Offset, always +ve)     = 14  ;ignored if no above

; Data can be plotted with respect to y ticks on the right 
; hand side of the plot window. 
; For example, plot elevation angle (0-90, left side y ticks) 
; and plot azimuth angle (-180-180, right side y ticks). 
;
; rhs_ytick = lhs_ytick * scale_factor + offset
; e.g.
; Y_Label,              = "Elevation (deg)"
; Y_RightYLabel,        = "Azimuth (deg)"
; Y_RightYOffset,       = -180
; Y_RightYScaleFactor,  = 4
Y_RightYLabel,       (enable the right Y label if not empty)  = 
Y_RightYScaleFactor, (scale the lhs y ticks by)               = 1
Y_RightYOffset,      (offset the lhs y ticks after scaling)   = 0
  
; SERIES INFORMATION (Up to 12 Series)
; Data for a series is contained within one file and must be column based.
; Data must be an ASCII data file.
;______________________________________________________________________________

Series1_DataPath,    (do not change this)                    = data.txt
Series1_X_Column,    (1 based index of the X data)           = 1    ;must be>0
Series1_Y_Column,    (1 based index of the Y data)           = 2    ;must be>0
Series1_IsConnected, (connected with a line, yes/no)         = yes  ;yes/no
Series1_Color,       (see above)                             = Blue
Series1_Label,       (a string, or empty if none)            = DataLabel
Series1_Units,       (a string, or empty if none)            = (units)

; The following option applies if PlotStatistics is enabled.
Series1_Precision,    (max nr of significant digits)         = 3 
; Data outside the plot window can be indicated (in Cyan) 
; along the plot borders by enabling the following option.
Series1_MarkOutlierData, (data out of plot range is marked)  = yes  ;yes/no
Series1_UsesRightYLabel, (pertains to the right ylabel)      = no   ;yes/no

; To add more series, change "NumberOfSeries" above and then 
; fill the fields below.
Series2_DataPath,    (do not change this)                    = data.txt
Series2_X_Column,    (1 based index of the X data)           = 1    ;must be>0
Series2_Y_Column,    (1 based index of the Y data)           = 3    ;must be>0
Series2_IsConnected, (connected with a line, yes/no)         = yes  ;yes/no
Series2_Color,       (see above)                             = LimeGreen
Series2_Label,       (a string, or empty if none)            = A label
Series2_Units,       (a string, or empty if none)            = (units)

; The following option applies if PlotStatistics is enabled.
Series2_Precision,    (max nr of significant digits)         = 3 
; Data outside the plot window can be indicated (in Cyan) 
; along the plot borders by enabling the following option.
Series2_MarkOutlierData, (data out of plot range is marked)  = yes  ;yes/no
Series2_UsesRightYLabel, (pertains to the right ylabel)      = no   ;yes/no

Plot2D Help Output

More Examples

MTXFX

If you like this application, you're sure to enjoy www.mtxfx.com. An online application for numerical analysis and data visualization.

License

Redistribution and use in source and binary forms, with or without modification, are permitted provided the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
The name(s) of the contributor(s) may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.