Often the actual value of data points depicted in graphs and plots are not available but urgently needed. That's a well known problem for many scientists and '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 of a piece of paper using a ruler and is by far more precise.
When launched, the xyscan main window pops up. Other than the menu bar you will see mainly blank canvas. 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 see 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. The figure below depicts the window after the pixmap was loaded but the markers (see below) aren't set.
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 top 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. The markers are called 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 Settings menu or (ii) use accelerator keys to place the marker.
After each marker is placed you are asked to define the corresponding axis value. Once all 4 markers are in place the main window looks as follows:
In the example above the x1 marker was assigned a value of 10, x2 = 100, y1 = 10, 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.
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:
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 to scan 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. Set the Scan X-Error Bar and/or Scan Y-Error Bar options in the Settings menu if you intend to scan the referring error bars. If set, 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:
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 severly 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. Here's the current status (Nov 2002) from the Qt documenation:
Qt currently supports the following image file formats: PNG, BMP, XBM, XPM and PNM. It may also support JPEG, MNG and GIF, if specially configured during compilation. The different PNM formats are: PBM (P1 or P4), PGM (P2 or P5), PPM (P3 or P6). PBM, PGM, and PPM format output is always in the more condensed raw format. PPM and PGM files with more than 256 levels of intensity are scaled down when reading.
Warning: Unisys has changed its position regarding GIF. If you are in a country where Unisys holds a patent on LZW compression and/or decompression and you want to use GIF, Unisys may require you to license that technology. These countries include Canada, Japan, the USA, France, Germany, Italy and the UK. GIF support may be removed completely in a future version of Qt. We recommend using the PNG format.
The support for the various formats depends slightly on the platform. JPEG format is for example only supported on Linux. 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. It looks as follows:
# 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.
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 there are only two supported platforms: Windows XP and RedHat Linux 7.3. That does not mean that this version of xyscan does not run on many other Linux version/installations or on Windows 2000; 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).
Windows: The current version of xyscan is compiled with Visual Studio 6 using the non-commercial Qt version 2.3. The Qt dynamic link library qt-mt230nc.dll is included in the installation archive. Most other DLLs required should be already installed on your system.
Copyright 2002 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.