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. 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.
xyscan is written using Qt, a cross-platform C++ GUI application framework. Whatever formats Qt support xyscan can handle. Here's the current status (Nov 2002):
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 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 simple check the change of the values when advancing ± one pixel in each direction. You should always check that the result is meaningful and estimate the accuracy.
Please note xyscan is distributed with NO WARRANTY OF ANY KIND. The author does not accept any responsibility for the consequences of using it.
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.