Basic │ FullView │ Shortcuts │ Rapid │ Scaling │ Grid│ ptLines │ Shapes │ Other
traceFigure can be used to manually digitize points on an image. For example, if you have an image of a line graph, you can digitize selected points. By digitize, we mean create a set of x,y coordinate pairs. These pairs can be saved as a CSV file, for use in a spreadsheet, etc.

 Displaying an image . Although you can don't need to have an image to digitize, the ability to trace (and otherwise locate) points on an image is what makes traceFigure useful!
There are two ways of drawing an image onto the work area.

1. Use the Upload at the top of the screen. This allows you to upload an image file from your computer -- which will then be drawn onto the working area.
2. Use the Load image button in the Other specs menu. This allows you to use an image currently on the server. This image file must be in (or under) the directory that contains traceFigure. So this is only useful if you have some control of the contents of your server (or are running traceFigure in standalone mode -- in which case files on your hard drive can be loaded).

 The basics. Digitizing points is done by moving the cursor (displayed as a large +) over a spot on the image, and then recording the location.

• First, click on the Add points button (its background will change from yellow to green)
• The cursor becomes a large +. Move the cursor onto the work area (where the image is drawn), and place it over spot whose position you want to digitize
  Since the mouse cursor can be imprecise, to see actual spot to be digitized -- click a mouse button. A ✠ crosshair is drawn.
  For finer movements, use the arrow keys (the ←, ↑ →, and ↓ keys) -- the ✠ crosshair will be displayed and will move as you hit arrow keys.
  Note: the ArrowRes input box (in the MoveOptions menu) controls how many pixels are moved with each arrow key click. Pixels are defined using the screen pixels: so a 5 pixel move is always the same movement on the screen. For larger images, a n pixel move is smaller move in terms of percent of height or width location on image.
• When you are over a desired spot, hit the Space bar to record the location.
• Repeat for as many points as you wish to record
• You can specify several different ptLines: just hit the Enter key (while the mouse cursor is over the image), and a new ptLine is started. Or, click on the New button in the ptLines container.
  Note: ptLine is shorthand for any collection of points -- they might be arranged to form a line, but they don't have to be (usually, they aren't)!
• The Lx_   input boxes can use used to set the name of a line (use just one word). The text above this lists how many points are in the line
• To display list of point locations in a text box (in a CSV format suitable for importing into some othe program), use the Show point values under ⤷ (the manipulate ptLine menu)

 Full view. You can switch between a full view, or a regular view.

• Full view: the working area (where the image is displayed) will occupy almost the entire window. The top line will still be displayed, but the list of options (the column on the right), the ptLine summaries (the column on the right), and status information (2nd and 3rd line at the top) are not shown
• Regular view: the working area is in the middle of the window, with other items (such as the options menu) shown

To enter (and exit) full view, click the button on the top line.
While in full view mode, you can display options menu by ..

clicking on the button.
After making your changes (i.e.; clicking on Add points, or changing tt>Move options), you can hide the menu by

clicking on the again.

Note: is only displayed in full view mode).

Hint: see the shortcuts for a mouse movement sequence that will bring up the options menu!

 Shortcuts Keyboard & mouse shortcuts: These shortcuts work when Add points is active.

• Place the mouse cursor over a recorded point to view the points ptLine [line name @ x location ,y location] information
• Hitting an arrow key will draw the ✠ crosshair at the current spot (if isn't already being displayed)
  Hitting a mouse key while on top of the ✠ crosshair will hide the ✠
• Arrow & keypad keys:
  The Home, PgUp, PgDn, and End keys will move in diagonal directions
  The 5 key is the same as hitting a space key
  The + (-) key will increase (decrease) the ArrowRes
• The Alt-L key will open the ptLine manipulation menu
• Mouse actions:
  Double clicking the mouse button simulates hitting a Space key
  A long click (clicking, and holding the mouse button down for more than a second), simulates hitting Alt-L (toggle view of the ptLine manipulation menu)
  Clicking the right mouse button (rmb) simulates hitting the Tab key
  Double clicking the right mouse button (rmb) simulates hitting the Esc key
  Holding the right mouse button down and moving the mouse (more than 10 pixels) will scroll the image (if there are no scroll bars, nothing will happen)
  Rotating the mouse wheel will zoom in, and zoom out, on the image
• While in full view mode
  Moving the mouse while the holding down the left mouse button has several effects:
  Move left: toggle view of the options menu
  Move right: toggle view of the ptLine summaries

 Rapid Entry. For quick entry of many points, you can select (under the MoveOptions menu) ...

• Continuous: Points are automatically recorded as you move the mouse (or move the ✠ using arrow keys).
• Segment: Points are recorded in linear segments
• Useage:
  Click on the desired checkbox ( Continuous or Segment), and click on the Add points button Move the mouse (or use arrows to move the ✠ ) to the first point to digitize
  Hit the Tab, key or the A key, or click the rmb (right mouse button). This enables continuous (or segment) entry, and records the current point.
  For continuous entry:, just move the mouse crosshair (or ✠). A new point will be entered when the crosshair (or ✠) is 10 pixels away from the prior point (starting with the spot where you hit the Tab key) Note this is pixels on the screen (not pixels of the original image) So 10 pixels in an zoomed in image yields a tighter set of points than 10 pixels in a zoomed out image.
  For segment entry: move the move the mouse crosshair (or ✠) to the end of the ptLine segement, and hit Space (or double click the mouse). As with continuous, points will be recorded every 10 screen pixels along this segment. Move the mouse crosshair (or ✠) again, hit Space (or rmb), and a new segment is recorded that starts from the end of the prior segment.
  To stop continuous (or segment) entry, hit Tab ( or A or rmb) again).
  Note: use the Resolution text box to change the 10 pixel resolution (for either continuous or segment entry)

 Scaling. Points are recorded using the location on the image: in percent of width and height of image. This location is zoom and image resolution independent. Thus, a location of 50.00 is in the middle of the image regardless of how much it is zoomed in (or out), and regardless of how much of the image is outsize of the viewport (i.e.; if you must use the scrollbars).

You might find it useful to scale these into image location values into real-world values; say that correspond to values in a line graph.

This is done using the Scale Specs menu

• Scaling works by comparing the location of a point to the location of an origin, and then using locations of known X and Y values. In all cases, the location is relative to the height and width of the image (i.e.; 60% to the left and 23.31% from the top).
• The set origin button is used to enter the origin. After clicking on it, move the mouse crosshair (or ✠) over the origin, then hit Space. And then enter the X and Y values corresponding to this point (often these will be 0 and 0, but you can choose any values you wish)
• The specify X (and specify Y) button is used to select a tic mark on the X (or Y) axis. After selecting the point, enter the X (or Y) value corresponding to this tic mark
  You don't actually have to find a tic mark. Any spot on the X (or Y) axis can be used -- so long as you know its value.
• For your convenience, you can chose one of several sets of scaling parameters (both image locations and real values) -- with the origin in the center of the image and xtic and ytic markers in the lower right and upper left corners (respectively). Just click on the defaults button (keep clicking to cycle through the set).

 Grid. Display a reference grid on top of the image.
Note: before displaying a grid, you must specify the Scale Specs

Clicking the Grid button will bring up a box showing grid specification options.
After setting these options, click the Submit button!

  Grid options:

• Enable grid checkbox: Click this to enable the grid. Unclick, and the grid is removed
• Snap to grid: All entered points will be snapped to the grid. That means that instead of recording the point where the cursor (or ✠) is, the closest grid vertex is used. This is ignored if the enable grid checkbox is not checked.
  The gridlines snapped to do not have to be displayed! Thus, the resolution of snapping can be much greater than the actual gridlines displayed.
• Grid resolution The resolution of the grid, in real values (not in image location). You can specify different scaling for x (vertical grid ines) and y (horizontal grid lines). The value must be >0
• Grid display frequency What fraction of the grid lines to display. More precisely, display one of every N grid lines (so a 5 means display every fifth grid line.
  You can specify seperate display frequencies for X and Y grid lines.
  A value of 0 means do not display any gridlines (except for the grid line(s) through the origin)
  Hint: to not display any grid lines (including ones through the origin), set opacity to 0.0.
• Grid display: line style Choose one of the line styles.
• Grid display: line thickness The thickness (width for vertical lines, height for horizontal lines) of the gridlines, in pixels
• Grid display: line color Choose a color to use for the grid lines.
• Grid display: line opacity Must be a number between 0.0 and 1.0 (inclusive).
  0.0 means gridlines are fully transparent (not visible). 1.0 means non-transparent (will coverup anything below)

Note: place the mouse cursor over a grid line to view its X (or Y) location (in scaled values, not in pixels)

 Working with ptLines. You can delete, modify, or view the digitized results stored in a ptLine... by clicking on the ⤷ icon . A box will open showing a menu of actions.

Delete ptLine	Upload ptLineMenu	Copy ptLine	Add to	Remove points	Tweak points
Display points (all or none)	Show point values	Fill-in/remove duplicates	Merge ptLines	Add connecting lines	Vertices

•    Delete ptLine. Click on this to completely remove all points (and their markers) from the currently selected ptLine. If this is the last line, clicking again will remove the line completely.
•    Upload ptLine menu. Use this to manually specify a number of points to add to the current line. This is done by entering x,y pairs in a text box; where x and y are image locations (% of width and height). x and y values should be seperate by a comma, with just one pair per row.
  Or, you can load a list of points from a file on your local hard drive. In particular, a list of points created by Show point values (discussed below).
  Special feature: You can also use scaling specs to specify the scaling specifications (the origin, X_tix, and Y_tic) locations. These scaling specs can be added by Show point values.
  Example of scaling specs:

  
  x0Pixel=0.50000           X location, relative to the   width of the image, of the scaling origin (must be between 0.0 and 1.0)
  y0Pixel=0.50000           Y location, relative to the   height of the image, of the scaling origin (must be between 0.0 and 1.0)
  xticPixel=0.97000         X location, relative to the   width of the image, of the Xtic (must be between 0.0 and 1.0)
  yticPixel=0.03000         Y location, relative to the width of the image, of the Ytic (must be between 0.0 and 1.0)
  x0Value=0                   Scaled X value of the origin 
  y0Value=0                   Scaled Y value of the origin 
  xticValue=100               Scaled X value (at the Xtic mark)
  yticValue=100               Scaled Y value (at the Ytic mark)
  
  L1_N,L1_Xpx,L1_Ypx,L1_Xval,L1_Yval
  1,8.869,14.55,-87.51,75.42
  2,9.950,14.90,-85.21,74.68
  3,11.03,15.25,-82.91,73.94
  4,12.11,15.60,-80.61,73.20
  5,13.19,15.95,-78.31,72.46
  6,14.27,16.29,-76.01,71.72
  7,15.35,16.64,-73.71,70.98
  8,16.44,16.99,-71.41,70.24
  9,17.52,17.34,-69.11,69.50
  10,18.60,17.68,-66.81,68.76
  11,19.68,18.03,-64.52,68.02
  12,20.76,18.38,-62.22,67.28
  

•    Copy ptLine. Copy points in a current ptLine to a new ptLine.
  Every point is copied as is. That means the new ptLine's point will be exactly on top of the current ptLine's points!
  Although its easy to move all points of this new (or current) ptLine all at once (using Tweak), you can avoid this trouble by automatically adding an X and a Y offset (in image location) to each of the new ptLine's points.
•    Add to .... Copy lines from current ptLine to an existing ptLine.
  This is a copy -- so the existing and newly created point have the same location.
  Specify which ptLine to append these points to (using the ptLine's number).
  Specify the range of points to copy from the current ptLine (by default, all points will be copied).
  If you check the add offsets? checkbox, the X and Y offsets (specified in Copy ptline) are added to each point.
  
  You might want to not display markers when you do the copy (by unchecking the MarkPoints checkbox before the copy).
  Reminder: to display (or hide) all points on a ptLine, use Display all
•    Remove points. Remove points from the selected ptLine.
  Points on the current ptLine will be displayed with an orange background. Click on a point (or move the mouse over a point and then hit Space) to select. When selected, the background will become gray.
  After you have selected all the points you wish to delete, hit the Del (or Tab ) key.
  Shortcut: To select a number of points at once.
  1. Click on the first point (or move the mouse over it and then hit the Space key)
  2. Hit the Ins key
  3. Click on the last point
  4. Hit the Ins key again
  All points between these two are selected. Actually, the selection is toggled: selected points are unselected.
•    ⥮ Tweak points. Modify the X & Y locations (the image location values) of each point in a ptLine.
  Using the PgUp; and PgDn; keys, select a point to modify (each point will have a dotted box around it).
  Then increase (or decrease) Y values with the ↑ and ↓ keys; and increase (or decrease) X with the → and ← keys.
  Shortcut: click the 5 key to select a number of points -- the arrow keys will modify all of them at once (click the 5 key again to cancel this multi-point selection).
  Shortcut: hit * to select (or deselect) all points; which can then be moved en masse.
  Controlling movement speed:

  • The + and - keys can use used to control how quickly to increase (or decrease) the X and Y value(s).
  • The Home and End keys control how quickly to traverse the points in the ptLine
  When you are done tweaking points, hit Esc
  Note: you can also use the mouse to move one point at a time:
  Move the mouse over a point
  Click on it
  The mouse cursor changes to an arrowy crosshair.
  Move this to a new point
  Click again -- the point will be moved!
•    Display points.
  These buttons provide a convenient way of hiding temporarily hiding, or showing, ptLines.
  Click All to display (using the • marker) all points in the currently selected line.
  If points are currently being displayed, clicking this will re-display all the points using markers with the currently selected color/size/character.
  Or, click on none to undisplay all markers in this line.
•    Show point values. Click on this to view, in a popup box, the values for each point -- using one row per point, and a CSV format within each row.
  By default, just the pixel values are displayed. However, you can also display:

  the point number (1,2,...)

  The scaled values (assuming you specified scaling paramters using ScaleSpecs).
  You can select the precision (the number of places after the decimal point) to display by using the precision input box

  You can include extra rows of explanatory information, including:
  The variable names
  The scaling specifications (which, as described bove, can be used Upload ptLine).
  You can sort the output on a several fields.
  You can select the displayed values, and cut and paste then to a text editor (or to a spreadsheet). In particular, save it to a file that you can later retrieve using Upload ptLine!
  As of this release, you have to cut and paste this output -- there is no way to save it directly to a file (maybe in a later release ...).
•    Fill in/ remove duplicates You can:
  • fill in points between the selected points.
    
  • Or, you can remove duplicates -- points that are close to an earlier point.

  Fill in options

  % to retain : % of points to retain. More precisely, this is the number of pixels (on a line connecting a pair of existing points) where a new point will be created (saved for output, and optionally displayed using the chosen marker).
  Alternative: to choose a fixed number to retain, enter #nretain (precede the value with a # character). For example, #100 will retain 100 points.
  All Retain all the points, but only display the % to retain. Note: this can lead to a lot (i.e.; thousands) of points being added (even if only a fraction are displayed)
  Original: Retain the original points. If not checked, original points will not be retained (though the fill procedure might place a point at many of the original point locations)
  HiLite: Highlight (using a background) the original points. This highlighting goes away when you hit the Esc key.

  Remove duplicates options Resolution: The resolution (must be a number greater than 1.0). Higher values means less duplication (hence more points retained).

  The X & Y values of each point is multipled by this resolution weight, and rounded to the nearest integer
  This weighted, rounded pair is compared to earlier points in the line. If there is a match, the point is not retained>
  For example: if a weight 100 is used, and the ptLine is horizontal: then only one point for each percent of image width is retained.
•    Merge ptLines You can merge the values of several ptLines into a multi column matrix -- each row is a pixel X value, while each column is the Y (pixel or value) value of a ptLine (at a point with that X value)
  Details...
  • Merging will be by X (location in image). Each row of the output will be for a value of X
  • The X value will be rounded using the Weight parameter. Larger weights yield more accurate written output, but will also yield fewer matches. Examples:
    Weight=100: round X (and Y) to be integers betweeen 0 and 100 -- hence, there will at most 100 rows.
    Weight=1000: round X (and Y) to be between 0 and 1000 -- so at most 1000 rows.
  • If a ptLine has more than one pair with the same rounded X value, the earlier entry is used.
  • Use the precision box (in the Show point values menu above) to set precision of the X and Y scaled value display (eg; 0 will round to closest integer)
  • Column order:
    1. rounded X location
    2. rounded Y location -- line 1
    3. ..
    4. rounded Y location -- line N
    5. X scaled value
    6. Y scaled value (line 1)
    7. ...
    8. Y scaled value (line N)
•    Add connecting lines You can draw connecting reference lines between all points on a ptLine. These will not be drawn as lines, and not as a bunch of points. These lines are visual aids, they are not recorded (so they are not written when you chose Show point values).
  You can set the color, opacity, and thickness of these lines -- just hit the … for a menu of reference line options.
•    Vertices Use Vertices to simplify the current figure -- by removing all points except those that are on vertices. These are the points that, when connected by reference lines, would overlap all the points in the line.
  The algorithim to do this is inexact, so extra points are often added -- points that really are on a line drawn between surrounding vertices. You can limit this by setting the permitted deviation input box. This should be a value greater than 0 -- larger values means that a point can be further from the line connecting the surrounding vertices.
  Note that too large a value and you can remove points that really are vertices.

 Shapes: As a convenience, you can use the Shapes menu to enter the following shapes (as ptLines): lines (any angle, or vertical or horizontal), rectangles, circles, and polygons. Points along the edge of these shapes are recorded and displayed (the Resolution option under MoveOptions controls how dense these points will be).

To enter a shape, first select the desired shape, and then enter vertices (i.e.; by moving the cursor, and then hitting space)

• ⇀ Lines: enter the beginning and ending vertices of a ptLine (move the cursor, hit space). If you select either the vertical or horizontal checkbox, then the ptLine will be vertical or horizontal (regardless of where you place the 2nd vertex)
• ◻ Rectangle: enter the vertices of the first side (move the cursor, hit space). Then, enter a vertice the proper distance on either side of the line. A rectangle will be displayed.
• ○ Circle: enter the origin, then a point on the diameter.
• ☆ Polygon: enter the first vertex, then the second, etc. After you have entered the last vertex, hit the X or Tab key (or the rnb), and the polygon will be completed

 Miscellaneous specs:

• Marking selected points -- a • is placed on the screen for each recorded point.
  Click, the MarkPoints checkbox
  You can then select the color, the size, and the character attributes used for the marker. Typically, a • marker is used.
  If you change the color (or size or character), prior markers are not effected. However, if you display the line again, all points will be shown using the currently selected marker attributes.
  Hint: change the color right after you start a new ptLine!
• Tracking movement. You can view the current location of the mouse crosshair (or ✠)
  Click the Track checkbox.
  A box will open at the top of the screen showing the location both in scaled measures, and by image location (@px).
  The scaled location will not be displayed if you haven't specified the ScaleSpecs parameters.
• Jump to a specified location
  Open the JumpTo menu
  Enter X and Y coordinates
  Click on the pxJump button to jump to this image location (note that the upper left corner of the image is at 0,0)
  or, click on the valJump button to jump to this image location -- you must first set the ScaleSpecs options!
• Removing the last point in the current ptLine (you can do this iteratively): with Add points enabled, move the mouse anywhere over the image, and hit the Del key
• To support use of the Tab and arrow keys to select options and move around the image -- they can not be used to switch input fields. If this is a hassle, you can disable the Tab key (and use A to enable continuous and segment entry) by clicking on the NoTab checkbox in the Other specs menu
• Displaying image from the server. To retrieve an image from the server, and draw it onto the working area (rather than using an image you upload), look in the Other specs. menu:
  Enter a path/filename (which must relative to the location of traceFigure on the server),
  hit Load image
  Hint: the dir will display a list of files in the server's current directory (it will be displayed in a new window)
  Note: if you are running traceFigure in standalone mode (by reading it directly from your hard drive), Load image can be used to retrieve any file on your local computer. In fact, the Upload button is disabled -- you must use Load image to change the image.

  Syntax for specifying files: file:///x:/dir1/dir2/afile.ext.
  for example: file:///d:/photos/house/basement1.jpg

  The dir button will display files in the directory that traceFigure was loaded from.

  Technical note: by default, when traceFigure loads a sample line graph is displayed (figure4.gif). You can change this default image by editing the traceFigure source code.

  How are images displayed? When an image is chosen via Load image or via Upload, it will be written to the working area. If the image is not too big, the image is written as is. However, if it is too big, it will be resized to fit into the working area.

  You can resize the working area by resizing the browser window -- the larger the browser window, the larger the working area.
  However, traceFigure isn't quite smart enough to detect resizing -- and point placement can get messed up
  Thus, if you resize the browser window, it is recommended that you reload traceFigure (maybe we will enable resize detection in a future release)!
  The size button will reset the image size to be either the images's actual size. Or, if the size it too big, a size that will fit into the working area.

  You can resize the image to any dimension by inserting your own values in the height and width text boxes.

  The image will automatically be scanned after you enter each value (and then hit the Enter key).

  Careful...: for better or worse, you can size the image to be greater than the working area -- or even greater than the browser window!