Often the actual value of data points depicted in graphs and plots are not available in tabulated form. That's a well known problem for many scientists and the usual way out is to take a ruler and read the values off the plot yielding low precision. 'xyscan' is written to overcome this problem by providing a tool that allows one to retrieve these values with reasonable accuracy. The actual work, i.e. the scan, needs to be performed by the user but the program calculates the coordinates (and errors) and stores the data for later retrieval. This program overcomes the need to read the points off by hand and is by far more precise.
When launched, the xyscan main window pops up. The large area under the menu bar is called the canvas. At startup it shows a splash screen. The canvas is the desktop on which the scan is actually performed. First we need to open a file which contains the graph. To learn about the supported formats click here. Use Open in the File menu to load a pixmap or simple press CTRL+O. This will open a file dialog which lets you pick a file containing the graph to scan. The file dialog applies a filter which allows you to load only supported graphics formats.
Together with the pixmap a pair of two red lines appears, in the following referred to as crosshair. Both lines are exactly one pixel wide. The intersection between the vertical and the horizontal line defines the cursor position. The current x,y coordinates of the cursor can be checked with the Coordinate Display. Click on Coordinate Display in the View menu or the accelerator keys ALT+1 to pop it up. Figure 1 shows the main window after the pixmap was loaded but the markers (see below) are not set yet.
Figure 1: xyscan main window after pixmap is laded but no markers are set yet.
Move the cursor (crosshair) using the arrow-up, arrow-down, arrow-left and arrow-down keys. The step size for movement is 1 pixel. If you want to move the cursor faster (in larger increments) press the Shift key together with the arrow key.
Next step is to place 4 markers that allow xyscan to perform the coordinate transformation from pixel to graph coordinates. In the following we call the markers x1, x2, y1, and y2. You can place them in any order but make sure that x1 < x2 and y1 < y2. The x1 and x2 marker are red, y1 and y2 are rendered in blue. To place a marker, move the cursor (crosshair) along the x- or y-axis and stop exactly at the intersection between the axis line and a tic mark. Although an x-axis marker is mainly used to define a reference point in x, its y position matters since it is used to determine a possible tilt of the x-axis with respect to the canvas (same for y -axis of course). Once you consider the cursor correctly placed you can use (i) either the Place ... Marker items in the Marker menu or (ii) use accelerator keys to place the marker.
After a marker is placed you are asked to define the corresponding axis value in a dialog window. Once all 4 markers are in place the main window looks as depicted in the example in Fig 2.
Figure 2: Main window after all 4 markers are set. x markers are red, y markers are blue.
In the example above the x1 marker was assigned a value of 0, x2 = 100, y1 = 15, and y2 = 100. Remember that the markers can be re-placed anytime in any order. They also can overlap and even can sit on top of each other. We are now ready to scan data points.
Move the cursor (crosshair) to any point. The Coordinate Display now also shows the transformed position, i.e., the position in graph coordinates, while you move the cursor over the canvas. Make sure everything is correct before you start to store data points.
Figure 3: Coordinate Display after all markers are set. Numbers in the left column are "raw" coordinates, on the right the transformed numbers corresponding to the plot metric (if the markers are set correctly).
To store the coordinates of the current cursor position (the values of the data points) press the space key. To see what data points you already stored pop-up the Data Table. To do so use Data Table in the View menu or the accelerator key ALT+2. The window looks as follows:
Figure 4: Data Table window. Shown is an example of a scan that extracted only the x,y position but no errors.
Note, that in this example we scanned only the data points not the error bars. That's why all errors have a value of 0 in the table above. Since xyscan version 2.03 it is possible to remove the last row in the table by selecting Remove Last Row in the new Table menu (or use accelerator key Ctrl+Z). This is especially useful when you accidentally scanned the wrong point, or if you are not happy about the accuracy of a previous scan. In case you want to start all over again select Clear All in the Table menu. This will clear the whole table. In order to write the data points stored in the table to file use Save or Save As in the File menu. The output format is discussed below.
To summarize the basic steps for every scan session:
xyscan also allows scanning error bars. It always assumes asymmetric errors, i.e. you always have to scan the left (lower) and the right (upper) error bar separately, even if the errors are symmetric. However, depending on the settings xyscan allows you to store symmetric errors, i.e., one error value for x and/or y, respectively. The symmetric error value is then derived from the two asymmetric errors (upper|lower or left|right) either by averaging in order to increase precision or by using the larger of the two error values error in case you want to play it safe. To select the referring option use the submenus Scan X-Error Mode or Scan Y-Error Mode in the Settings menu. Select one of the following:
If you decide to scan the errors in any of the modes described above the work flow described in the simple example above changes slowly:
xyscan can handle tilted plots although the accuracy will be somewhat degraded. It is very important that the markers are placed as accurately as possible. Here's an example:
Figure 5: Example of a scan of a tilted plot. Note the positions of the marker.
The exact position of the markers on the canvas allows the program to determine the tilt and take it into account. Note that xyscan cannot handle distorted plots of any kind other than tilts. Also keep in mind that the precision is severely deteriorated when scanning from tilted graphs, especially for the error bars. It is strongly recommended to correct the tilt before scanning using one of the many graphics manipulation programs available on Linux and Windows.
xyscan is written using Qt, a cross-platform C++ GUI application framework. Whatever format Qt supports can be handled by xyscan. For version 2.09 that is: PNG, BMP, XBM, XPM and PNM. It also support JPEG (at least on Windows, and Linux). GIF is not supported. PS or EPS files need to be transformed to one of these formats before it can be used. The most portable format is indeed the PNG format which provides loss-free compression and 8 or 24-bit color encoding.
The scanned data can be written to file using Save or Save As in the File menu. The output format is plain ASCII text. Here is an example:
# Created by xyscan on: Wed Oct 30 21:07:52 2002
# x y -dx +dx -dy +dy
34.0433 68.7861 0 0 0 0
38.7545 63.3237 0 0 0 0
89.9278 28.2081 0 0 0 0
80.0181 80.2312 2.43682 2.43682 0 0
74.9819 75.0289 5.0361 10.2347 0 0
35.9928 60.9827 0 0 0 0
26.4079 51.3584 1.94946 2.43682 0 0
# EoF
The output is in table format with x and y in the first two columns followed by the asymmetric errors in x and y. The format is always the same independent of the settings used for the scan. It is easy to import the table into analysis and plotting frameworks such as PAW and ROOT.
The precision one can achieve depends pretty much on the quality of the plot and of course on how careful the scan is performed. Assuming a perfect plot and a perfect scan the precision is not better than the equivalent of one pixel. To get a feeling on the achievable precision select Current Precision in the View menu (or use the accelerator key Ctrl+P). The information dialog that pops up displays the current precision corresponding to +/- one pixel in every direction. For logarithmic axis the errors will be of course asymmetric. Although not a perfect estimate, the errors shown should give you a feeling on the precision of the scan and how serious you should take the obtained values.
Figure 6: Popup dialog showing the current precision of a scan.
Note: the accuracy for tilted plots is worse than that. This is especially a problem for the error bars, whose tilt is not currently taken into account.
Currently three platforms are supported: Windows XP, Mac OS X, and Linux. That does not mean that this version of xyscan does not run on various other UNIX or MS platforms; it simply means that the author has no means (and no time) to test in on platforms other than the supported ones.
Linux: Requires the presence of Qt shared libraries. This is usually not a problem since a non-commercial version of Qt comes with a GNU General Public License and is available on almost all Linux installations. If not you can download it from Trolltech (http://www.trolltech.com). Works with Qt 3 only.
Windows: The current version of xyscan compiles flawless with Visual Studio 7 using the non-commercial Qt3 version. The referring Qt dynamic link library is needed. Most other DLLs required should be already installed on your system.
MacOS: This is a new platform I try to support. This applies to Mac OS X only of course. It compiles with gcc shipped with MacOS and Qt 3.
xyscan comes with a detailed manual (the one you are currently reading) that can be viewed by either pressing Ctrl+M or selecting Manual in the Help menu. There is also a quick help window that provides a short description of the most important commands and their shortcuts. To view, use Ctrl+I or select Quick Help in the Help menu. For version number, license, and copyright notice select About xyscan (no shortcut). If you have a real problem using or installing xyscan you can also contact the author (thomas.ullrich@bnl.gov).
New features:
Copyright 2002-2007 Thomas S. Ullrich
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.