GAUSSplotTM Professional Graphics Aptech Systems, Inc. — Mathematical and Statistical System Information in this document is subject to change without notice and does not represent a commitment on the part of Aptech Systems, Inc. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of the agreement. The purchaser may make one copy of the software for backup purposes. No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose other than the purchaser’s personal use without the written permission of Aptech Systems, Inc. c Copyright 2005-2006 by Aptech Systems, Inc., Maple Valley, WA. All Rights Reserved. ENCSA Hierarchical Data Format (HDF) Software Library and Utilities Copyright (C) 1988-1998 The Board of Trustees of the University of Illinois. All rights reserved. Contributors include National Center for Supercomputing Applications (NCSA) at the University of Illinois, Fortner Software (Windows and Mac), Unidata Program Center (netCDF), The Independent JPEG Group (JPEG), Jean-loup Gailly and Mark Adler (gzip). Bmptopnm, Netpbm Copyright (C) 1992 David W. Sanderson. Dlcompat Copyright (C) 2002 Jorge Acereda, additions and modifications by Peter O’Gorman. Ppmtopict Copyright (C) 1990 Ken Yap. GAUSSplot, GAUSS and GAUSS Engine are trademarks of Aptech Systems, Inc. Tecplot RS, Tecplot, Preplot, Framer and Amtec are registered trademarks or trade- marks of Amtec Engineering, Inc. Encapsulated PostScript, FrameMaker, PageMaker, PostScript, Premier–Adobe Sys- tems, Incorporated. Ghostscript–Aladdin Enterprises. Linotronic, Helvetica, Times– Allied Corporation. LaserWriter, Mac OS X–Apple Computers, Incorporated. Au- toCAD, DXF–Autodesk, Incorporated. Chears–ChevronTexaco Corporation. Com- paq Computer Corporation. Elan License Manager is a trademark of Elan Computer Group, Incorporated. Alpha, DEC, Digital, LaserJet, HP-GL, HP-GL/2, PaintJet– Hewlett-Packard Company. X-Designer–Imperial Software Technology. Builder Xcessory– Integrated Computer Solutions, Incorporated. IBM, RS6000, PC/DOS–International Business Machines Corporation. Bookman–ITC Corporation. VIP–Landmark Graph- ics Corporation. X Windows–Massachusetts Institute of Technology. MGI VideoWave– MGI Software Corporation. ActiveX, Excel, MS-DOS, Microsoft, Visual Basic, Vi- sual C++, Visual J++, Visual Studio, Windows, Windows Metafile–Microsoft Cor- poration. HDF, NCSA–National Center for Supercomputing Applications. UNIX, OPEN LOOK–Novell, Incorporated. Motif–Open Software Foundation, Incorporated. Gridgen–Pointwise, Incorporated. Eclipse, FrontSim–Schlumberger, Limited. IRIS, IRIX, OpenGL–Silicon Graphics, Incorporated. Open Windows, Solaris, Sun, Sun Raster–Sun MicroSystems, Incorporated. All other product names mentioned herein are trademarks or registered trademarks of their respective owners. Part Number: 005712 Version 8.0 Documentation Revision: 860 July 20, 2007 Contents Contents 1 Overview 1.1 Getting Started ................................... 1-3 1.1.1 Setup and Initialization . 1-3 1.1.2 Creating Data .............................. 1-4 1.1.3 Setting Plot Options . 1-5 1.1.4 Plotting the Graph ............................ 1-6 1.2 What Next ..................................... 1-7 1.2.1 Customizing Your Graph . 1-7 1.2.2 GP Tools ................................. 1-8 1.3 Data Files ..................................... 1-8 1.3.1 Structure of a Data File . 1-8 1.3.2 Data File Creation Commands . 1-9 1.3.3 Inputting Data . 1-11 1.4 Basic Structure of a Graph . 1-18 1.4.1 Workspace . 1-18 1.4.2 Frame . 1-18 1.5 Plot Types ..................................... 1-19 1.5.1 Basic Plot Types . 1-19 1.5.2 Line Plots . 1-19 1.5.3 Field Plots . 1-19 1.5.4 GAUSSplot Plot Types . 1-22 1.6 Categorization of Commands . 1-31 1.7 Working With Structure Pointers . 1-33 1.8 Structure Files . 1-34 1.9 Error Handling . 1-35 1.10 Examples ...................................... 1-35 1.10.1 Line Plots . 1-35 1.10.2 Field Plots . 1-41 1.10.3 Graphs Containing Different Plot Types . 1-44 v GAUSSplot 8.0 2 Command Overview 2.1 Commands ..................................... 2-1 2.1.1 Setup and Initialization . 2-1 2.1.2 Creating Data Files . 2-2 2.1.3 Specifying Data and Macro Files . 2-3 2.1.4 Adding Frames to a Graph . 2-3 2.1.5 Setting Line Map Options . 2-4 2.1.6 Setting Field Zone Options . 2-9 2.1.7 Setting Axes Options . 2-15 2.1.8 Sizing and Positioning the Graph . 2-23 2.1.9 Animation . 2-24 2.1.10 Setting Frame Options . 2-24 2.1.11 Adding Text . 2-25 2.1.12 Adding Arrows . 2-26 2.1.13 Adding Line Segments . 2-26 2.1.14 Adding Other Geometries . 2-27 2.1.15 Printing and Exporting . 2-27 2.1.16 Plotting the Graph . 2-29 2.1.17 Miscellaneous Commands . 2-30 2.2 Global Variables . 2-31 2.2.1 GAUSSplot Colors . 2-31 2.2.2 GAUSSplot Fonts . 2-32 2.2.3 GAUSSplot Line Patterns . 2-33 2.2.4 GAUSSplot Symbols . 2-33 2.2.5 GAUSSplot Error Messages . 2-34 2.2.6 GAUSSplot Debugging . 2-35 3 Command Reference A Character Table vi Contents B Obsoleted Commands Index vii Overview Overview 1 GAUSSplot is simple enough to allow users to create a graph with only a few lines of code, yet flexible enough to allow for the creation of elaborate graphs incorporating different types of plots. Users can add text, legends, arrows and symbols to a graph, as well as configure a wide variety of output and view options. To illustrate GAUSSplot’s ease of use, let us begin by demonstrating how to create a simple XY Line plot. The graph in Figure 1.1 is generated by these lines of code: // Set up library and include file with structure definitions library gaussplot; #include gp.sdf // Create gpPlotControl structure and set members to default // values struct gpPlotControl gp; gp = gpXYLinePlotCreate; // Generate data x = seqa(0.2,.2,15); 1-1 GAUSSplot 8.0 Frame 001 12 Sep 2006 gp06ac010F52F84506e17c0030d -0.4 -0.6 -0.8 V2 -1 -1.2 0.5 1 1.5 2 2.5 3 V1 Figure 1.1: Simple XY Plot 1-2 Overview Overview y = log(x/5); // Write data to data file and create graph ret = gpMakeXYLinePlot(&gp,x,y,""); This example is a slightly simplified version of xylineplot1.e, which can be found in the gaussplot/examples subdirectory of your GAUSS installation directory. For more examples, see Section 1.10 or your gaussplot/examples subdirectory. 1.1 Getting Started There are four steps to creating a graph with GAUSSplot: 1. Setup and initialization 2. Creating data and writing the data file 3. Setting various plot options 4. Plotting the graph These must all be present in any program that creates a graph using GAUSSplot, with the exception of the second step if the necessary data file already exists. 1.1.1 Setup and Initialization The setup and initialization process must include the following calls: library gaussplot; #include gp.sdf struct gpPlotControl gp; 1-3 GAUSSplot 8.0 as well as a call to the appropriate gpPlotTypePlotCreate command for the type of graph that is to be created. For instance, if you wanted to create a 3D Cartesian graph, you would add the following line to the above: gp = gp3DCartesianPlotCreate; See Section 1.5.4 for a list of all of the plot types that are supported in GAUSSplot and Section 2.1.1 for the available gpPlotTypePlotCreate commands. 1.1.2 Creating Data If the necessary data file does not already exist, then the next step is to create data. If you are going to use gpPlot to plot the graph (see Section 1.1.4), then you must also write the data file at this point in your program. However, if you use one of the gpMakePlotTypePlot commands to plot the graph, then it will write the data to a data file for you, and you need only to generate that data. The following code creates data for a data file with one zone, containing three variables, and writes the data file: struct gpData gdat; // Generate data for 3D Cartesian frame a = seqa(0,pi/12,25)’; r = seqa(6,-0.25,25); x = r.*cos(a); y = r.*sin(a); z = rev(1.5*r).*ones(25,25); // Put data into an array a = aconcat(x,y,3); a = aconcat(a,z,3); // List variable names string vnames = { "X", "Y", "Z" }; 1-4 Overview Overview // Set data in gpData structure gdat = gpInitPlotData(vnames); ret = gpAddZone(&gdat,"Zone One",a); // Write data file ret = gpWritePlotData(&gdat,"mydata.plt"); For an explanation of zones and data file structure, see Section 1.3. 1.1.3 Setting Plot Options GAUSSplot contains many plot option commands, which allow you to specify the number of line maps or field zones that are displayed in a plot and how they are to be displayed. For an explanation of line maps and field zones, see Section 1.5.4. Most of these commands are optional. GAUSSplot will use defaults for all options that have not been explicitly set. However, if you use gpPlot to plot your graph, then it is necessary to call gpSetDataFile before calling gpPlot in order to specify which data file(s) are to be used for the graph. It is at this stage in a GAUSSplot program that you need to add frames for a multiple frame graph (see Section 1.4 for an explanation of frames). If you use gpPlotCreate to initialize your plot control structure, then your graph does not contain any frames by default. Therefore, you need to use the various gpAddPlotTypeFrame commands to add frames before plotting the graph.