STIPlotDigitizer. User s Manual

Transcription

1 STIPlotDigitizer User s Manual

2 Table of Contents What is STIPlotDigitizer?... 3 Installation Guide... 3 Initializing STIPlotDigitizer... 4 Project GroupBox... 4 Import Image GroupBox... 5 Exit Button... 5 Calibrating the Software... 6 Image Window... 6 Zoom Window... 6 X and Y Axes GroupBoxes... 7 Point Markers GroupBox... 7 Image Information Textboxes (Before the Calibration Process)... 9 Creating a Series Image Information Textboxes (After the Calibration Process) Series Entry Series Name Textbox Color Button Marker Type Selection Interpolation Type Selection Interpolation Line Style Selection Creating Digitized Data Points Data Points GroupBox Manual Plot Digitization Automatic Plot Digitization Visualizing, Manipulating, Interpolating, and Exporting Data Points Interpolation GroupBox Table of Values GroupBox Export Data GroupBox Export Data Format... 18

3 What is STIPlotDigitizer? Data in reports and publications is often presented as X-Y type line or scatter plots. STIPlotDigitizer is software that allows you to convert these images and graphs to data points, in other words to digitize data from plots. This is very useful if you wish to analyze plot data, perform mathematical operations such as regression on the data or plot the data using your favorite graphing software. STIPlotDigitizer allows you to digitize and store data for multiple curves contained in the same image. STIPlotDigitizer contains the following features: Automatic (selection is based on pixel color) & Manual Point Selection (selection is made using a mouse). Interpolation of data points using: Piecewise Cubic Hermite Interpolating Polynomial (PCHIP); Spline; Linear; Nearest-Neighbor Interpolation Type. Digitized can be exported as a text file, to Excel or to Matlab. Corrects for the rotation of images as well as the non-orthogonality of the axes. Unique 3-point Graph Calibration. Include & Exclude Areas from the image. Supports linear, semi-log, or log-log plot Installation Guide STIPlotDigitizer uses the MATLAB Compiler Runtime (MCR) and therefore MCR must be installed in order to use the software. The version of MCR used is 8.4 (R2014b) for 64-bit Windows and is included with the software. Follow instructions for installation of MCR. The next step is to run the licensing application, STIMathSoftwareLicensing.exe. On first time use, the licensing application will detect that the application has not been registered in the Windows registry and will attempt to validate the license key, which a user will have received by . Enter the license key in textbox (shown below) and click the Validate/Check License Key button. The validation and registration is done on our server and requires an Internet connection. The STIPlotDigitizer executable can reside in any folder a user wishes to use.

4 Initializing STIPlotDigitizer On launching the software, a window resembling Figure 1 will be displayed Figure 1 - STI Plot Digitizer Initialization STIPlotDigitizer contains various elements such as tables, groupboxes, buttons and textboxes, which become active or inactive, depending on the whether their functionality is meaningful. The following become active: 1. Project GroupBox 2. Import Image GroupBox 3. Exit Button Project GroupBox The Project tab allows you to Create a New Project, Open a Project, or Save a Project. A project is a collection of all data and digitization associated with an image. This is accomplished by the New, Open, and Save buttons, respectively, when active. The New button clears the current project and all associated data. The Open button opens a previously saved project. The Save button saves the current project to a Matlab binary file, referred to as a.mat file.

5 Import Image GroupBox The Import Image groupbox allows the user to import the image that is to be digitized. An image can be imported from any of the popular image types such as JPG, BMP, GIF or from the Windows clipboard. The From File button allows you to import and image from a file. The From Clip button allows you to import an image that is currently in the Windows clipboard. Simply click either on the From File or From Clip button to import an image to STIPlotDigitizer. If there is no image in the Windows clipboard and you click From Clip, an error pop-up will appear. Exit Button The Exit Button can be clicked at any point to exit STIPlotDigitizer. You will be prompted to confirm exiting the program because all data that is not saved will be lost.

6 Calibrating the Software After importing an image to STIPlotDigitizer (either through the From File button or the From Clip button in the Import Image Tab), more groupboxes will become active as shown in Figure Figure 2 Calibrating the Software The following areas will become active after importing an image: 4. Image Window 5. Zoom Window 6. X and Y Axes Groupbox 7. Point Markers Groupbox 8. Image Information Textboxes Image Window Displays the image that is being digitized. Zoom Window Shows a magnified view of the Image Window in the vicinity of the cursor by a factor specified in the Zoom listbox. The zoom value can be varied between 2 and 10.

7 X and Y Axes GroupBoxes Allows you to specify the X and Y Axes properties and names. It contains the following: The Label textbox specifies the label used for axis. The Style buttons specify the type of axis, which can be one of the following: Lin - linear Log 10 - log base-10 Log e - base-e Point Markers GroupBox Elements in this groupbox are used to calibrate the software, which is a prerequisite that enables other elements of the software that depend on calibration. The Point Markers groupbox contains the following: The Point X buttons (where X ranges from 1-3) allow the user to create a point marker within the Image Window. Please note that the 3 point markers cannot all be collinear, meaning they cannot all lie in a single line. The Point Coordinates textboxes allow the user to specify the X and Y coordinates of the points created through the Point buttons. The Cal button is used to calibrate the image after the Points and Coordinates have been created.

8 The following lists the steps involved in calibration: 1. Create point markers for Point 1, Point 2, and Point 3 in the Image Window. This can be done by clicking each of the Point X buttons, and clicking on the Image Window. For accurate calibration, it is always preferable to have the points should spaced out as much as possible, as shown in Figure Figure 3 Point Markers Example 2. Input the point marker coordinates in the textboxes provided. For example, for Figure 3, the calibration coordinates would be (20,0), (180,0), and (100,4500) for Point 1, Point 2, and Point 3 respectively. Coordinates could also be entered in scientific notation; i.e. (2E1,0), (18E1,0) and (1E2, 45E2). 3. Click on the Cal button, indicated by the red arrow below, to finish the calibration process. Figure 4 - Calibration Button ("Cal")

9 Image Information Textboxes (Before the Calibration Process) The image information shows the following textboxes before the calibration process: The File Name textbox shows the location of the image. The Image Size textbox shows the size of the image in pixels. The Cursor, Theta, and Phi textboxes become active after the calibration and are described in detail in the Creating a Series section.

10 Creating a Series After calibration, the workspace will resemble what is shown Figure Figure 5 - Creating a Series The following will become active after calibrating STIPlotDigitizer: 8. Cursor, Theta, and Phi Textboxes 9. Series GroupBox Image Information Textboxes (After the Calibration Process) The image information now also shows the following textboxes: The Cursor textbox displays the mouse coordinates. The Theta textbox shows the automatically calculated angle of rotation of the image with respect to the X and Y axes in the image window. It is used by the software for calibration of rotated images. The Phi textbox shows the automatically calculated angle between the image X and Y axes. In a perfectly aligned image, this angle is 90 degrees. It is used by the software for calibration of skewed images.

11 Series Entry After calibration, the next step is to create a data series in which to store the data points for the digitized curve. STIPlotDigitizer allows you to digitize and store data for multiple curves in the same image. A series contains the data points associated with the digitization of a particular curve. The following are the buttons in the Series groupbox. New - Create a new series. Delete - Delete an existing series. Edit - Edit an existing series. Clicking the New button will make a pop-up window appear with various properties used to specify a new series, as shown in Figure 6 below. Figure 6 - Series Parameters Series Name Textbox This textbox allows the user to define the name of the series, which is a required input. No two series can have the same name, and a series name cannot contain any spaces. The string for this entry must be a valid Matlab variable name. A valid variable name is a character string of letters, digits, and underscores, and beginning with a letter. As well, the use of brackets of any kind (squared round or curly) is not allowed. A message box will be displayed if the string used is not a valid format. Color Button The color button allows you to select a color for the digitized data point markers and lines.

12 Marker Type Selection The marker type selection allows you to choose between several symbols or letters for the digitized data point markers. Interpolation Type Selection The interpolation type selection allows the user to select a type of interpolation to fit the digitized point markers into a curve. The following options are available: pchip - Piecewise Cubic Hermite Interpolating Polynomial (PCHIP) Interpolation spline - Cubic Spline Interpolation Linear - Linear interpolation Nearest - Nearest-Neighbor Interpolation Interpolation Line Style Selection The interpolation line style selection allows you to choose between different line styles for the fitted curve. The interpolation points line color will be the same color as the markers.

13 Creating Digitized Data Points After creating the first series, more tabs will become active and the window will resemble what is shown in Figure Figure 7 - Creating Digitized Data Points The following groupboxes will become active: 10. Data Points 11. Table of Values Data Points GroupBox Allows you to control the way in which data points for the digitized are entered, which can be Manual or Auto. Manual - digitizing option, where you select the data points manually using the mouse. Auto digitizing option, where data points are automatically selected based on pixel color. The following sections will describe how the Manual and Automatic data point digitization work.

14 Manual Plot Digitization The Manual option requires the user to add data points manually. It can be controlled by the buttons shown in Figure 8. Figure 8 - Manual Point Selection The Add button allows the user to click on the Image Window to create data points. The Del button is used to delete data points that have been entered. To delete, click the Del button and click on a point in Image Window near the location of the data point to be deleted. The listing of data points will be updated to reflect points that are added or deleted. Automatic Plot Digitization The Auto option allows STIPlotDigitizer to automatically create data points from the image based on pixel color. It can be controlled by the buttons and options shown in Figure 9. Figure 9 - Automatic Point Selection Plot Color - allows you to click on the Image Window to select the color of the pixels that for the curve to be digitized. The selected color is displayed to the right of the Plot Color button. Back Color - allows you to click on the Image Window to select the color of the background. White is the default background color. The selected color is displayed to the right of the Back Color button. Win Width - used to specify the width in pixels of the averaging window. It controls how many pixels to average over in the horizontal direction when scanning a plot line the larger this number, the fewer the number of points produced. Color Tol - is used to specify the color tolerance. The higher this number the wider the range of colors that the software will recognize as valid data points.

15 Win Height - used to specify the width in pixels of the averaging window. It controls how many pixels to average over in the vertical direction when scanning a plot line the larger this number, the fewer the number of points produced. Scan scans the image for data points based on settings for the Auto digitizing option; namely Plot Color, Back Color, Win Width, Color Tol and Win Height. The digitized points will appear as markers in the Image Window. Import Scan imports the Auto scanned data points to the Table of Values grid. Undo Scan deletes the markers in the Image Window. Include and Exclude used to define polygons within the Image Window to control the area of digitization. The Add button adds an area, Del button deletes them, and Col button controls the color of the polygon. Automatic Plot Digitization: Include and Exclude Areas Include and Exclude Areas allow the user to have more control over the data points selected during automatic selection. An Include Area forces the software to only select data points within this area. On the other hand, an Exclude Area prevents the software from selecting data points within this area. Note that an Exclude area can be defined within an Include area however an Include area cannot be defined within an Exclude area. The following is a guide on how to use an Include or Exclude area. 1. Click on either the Include or Exclude Add Button. 2. Click on the Image Window to define the Include/Exclude polygon s vertices. 3. Click on the Add Button again to close the polygon. 4. Click on the Scan Button to scan for Data Points.

16 Figures 10 and 11 show examples of Include and Exclude Areas. Figure 10 - Include Area (Blue) Figure 11 - Exclude Area (Red) within an Include Area (Blue) Automatic Plot Digitization: Importing Data Points to the Table of Values Once the software has generated adequate Data Points, the user can click on the Import Scan button to accept these values and import the data points to the Table of Values Tab. Alternatively, the user can click on the Undo Scan button to discard the automatically generated Data Points.

17 Visualizing, Manipulating, Interpolating, and Exporting Data Points After data points have been entered, the software window resembles what is shown in Figure Figure 12 - Visualizing, Manipulating, Interpolating, and Exporting Data Points Arrows show the locations of the following: 12. Interpolation Groupbox 13. Table of Values Groupbox 14. Export Data Groupbox Interpolation GroupBox The Interpolation Tab allows the user to have data points interpolated to create more points. The interpolation type (e.g. pchip, spline, etc ) to be used for a series is specified when creating the series but can be modified at any time, as can other series properties, using the Edit button in the Series groupbox. It contains the following buttons and textboxes: Clicking OFF will turn interpolation ON. By default, interpolation is turned off. # of interp. pts. controls the number of interpolation points. A valid entry is an integer between 10 and Undo deletes the generated interpolation points from the Image Window.

18 Table of Values GroupBox The Table of Values grid lists all the digitized data points as well as interpolated points. The following shows how to control what is displayed in the grid. When the Data radio button is selected, the table of values only shows the digitized data points. Interpolated data points are not shown. When the Interp. Radio button is selected, the table of values only shows the interpolated data points. Digitized data points are not shown. When the Project radio button is selected, the table of values shows the data points of all the series within the current project. When the Series radio button is on, the table of values only shows the data points of the selected series. The Delete button is used to delete data points from the table of values. To delete data points, highlight data points in the Table of Values grid and click on the Delete button. Non adjacent values can be selected using the CTRL button. The Undo button allows you to undo data points that have been previously deleted. Export Data GroupBox Data can be exported in various formats using selections in the Export Data groupbox. The following are used to control what project data you wish to export and its format (e.g. text file, Excel or Matlab). Data - checkbox to select whether to export digitized data points. Interp. - checkbox to select whether to export interpolated data points. When the Project radiobutton is selected, the software will export the data points within the table of values of all the series within the current project. When the Series radiobutton is selected, the software will export the data points within the table of values of only the series that is currently highlighted. The Delimited button exports the data points in.txt format where data is delimited by the symbol specified on the textbox next to it. The default is, for comma-separated values format. The Excel button exports the data points as an Excel.XLS file (Microsoft Office Excel ). The MATLAB button exports the data points as a.mat file, which is the standard Matlab binary file format. Export Data Format Exported data in text and Excel format, have as the first row, column headers for the data. The column headers are formed by concatenating the name of the series with the axis label. For example if you named one of your series Seies1 and called the x-axis Hook Load then the column header for the x-axis digitized data points would be Series1Hook_Load. If you named the y-axis Measured_Depth, then the y-axis data column header is Series1Measured_Depth. The interpolated data column headers have a similar naming convention. The only difference is the word Interpolated.

19 For the same series, the header for the x-axis interpolated data points would be Interpolated_Series1Hook_Load and for the y-axis data column header would be Interpolated_Series1Measured_Depth. When the project data is exported as a Matlab file, the following arrays hold the data. DataPointsArray contains the columns of digitized data points. There will be 2 columns; an x-axis column and a y-axis columns for each of the series in the project. InterpPointsArray contains the columns of interpolated data points. There will be 2 columns; an x-axis column and a y-axis columns for each of the series in the project for which interpolations has been used. SeriesNamesArray contains the names of each of the series. Because of the way in which STIPlotDigitizer exports data, the string for this entry must be a valid Matlab variable name. A valid variable name is a character string of letters, digits, and underscores, and beginning with a letter. Any spaces will be replaced with an _. As well use of brackets of any kind (squared round or curly) are not allowed. A message box will be displayed if the string used is not a valid format. Xlabel text used for x-label. Because of the way in which STIPlotDigitizer exports data, the string for this entry must be a valid Matlab variable name. A valid variable name is a character string of letters, digits, and underscores, and beginning with a letter. Any spaces will be replaced with an _. As well use of brackets of any kind (squared round or curly) are not allowed. A message box will be displayed if the string used is not a valid format. Ylabel text used for y-label. Because of the way in which STIPlotDigitizer exports data, the string for this entry must be a valid Matlab variable name. A valid variable name is a character string of letters, digits, and underscores, and beginning with a letter. Any spaces will be replaced with an _. As well use of brackets of any kind (squared round or curly) are not allowed. A message box will be displayed if the string used is not a valid format.