GPLOT DOCUMENTATION (Programmer's reference) Executive Summary: "Gplot" is the starting point for a Matlab 5.3 suite of programs created to provide a convenient, graphical interface for generating ADCP data plots. Gplot accesses four basic plotting packages: vector plots, contour plots, panel plots, and web (html) plots. In general, each of these four areas has a primary dialog window (gplotvector, gplotcontour, gplotpanels, and gplotweb). The dialogs are initialized, modified, and interpreted by their respective control files (vectormaster, contourmaster, panelmaster, and webmaster). These control files, which make up the centralized reference point for each of the four packages, in turn call other specific programs to realize the final plots on screen, namely: gvector, gcontour, gpanel. The webmaster functions throw back to the vector and contour plots as requested. Files with an appended "2" are direct derivations of their parent files with the necessary adaptations to make them compatible with this GUI package. M-file list and overview of relationships: Name Function Called from Calls to ___________________________________________________________________________ gplot opening dialog window keyboard plotmaster plotmaster est. I/O files & plot type gplot gplotfiles gplotconfig gplotfiles I/O dialog plotmaster plotmaster gplotconfig alternate I/O dialog plotmaster plotmaster _____________________ vectormaster vector controls plotmaster gplotvector gvector mvecfig paramfig gxytzoom2 gplotvector vector plotting dialog vectormaster vectormaster gvector generates specific plot vectormaster topograys topograys allows b/w topography bkgrd gvector mvecfig custom arrows, temp, etc. dlg vectormaster vectormaster mvecsuppfig mvecsuppfig custom circle (station) dlg mvecfig vectormaster paramfig custom proj, grid parameters vectormaster vectormaster gxytzoom2 graphical selection of data vectormaster gxytnumbers gxytnumbers numerical selection of data gxytzoom2 gxytzoom2num gxytzoom2num required helper file for nums. gxytnumbers ___________ contourmaster contour controls plotmaster gplotcontour gcontour others * gplotcontour contour plotting dialog contourmaster contourmaster gcontour generates specific plots contourmaster ___________ panelmaster panel controls plotmaster gplotpanels gpanel mixedpanelsdlg others * gplotpanels panel plotting dialog panelmaster panelmaster gpanel intermed. aiding panelmaster panelmaster agetmat2 aplotit2 mixedpanelsdlg dialog for diversified panels panelmaster agetmat2 extract info from database gpanel aplotit2 generates specific panels gpanel ___________ webmaster web controls plotmaster gplotweb firstplt mksecplt2 del_section wrt_html2 others * gplotweb dialog to confirm I/O webmaster firstplt produces cruisetrk map webmaster others * mksecplt2 shows selected sections webmaster del_section deletes specified sections webmaster wrt_html2 generates html files webmaster ___________ others * -- includes the gxytzoom2 group and other pre-existing files. There is also a set of customized utilities which are convenience dialogs to inform, give warnings, retrieve choices, or obtain specific information from the users. These include: select.m, notice.m, noticeOK.m, and getdatadlg.m. General scheme: Each of the *master files begins with a switchyard function of the same name. This enables them to act as "procedure files" for the numerous callbacks. For example, plotmaster.m starts with the function plotmaster(fctn, varargin). Within this function is a "switch" (case) structure which then directs the processing to the function actually needed. Continuing this example, if a radio button on gplot is activated, the callback might be 'plotmaster(''radioreset'',''1'')'. The switch structure redirects the input to the function radioreset with the argument '1'. '1'(= vectors) as an input argument then resets all appropriate radiobuttons and fixes other variables associated with the upcoming vector processing. Procedure files with switchyarding obviate the need for numerous files of only one function each, which is how Matlab customarily works. The three general master files (vector, contour, & panel) are each called initially for their 'setup' functions (variously named). This initializes numerous variables and inializes certain features to be displayed with their respective dialogs. The setup functions also establish the initial data sets. These data are divided into global structures. UVDATA contains the actual current values. XYDATA contain lat-long data and other information regarding depths, database path and names, and time data. The other variables that need to be shared among the functions, but which are inconvenient to pass directly are stored under their respective names, VECFIG, CONTFIG, PANELFIG, & WEBFIG. There is also an ALLFIG used at the front end for some important values. These structures effectively 'hide' the data, which again obviates the usual problems associated with globals. They also provide a convenient means of storing the multitude of plotting options in configuration files. These same master files can also be called from the web plotting option. In this case the setup is specialized somewhat and starts with the function websetup(). Similarly, sometimes the plots are initialized by loading a config file. In this case the startup function is configsetup(). Other functions generally found in all of the master files, but each customized to its own plotting features are: a read function -- to retrieve all of the settings and to call the plotting program, a save function -- to save the config data, a load function -- to recall the saved config file and its restore its settings, a title fixing function -- to modify the title as requested, the xytsection function -- for calling xytzoom2 and process the return values, a print function -- to produce the *.ps files, and a cancel function. DETAILS OF SPECIFIC FILES: PLOTMASTER. Besides controlling the initializing and interactions from gplot.m itself, this file interprets the callbacks from the beginning input screens. The first callback come from gplot 'okcallback()'. This then calls (via calldatafiles()) the filename input screen (gplotfiles.m) or if the configuration checkbox was clicked the config filename input screen (gplotconfig.m) via callconfig(). These two screens do little more than receive input. When the gplotfiles.m OK button is clicked, it returns to plotmaster 'okcallback2'. This in turn calls the appropriate master program with the file information. If instead the config input was used, the callback is 'okcallback3', and it does the same thing using the config filename information. Both of the small screens have a [...] button to permit graphical selection of files through the Matlab uigetfile() function. This too is controlled via callbacks to plotmaster (getcfgfile or getmatfile), which in turn calls the internal function, getfile(), with an index to indicate regular or config file type searches. VECTORMASTER. The primary dialog screen for vector plotting is gplotvector.m. It is initialized and controlled with this master program. The following table lists the functions. Callback instigators are also gived. Internal documentation in the file gives the callback sources. Summary of callbacks and functions: Callback Function() Action _______________________________________________________________________ setup figvectorsetup initializes dialog (gplotvector.m) configsetup configsetup " " using saved config file websetup webplotsetup " " using web related values readfigvector readfigvector extracts all dialog info and calls gvector.m gvector.m draws the plot - (Preview btn) mvecfigsetup mvecfigsetup initializes dialog for customized markers markers dialog screen = mvecfig.m mvecfigOK mvecvbls extracts dialog info and closes screen xytsection xytsection calls xytzoom2.m for coordinates dprange fixtitle updates title with depth range info calendar fixtitle updates title with calendar dates decimal fixtitle updates title with decimal date info mindepth fixtitle amends max depth pull-down list; title maxdepth fixtitle amends min depth pull-down list; title moreboundaries (self) provides numerous projections (Ortho, UTM, etc.) boundaries paramfig call suppl. dialog screen paramfig.m inputs optional lat/lon, etc. initialized with load_param_defaults() coast paramfig call suppl. dialog screen paramfig.m inputs optional lat/lon, etc. initialized with load_param_defaults() grid paramfig call suppl. dialog screen paramfig.m inputs optional lat/lon, etc. initialized with load_param_defaults() basin (self) calls select.m to get basin type, e.g. lines addparams addparams callback from paramfig.m; sets new values savenow (self) calls Matlab's save() to make config file loadnow loadnow re-establishes saved config values on dialog printfile (self) sets print flags cancel (self) closes dialog; returns to gplot.m determine_ranges revises min/max lat/lon, e.g. after xytsection Most of the functions and callbacks are straightforward; some are strange or convoluted. These latter are due to untimely suggestions or revisions that occurred after the main structure was in place. For example, the loadnow() function deserves additional explanation. After revising the filename input scheme, which became somewhat convoluted, it became apparent that config files could be called two ways. First, they could be called from gplot at the very beginning. Such requests now re-establish the plot in its entirety. Secondly, a user can have a new cruise and section under construction, and then call the loadnow() function to superimpose a previously saved configuration layout - no date stamp, bold, etc. To accommodate these differences, loadnow() is called with an index. loadnow(0) means the immediate load button was selected, and the config info should superimposed on current data. Loadnow(1) means that the config data was loaded already and that the additional config parameters should be added. A large if-structure governs whether or not the section data and its related parameters are overwritten. Another potentially confusing area concerns the dialog buttons allowing the user to make almost unlimited changes to the m_map parameters. These include several categories such as lat/long extents and plot features, e.g. tick marks "in"|"out". Both Matlab and m_map accommodate such customizations with parameter-value pairs. As these all work the same way, changes in projection, coast, or grid features are all bundled in the same functions, load_param_defaults() and addparams(). Regardless of the request, these functions include the request by building new stings. For example, a new patch color or "tickdir"|"out" pair would be included in one of several strings. These are saved as globals, namely VECFIG.m_proj_str, VECFIG.m_coast_str, and VECFIG.m_grid_str. Once all of the possible plot parameters are known and saved in VECFIG, gvector.m is called to do the plot. Gvector.m first does the m_map setups, like topography, then establishes any temperature color indexing, then evaluates the above mentioned strings, and then finally calls m_vec_ell.m, which contains the actual Matlab plot() function. This may be called in several ways depending upon the display (e.g. black & white) and the colorbar(s). After the plot is produced, vectormaster processes the printing routines as needed. Upon completion, control is returned to gplot for quitting or for other types of plots. CONTOURMASTER. The primary dialog screen for contour plotting is gplotcontour.m. It is initialized and controlled with this master program. The following table lists the functions. Callback instigators are also gived. Internal documentation in the file gives the callback sources. Summary of callbacks and functions: Callback Function Action _______________________________________________________________________ setup figcontoursetup initializes dialog (gplotcontour.m) configsetup configsetup " " using saved config file websetup webfigsetup " " using web related values readfigcontour readfigcontour extracts all dialog info and calls gcontour.m gcontour.m draws the plot - (Preview btn) radio radioreset est. button state for lat, long, or time xytsection xytsection calls xytzoom2.m for coordinates llrange fixtitle updates title with lat/lon range info calendar fixtitle updates title with calendar dates decimal fixtitle updates title with decimal date info savenow (self) calls Matlab's save() to make config file loadnow loadnow re-establishes saved config values on dialog printfile (self) sets print flags cancel (self) closes dialog; returns to gplot.m determine_ranges revises min/max lat/lon, e.g. after xytsection See the internal documentation for the sources of the callbacks. The loadnow() scheme for contours is the same as for vector plots. All of the data are stored in the global CONTFIG. When gcontour.m is ready to be called, it does some matrix manipulations and regridding, then evaluates what contour intervals are needed. It then sets up Matlab subplots() and repeatedly call the internal function contour_panel(). The latter also takes care of the colorbars. After the plot is produced, contourmaster processes the printing routines as needed. Upon completion, control is returned to gplot for quitting or for other types of plots. PANELMASTER. The primary dialog screen for panel plots is gplotpanels.m. It is initialized and controlled with this master program. The following table lists the functions. Callback instigators are also gived. Internal documentation in the file gives the callback sources. Summary of callbacks and functions: Callback Function Action _______________________________________________________________________ setup figcontoursetup initializes dialog (gplotcontour.m) configsetup configsetup " " using saved config file websetup webfigsetup " " using web related values readfigpanel readfigcontour extracts all dialog info and calls gpanel.m mixedtypes mixedpanelssetup calls dialog mixedpanelsdlg.m mixedok readfigmixed est. type and sequence of varied panels datefix datefix est. the begin and end dates update datefix " " before panel preview xytsection xytsection calls xytzoom2.m for coordinates calendar fixtitle updates title with calendar dates decimal fixtitle updates title with decimal date info savenow (self) calls Matlab's save() to make config file loadnow loadnow re-establishes saved config values on dialog printfile (self) sets print flags cancel (self) closes dialog; returns to gplot.m getname est. PANELFIG.titlelist, e.g. pg, amp, w, etc. See the internal documentation for the sources of the callbacks. The loadnow() scheme for contours is the same as for vector plots. All of the data are stored in the global PANELFIG. When gpanel.m is ready to be called, it sets up new structures and calls agetmat2(). It then begins a large loop, with each loop representing a page to be displayed or printed. Within each page, it loops through the panels to be plotted per page. Each panel call routines as needed for data and does the plot (getfield, subdata, and aplotit2 primarily). After the inner loop for individual panels is finished, the main outer loop checks for printing and other details for each page. As usual, panelmaster returns to gplot for other types of plots. WEBMASTER: This file is unusual in that it was derived from a script, websectt. It was converted to run as a function so that the user would have ready access to the command line. The initial switch control only calls two functions, websetup() and main(). The websetup does little but check path information and call up the web plotting dialog. Likewise this dialog does little but provide the opportunity to verify inputs and change a few rarely altered global variables. So the program is immediately running under the main function. The main function retrieves the dialog information in this case. It checks a number of paths and files, loads the xy and uv data, and establishes the lat/lon ranges. It then begins what it labelled the GRAND ACTIVE LOOP. The starts with a 4-way selection box: Add New Sections, Delete Section(s), Finished (process html etc.), and Cancel/Abandon. It loops on the first two, continues on the third, and returns to gplot on the fourth. Obviously, the first choice is the workhorse, and it graphically solicits sections to be plotted and determines if both vector and contour type of plots are wanted. It is from this point that the vector and contour programs are called up in the web mode. Once finished with the first two choices, the user must select three or four. With three, the processing continues with the FINAL PROCESSING. This consists of saving the sectinfo data, writing a number of html files, and usually converting a number of .eps files to .gif.