In the past I had some problem with different operating systems where the decimal separator is not '.'. Therefore I changed the behavior of QtGrace in responce to decimal separators in general. Internally always '.' is used. Only for display purposes and for data input something else is possible. In the Preferences->QtGrace-Behavior the decimal separator can be selected (at the moment only '.' and ',' can be used). The one you select will be used for every display of numbers (the display has been inconsisted before version 0.2.4) and for every input (keep that in mind: if you select ',' as decimal separator you have to enter all numbers with ',' as decimal separator and '.' will be ignored.). Numbers already stored in QtGrace will be redisplayed with the new decimal separator if you change the separator-preference.
For saving and reading of files '.' is used. In case of Drap-and-Drop or Paste the number of ',' is counted and if it is greater than the number of '.' in the file the user is asked whether ',' should be used for this one import-operation. For Copy-operations the default setting of the operating system is used for the decimal separator. If the user does Data->Import->Ascii... the '.' is used for import by default, but the user can select whether ',' is wanted (no counting of ',' or '.', just simple import as selected).
In some formulars ',' is used to separate different values (e.g. in the atan2-function). Therefore if ',' is used as decimal separator '|' has to be used to separate values.
The original Grace does not support UTF-8-encoding. All supported characters/glyphs are part of the T1-font-encoding which is more or less hardcoded into Grace. This is useful in conjunction with LaTeX but not very helpful if someone wants to use characters outside the T1-encoding.
In the latest version of QtGrace the support for UTF-8-encoding is included in the following way:
The Qt-library supports UTF-8 for all input-widgets (like line-edit). Therefore it is possible to enter any UTF-8 character in any input-dialog QtGrace offers (as long as text input is allowed - some inputs only accept numbers).
The computation and the display of graphs and especially text in QtGrace is still (mostly) taken unchanged from Grace. Therefore it can not handle UTF-8 characters that are not part of the first 128 characters of the ascii-table.
To display any UTF-8 character QtGrace uses the font-library of the operating system and the painting methods of Qt.
In Preferences->QtGrace-Behavior you will find a setting for the file encoding. For all inputs UTF-8 is used; for loading and saving text from and to files the selected encoding is used. Every time data is loaded from a file (not only loading a project file) all text-entries are updated (therefore any unapplied text-changes/inputs are lost after data is loaded - sorry).
Please note, that at the moment only the output-devices that use a raster driver support the output of text with fonts other than the usual 14 Grace/T1-fonts fonts. The only exception is the svg-driver: Since svg-files are written directely with Qt, every font is supported. I hope to improve the support in the future, but this is not so easy, because it is not garanteed, that every font is present on every system. (This means for example that there is no text output with PS or EPS.)
Detailed description:
QtGrace saves every text-string in two locations. One location is used for displaying the text using as much of the original Grace functions as possible (let us call it the 'Grace'-version of a text-string). The second location is used to store the original version of every text-string. The 'original' is the text the user entered (or which has been loaded from a file) and it is always stored in UTF-8 encoding.
When text is entered via direct input in a dialog it is stored in the 'original'-location. Then the text is converted into a version that can be interpreted by the display driver. If Qt-fonts are not to be used (i.e. the original Grace-fonts are used) the original text-string is converted into the iso-latin-1 encoding, if QtFonts are to be used the text-string is just copied from 'original' to 'Grace'.
If LaTeX-commands are to be used: During the conversion the 'original' text is analyzed and the LaTeX-commands are replaced with the appropriate Grace-commands. (Remember: the original version is always stored in the 'original' location including the LaTeX-commands as entered without change.)
When text is loaded from a file the text-string is stored in the 'Grace'-loaction. This version of the string is considered as the original. To copy it into the 'original' location it is interpreted in the preselected encoding and converted to UTF-8. The preselected encoding is stored in every project-file and is used after loading text from this file. (If you open an old file with no information about the encoding used the one you selected in Preferences->QtGrace-Behavior is used.)
For interpreting the text-string in the original location the encoding that is set in Preferences->QtGrace-Behavior is used. When data is to be saved in a file the original-string is copied to the 'Grace' location and converted into the encoding set in Preferences->QtGrace-Behavior. Then the text-string in the 'Grace' location is saved.
After loading or saving the text in all string-locations is reconverted (encoding-changes and LaTeX-conversions are applied - which may cancel all unapplied text-changes as mentioned above; and again remember: the reconversion is done after EVERY load or save operation).
Changes when QtFonts as activated:
In every font selector the label on the left side saying 'Font:' will change to a command button and pressing on it will display fonts that are available for use with the Qt-drivers (This should include most of the fonts available on your operating system. This is not restricted to the T1-fonts in the QtGrace-folder.). These fonts are only used for printing when Qt is used. This is the case for the display/screen, for using the native printer dialog and printing to 'jpg', 'png' and 'bmp' files. The T1-standard-fonts are used for printing on all other devices (like 'ps'). At the beginning the combo-box will only show the standard fonts supported by the original Grace. If you want to add other fonts: click on the command button saying 'Font:' and select a font from the font dialog of your operating system (usually the font size can be selected here as well, but this setting is ignored at the moment).
When using the 'QtFonts'-option the Font-Tool will be considerably slower (I hope to improve this in future releases).
Using the Symbol-font will not have the same effect as it has with the T1-fonts: In T1 the Symbol-font contains the greek letters (only). In the Qt-fonts every font contains the greek letters (but not at the same positions as the latin-letters). That means if you want to use the QtFonts and latin and greek letters at the same time you have to enter the unicode-numbers of the greek letters or copy and paste the letters from the Font tool or use LaTeX-commands (see below). In Preferences->QtGrace-Behavior there is now an additional option to specify, that the Symbol-font is special. This is only available with QtFonts activated. If the Symbol-font is marked as special, the characters entered normally are sorted differently and replaced if the symbol font is used. This way the usage of the symbol-font is the same as with Grace.
I can not guarantee that all special font commands like "\s", "\S" or similar will work all the time (due to differences between UTF-8 and Ascii/T1-fonts). Using the LaTeX-shortcuts may also be unreliable while using QtFonts because the character positioning has been optimized for T1-fonts.
The Grace fonts and their ordering is used for the first Qt-Fonts. If new Qt-fonts are added to the list the Qt-Font-list will be longer then the Grace-Font-Liste. If a Qt-Font is used with a higher number then the amount of Grace-fonts this font can only be used with useQtFonts activated. If Grace-Fonts are to be used (use QtFonts off) there is no font with such a high number. Text in this font will be displayed in Times Roman. The QtFonts are stored in every project file. The original Grace-fonts are saved as well, but the font lists may be different.
Conversion of path-names to ascii-characters is done using the default system-encoding (as reported by the operating system), because this is necessary for the internal file-operation-functions.
The support for simple LaTeX-commands can be activated in the Preferences dialog in Preferences->QtGrace-Behavior.
The LaTeX-support is meant for the input of simple LaTeX-commands declared by '$$' at the beginning and the end of the command (without'). Only text-input-widgets that are ment for comments/labels do accept the LaTeX-commands and only if the option is activated in Preferences->QtGrace-Behavior. This should be helpful to write formulas for people who know how to use LaTeX. For Example: You can enter something like '$$E=(\frac{1}{2}\pm\nu)\cdot\hbar\omega$$' and this command will internally be translated in the Grace-typesetting language (there is no real LaTeX-typesetter included - just some sort of makro-translator). At the moment the translation is one-way only. The original input is stored and you can switch between the original and the translated version. Usually the original will be shown. If you want to edit the translated text click on the label on the left of the text-input-widget. The text will be shown in red then. If you edit something in the converted version and click on Apply or press Enter while Immediate Update is on the text containing the Grace-font-setting-commands will be stored as original and your LaTeX-input is lost.
I did not copy every command from a LaTeX-handbook - I only included commands I thought could be useful and that are simple enough to include. (Take a look into ListOfLatexCommands.cpp if you want to know which commands are recognized at the moment.) Complex commands (like special braces like \underbrace or \overbrace) are not recognized at the moment and the overall translation is not completely fail-save. Don't use it in critical situations and save often. (If you enter a command and it is not recognized correctly try experimenting with spaces before or after it.) Nevertheless I would be very interested in your experiences in using this feature. I also would like to know which commands would be most useful to you if they were included. Font attributes are copied. Please notice: there is no font-command for making a font bold. Therefore characters that use the symbol font can not be displayed in bold. Sorry.
To import data from a binary file go to: Data->Import->Binary...
This will open a dialog. Be aware, that you have to know exactly (!) how the structure of the file is that you want to open. You have to tell the import-filter the exact format once and afterwards you may chose to save this format-information to reuse it later (currently the format is saved in a specification file version 2; the old version 1 can still be read from QtGrace, but saved format specifications will always be version 2; Version 1 only consisted of numbers which where hard to read, version 2 contains comments to tell the user what different settings mean. Therefore the format specifications version 2 can easily be edited by the user.). As an example I have included the file-format-specification of wav-files: Click 'Load Format Settings' in the settings-menu and select 'wav_format.fmt' in the bin-folder or click 'Load Std. Import Settings' and choose the wav-format. To select the actual binary file click on 'Browse...' on the right hand side of 'Datafile:' (or drag-and-drop a file into the Datafile-line). By default it is assumed that the binary file also contains a header that has some information about the data present (e.g. this is the case for wav-files).
The first part of telling the filter about the file format is to define the header-contents (byte for byte). This is done by adding a token to the list (click on '+') and tell the filter the format of the token (usually this is the kind of numerical representation of a number in a C-like format). The 'Bytes' box is only used for 'Offset' tokens that are ignored during data import later. It is possible (but not strictly necessary for every file type) to tell the filter how to use the header-information via the ComboBox 'InputAs'. In case you have done something wrong you are able to delete a token by clicking on '-'.
By clicking 'TestLoad' you can check whether your input has been correct (I always recommend clicking 'TestLoad' since it is needed for some files). The 'File-Info'-tab contains the data read from the header.
The second part is setting the Data-Format. It is assumed, that the data is present after the header in the file as a stream of bytes (no additional information in-between). It is also assumed, that the data-points are either present one after the other or one channel after the other. You have to set the format of every channel present in the file and whether or not this channel shall be imported.
The last step is to set the destination for the import: set-type and graph-number. It is also possible for data and header to be present in different files. You may select both of them in this case. For the header-information two versions are supported yet: header-information in binary format or in the format of ini-files (like system settings: '[Data] t0=5 dt=0.1' separated by new lines).
Experiment with binary import on wav-files. This may give you a good idea of how I meant it to work.
You may import more than one set at once. In order to do so set more than one import-channel to the same column (like one 'X' and three times 'Y').
Beginning with v0.2.2 it is possible to select several files for binary import at the same time. Doing so, the import filter will assume the files to have the same format and import the selected data from every file into a new set (or new sets). You may also activate an option to tell QtGrace to look for a seperate header file for each data file. Otherwise one header is used for several files. If you select multiple data-files and no header files, but tell QtGrace, that header files are present in ini-format, then QtGrace will look for ini-files at the same location and with the same name as the data-file but with an ini-suffix. If you select a different header-format than ini you have to select at least one header for QtGrace in order to tell the import filter the suffix of the header file(s). If you select more than one header file for multiple data files and tell QtGrace that there are seperate header files for each data file, than the number of headers have to match the number of data-files. In this case the first header is used for the first data file, the second header for the second data file and so on. If the number of header files does not match the number of data files, then just the suffix of the first header is used and it is assumed, that the headers have the same name as the data files. If you do not select "separate header file for every data file", then the number of header files is not importand, always the first one is used. If the header format is not ini, then you have to select at least one header. If you select ini-format and select a header file, then the suffix of this header is used, but the contents of this files are assumed to be in ini-format.
One channel in a file can be declared as a trigger channel. This channel is used as a reference for the x-axis. You can use rising edge/falling edge or whatever edge is the first to cross the trigger-level and you have to set a trigger level if a trigger channel is selected. After the data import the x-position of the trigger-edge is detected and all imported sets are shifted to set the position of this edge to x=0. By default the trigger channel is not imported, but if you want it to, then select "Keep trigger channel" in the Data-Format-tab. The trigger channel is interpreted as a Y-channel.
There is also a binary-export-dialog for saving sets. I included a file format specification for these files as well ("grace_binary_format.fmt"). Please remember to select "Read Data until EOF" in the Data-Format settings if you operate with data files of different lengths and do not want to set the exact number of data points for every file.
With the new format specification verison 2 it is now possible to define a standard-input-format for binary files. These special format specifiers are stored in the bin-subfolder under the name "QtGrace_std_bin_format_*.fmt" with the "*" replaced by a user selected standard name. Files with this name in the bin-subfolder are loaded by QtGrace at startup to determine the format of (for you) common binary files. With this formats known to QtGrace it is then possible to drag-and-drop binary files into the QtGrace-Window to be loaded automatically. If a binary file is recognized during drag-and-drop QtGrace tries to find a matching standard import format (the match is done via the file suffix only!!). If one is found, then the settings in the format specifier version 2 is used to import data from these files. This is very conveniant if you use the same binary file format regularely. You just have to prepare the QtGrace_std_bin_format_*.fmt-file. In order to do so, just use the Binary-Import-Filter-dialog for one of your binary files and set everything like you need it to be for your binary file and try if it is imported correctely by pressing Apply. If everything works, use "Save Std.-Format" and select a simple name for the specifier (only a word, no suffix or anything, just the thing, that will go instead of the "*" in the format specifiers file name). Afterwards I recommend you to open the new specifier-file in the bin-subfolder with a text-editor and edit the file to include more channels, just in case you later have files with more channels than you used, when you set the import format.
The automatic import of files depends on the fact, that usually somewhere in the header the number of data points and channels is stored. Otherwise, the binary format has to be very simple to be understood by QtGrace.
If you have specified a std-bin-import-format for a data file and an associated header file, then please remember, that during drag-and-drop QtGrace looks at the files one after the other. This means, that if you drop a header file QtGrace tries to find the matching data file and imports the data. If you drop a data-file the associated header is searched and the data imported. This means that if you drag-and-drop header- and data-file then this data is loaded twice, because QtGrace tries to match both files. Therefore please only drag-and-drop the data-files you want to load, the header-files are found automatically, if the filenames match (and only the suffixes differ). Other naming shemes for header files are not supported at the moment.
Any suggestions for improvements are welcome.
To import data from a file with comma-separated values go to: Data->Import->CSV...
This will open a dialog. In the Filename box you may enter the name of the file (the complete path!) you want to load data from. Although: The usual method would be for you to click on "Select CSV file" and use the operating systems file selection dialog. After selecting a file or clicking on "Re-guess columns" the first lines (ending with a new-line-character) of the files are loaded and shown in the File contents box. You may also notice a "-#-#-#-#-#-#-#-#-" somewhere in this box. This indicates the separation between a header (which is ignored) and the actual data columns below.
On the right hand side of the dialog you can select the target graph data will be imported into.
In the middle of the dialog you have to set the file format yourself (since there is no standard for csv, the files are different depending on how they have been generated).
At first you have to set how many lines at the beginning of the file are to be ignored (please note, that these header lines have to be separated by newline-characters or they may not be recognized as actual lines). The Data-set-separator specifies the ending of every data point. It is assumed, that every point consists of a number of values and in the file the end of one point and the beginning of a new point is announced by a special character like a newline-character. A newline has to be entered as '\n'; a tab-character as '\t'; except this all separators have to be single characters! Different (column-)values of one data point are separated by the Column-separator; Strings are indicated by a text-separator-character at the beginning an the end of the string (internally the string separator for Grace is always " therefore the use of the Text-separator or " inside the strings is very dangerous).
After entering all these format settings it is strictly advised to click on "Re-guess columns" since this will show whether the import filter works correctly. The guessed column-formats are shown in the contents-box below the first six data lines below '...'. It is possible to use ',' instead of '.' as decimal separator during import operation (usage of ',' as a column- or Data-set-separator is not advisable in this case). The guessing also sets the presumed number of data sets present in the file (=Number of data columns-1) and the formats in the column import selectors above the Apply/Accept/Close-buttons. The standard-import targets are set to: import first column as X-value for all new sets, import all following columns as Y-Values for new sets. If you set higher target columns (like Y1, Y2, ...) the set-type of the new sets will be adjusted automatically in order for the set to represent enough columns. If you need more sets than the guessed ones you can alter the "Number of sets to read". Strings can not be imported, they can only be recognized as columns between real values.
In short: suggested workflow:
Select a csv-file; Enter the separator-characters and the number of header-lines and press "Re-guess columns"; Set the import-format and import-targets for every column in the file; Press "Apply".
I noticed the lack of proper low-pass or high-pass filters for measurement data in Grace. Therefore I included a filter-dialog that uses fourier-transformations and filter functions in frequency space. The user has to select source and target sets and what kind of filter is to be used and how to realize this. Then the cut-off-frequency/frequencies and the order of the filter have to be selected (hint: a Brickwall-filter is a filter with infinite order). There has to be a linear relation between the current X-axis of the selected sets and the time in s. The formula to convert the x-axis into time in s has to be specified (if a wrong faktor is given here the selected cut-off-frequncies are not correct). Since internally the filtering is done by multiplying a filter function with the frequency-values in frequency-space (FFT data, multiplication, inverse FFT) and the fast fourier algorithm is used the number of data points in the data sets have to be a power of 2 (at least if you are not using the fftw-library). In order to arrange it to be so the method for extending the number of data points has to be selected (to increase the number of points to the next power of 2). If interpolation is selected oversampling may be selected. For nonperiodic data it may be helpful to select the "absolute value"-option in order to remove phase-shifts. (Please note, that starting with v0.2.6 the sign of the phase of the transfer function has been changes. In previous versions the filter violated causality. Now the filtered data is usually shifted in positive direction in time.) In case debug is selected intermediate data in the procession of the data is preserved (like the filter function and the fourier-transformed data).
Simply experiment with this dialog and you may see how it works.
It is also possible to use the filters in scripts (=Commands-dialog): Either you do a filter and use the "Translate selection to commands"-button in the UnDo-List or you enter the following command in the Commands-dialog
#QTGRACE_SPECIAL FILTER_SET <nr_of_source_sets>,<nr_of_target_sets>{<first_source_graph>,<first_source_set>;<second_source_graph>,<second_source_set>;...}{<first_destination_graph>,<first_destination_set>;...}{<type>;<realization>;<order_first_cutoff>;<order_second_cutoff>;<absolute_values>;<debug>;<point_extension>;<oversampling>;<region_nr>;<negate_region>;<first_frequency(Hz)>;<second_frequency(Hz)>;<chebychev_ripples(dB)>;<x_transformation_formula>}
You have to enter all entries in this command, although depending on the settings not all entries are used. All entries (apart from the x-transformation-formula) are numbers. Please relate to the Filter-dialog for what number represent what: on check-boxes: 0=not checked, 1=checked; on combo-boxes: first entry=0, the further below in the combo-selection-list the higher the number (e.g. "Band-Stop"=3); for the restriction: no restriction=-1, inside graph=-2, Region0=0, Region1=1 and so on. Example:
#QTGRACE_SPECIAL FILTER_SET 1,1{0,0}{0,1}{0;1;2;2;1;0;0;0;-1;0;10000.0;100000.0;10.0;1}
This means a 10 kHz Low-Pass-filter on set G0.S0 and the result will be written in G0.S1. A second order butterworth-filter using only absolute-values is used and the x-values are already in time in s (i.e. x-transformation-formula="1" - see last entry). No oversampling is used and the points are to be interpolated to the next power of 2. No debug-output, no restriction (the "-1"-entry), no negated restriction. The second frequency is entered as 100 KHz with order 2 and the Chebychev-rippels are entered as 10.0 dB but these three values are unused.
Suggestions for improvements are welcome.
Starting with version v0.1.3 I have included a feature to Undo and later Redo some operations the user does with graphs and data sets. It is deactivated as a default because it is of an experimental nature at this point. It will be activated as a default in a later release when I am sure that no harm is done by this function. To activate it: Go to Edit->UndoList and set the "Undo active"-option. This option will be saved in the ini-preference-file and will be restored at every startup of QtGrace (keep this in mind: if you activate Undo/Redo, it will stay active until you deactivate it again!). I do not recommend activating this option for Graphs that include large datasets (>100.000 points) since it may consume a lot of memory because the undo saves up to 100 states of your work. Since you now have been warned, let us get to the nice stuff: What is possible with this feature?
When "Undo active" is activated, every supported operation is recorded as can be seen in the UndoList. In this list you will find a description of what you have done (the last one is the one on the bottom) and at the beginning of one line the letter 'U' or the letter 'R'. Actions marked as such are the actions that will be Undone or Redone when you use Edit->UnDo or Edit->ReDo respectively. You may also select one or more actions in the list and click on "Undo" below the list. Undo will undo the actions form the last one upwards. Redo will undo the actions from upper most selected action downwards. Every UnDo- or ReDo- operation is considered as some sort of toggle-operation. After an action has been undone a "(*)" will appear at the beginning of the description in the UndoList. This means, that you already have made this undone. Clicking on it and clicking Undo afterwards will effectively redo it. This is also the case, when you use Edit->UnDo. An action that has already been made undone will be redone, when it is reached by the Edit->Undo-operation. Doing a normal operation in QtGrace will set the 'U'-marker to the last operation in the list. This means that by clicking Edit->UnDo the last operation will be made undone and the 'U' will go to the operation before this one. The 'R' for Redo will then be set at the last operation. Clicking multiple times on Edit-UnDo will set the 'U'-marker one operation back(=upwards) until the end of the list is reached or a new normal operation is done in QtGrace. You can always do a manual undo via the list. Manual operations do not alter the 'U'-marker. Using Edit->ReDo will Undo the Undo-operations until the end of the list is reached. Give it a try and you will see what I mean. The shortcuts Ctrl+Z and Ctrl+Shift+Z are used for Undo and Redo. Please note: In Grace Ctrl+Z is normally used for Zoom-operations. I use Ctrl+Z for an undo and Alt+Z for zooming.
One further warning: Operations that change the ordering of the sets in a graph or the ordering of graphs (like swap-operations or pack-sets) are a bit dangerous if you do manual undo. At the moment the undo-function does not check whether the set-number has been changed since the operation you want to undo. Doing a chronological undo with Edit->Undo should be save, manual undo can sometimes have unexpected results.
Simple description of what Undo/Redo does: Undo does set the state before the action has been performed, Undo again will set the state after the action has been performed. (Undo and Redo are only different with respect to the chronological order in which operations are made undone.) Undo/Redo does usually NOT really do the action again (there are some exceptions), only data is restored. Please use the manual undo-operation only for emergencies or if you really know what you want. Don't manually undo and redo several operations in arbitrary order to often, because unexpected results will be guaranteed. Chronological Undo via Edit->Undo or Edit->Redo is preferred.
Any suggestions are as always very welcome! Bug-reports as well.
For an improved interaction with other software (especially spreadsheet-applications) I implemented copy and paste as well as drag and drop into QtGrace. In order to work it is necessary, that the user only uses data in the usual spreadsheet format (multiple columns and rows without text-comments; only comments starting with '#' are allowed). It is for example possible to select a block of cells containing numerical data in a spreadsheet-edit-program and drag it over the QtGrace-window and drop it. It is also possible to copy the same data into the clipboard (Crtl+C) in your external application and click in the draw-area of QtGrace (a graph should be selected) and press Crtl+V. By doing so, the data will be imported as one or multiple new sets (depending on the shape of the data: empty lines are interpreted as a separation between sets and if more than two columns are present, the first column is interpreted as x-axis and the other columns are interpreted as the y-axes of several sets) in the current gaph. You may also select the "paste"-option in the context menu summoned by right-clicking in any set-list. Internally the data to be imported via drag-and-drop or paste is copied in a temporal file and then loaded via the usual ascii-import function. You may also drag and drop files directely from your file-browser into the QtGrace-window. If you select an ascii-file (or multiple files at the same time) the data is simply loaded via ascii-import. If the file is recognised as being binary (this is done on the basis as guesswork ;-) ) the binary import filter dialog is summoned and the user has to select the import-parameters (i.e. tell QtGrace the data structure of the binary file) to start the import. If a standard-binary-import-format has been set and the file dropped into QtGrace matches the set file extension, then the binary file can be imported automatically (see also the chapter about the binary import filter).
If you drag and drop a QtGrace project file (*.agr) a special dialog is shown that lets you select specific sets from the project file to import or open the whole file. This dialog can also be opened in the open-project-dialog.
A drag-and-drop operation from QtGrace to another application is not supported (no drag-out, only drag-into).
To get data from one or several sets from QtGrace to another program the user has to use the clipboard: select the data sets concerned and right-click in any set-list. This summons the context-menu and the user has to select the "copy"-option. The data is stored in the clipboard as ascii-data and can be paste in any other application that is able to use the clipboard (e.g. any spreadsheet editor). As decimal separator the default setting of the operating system is used.
On an experimental level some files in the LabView-Diadem-format can be imported by drag-and-drop (very rudimentary). The same goes for trace-files (*.dat) from Gould-oscilloscopes. Use at your own risk and the import may be incomplete at the moment (work-in-progress).
In XmGrace/Grace as well as in QtGrace you can zoom in and out via the buttons Zz and zz in the tool bar on the left hand side of the main window. If the axis-scaling is not linear (like logarithmical) the zooming can result in invalid values along the axis (like negative values for logarithmic scale). QtGrace does the zooming for nonlinear axes a bit differently so that the axes stay inside appropiade limits. The same goes for panning of the graph-area.
On the upper left hand side of the QtGrace-window there is now a new graph-selector. This selector shows all graphs present and the currently active graph is selected. Any change in graph-selection/activation is represented here. You can also change the current graph by using this selector. The main purpose of this is to be able to select more than one graph for zoom-in and zoom-out. All zoom-operations that are shown in the toolbar use this selector for determining on what graph(s) they should be used. Please mind, that internally Grace supports only one active/selected graph. This one is usually shown with focus-markers. This new graph-selector will only work with the zoom-buttons in the toolbar and is meant for people who use superimposed graphs and want to zoom in and out simultaneously.
I added a zoom-slider in the toolbar on the lower left hand side of the QtGrace-window. You will find it just above the 'Exit'-Button. The slider-value is changed logarithmically and can be set between 0.1 and 10.0. (The internal values of the slider range between -100 and +100 and the actual zoom-factor is calculated by 10^(value*0.01). The current value of the slider is saved in the QtGrace-ini-file as "PageViewZoom". (If you have problems resetting the page zoom to 1, set this value in the ini-file manually back to 0. To reset the slider to factor 1.00 you may use the shortcut 'Crtl+1'.) The setting only effects the visual display on screen. Print-commands are unaffected by this. There is also no Undo for changing the slider setting because this in nondestructive. The setting is saved when QtGrace is closed and will be reset to the last value at the next startup. I intended this for people who have uncommon display-resolutions. QtGrace calculates the size of the visual page according to the resolution of the computer-screen used. This is ok for most users. It is very inconvenient for people using notebooks with small screens (like 12") because they will not be able to see the whole page. With this new zoom-slider you can reduce the page size for the display according to your needs. You are still able to produce hardcopies (in Print or in Files) with an exact resolution.
Please note: The Zoom-Slider is deactivated if QtGrace is started with the '-free' option, because it is useless in this case!
The 'Fit'-Button below the page-zoom-slider sets the zoom-slider in order to fit the page-size to the available space of the window. (Thank you jhenin for suggesting this and supplying the source-code which I modified a bit.)
In the preferences you can activate the zooming with the mouse-wheel. If you scroll the mouse-wheel while the cursor is inside a graph you can zoom in and out a the cursor-location. The graph does not have to be the current graph for the zooming. Please note, that the selection ihn the graph list is not used for mouse-wheel-zooming. Just one graph is zoomed. If the cursor is outside a graph while the mouse-wheel is used, nothing will be done.
In the original Grace it was possible to use more than the 16 colors preset in Grace, but you had to enter them in the file header manually. I wanted to have a more convenient method.
In the Preferences-dialog you can change the current Color palette used for the project. In the upper part you can select a color from the current palette and edit it. You may enter the red/green/blue-color-components and the color name. Below you will see a preview of the edited color. You have three options for the single color: delete the color with the specified number from the palette, add the color as a new color to the palette or replace the color with the specified number with the new color (Edit color). The option 'Define color' lets you select a color from the color-selector-dialog of your operating system. If you want to add this new color to the current palette use add or edit (to replace an existing one).
You may also edit the whole palette in one go. You may set the palette for example to a specified spectrum of colors. You may use predefined spectra or set your own spectrum. By selecting 'Custom...' and setting a number of path-points you may define the spectrum by specified colors that have to be part of the spectrum. For each path point you have to specify a color via 'Current path point' and 'Color'. Below you will see a preview of the spectrum. Please note, that the first two colors in the spectrum will always be white and black because otherwise you will get very irritating results. If you don't want this: set a spectrum and edit the first two colors afterwards (but consider yourself as having been warned).
Please note also: everything you edit in the Color management dialog only effects the color-palette of the color selector in this dialog. If you want the change to take effect in the current project you have to click Apply or Accept (no immediate update here!).
I included an option in the Undo-List-dialog: If some of the entries in the undo-list are selected the button below the list may be pressed. This will convert the undo-entries into appropriate commands in the Command-dialog. By doing so it is possible to record a script of what has been done (Do something in the normal way while Undo is active. Then afterwards select the actions that should make up a script and then press the button. In the Commands-dialog you may then alter the commands, save and load them.). Unfortunately this feature is still incomplete at the moment. Loading and saving data is not fully supported yet. The scripting works concerning style-changes in things like Graph-Appearance, Set-Appearance and so on.
In the commands-dialog I inserted a set-selector for source and destination set and a new command-button: "Replay replacing set-Ids". By pressing this button the list of commands is executed as would be the case with the Replay-button, but in contrast to this every set-id in the command is replaced by the selected ids (separated in source and destination). This is very useful for scripting complicated commands like regression or filtering.
I also included an option to use special let us call them "clipboard-commands": remember value (including the last formula used in fits or for evaluate expression), add/multiply/substract/divide by last or remembered formula/saved formula/saved value. This can be used for example for generating scripts to remove offsets and process measurements: load measurement (without script) and define a region for the offset-correction (an area where your signal is zero, but background signal is not zero), then use a script command for regression in this area (maybe without displaying the result); the resulting formula is automatically remembered internally as the last formula; then use the special command "Minus last formula" to substract the offset from the complete set; following this you may for example use the filter (scriptable as well). (I have used this scripting method to remove the offset and used the filter on 100 sets at the same time by only one click on the "Replay replacing set-Ids"-button.)
Concerning "Replay replacing set-Ids": For some complicated scripts I included options for the set-ids in the scripts: If a set-id is given in the usual way (e.g. g0.s0, please do not use a shortened form here) it is replaced by the selected set-id. If you do not want an id to be replaces write a '$' after it (e.g. "G0.S0$.Y", not "G0.S0.Y$" or "G0$.S0"); in this case the operation will be done with the same set every time regardless which sets are selected (like the standard "Replay"-button does). If a '#' is typed after a set-id the given number is taken as the first id to be used with the first selected set, but the number will be increased for every other selected set. For example: if you select S0, S1 and S2 in G0 as source and destination and have a command like "G0.S0.Y=G0.S0.Y+G0.S3#.Y" and click on "Replay replacing set-Ids" then the set s3 is added to set s0, the set s4 is added to s1 and s5 is added to s2. These extensions will only work in the Commands-dialog if "Replay replacing set-Ids" is used (nowhere else!).
I also included an option to get the set-id or graph-id: Type S# or G# to get the number, i.e. if you select a source set S5 and use S# in the commands somewhere you only get a 5. This is useful if you did feature extraction and want to use every feature-value in the list with a different set: A formula like x=x-G0.S5$.Y[S#] works in this case. This type of formula can also be used in the Data->Transformations->Evaluate Expression-dialog (without the $). Example: Take some measurements and do Feature-extraction: zero-crossing. Now you have your measurements and a new data-set containing the x-value where the measurements cross the x-axis. To shift all measurements in order to cross the x-axis at x=0 select every measurement set in source- and destination-list in the Evaluate-expression-dialog and type: x=x-S7.Y[S#] (the S7 should be the number of the last set, i.e. the one with the zero-crossing-values in it, just replace the 7 with the number of measurements you have) and press apply.
If you need a new set or a new graph, please type S0N or G0N in a command. The number in the id is up to you and is used to refer to the same new id every time you type this command. If you are using this in the commands dialog or the evaluate expression dialog, then the new set or graph is only generated once, even if you selected 50 sets to work on and the command(s) you entered are evaluated 50 times. The set or graph is generated at the first time and the set- or graph-id of the new set or graph is used the remaining times. If you press Apply again, new sets and graphs will be generated again. You can use G0.S0N and G0.S1N and this will generate two new sets in graph 0 and you can work with the identifiers G0.S0N and G0.S1N like with usual set ids. If you use G2N a new graph will be generated. If you use G2N.S3 it is the same as G2N.S3N and it reults in a new graph and a new set, but they are not treated equally if you use both ids in one commands (or list of commands). Then one new graph, but two new sets will be generated. For example: if you have a graph G0 and nothing else and use something like G0N.S3 you will get a new graph G1 and a new set G1.S0. You can refer to this new set as G0N.S3 or G1.S0 and both should work. For new graphs and their sets please use the id you used to create them. If you just create a new set in an existing graph, it is ok to use the usual set-id as well. For example: you have a graph with S0, S1 and S2 and use something like S0N. The internally S0N is always replaced by S3 (the next unused set-id). In commands after the generation of the new set you may then use S3 normaly, because S3 exists then (but be aware of one thing: if you use replay-replacing-set-ids then S3 is replaced and S0N not). You may also use S0N if you like to refer to S3. It does not matter in which order you enter the new commands, just the name is important. If you use S1N and afterwards S0N, then S1N will be the first new set and S0N the second (even with different numbers in the id) because QtGrace does not look ahead. You may as well use an id like S1371N and just get something like S3 as a new set. The number is just to refer to the new set always by an unique identifier. (I hope this was understandable.)
I included an example on the advanced scripting. Try this and you may see how the advanced scripting works.
Because the coordinates in Grace/QtGrace are usually relative to the smaller page-dimension (viewport-coordinates) there is no simple transformation formula between Grace/QtGrace and other applications. Let us assume a page in landscape orientation with the x-y-dimensions a x b in pixels (like 792 x 612 pixels for a Letter-page in 72dpi). In this case b is the smaller dimension and Grace/QtGrace will scale everything in relation to this value (viewport-coordinate '1' corresponds to b pixels in this case; generally: viewport-coordinate '1' corresponds to the smaller page dimension).
In comparison with other applications which give font-sizes in points (pt) I have derived a rough formula for converting font-sizes:
(Grace-char-size) = 445/9*fontsize(pt)*resolution(dpi)/(lower page dimension in Grace)
Or for example in two simple cases:
(Grace-char-size) = 5.817*fontsize(pt) (for letter-pages in 72 dpi)
(Grace-char-size) = 5.983*fontsize(pt) (for A4-pages in 72 dpi)
If you use a letter-page in 72 dpi and want a font-size of 20 pt you have to set the char-size in QtGrace/Grace to 116. As mentioned before: This is a rough conversion based on experimental values. Suggestions for improvements are welcome here as well.
For the regression I created the possibility to generate sets with an arbitrary abscissa. Like with "Create set->by formula" you may now enter values for a paramter $t and a formular that generates x-values form $t (default: "Load x as $t"). In this way you may for example generate sets with x-values increasing as powers of 10 ("Load x as 10^$t" and set start=-5 and stop=5 for x-values between 0.00001 and 100000) which is handy for logarithmic scaling of the x-axis.
This new option is also included in the NonLinearFit-Dialog.
I also included the possibility to just do a regression without producing a new set. Just select "Load: None". This may be useful if you want to use the regression inside a script.
In the same way the filters can be used in the Commands-Dialog you may also use the regression by the following command (you may also use the UnDo-List to automatically generate a command for a script):
#QTGRACE_SPECIAL REGRESSION <nr_of_source_sets>,<nr_of_target_sets>{<first_source_graph>,<first_source_set>;<second_source_graph>,<second_source_set>;...}{<Type_of_fit>,<restriction>,<invert_region>,<nr_of_points>,<Load>,<start>,<stop>,<x_$t_formula>}
Like with the filter-command (see above) please refer to the regression dialog on what numerical values to enter. Example:
#QTGRACE_SPECIAL REGRESSION 1,1{0,2}{0,4}{1;-1;0;250;2;-8.0;-1.0;10^$t}
This will do a linear regression on set G0.S0 and save the result to G0.S4. No restriction is to be used and no inversion. The new set will have 250 points and the x-values will be calculated via "10^$t" with $t ranging from -8 to -1 which results in x-values from 0.00000001 to 0.1. The Load-options is 2 here which means, that the new set will be calculated by a function.
In the Interpolation-dialog I included a few extra options: it is now possible to select a set from a diffent graph as the source-set for the new abcissa.
There is an option to increase the setlength to the next power of 2 (if the setlength is already a power of 2 nothing is changed). If this options is activated, the field for entering the new length is disabled.
For sampling you may now select "Linear in original bounds". This will disable the fields for Start- and Stop-entry and take the minimum and maximum values of x as start and stop. The new set will have the new length as entered (i.e. the value entered in the Length-field or the next power of 2 if this option has been selected). This is different from the Grace-standard-option "Linear mesh" in combination with the "Strict"-option. These settings can reduce the actual length of the interpolated set if start and stop are outside the original source bounds.
The last new option "Expand bounds, keep stepping" will pad the original set with new points (or remove points) by extrapolating the set at the beginning and the end in order to increase (or decrease) the setlength to the Length entered.
In QtGrace it is possible to fill the area between two sets (in Grace only the area between a set and y=0 or y=ymax or other constant values can be filled).
To do so open the set-appearance-dialog for the first set and go to the Line-Tab. Select Type="As polygon" in the Fill properties and select the second set as Polygon base set.
Please note: This option is specific for QtGrace and will not be used if the file with this filling-option is opened in the original Grace.
I want to start this section with a warning: I do not recommend using the options to change the line-style-setup. Only use this if you absolutely have to. The predefined Grace-linestyles should be enough.
You can find the linestyle-selection in the Preferences-dialog. In this tab you can edit different dash-patterns of the current list of linestyles/dash-patterns.
You have to modify each linestyle separately and press one of the command buttons (Edit, Insert, Append) to store the modified linestyles in the list in this dialog. To make your changes effect QtGrace itself you have to press Apply (or Accept). Otherwise your changes will be lost if you close the preferences-dialog.
At the top of the dialog you will find a list with four entries: Current, from project file, from ini file, Grace default. These are the four linestyle lists QtGrace knows at the moment.
"Current" is the list currently used to display lines. If you edit something here it will immediately show in your plot after you press Apply (or Accept). The current list of linestyles is saved into the project-file. On loading a project file the current list of linestyles will be replaced by the list found in the project file to get the same display as was shown when the file was created. If no list of linestyles is stored in the project file, then the list from the ini-file is used.
"from project file" is the list loaded from the project file (if one was present in the file, otherwise this should be the same as the list from the ini-file). This entry is used as a backup in case you edited something and want to go back to the last default of this project.
"from ini file" is the list loaded from the ini-file used to store all general setting of QtGrace. This list is a fallback-option used, if no list of linestyles is stored in the project file.
"Grace default" is the list of linestyles traditionally used by Grace. This list can not be edited - just examined and copied.
In the second line of the dialog you will find a usual linestyle selector. Selecting one of the dash-patterns here will show you the settings for this pattern: the position in the list of patterns, the length of the definition (how many black and white blocks) and a representation of the elemental blocks for this pattern. Every pattern is defined by a number of blocks (like pixels) in either black or white. You can change the color of a block by clicking onto one of the rectangular fields below the "Length" selector. This will just change the current display in this dialog to show you how this edited linestyle would look like. To actually change the list currently selected, you have to use Edit, Insert or Append. Edit changes the linestyle at the currently selected position, Insert moves all following linestyles one number downwards and inserts the newly edited linestyle. Append just appends the new linestyle at the end of the list. Every editing just effects the list currently selected. You may also delete some linestyles or change the order by using Up or Down to move the linestyles inside a list.
Please note, that editing the "from project file"-list is (in most cases) useless, because this list is not used and not saved (it is just ment as a backup). Editing the "from ini file"-list will change the general fallback default list for the future. Changing the Current list will take effect immediately and these settings will be stored in the project file on the next save operation.
To copy one list, you have to use the buttons "Use these linestyles as current" or "Use these linestyles as current and general defaults". In this way you can for example reset the linestyles to the Grace-styles. Using just current, means, that this effects only the current project. With General defaults, this will also effect the linestyles stored in the ini-file.
QtGrace starting from v0.2.5 has a largely extended Preferences dialog.
The first tab (Grace) contains the standard preferences from Grace. The tabs QtGrace-GUI and QtGrace-Behavior and Miscellaneous contain specific options for QtGrace, the Defaults-tab contains the defaults used by QtGrace to initialize new items and the last two tabs are the Color-Management and Line-Style-Selector (see separate chapters for these two tabs).
One important thing to remember about the Preferences dialog: The Apply/Accept-buttons do effect the tabs from Grace to Miscellaneousa and not Defaults/Linestyles/Colors. These tabs have their own Apply/Accept-buttons. This is for safety in order not to change something involuntarily.
The GUI-tab and the Behavior-tab contain settings about the behavior of QtGrace and about the appearance of the dialogs. You can set here what encoding and what decimal separator you want to use. You can also set whether you want to use the QtFonts and whether you want to use the LaTeX commands. Immediate updates let every change you make immediately be represented in the plot. The drawback is, that you also get a lot more entries in the undo-list. You can select the font used for all dialogs (or reset it to the systems-default). Usually the background of the main Window is of the same color as any dialog. The plot area is usually white. You can change the background-color of the widget around the draw area to the Plot/Page-background-color or any other color you like. The other options should be self-explanatory.
The interface customization concerns the main dialog of QtGrace. You can activate or deactivate different features in the tool-bar on the left hand side and edit what is displayed in the status bar on the right hand side.
The gui-settings at the bottom of this preferences-tab take effect after you restart QtGrace. This includes for example the setting of the dialog language (please note, that appart from english only german is listed here at the moment, but the german translation is faaar from being complete - I will improve this, when I have some time - maybe next release). The default printing device is used as a standard setting for the print setup. You may also select "Last selection" which means, that the setting you used the last time will be set at the next restart of QtGrace.
You may also select here the default-project-file QtGrace uses if you restart QtGrace or when you do File->New (this setting has an immediate effect: after pressing apply the file that is loaded when you do File->New is the one that is set here). Please note, that the default file has be placed in the bin-subfolder. Also keep in mind, that the settings in the Defaults-tab only effect new items. The settings for the first graph and for the plot are stored in the default file that is loaded on startup. If you for example want to change the default fonts everywhere, you have to alter the Default.agr-file and the settings in the Defaults-tab.
Finally there are the settings about the size and position of QtGrace on startup. You can set the current size and position as default if you like or set some specific values. To take effect you have to press Apply, close QtGrace and restart it. Closing QtGrace is important here, because these settings are stored in the ini-file and this file is written to only when QtGrace closes normally. For savety reasons the x- and y-values that can be set here are limited to 90% of your screen size and the height and width is limited to your screen size. Please note, that if the set dimensions or positions do not fit your screen, your operating system might ignore some of these settings.
In the Miscellaneous-tab you can choose to open help-files in a specific browser (instead of the defult browser of your system). The Show/hide workaround is sometimes needed on Linux-system, but I think it should not be neccessary. You can also set, that you want to use a print-command instead of the native printer dialog of your operating system. For the physical printer there are two output-quality options. Either use the screen-resolution or the much higher printer resolution. If you activate the HD-output-option, then the maximum printer resolution is used. Please note: the higher resolution results in finer fill patterns. You may also set a few other things that should speak for themselves. You can alter the settings about the external libraries libFFTW3 and libHaru.
If the external libraries are not compiled in statically and you want to use them you have to set the path to the dynamic libraries (*.dll on Windows and *.dylib on Mac OS X) here. After library files have been chosen, QtGrace checks, whether the functions needed are inside the selected libraries. If this is the case you should see a green box stating, that the library is usable. If you want to use it, you also have to check the "Use FFTW3"- / "Use libHaru"- Box. If the libraries are included statically during compilation, then you only have to choose whether you want to use them or not.
The Defaults-tab contains the settings used when new elements like graphs or sets are generted. There are different defaults here: the Current ones used at the moment, the ones loaded from the project file, the ones loaded from the ini-file and the Grace-default. The defaults are stored in every project file, but there is also a set of defaults stored in the ini-file. QtGrace uses the defaults stored in the ini-file. The settings loaded from the project-file are remembered and saved in the file again, if you resave it. The current settings will be saved in the ini-file if you close QtGrace. To alter the defaults stored in the project file, use the button "Use there defaults for this project file". To replace the current defaults use the button "Use these defaults as current defaults". I hope this is understandable for you and you understand why I did it this way: I wanted to have just one set of defaults (the one in the ini-file that is used constantly), but I did not want to lose the old settings. Suggestions for improvements are always welcome!
In every popup-menu (summonded via right-clicking) for graph- or set-lists there is a Selection-item at the bottom.
There are now additional options. Every one of the following options is an additional selection - already selected sets or graphs will be kept selected.
QtGrace can now communicate with external programs (clients) using a QTcpSocket connection. QtGrace is setup as a TCP socket-based server using the QTcpServer class from Qt.
In order to communicate with QtGrace, QtGrace has to be started in ServerMode with 2 extra arguments. The first argument is the QTcpSocket port used to write data to QtGrace from the client, and the second argument is the port used to read data from QtGrace to the client (QtGrace uses the LocalHost as address). It's a requirement that the client uses a QTcpSocket connection to communicate with QtGrace. In the QtGrace client example a communication protocol has been implemented for the user to see how to read and write from/to QtGrace via a QTcpSocket connection (see qtclient-folder in the examples-folder).
In conclusion, QtGrace acts as a server when it reads the data from the client and QtGrace is therefore processing the data. When QtGrace sends data, QtGrace is using a new socket to communicate with the client. Therefore the client is processing the data received from QtGrace.
Please refer to the Qt-documentation for further information about the QTcpSocket communication protocol.
In the following section the low-level communication protocol in the QtGrace client example is explained (I will not give a description on how the TCP-communication and the internal states work.)
Each communication with the client is initiated with a command to tell QtGrace how to handle incoming/outgoing data. The client can send the following 10 commands to QtGrace (please see the communcationsProtocol.ccp file in the QtGrace client example):
// Clear the plot and send the graph and set information to QtGrace
cleanPlot();
sendDataVector(int dataLength, double*xData,double*yData )
setRedrawMode();
sendPSFileName();
sendScalingModeInfo(int graphNo, int mode, double xStart_value, double xEnd_value);
The client can send 3 different types of scaling (mode):
DEFAULT_LAYOUT, number 0 //do nothing
AUTOSCALE_ALL_AXES_OR_JOIN_PLOT, number 1 /* autoscale all axis - default*/
AUTOSCALE_Y_AXIS_OR_OVERLAY, number 2/* autoscale y axis (send xStart_value and xEnd_valuea */
setRedrawAndWritePSMode();
sendLayoutModeInfo(int graphNo, int layout, int col, int numGraphs)
The client can send 4 different types of layouts:
DEFAULT_LAYOUT,number 0 //do nothing
AUTOSCALE_ALL_AXES_OR_JOIN_PLOT, number 1 // join plot
AUTOSCALE_Y_AXIS_OR_OVERLAY,number 2 //overlay
GRAPH_POSITION, number 3 //Set graph position, i.e. numbers of columns and rows.
killChild();
endTransmission();
sendDataSetToQtGrace(double *x,double*y);
readPlotParametersFromQtGrace();
The function returns a QString with the plot parameters.