Therion th2 Visual Editor

A VS Code extension for editing Therion cave-drawing files (.th2) graphically, with a built-in 3D viewer for compiled cave surveys (.3d, .lox).

---

Features

Visual .th2 editor

• Canvas editor — draw and edit scraps, points, lines, and areas directly on a zoomable canvas; the underlying .th2 text file stays in sync at all times.
• Drawing tools — Select (V), Point (P), Line (L), and Area (A) tools; keyboard shortcuts for every common action.
• Background sketch images — load scanned survey notes as a background layer; control per-image visibility, opacity, and position.
• Properties panel — type-specific fields for every point and line type (orientation, alignment, scale, text, altitude, gradient, …); custom key/value attribute editor for anything not covered.
• Scrap management — create, rename, and delete scraps; move objects between scraps; edit scrap projection, scale, flip, and author/copyright entries.
• Multi-select — Shift+click or rubber-band drag to select multiple objects; bulk delete in one undo step; move selection to another scrap.
• Per-vertex editing — drag Bezier control handles; insert or delete vertices; set per-vertex altitude (wall), gradient tick (contour), direction tick (section), and subtype overrides.
• Two-way sync — changes made in the text editor are immediately reflected in the canvas, and vice versa. Use Canvas / Text / Split view modes from the toolbar.
• Undo / redo — backed by VS Code's native undo stack; every edit is a WorkspaceEdit.
• Parse warnings — malformed directives are flagged with an amber ⚠ badge in the status bar.

3D cave viewer (.3d / .lox)

• Renders compiled Therion surveys from Survex .3d and Therion .lox files.
• Toggle survey legs, splays, stations, scraps, and terrain layers.
• Ortho / perspective projection; quality and downsampling controls.
• Station depth shown in the VS Code status bar.

---

Getting Started

1. Open a folder containing your Therion project in VS Code.
2. Click any .th2 file in the Explorer — the visual editor opens automatically.
3. Use the toolbar to pick a drawing tool and start editing.
4. Save with Ctrl+S / ⌘S as usual.

To open a .3d or .lox file, click it in the Explorer — the 3D viewer opens automatically.

Switching views

The toolbar offers three view modes for .th2 files:

Button	Action
Canvas	Visual editor (default)
Text	Built-in VS Code text editor
Split	Canvas and text editor side by side

---

Drawing Tools

Tool	Key	Description
Select	V	Click to select; drag to move; Shift+click or drag empty space for multi-select
Point	P	Click to place; type defaults to station (auto-incremented)
Line	L	Click vertices; double-click or Enter to finish; Escape cancels
Area	A	Click existing closed lines to define the boundary; press Enter to finish

Line drawing tips:

• Drag while placing a vertex to pull out Bezier handles.
• Approach the first vertex to snap-close the line automatically.
• Alt+click a segment to insert a vertex; select a vertex and press Delete to remove it.

---

Properties Panel

Selecting an object opens its properties on the right:

• Points — type, subtype, name (station), text (label/remark), orientation (drag the on-canvas handle), alignment, scale, value, and more.
• Lines — type, subtype, id, close/reverse toggles, outline, altitude, gradient, direction, and other type-specific options; vertex panel when a vertex is selected.
• Areas — type and referenced line IDs.
• Scraps (when nothing is selected) — name, projection, flip, scale, object count, sketches list, and author/copyright entries.

A Custom Options section at the bottom of the panel lets you add, edit, or delete arbitrary -key value pairs for any object.

An Attributes section handles -attr name value entries on points, lines, areas, and scraps.

---

Background Images

Click + Add Image in the Background Images panel to attach a scan to the current scrap. Then:

• Toggle the global Bg button or individual ●/○ buttons to show/hide images.
• Drag the opacity slider to dim the background while tracing.
• Edit the X / Y fields to reposition an image.

---

Keyboard Shortcuts

Key	Action
V	Select tool
P	Point tool
L	Line tool
A	Area tool
Delete / Backspace	Delete selected object(s)
Escape	Cancel drawing / clear selection
Ctrl+Z / ⌘Z	Undo
Ctrl+Y / ⌘Y	Redo
Alt+click	Insert vertex on a line segment

---

Supported File Formats

Extension	Handler
.th2	Visual canvas editor (read/write)
.3d	3D cave viewer (read-only)
.lox	3D cave viewer (read-only)

---

Requirements

• VS Code 1.85 or later.
• No external tooling required — the extension bundles everything it needs.

---

Known Limitations

• The canvas renders points as simple circles and lines as Bezier paths; it does not reproduce Therion's full MetaPost symbol library.
• The parser handles scrap, point, line, and area directives. Other Therion directives (centerline, map, surface, …) are preserved verbatim but not editable in the canvas.

---

License

ISC — see LICENSE.