File Menu - SPEDAS GUI

The File menu contains selections that are related to loading and saving GUI documents and templates, as well as printing and exporting image files from the main plot area. It also contains the Configuration Settings for the plug-ins. The figure on the right shows the options in the File pull down menu.

Open SPEDAS GUI Document

The SPEDAS GUI includes the capability to save the state of a GUI session to a "SPEDAS GUI Document" file (.tgd file extension). TGD files are plain ASCII text, use XML to represent properties of GUI objects and loaded data, and can be examined with any ASCII file editor. Many web browsers also include support for viewing XML documents (although one may need to change the file extension to XML to get the browser to recognize the format).

Any loaded data associated with a GUI session is NOT directly stored in the TGD file; instead, the document contains the information necessary to reconstruct the sequence of calls that were initially used to load the data. There are some pros and cons to this approach that users should be aware of:

TGD files are relatively small, and can be easily shared as email attachments. Because they are plain ASCII text, there are no significant file format differences between different platforms, so TGD files are portable between systems.
Opening a TGD file may require internet connections to data servers in order to download any data files that are not already cached in the user's local file system.
Since the TGD file only records operations performed within the GUI, operations performed outside the GUI or data that is imported via manage data or tplot_gui will not be recorded in the SPEDAS Document.
Opening a TGD file is a DESTRUCTIVE operation that wipes out the current window configuration and loaded data, replacing it with the contents of the TGD file. We recommend that users save their work before opening a new TGD file, and pay attention to any warning dialogs to avoid nasty surprises.
No versioning information is stored in the XML file, TGD files created under a particular version may not be readable in other versions. Although, since the GUI interfaces are more stable than they were originally, this is less of a problem in recent releases.

To open a TGD file, select "Open SPEDAS Document..." from the File pull-down menu. Navigate to the file you wish to open, and click "Open" (or perhaps "OK", depending on your platform).

This should trigger the process of loading the data specified in the TGD file you just opened; you should see progress messages scrolling by in the IDL command window. It may take several minutes to load all the data, depending on how complex a document is being loaded; SPEDAS may also need to open an internet connection to the data servers to download any data files not already cached on your local file system.

If all goes well, when the data is finished loading, the main draw window should update and show the plots for the first GUI page specified in the TGD file. Other pages saved in the TGD file should be accessible through the "Pages" drop-down menu button. Any errors detected while parsing the XML file or loading the data will be reported by a pop-up error dialog, or a message in the status area at the bottom of the main GUI window.

Save SPEDAS GUI Document

Warning: Due to an IDL bug on Windows platforms, the condition "write permission denied" is not properly detected, and will probably crash your entire IDL session if you attempt to save to a file without write permission.

We recommend a workflow something like this:

Use one of the three "Data -> Load Data [...]" dialogs to load the all the data you want to work with,
Use the "Plot -> Plot/Layout Options" dialog to create some plots,
Use "Save SPEDAS GUI Document" to save a TGD document containing the window configuration, plot properties, and loaded data call sequence information, creating a "checkpoint" that can easily be restored later
Perform any other manipulations (e.g. non-GUI operations), and be prepared to repeat them after opening the TGD file at some later time to restore the check pointed GUI configuration.

When you're ready to save your plots and loaded data, click "Save SPEDAS GUI Document" under the File pull-down menu. All pages, plot settings, data, and data operations will be saved. If this session has not yet been saved to a TGD file, a platform-specific file-saving dialog will appear. Navigate to the directory where you'd like to save the file, select a new filename if you don't like the default, and click "Save" (or maybe "OK", depending on your platform).

If "Save SPEDAS GUI Document" has already been invoked, or if the current session is the result of loading a TGD file, the file picker dialog will not appear, and the filename from the most recent save or open operation will be used again.

If the save attempt fails, an error message should be displayed, either in a pop-up warning dialog, or a message in the status area at the bottom of the main GUI window. If the save succeeds, a success message will appear in the status area.

Hint: The SPEDAS document can also be used to save default plot settings. Once you have created the font, size, colors, grids, axes, etc. that you prefer, the save document option will preserve those values. Each subsequent time you start a GUI session, you simply need to open the saved document to restore your preferences.

Save SPEDAS GUI Document As

The File->Save SPEDAS Document As... dialog also saves a TGD file. The only difference between "Save SPEDAS Document" and "Save SPEDAS Document As..." is that "Save SPEDAS Document As…" always pops up a file picker dialog, allowing one to change the filename associated with the GUI session. "Save SPEDAS Document" will reuse the last filename successfully saved to, only displaying a file picker the first time the GUI state is saved.

GUI Plot Options Template

SPEDAS templates allow the user to save settings such as font size, colors, line options, etc. SPEDAS templates are saved with the default file extension TGT.

Open Plot Options Template

Open Plot Options Template allows you to open a previously saved SPEDAS template (see the sections that follow for how to create a saved SPEDAS template). Choosing Open Template will bring up a standard file picker dialog. The exact appearance and functionality will depend on your platform. Once a template has been loaded the settings saved in the template will be applied to any new work in the GUI. For example, saved settings such as the page title and background color will be applied if you create a new page, saved settings including panel options such as grid lines will be applied to any new panels, and so on.

Note: to set a default template that will be opened whenever the GUI is run, see the Configuration Settings section.

Save Plot Options Template

SPEDAS templates allow you to save page, panel, line, axis, and variable settings. For example, to save page settings first use the Page Options to format the page title, footer and layout. Then, in the Page Options window, select “Store for a Template”, then “OK”. From the File menu select GUI Plot Options Template->Save Plot Options Template. This will bring up a file dialog. Navigate to the directory where you wish to save the template, and change the file name if you wish and select Save.

The process for saving panel, line, axis, and variable settings is the same as for the page settings. First open the relevant options window, choose your settings, and select “Store for a Template”. Then choose File->Template->Save Template to save the template. Note that page, panel, line, axis, and variable settings can all be saved within a single template file. For example, to save both page and panel settings, apply and “Store for a Template” both the page and panel settings before choosing File->Template->Save Template.

Selecting Store as a Template in the Panel Options window will save only the currently selected panel’s settings. Similarly Store for a Template in the Line Options window saves the settings from the currently selected trace.

If “Save Template” has already been invoked in the GUI session, or a template has been loaded, the file picker dialog will not appear and you will instead be prompted as to whether you wish to overwrite the existing template file. If you have, for example, loaded a template containing page settings and now wish to save panel settings, choosing “Save Template” and selecting “Yes” to overwrite the existing template will create a template with the new panel settings that also retains the page settings.

Save Plot Options Template As

“Save Plot Options Template As” also saves a SPEDAS template TGT file. Unlike “Save Template”, “Save Template As” will always bring up a file picker dialog allowing you to change the filename of the SPEDAS template you are saving.

Reset Plot Options Template

Reset Plot Options Template allows you to reset to the SPEDAS default template. For example, selecting Template->Reset Page Template will reset the page settings (e.g. title, background color) to the SPEDAS defaults for any new pages you create, while retaining any panel, line, axis, and variable settings saved in the template.

Save Page As Image File

The Save Page As Image File allows you to generate an image file of your currently active page. The SPEDAS GUI supports the following file types: Portable Network Graphics (.png), Encapsulated Postscript (.eps), Windows Meta-File (.emf, Windows Only), Windows Bitmap (.bmp), Graphics Interchange Format (.gif), Joint Photographic Experts Format/JPEG (.jpg), JPEG 2000 (.jp2), Apple PICT format (.pic).

The EPS export uses the routine ssl_general/misc/fancompress.pro to decrease the size of line plots when exported to EPS. EPS files without compression can be tens or even hundreds of MB large. Fan Compression should generally keep the EPS size down to less than 1 MB. Fan Compression removes redundant data points using an IDL implementation of the algorithm described in the paper: Fowell, Richard A. and McNeil, David D. , “Faster Plots by Fan Data-Compression,” IEEE Computer Graphics & Applications, Vol. 9, No. 2,Mar. 1989, pp. 58-66.

EPS files created by the GUI with large line resolution percentages may take a long time to read in postscript readers.

Figure 3.3.9 shows the Save Image window. The directory to which you will output is listed at the top. The 'Arrow' button will allow you to move up one directory. You can also edit the directory by typing directly into the directory field, or selecting the desired directory from the directory list below.

The file name for output is listed in the text box at the bottom. Change the output format by selecting a different type from the 'Save As' dropdown menu at the bottom. The 'Options' button will show the graphics output options for the selected file type. These options will change depending on the file type. They involve things like the size and resolution of the output file.

When you are ready to actually save the file, select the 'Save' button, and the requested file will be saved to the selected directory. If you change your mind select the 'Cancel' button or the 'X' in the corner.

NOTES:

.EPS and .EMF both support vector output. A file produced with vector output can be resized without pixelation, and can be edited in Illustrator (or similar programs) e.g. text (labels, titles) that appear in the document can be edited directly as text objects, fonts can be changed, line color can be edited. To turn on vector output for either of these format types, press the 'Options' button and select 'Vector'.
If vector output is selected for .EPS or .EMF format, text that runs of the edge of the page will not appear in the saved image file e.g. if part of a y axis label is cut off the left hand side of the active page, the entire label will not appear in the saved file. Page margins can be easily changed under Graph->Page Options, Layout tab, to ensure all labels are visible on the page.
Setting line plot resolution at or past 70% can make the file unreadable due to the size of the file.

Print

When the Print option is selected under the File pull down menu an IDL print dialog window will be displayed. The default print device will be displayed and you can choose the number of copies you would like printed out. If you do not wish to use the default printer listed, please see the next section, Printer Setup, which allows you to select from all printers that are recognized by your system. In addition, the Printer Setup window allows the user to control additional print parameters.

Figure 3.3.10 shows an example of the print dialog window.

NOTE Printing in IDL can be unreliable depending on your combination of Printer and OS. If you have any problems printing, you should export your document to an Image (EPS or PNG) and print directly using your an OS specific image viewer.

Print Setup

The Print Setup option available under the File pull down menu allows the user to set up print parameters, select print devices, and print. The Print Setup option displays the standard IDL print dialog window. All print devices that your system can detect are listed in the Select Printer box. In addition, you can control the number of copies, page range, collating details, and preferences associated with the print device you selected. For detailed information about this dialog box and the preferences you can set, please refer to the IDL User’s Guide.

Configuration Settings

This button pops up a window that allows access to the system variables that control the automatic downloading process. You can type in values for the different options in the window. Tabs at the top of screen allow selection of configuration parameters for the different missions that the GUI supports loading data from. New tabs can be added (of removed) in the future, depending on the number of missions that the GUI supports directly.

The first tab contains general SPEDAS configuration settings, such as the temporary directory that can be used for downloading files, the verbose level for tplot messages (warnings and general information messages) and the name and path of the preferred browser executable (which is especially useful for Unix-type machines).

The next tab contains information for the THEMIS mission files. The top text box gives the local data directory. THEMIS data that are downloaded are written to this directory. The default value for users who are logged on to an ssl.berkeley.edu machine is "/disks/data/themis/". For windows users, the default value is "C:\data\themis\". It can be set to any directory for which the user has write permission.

The second text box shows the remote data directory. The default is http://themis.ssl.berkeley.edu/data/themis/

Next is the control for automatic downloads. (This should be set to "Use Local Data Only" for local SSL users, or anybody who has the entire database stored locally).

Next is the control for file updates. If turned on, a file will be re-downloaded if a file with a newer timestamp is found in the remote data directory. If turned off, files will only be downloaded if they are not stored locally.

The verbose flag controls the number of messages that will be displayed. Set this to a number from 0 to 10. The higher the number, the more messages you get during processing.

The graphics mode allows you to select whether the graphics rendered are done with hardware or software. Rendering of graphics varies based on your system and platform. If your graphics are slow to display, you might want to switch your graphics mode. Our testing has found that software rendering generally provides faster graphics with fewer artifacts.

The template check box gives you the option of choosing a previously saved SPEDAS template to load whenever the GUI is run. This lets you set default plot and axis options e.g. font sizes, colors, grids etc. See Section 3.3.4 for general information about SPEDAS templates. Note that when a default template has been loaded from the configuration settings it is still possible to change the template in use in the GUI session by choosing File -> Template -> Open Template.

The Configuration Settings window is show in the figure to the right.

RESET: If you press this button, configuration settings are returned to their original state prior to opening this window.

RESET TO DEFAULT: If you press this button, the configuration is returned to the default state in THM_CONFIG.pro, and any saved configuration file is deleted. This means that if you want to go back to a configuration that you have saved previously, you need to reset the values and then save the configuration. Alternatively, you can locate the previously saved file and copy it to the appropriate location in the APP_USER_DIR shown below.

SAVE: If this button is pressed, then the current configuration is saved in a file. This file ends up in a directory created by the IDL APP_USER_DIR routine, on a windows system the path looks like this: "C:\usernme\.idl\themis\thm_config-4-win32\thm_config.txt". On a Linux machine, it looks like: "$HOME/.idl/themis/thm_config-4-linux/thm_config.txt"

Important

Once you have saved this file, it will always be read when you run any SPEDAS routines -- you should only need to do this once for each operating system that you are using. Whenever you save a new file, the old file is copied to a file tagged with the current date and time.

Exit

The Exit option under the File pull down menu will terminate the SPEDAS GUI session. All windows will be closed and control returned to the command line.