Trace Map: Complete Digitizing Guide

Trace Map—also shown as Vector Crack Tracer—is FracSTAT’s workspace for digitizing fracture traces over a photograph or editing an existing SVG trace map. This guide follows the controls and behavior implemented in core/tracer.py, from opening source data to saving an analysis-ready SVG.

1. Recommended End-to-End Workflow

1. Launch Trace Map from a FracSTAT Analyzer workspace.
2. Open a reference photograph with Open Image, or load existing vectors with Import SVG.
3. Improve image visibility, if needed, using Image Settings.
4. Set the working extent with Canvas Size or Crop Tool.
5. Create layers for the trace classes you need to keep separate.
6. Set the trace colour and stroke width, then digitize all fracture paths with the Pen Tool.
7. Inspect every trace at high zoom; select, erase, delete, undo, or redraw mistakes.
8. Decide whether the reference image should be embedded in the SVG.
9. Choose Save to FracSTAT when launched from FracSTAT, or Export SVG in standalone use.
10. Close Trace Map and continue the analysis with the generated SVG.

2. Open Trace Map and Source Data

Use the workspace header’s Trace Map control to launch the tracer. When FracSTAT supplies an output path, the tracer can write directly back to the application; its title includes the target SVG filename and the Save to FracSTAT action is available.

File action	Use
Open Image	Loads a raster reference image for digitizing. The image is placed on the reference-image layer behind the vectors.
Import SVG	Imports SVG paths as editable traces. When the SVG includes an embedded image, that image can also become the background.
Export SVG	Prompts for a destination and writes the current vector workspace as an SVG.
Export BG	Exports the current background as PNG. If a crop has been applied, choose a straightened crop or the tilted appearance.
Save to FracSTAT	Writes to the output path supplied by FracSTAT so the application can load the map after the tracer closes.

If an existing FracSTAT trace map is reopened, Trace Map can restore its background and editable vectors from companion files. Imported paths are normalized into the current SVG/canvas coordinate space.

3. Workspace and Toolbar

The center canvas holds the background and vector traces. The top toolbar is divided into File, Edit, Draw, Options, and View controls; the right sidebar contains layers, metrics, and image settings.

Control	What it does	When to use it
Select Tool	Selects one trace or drag-selects multiple traces.	Reviewing, moving, or deleting existing vectors.
Pen Tool	Creates a multi-node polyline, including a two-node straight trace.	All fracture traces that must be included in the exported SVG.
Line Tool	Creates a temporary two-point scale/reference line; an existing line body can be moved and its endpoints rotated.	Measurement or alignment reference only. These lines are excluded from SVG and background exports.
Eraser Tool	Removes the part of a path under the circular eraser and splits surviving portions into paths.	Local corrections without deleting a complete trace.
Hand Tool	Pans the view without modifying vectors.	Navigation while zoomed in.
Crop Tool	Displays a movable/resizable crop area with a rotation angle and Apply/Cancel controls.	Restricting the map to the study area or straightening a tilted image.
Color	Changes the active trace colour.	Before drawing a class or set that should be visually distinct.
Image Settings	Shows or hides the image-processing panel.	Improving faint or unevenly illuminated source images.
Clear All	Removes every trace on every layer after confirmation.	Restarting vector interpretation; the operation can be undone immediately.
Delete Item	Deletes the currently selected/highlighted trace or traces.	Removing complete incorrect paths.
Canvas Size	Sets the canvas width and height numerically.	Working to a known pixel extent or creating a blank vector canvas.

3.1 Drawing Options

Option	Effect
Stroke Width	Sets the width used for newly drawn traces.
Include Image in SVG	Embeds/renders the background in the exported SVG. Leave it off for a vectors-only analysis map.
Allow Trace Outside Image	Allows points outside the scene boundary. When off, new points are clamped to the canvas edge.
Include Path Nodes	Keeps clicked vertices as a multi-node polyline. With it enabled, a one-point path is discarded when finished.

4. Draw Accurate Traces

4.1 Pen Tool for Polylines

1. Select the destination layer in the layer tree.
2. Set Color and Stroke Width.
3. Activate Pen Tool or press D.
4. Click the first visible endpoint of the fracture.
5. Move along the fracture and click only where its direction changes. A preview segment follows the pointer.
6. Press Enter to finish the trace, or Esc to cancel the unfinished path.
7. Zoom in and verify that the vector follows the intended feature from endpoint to endpoint.

4.2 Line Tool for Temporary References

1. Activate Line Tool or press L.
2. Click the first endpoint and then the second endpoint; the line finishes automatically.
3. To adjust it while the Line tool is active, drag the line body to move it or drag an endpoint to rotate/resize it around the opposite endpoint.

4.3 Snapping and Intersections

While drawing, Trace Map searches visible traces near the pointer. A new point can snap to an existing path, helping shared endpoints and intersections meet cleanly. Zoom in before placing junctions so the intended target is unambiguous.

5. Select, Edit, Erase, and Undo

• Select one: choose Select Tool (S) and click a trace.
• Select several: drag a selection rectangle around the traces, or hold Ctrl while clicking to add/remove traces from the selection.
• Select a layer: press Ctrl+A to select all traces on the active layer. In a text or numeric editor, the same shortcut selects the editor text instead.
• Move selected traces: drag a selected trace with the Select tool; a multi-selection moves together.
• Delete complete traces: press Delete or Backspace, or choose Delete Item.
• Erase part of a trace: activate Eraser (E), then click or drag over the unwanted segment. Remaining portions become separate paths where necessary.
• Undo/redo: use Ctrl+Z and Ctrl+Y, or the toolbar buttons.

The layer tree mirrors canvas traces. Selecting a trace child in the tree highlights it on the canvas. Selecting a layer heading makes that layer active for subsequent drawing.

6. Organize Layers and Monitor Metrics

The workspace begins with a protected reference-image layer and a drawing layer. Use Add Layer to create additional vector layers and Delete to remove an unwanted vector layer. The reference-image layer cannot be treated as a normal trace layer.

Layer-tree action	Result
Click a layer name	Makes it the active destination for new traces.
Check/uncheck a layer	Shows or hides that layer’s vectors; hidden traces are not snapping targets.
Click a trace child	Highlights the corresponding path on the canvas.
Add Layer	Creates another named vector layer.
Delete	Deletes the selected vector layer and its traces after the applicable checks.

The Trace Metrics card reports the active layer, total paths, and total nodes. Use it as a quick check that traces are being created on the intended layer and that a clear/erase operation did not remove more data than expected.

7. Prepare the Background Image

Image Settings modifies the displayed reference while preserving an original copy for comparison and reset. Adjustments can make subtle fractures easier to see but should not replace geological judgment.

Adjustment	Purpose
Brightness / Contrast	Corrects an image that is too dark, bright, flat, or harsh.
Gamma	Changes midtone visibility without applying a simple linear brightness shift.
Sharpness	Emphasizes local edges.
Saturation	Reduces or increases colour intensity.
Grayscale	Removes colour to emphasize tonal structure.
Auto Contrast	Expands image contrast automatically.
Invert	Reverses tones.
Hist. Equalize / CLAHE	Enhances global or locally varying contrast.
Rotation	Rotates the displayed source image.
Threshold controls	Convert tonal ranges to a binary-style view; Adaptive and Otsu provide automatic thresholding approaches.
Show Original / Show Processed	Switches between the unmodified reference and processed result.
Reset to Defaults	Returns processing controls to their shipped values.

8. Crop, Rotate, and Set the Canvas

8.1 Crop Tool

1. Activate Crop Tool or press C.
2. Drag inside the crop area to move it.
3. Drag an edge/corner handle to resize it.
4. Enter a rotation angle in the floating crop card if straightening is required.
5. Select Apply Crop to commit, or use the crop card’s Cancel button to leave crop mode without applying.

Applying a crop remaps the workspace to the cropped rectangle, updates the background, shifts vectors into the new origin, fits the view, and clears undo/redo history. Confirm the crop carefully before applying it.

8.2 Canvas Size

Choose Canvas Size, enter Width and Height, and accept the dialog. The scene boundary is updated and the workspace is fitted to the view. Unless Allow Trace Outside Image is enabled, drawing points are constrained to this boundary.

9. Save, Export, and Companion Files

Output	Contents and behavior
Save to FracSTAT	Writes the SVG to FracSTAT’s supplied target path. Close the tracer afterward to return; FracSTAT loads the map automatically.
Export SVG	Creates a user-selected SVG file. The background is included only when Include Image in SVG is checked.
Export BG	Creates a PNG of the current background. For a rotated crop, choose straightened or as displayed.
<svg_base>_bg.png	Sidecar background copy associated with a FracSTAT output path.
<svg_base>_traces.json	Editable trace/layer sidecar used to restore the tracer workspace.

Temporary scale/reference lines are not rendered into the SVG output. If the tracer is closed with unsaved changes, it prompts to update the FracSTAT target or export the standalone work before closing.

10. Keyboard and Mouse Key Map

10.1 Keyboard Shortcuts

Key	Action	Context
S	Select Tool	Select, box-select, and move traces.
D	Pen / Draw Tool	Create exported fracture paths.
L	Line Tool	Create or manipulate temporary scale/reference lines; they are not exported.
E	Eraser Tool	Erase path segments.
P	Hand / Pan Tool	Pan the canvas.
C	Crop Tool	Open crop controls.
T	Trace colour	Open the colour chooser.
I	Image Settings	Show/hide the image-settings panel.
X	Delete selected	Removes highlighted complete paths.
+ / =	Zoom in	Zooms around the viewport center.
- / _	Zoom out	Zooms around the viewport center.
0	Fit workspace	Fits the complete scene in the view.
Arrow keys	Nudge view	Scrolls the viewport in small steps.
Space (hold)	Temporary pan	Returns to the previous tool when released.
Enter / Return	Finish current trace	Commits the active Pen path.
Esc	Cancel current trace	Discards an unfinished Pen or Line path.
Delete / Backspace	Delete selected trace(s)	Removes highlighted complete paths.
Ctrl+A	Select all traces	Selects every trace on the active layer.
Ctrl+Z	Undo	Reverses the latest supported vector operation.
Ctrl+Y	Redo	Reapplies an undone operation.

Single-key tool shortcuts are ignored while typing in a text field or numeric spin box, preventing accidental tool changes.

10.2 Mouse Map

Input	Action
Mouse wheel	Zooms in/out around the pointer position.
Left click with Pen	Adds a fracture-path node.
Left click with Line	Places a temporary reference-line endpoint; drag an existing line body to move it or an endpoint to rotate it.
Left click with Select	Selects a trace; click empty space to clear selection.
Ctrl + left click with Select	Adds/removes a trace from a multi-selection.
Left drag on empty canvas with Select	Draws a selection rectangle.
Left drag on selected trace(s)	Moves the selected vector paths.
Left click/drag with Eraser	Erases portions of traces under the eraser.
Left drag with Hand or held Space	Pans the view.
Crop-area drag	Moves the crop; dragging handles resizes it.

11. Quality-Control Checklist

• Trace the intended geological feature—not shadows, vegetation, labels, ruler edges, or enhancement artifacts.
• Keep endpoint criteria consistent across the entire image.
• Use enough Pen nodes to follow curvature, but avoid dense unnecessary nodes that add noise.
• Inspect intersections at high zoom and ensure connected traces actually meet.
• Check that traces do not unintentionally continue outside the canvas.
• Confirm the active layer before each interpretation class.
• Compare processed and original image views before accepting subtle traces.
• Review Trace Metrics for unexpected path/node count changes.
• Export a test SVG without the background and load it in the target Analyzer before extensive downstream work.
• Preserve the original image and record crop, processing, interpretation, and scale decisions with the project.

12. Troubleshooting

Problem	Check or solution
A new trace is not visible	Confirm the active layer is visible, the colour contrasts with the image, and stroke width is large enough at the current zoom.
The path stops at the canvas edge	Enable Allow Trace Outside Image only when tracing beyond the current boundary is intentional, or enlarge Canvas Size.
Shortcuts type into a field instead	Click the canvas first. Tool keys intentionally do not override active text or numeric editors.
Fractures do not connect downstream	Zoom into junctions and redraw/snap endpoints so the vector geometry truly meets.
The exported SVG contains the photograph	Turn off Include Image in SVG and export/save again.
The background is missing after reopening	Keep the generated _bg.png beside the corresponding SVG and avoid renaming only one member of the set.
Editable layers are missing after reopening	Keep the generated _traces.json companion file beside its SVG.
Undo no longer reaches work before a crop	Applying a crop clears undo/redo history by design. Save/export before major crop changes.
Image enhancement creates false edges	Switch to Show Original, reduce processing, and map only features supported by the source image.
Closing warns about unsaved work	Choose the save/update option. In FracSTAT mode this updates the supplied SVG; in standalone mode use Export SVG.