xyscan 2.09 - Manual

Content

  1. Introduction
  2. A Simple Example
  3. Log Scales and Error Bars
  4. Scanning Tilted Plots
  5. Supported Graphic Formats
  6. Writing Data Points to File
  7. Tips for Generating Pixmaps
  8. Remarks on Precision
  9. Supported Platforms
  10. Getting Help
  11. What's new in ...
    1. 2.07
    2. 2.09
  12. Copyright Notice and License

Introduction

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.

Top

A Simple Example

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:

  1. Open the pixmap
  2. Place the 4 markers
  3. Scan data points and store their values
  4. Write data to file

Top

Log Scales and Error Bars

The example above is a much idealized one. Often x- and/or y- axis have a log scale and usually we want to know the errors associated with the data points as well, i.e. we need to scan the error bars. All this can be done by selecting the appropriate options in the Settings menu. If the x-axis has a logarithmic scale set the Log-X option, if the y-axis is in log set the Log-Y option. xyscan will automatically take the log scale into account when performing the transformation from pixel to graph coordinates.

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:

No Error Scan
No error scan will be performed and you proceed as in our simple example above.
Asymmetric Errors
Lower and upper (left and right) error bars are scanned and stored separately.
Symmetric Errors (use [upper+lower]/2)
Lower and upper (left and right) error bars are scanned but only the average (arithmetic mean) of both is stored. Choose this option when the error are symmetric and you want to increase the precision of the error values.
Symmetric Errors (use max[upper,lower])
Lower and upper (left and right) error bars are scanned and but only the largest of the pair is stored. Choose this option when you want to play safe.

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:

Top

Scanning Tilted Plots

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.

Top

Supported Graphics Formats

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.

Top

Writing Data Points to File

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.

Top

Tips for Generating Pixmaps

xyscan only accepts bitmap and pixmaps of certain formats. More sophisticated vector-graphics formats such as PS, EPS, and PDF, are not supported. It is however easy to convert them into any accepted pixmap format. There are many (free) converter tools available for almost every platform. On Linux there are for example ghostscript, convert, ee, xv, gimp, and many more. On Windows there are: GSView, the Windows Picture Viewer, and of course Photoshop and Illustrator. Here a few tips you should consider when creating the pixmaps:

Top

Remarks on Precision

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.

Top

Supported Platforms and System Requirements

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.

Top

Getting Help

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).

Top

What's new in ...

2.07

New features:

  1. Changes in the error scan procedure: xyscan 2.07 now allows to store symmetric errors. You still need to scan the upper|lower and/or left|right edges of the error bars but only one error value gets stored. The error scan mode can be selected in a new submenu under the Settings menu. For more details see chapter Log Scales and Error Bars.
  2. Documentation updated.

2.09

Improvements and modifications:
  1. Qt3 is now used on all platforms. Qt4 has to wait.
  2. The File Browser now starts by default in the home directory and from then on xyscan will remember the last directory visited. This applies for the directory where the loaded pixmap is located as well as the directory where the tables get stored. The last visited directories (pixmap and table) are stored at the end of the session and will be used by default when you start xyscan again.
  3. All versions now also with jpg support (gif still missing everywhere).
  4. New main menu 'Marker' that contains all set-marker commands.
  5. Mac version now comes with its own set of icons.
  6. xyscan can now handle transparent plots, a problem in the previous version.
  7. Fixed broken Shift+arrow functionality for fast crosshair movement on the Mac.
  8. xyscan now reads startup pixmap from the command line (Usage: xyscan [-v] filename).
  9. Main window now resizes accurately when a new pixmap is loaded. Canvas becomes exactly the size of the pixmap, not more or less.
  10. Few minor bugs fixed.
  11. Documentation updated.

Top

Copyright Notice and License

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.

Top