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:

Drawing Tools

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

Supported File Formats

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.