CLPLOT : a 2-D graphics plotter

*********************************************************************** >>>>> Version 1 <<<<< >>>>> July 1998 <<<<< ***********************************************************************

Stavros C. Farantos

Institute of Electronic Structure and Laser Foundation for Research and Technology Hellas P.O. BOX 1527 Iraklion 711 10, Crete GREECE Tel : 0030-81-39 1813 (personal ) : 0030-81-39 1301-3 (secretary) : 0030-81-23 8468 (Chemistry) : Fax : 0030-81-39 1305 E-mail : farantos@iesl.forth.gr WWW URL: http://www.cc.forth.gr/~TCCC/ ***********************************************************************

Definitions

canvas is the total plotting area which appears when you run clplot.tcl frame is part of the canvas area. canvas is divided in n_row and n_column frames separated by n_gap pixels. graph is the result of plotting one data_set. data_sets may be in one file or in separate files. clplot.tcl is a tcl-tk script for 2-D and 3-D graphical displays of data, images and bitmaps based on tcl8.0.4 tk8.0.4 libraries and the patch file tk8.0.4dash.patch. It reads multiple sets of data stored in one or more files which may be plotted in one frame or in separate frames arranged in n_row and n_column. You can edit (select-cut-paste-move) any canvas-object (text-point-line-image-bitmap-window) as well as a canvas-frame. Canvas-objects and canvas-frames may be stored in the clipboard and restored anywhere on the canvas area or in a new canvas of another clplot.tcl application. To see the current bindings of the mouse buttons PRESS button (?) and select [bindings]. ***********************************************************************

CONTENTS

FILES INPUT FILES AND HOW TO CHANGE GRAPH'S PARAMETERS ENTRY WIDGETS HOW TO PLOT PARAMETERS (THE I/O WIDGET) BUTTONS - UPPER PART BUTTONS - LOWER PART BINDINGS FOR CANVAS OBJECTS ***********************************************************************

***** FILES *****

*********************************************************************** clplot.inc: defines fonts-colors-images and some global variables. : it is read with a source statement in the program : clplot.tcl and in the subprocedure plotcomm. *.clplot : the file which initializes the parameters of graphs and : it has usually, but not necessarily, the extension : *.clplot is given as the first argument ($argv 0) : in calling clplot.tcl from a terminal or is : selected from the filemanager BOSS. If this file is : NOT given, then, the permanent file : $HOME/tcl-tk/graphics/input.clplot is read. : : the next second argument ($argv 1) which may be given : is the maximum number of graphs (max_graph) to be plotted. : : the third argument ($argv 2) is a list of filenames : (file_list) with the names of input data_file(s). : however you may select data_files after opening clplot; : see below. data_files: files which contain two columns of data (the (x,y) : coordinates). : sets of points which correspond to different graphs are : separated by an empty line. *.cobj : the extension of files where a whole graph is saved in : tk-form language. : this file is APPENDED every time you save : a graph (with the menubutton *Save*[GraphSave]). : if a file in the file_list has the extension *.cobj, : PRESS button R_COBJ if you want to read it. : clplot.tcl plots it and adds the data_file name in the : list of filenames (menubutton *Data*). : this option is used if you want to continue later on : interrupted work. *.canvas : the extension of files where everything on canvas : (many graphs) is stored in tk-form language. : this file is APPENDED every time you press the menubutton : *Save*[CanvasSave]. : if a file in the file_list has the extension *.canvas, : PRESS button R_COBJ if you want to read it. : clplot.tcl plots it, updates the value of the variable : max_graph and adds all the data_file names : in the list of filenames (menubutton *Data*). : this option is used if you want to continue later on : interrupted work. *.bobj : the extension of files where a selected area on the : canvas is saved in tk-form. This happens by using the : menubutton *Save*[BoxSave]. These files are created with : the canvas-edit facilities in the menubutton *EditC* and : are read by pressing button R_BOBJ. ***********************************************************************

***** INPUT FILES AND HOW

TO CHANGE GRAPH'S PARAMETERS *****

*********************************************************************** ->->->->->-> You can call clplot.tcl from an xterm or from the file-manager BOSS where you can also select at the same time the input data_file(s): with NO arguments, e.g. $HOME/tcl-tk/graphs/clplot.tcl with ONE argument, the file which initializes the parameters of the graph, e.g. $HOME/tcl-tk/graphs/clplot.tcl input.clplot (or any other name with or not the extension .clplot) it is recommended to use one such file for each application. you then store in it possible changes of the parameters for future use when you want to replot the graphs with THREE arguments, the file *.clplot, the total number of selected files and a list with the names of the input data_files, e.g. $HOME/tcl-tk/graphs/clplot.tcl input.clplot $max_graph $file_list ! if you run clplot.tcl from BOSS you MUST give at least one argument.! ->->->->->-> if one or more selected files have the extension *.cobj, clplot reads them with the button *R_COBJ* and adds the input data_file(s) name(s) in the list of filenames (menubutton *Data*). this option is used if you want to continue interrupted work. ->->->->->-> if one selected file has the extension *.canvas, clplot reads it with the button *R_COB*, updates the value of the variable max_graph and adds all the data_file names used in the graphs in the list of filenames (menubutton *Data*). this option is used if you want to continue interrupted work. ->->->->->-> if one or more selected files have the extension *.bobj clplot reads them by pressing the button *R_BOBJ*. ->->->->->-> With the clplot.tcl widget on, you can add a new data_file name in the list of menubutton *Data*; (i) by typing its name in the entry widget (next to *Files* menubutton), this entry stores the name of the current data_file, variable $file; (ii) in the entry of the *I/O* widget and then selecting from the menu *Data_Var* the choice *current-files*; (iii) by using the browser *FileSelect* from the menu selection *Files*. After entering a new name of data_file in the entry widget press the menubutton *EditM* selection *add* to add it in the list of filenames (menubutton *Data*). You can delete the shown filename in the entry widget by the menu editor *EditM* selection [delete]. ->->->->->-> You can inspect the values of the parameters of a graph by pressing the appropriate menubutton of the *I/O* widget. To change the parameters of the graph FIRST put the new value in the entry of the *I/O* widget and THEN select from the menu the name of the parameter which is to be changed. This immediately changes the value and you can see the new parameter values by PRESSing again the *I/O* button. ->->->->->-> If you have data_files with multiple columns (x1,x2,...,y1,y2,...) use the unix command "awk" to select the two columns to be plotted. Select columns c1 and c2 transformed by the expressions f1 and f2 using the command "awk '{print c1^f1,c2^f2}' < input_file > (or >> to update an old file) output_file", where "^" is an arithmetic operation (+,-,*,/). ->->->->->-> You can plot contour plots by creating first (x,y) files for the contours by editing and running the program cont_surf_clplot.f which calls the routine contor. Similarly, you can plot 3-D graphs with dots or lines by running the program cont_surf_clplot.f which calls the subroutine purjoy. ->->->->->-> The bindings of the mouse buttons are defined from the menubutton *EditC*. The selection [CanvasEditBind] is for text-editing. The selection [CanvasBind] is for bindings on all graphical objects. The selection [CanvasBindDelete] erase all bindings. ***********************************************************************

***** ENTRY WIDGETS *****

*********************************************************************** There are three entry widgets in CLPLOT.TCL One on the top-left which keeps the name of the current data_file (variable $file). Two at the bottom which keep the x- and y-coordinates of the current point in the coordinate space of the current frame. Thus, if you change frame you change the coordinates' origin in a multiframe plot. ***********************************************************************

***** HOW TO PLOT *****

*********************************************************************** Step 1: CHOOSE the number of frames arranged in rows and columns and where to put the current graph. You can increase (+) or decrease (-) by one the number of rows and columns from the menubutton *Frames*. From the same menubutton you define the gap between successive frames. The frames are arranged in (i_row,i_column) order and the active frame is defined from the menubutton *Gfrm*. Step 2: CHOOSE the data_file to be plotted in the active frame from the menubutton *Data*. The name of the data_file appears on the entry widget on the left. You can edit the list of data_files from the menubutton *EditM* where you can [add] or [delete] data_file names. Step 3: PRESS button READ (or R_COBJ or R_BOBJ) to read the data_file and to transform the point to the canvas coordinate system if the file is in tk-form (for example those which have the extension *.cobj, *.canvas), then, PRESS button R_COBJ. Similarly for files *.bobj PRESS button R_BOBJ. Step 4: PRESS button Plot for a new plot button Overlay to put several data_files on the same plot and with fixed (xmin,xmax), (ymin,ymax). button Refresh replots periodically the current frame at every $rate milliseconds (ms). Remark: Steps 1 and 2 may be reversed. Remark: The ranges of the x- and y-axis, (xmin,xmax), (ymin,ymax), are adjusted every time a new data set is read from the same file or different files and the parameter xyminmax_fix is zero. They may be fixed to prespecified values by setting the parameter xyminmax_fix equal to 1. ***********************************************************************

***** PARAMETERS (I/O WIDGET) *****

*********************************************************************** You can change the initial values of the graph parameters from these menubuttons. Use the power of the tk widgets by detouching the menu (clicking at the broken line) to have it in a permanent view. FIRST give the new value in the entry widget of *I/O* and THEN click on the appropriate menu the parameter you want to change. In this way YOU AVOID OF CREATING AND CLICKING ON MANY WINDOWS! To inspect the new values of the modified parameters you must press again the *I/O* button.
//////// Font \\\\\\\
A new widget appears which shows all the fonts available in your system. The selected font is automatically stored in the entry widget of *I/O*. To change the previous font you either press the button *Font* on the Font widget or you select from the *Data_Var* menu in the *I/O* widget.
//////// Color \\\\\\\
A new widget appears which shows the available named colors in your system. After selecting a color you may double click on it to see the color and store its name in the entry widget of *I/O*. Then, you click on the appropriate variable in the menubutton *Plot_Var* or *Frame_Var* on which the chosen color will apply. Continue with new colors.
//////// Frame_Var \\\\\\\\
ALL_VAR : edit with your editor the input file, *.clplot CLPLOT : call clplot.tcl to open a new canvas widget color_bg: background color color_fg: foreground color width, height: canvas dimensions xred yred: scale parameters, width/xred, height/yred, to define the : dimensions of a frame. currently are : xred = n_row and yred = n_column. box-xscale-: a x reduction factor for a selected box [BoxSelect] on : the canvas (see *EditC* menubutton). box-yscale-: a y reduction factor for a BoxSelected area box-xscale+: a x magnifying factor for a BoxSelected area box-yscale+: a y magnifying factor for a BoxSelected area rate : refresh canvas every $rate ms n_column: number of column frames n_row : number of row frames n_gap : separation of the frames in pixels
//////// Axis_Var \\\\\\\\
xyminmax_fix: 1 for fixed (xmin-xmax,ymin-ymax) values, 0 otherwise xmin,xmax: range in the x-axis ymin,ymax: range in the y-axis xtick,ytick: number of major ticks in x-,y-axis xaccur,yaccur: format of the numbers in the x,y axis width_axis: the width of axes' lines width_tick: the width of the tick lines tickh : the height of the tick lines ptitle : graph title x_axis : x-axis title y_axis : y_axis title
//////// Plot_Var \\\\\\\\
dash : assign a pattern to the -dash parameter(line,rect,oval,arc) : -dash . = -dash {2 4} : -dash - = -dash {6 4} : -dash -. = -dash {6 4 2 4} : -dash -.. = -dash {6 4 2 4 2 4} : -dash {. } = -dash {2 8} : -dash , = -dash {4 4} curves : 1 to draw curves (solid or dashed lines) : 0 no lines points : 1 to draw points : 0 no points lsize : the width of lines psize : the width of points symbol : the type of symbol for the points : oval : rect : triup : tridown : diam : 0 -> "x" : 1 -> "+" : 2 -> "o" : 3 -> "." : 4 -> "#" : 5 -> "*" width_outline : the width of the outline of the symbols t_leave : the color when cursor leaves the text object t_enter : the color when cursor enters into the text object p_leave : the color when cursor leaves the point object p_enter : the color when cursor enters into the point object l_leave : the color when cursor leaves the line object l_enter : the color when cursor enters into the line object c_line : the color of lines c_text : the color of text c_char : the color of characters c_symbol : the color of symbols c_outline : the color of the outline of a symbol c_fill : the list of colors to fill an object area_fill : 1 for filling the interior of a polygon with the : selected fill color (c_fill) : 0 no filling
//////// Data_Var \\\\\\\\
legend : the list of legends for graphs used in association : with the *Win* menubutton fonts : canvas font images : the list of image (*.gif) files bitmaps : the list of bitmap (*.xbm) files max_graph : maximum number of graphs to be drawn file : the name of the current data_file
//////// Write \\\\\\\
store the parameter values in the input file *.clplot ***********************************************************************

***** BUTTONS - UPPER PART *****

*********************************************************************** TC3: call netscape to link to TCCC Quit: abandon clplot I/O: edit the input file *.clplot to change the values of the : parameters of the graphs Save: save a selected box with the choice [BoxSelect] of the : menubutton *EditC* in the file which has the name of the : input data_file ($rootname) and extension *.bobj : : save a whole frame in the file $rootname.cobj in tk-form : with the selection [GraphSave] : : save all the canvas in the file "canvas.canvas" in tk-form with the selection [CanvasSave] EditC: edit arbitrary regions of canvas by first selecting a box : [BoxSelect], which can be cut [BoxCut], reappeared anywhere : on the canvas [BoxPaste], reduced in size [BoxScale-] or : magnified [BoxScale+] : : from the same menubutton we can put as a background in the : active frame a gif file [CreatImage] or a bitmap file : [CreatBitmap]. the latter can be printed : : we also define the mouse button bindings, for editing text : [CanvasEditBind], graph objects bindings [CanvasBind] : as well as erasing all bindings [CanvasBindDelete] EditM: edit the *Data* menu list Data : list of the selected data_file names Gfrm : choose the (n,m) frame as the active frame Frames: increase/decrease by $drow or $dcolumn the number of rows : and columns of the frames as well as the gaps among the : frames by $dgap pixels at a time. to change these rates edit : "clplot.inc" Files: [FileSelect] a browser to select data_files : [ColumnSelect] to select columns from a multiple column : dat_file, and : [Contout&Surface] for producing two-column data for contour : or surface plotting ***********************************************************************

***** BUTTONS - LOWER PART *****

*********************************************************************** Plot: plot a new frame Overlay: put many graphs on the active frame READ: read data_file and transform the points to the canvas : coordinate system. R_COBJ: read file in tk-form language. Those created by CLPLOT : have the extensions *.cobj or *.canvas, but you can give : any name. : These files have the form : : first line : Number of data_files : second line: filename of data_file #1 : : ................... : : tk-data : : ................... : : filename of data_file #2 : : ................... : : tk-data : : ................... : : ................... : : REMARK: after editing a couple of tk-form files you will : learn how to MAKE GRAPHS BY A TEXT EDITOR. R_BOBJ: the same as R_COBJ but now for reading tk-form scripts : created by EditC tools WIN: you can put window widgets with labels anywhere on the canvas : first choose the relief of the widget. the label is the : [legend] parameter defined in the *Data_Var* menubutton of : *I/O* widget. Have a fun! TRIM: includes several extras for the graphs; filling with colors, : smoothing curves, putting points and labels on them, rotate : the plot by +/-$drotate and put or erase axis. : to change it edit "clplot.inc" Ticks: decrease/increase by $dtick the number of ticks in the : x-, y-axis. to change $dtick edit the file "clplot.inc". Size: reduce/magnify the size of the current frame. current step : is $dsizepixels pixels. to change it edit "clplot.inc". Focus: zoom parts of the current graph by defining the focus area : with a rectangle by pressing and dragging mouse Button-1 Grids: to put a grid on the canvas (bitmap files) of variable : density or to draw a grid [Grid_graph] at the tick points : of the active frame Art: plot several geometrical objects which may be filled with : a pattern. the pattern, a gif or bitmap file, is defined : in the menubutton *Data_Var* of the I/O widget : Marks : put a few symbols on canvas (oval-rect-triap-diam) : Curves: smooth curves : Lines : straight lines : Arrow : straight lines with an arrow at the end : Poly : polygons : Poly_smooth : change the polygon with a smooth curve : Poly_fill : fill and smooth the polygon : Rectan : draw a rectangle : Oval : draw an ellipse : Arc : draw arcs : Bindings for Art : Button-1 : initialize the drawing : B1-Motion : draw and resize the curve : ButtonRelease-1: tag the geometrical object : B2-Motion : draw and resize a curve and : fill it with a pattern : ButtonRelease-2: tag the geometrical object Erase: erase parts or the current frame or the whole canvas : you can erase separately text, points, lines, images, : bitmaps, grids and windows Stop: stop refreshing the canvas Refresh: refresh canvas every $rate ms. in this way you may : plot new data which are stored in the input data_file Printf: make a postscript file with the name $rootname.ps$ips : $ips labels different versions of the postscript file : : the area of canvas which is translated in the postscript file : is : -x $dxps -y $dyps, : and the size of the translated canvas area is set to : -width [expr $ypsscale*$width : -height [expr $xpsscale*$height : : to change these settings you must edit the clplot.inc file. ? : what; calls netscape to read file what.html : bindings; creates a new widget which describes the current : bindings of mouse buttons. you can edit old bindings and : define new ones ***********************************************************************

***** BINDINGS FOR CANVAS OBJECTS *****

*********************************************************************** Button-1 : put the cursor in a text object to start editing Double-1 : mark the point on the canvas at which you want : to put text. : to start editing press Button-1 again. : Delete -> Delete : Control-d -> Delete on the right : Control-h -> Delete on the left : Backspace -> Delete on the left : Control-Delete -> Delete up to the end of the line : Return -> start a new line : Any-Key -> insert a character : Control-f -> move forewards : Control-b -> move backwards : Key-Right -> move right : Key-left -> move left Button-2 : paste text (from the clipboard) at the current point Shift-2 : put the label (set_index,point_index) : at the current point Button-3 : select the current point or an object on the canvas Double-3 : cut the selected object on canvas Shift-3 : paste the cut object at the current point Ctrl-1 : cut the selected graph from the canvas Ctrl-2 : select a whole graph Ctrl-3 : paste the cut graph at the current point B1-Motion: select text B2-Motion: move a whole graph B3-Motion: move only a selected object on the canvas ***********************************************************************