Virtual Field Guide Editor

A virtual field guide is a set of linked pages that lives inside your VRGS project and is read beside the 3D scene — a field trip booklet whose "go and look at this" links actually take the reader there.

VRGS authors guides in a WYSIWYG editor: you build the guide's structure in a sidebar, write the pages the way you would in a word processor, and drop in the things a booklet cannot do — a link that flies the camera to an outcrop, a map of the trip, a comparison slider between photo and interpretation, a quiz.

Requires WebView2

The editor and the reader are both built on the Microsoft Edge WebView2 runtime. Without it, guide pages can still be opened as plain files but the editor will not start.

How a guide is laid out

Everything lives under the project's HTML folder, listed in the HTML branch of the Collections tree. A field guide is a direct subfolder of that HTML root — that is the whole rule. Anything loose at the root is just a page.

A guide folder holds:

File / folder	What it is
map.html	Home — the map hub the guide opens at. Both View Field Guide and the reader's Home button land here.
index.html	Contents — a live table of contents rendered from the guide's navigation, so it follows the Guide sidebar and never needs editing by hand.
dayN.html	A Day — a hub for its own stops.
dayN-stopM.html	A Stop — the page about one place.
info.html	Safety, logistics, references.
menus/main-nav.json	The guide's structure: order, labels, nesting.
images\, videos\, style\	The guide's media and stylesheet.

Each page also declares what it is in a vrgs-page-type tag. That is what gives it its symbol in the Guide sidebar, in the reader's navigation bars and on the map — nothing is inferred from the file name, so a page keeps its identity through a rename.

Creating a guide

From the Collections tree:

1. Right-click the HTML branch → New Folder, and name it after the trip.
2. Right-click the new folder → Add Field Guide Template.

The template is a worked clastic / fluvial example laid out as a navigation hub rather than a linear booklet: a map home page, a live contents page, four Days with two Stops each, and an info page. It is meant to be edited into your own trip, not read as-is — but it shows every block the editor can produce, in place.

note

Add Field Guide Template on a guide that already has pages asks before overwriting them.

Alternatively, select loose pages at the HTML root, right-click and choose Group into Field Guide — they are moved into a new guide folder together.

Guide folder commands

Right-click a guide folder in the Collections tree:

Command	Effect
View Field Guide	Opens the guide in the reader (the WEB panel), entering at its map. Also makes it the active guide, so Home and Navigate to resolve here.
Add Field Guide Template	Writes the worked example into this folder.
New Page	Adds a page to this guide.
Open in Editor	Opens the guide's contents page for editing.
Rename	Renames the guide folder.
Delete Field Guide	Moves the guide and all its pages to the project's RECYCLING folder, after closing any of its pages open in the editor.

Individual pages and asset files under HTML have their own menu: Open in Editor, Copy HREF, Open File Location, and Delete File / Delete Folder (to the recycle bin).

The editor window

Opening a page gives you three areas:

• Guide sidebar (left, top) — the guide's pages as a nested list, with a symbol per page type. This is where the guide's structure is edited.
• This page (left, bottom) — the current page's headings. Click one to jump to it.
• The page itself — the WYSIWYG canvas, with the toolbar above it.

Opening any page of a guide makes that guide active, which scopes the Guide list, the shared menus, the media browser and the reader panel to it.

Building the guide structure

Right-click a row in the Guide sidebar:

Command	Effect
Open in Editor	Edit that page.
Add Stop to Day	(Days only) Creates a Stop inside that Day — it appears under it in the sidebar, in the Day's own stop list and in the reader's navigation. It also takes the current 3D view as its viewpoint, which is what puts it on the map.
Add Page to X	Creates a page of extra detail inside whatever you clicked. Something the reader clicks through to and reads, not a place — it gets no viewpoint and never appears on the map.
New Page (top level)	A page alongside the Days rather than inside one.
Add Map Page	Adds a map page to the guide.
Duplicate	Copies the page, keeping its type.
Rename…	Sets the label shown in the guide. Clearing it falls back to the page's own first heading.
Move Up / Move Down	Reorder within the same level.
Restore Previous Version…	Recover an earlier saved version of the page.
Delete…	Remove the page from the guide.

Rows can also be dragged: drop on the top third of a row to place before it, the bottom third to place after it, and the middle to nest inside it. A page cannot be dropped into its own subtree.

Where a new page goes is decided by what you right-clicked, so there is nothing to choose and no way to get it wrong. A page added under a Day inherits that Day's layout, so the reader can navigate back to it and across to its siblings.

Writing a page

The toolbar carries font and size, text and highlight colour, bold / italic / underline, paragraph and heading levels, quote, alignment, lists, and clear formatting. Ctrl+S saves; Ctrl+Z / Ctrl+Y undo and redo; </> toggles the HTML source.

Insert

Item	What it adds
Table	A table.
Callout	A coloured note box.
Quiz	A multiple-choice question with your own right/wrong responses, marked in the reader.
Link	An ordinary hyperlink.
VRGS Link	A link that acts on the 3D scene — see below.
Object Link	A link to an object in the project; clicking it in the reader navigates to that object.
Anchor Target	A named target elsewhere on the page can link to.
Image	An image from the guide's images folder or a URL.
Image with Caption	The same, as a captioned figure.
Comparison Slider	Two images with a slider between them — the standard photo-versus-interpretation figure.
YouTube Video	An embedded video.
Local Video	A video from the guide's videos folder.
Menu Bar	One of the guide's shared navigation bars.
Map	A live map block — see below.
Table of Contents	Built from the page's own headings.
Page Navigation	Previous / next links across the guide.

VRGS links — the point of a virtual guide

Insert → VRGS Link offers three kinds:

Type	What it does
Geo Location (geo://)	Flies the 3D camera to a position. Press 📷 Get Viewpoint to fill it in from the view you are looking at right now.
VRGS Command (vrgs://)	Runs an application command.
Flight Path	Starts one of the project's flight paths in the 3D scene. The dropdown lists the paths in the project.

Give it a display label, and tick Show as a full-width bar to make it a bar across the page rather than an inline pill — which is what you want for the one viewpoint a Stop is really about.

Capture the view, don't type coordinates

Frame the shot in the 3D view, then insert the link and press Get Viewpoint. The same capture is what Add Stop uses, which is why a stop added from the sidebar already knows where it is.

The map block

A map block is a live map of the trip, and it is the same map the reader shows.

• Basemap — a street map, or an image you supply with geographic bounds.
• Spots — the guide's own Days, Stops and Viewpoints, derived from the pages themselves. A page that has a viewpoint has a place on the map; one that does not, does not appear. There is no separate list to keep in step.
• Outcrop model (DOM) outlines — the project's models, drawn live as dashed footprints. They are not stored in the page: the project is the source, so the outlines follow the models. Right-click one to navigate the 3D view to it.
• Right-click the map (while editing) to 📍 Add Stop here, or to add a 3D Viewpoint at that point.
• A legend switches the layers, and the basemap / overlay choices you leave it on are remembered while the project is open.

Images and video

Images and videos live in the guide's own images and videos folders. You can drag and drop a file straight onto the page — it is copied into the guide and referenced from there — or press Browse… in any image or video field to pick from what the guide already has.

Keep media inside the guide

A page that points at an image on your own desktop shows nothing for anyone else. Dropping the file onto the page (rather than pasting a path to it) is what puts a copy inside the guide, where backups and file sharing will carry it.

Shared menu bars

A guide's navigation bars are shared: defined once and inserted on as many pages as you like, so changing the bar changes it everywhere it appears rather than on the page you happened to be editing. Create and edit them from the menu editor, and place one with Insert → Menu Bar.

Saving

The editor pushes its content to VRGS whenever you pause typing, when the editor loses focus, and when you save — each push stamped with the page it came from. Saving is therefore a write of content already in hand: it never has to wait on the editor, which is what stops a save freezing the application.

Two consequences worth knowing:

• A previous version of each page is kept, which is what Restore Previous Version… in the Guide sidebar reads.
• If a save is refused because the editor holds a different page than the one being saved, VRGS says so and offers to reload from disk. That is the one refusal with a way out; the others are reported with the reason.

Reading a guide

View Field Guide on the guide folder opens it in the WEB panel — VRGS's reader — at the guide's map. From there:

• Navigation bars and the contents page are rebuilt live from the guide's structure, so they always match what the Guide sidebar shows.
• geo:// and flight-path links act on the 3D view, which is the whole point: the reader and the scene are side by side.
• The reader has a search box across the guide's pages.
• Navigate to on an object in the project tree switches the reader to the active guide's map with the live location marked, rather than to the web map.

Reports use the same editor

The Report editor is this editor in a second mode. A report is deliberately not a guide page — it lives in the project's Reports folder, has its own stylesheet and print rules, and opening one never re-points the Guide list or navigates the reader away from the guide you were reading. A report opened in a guide window (or the reverse) still parses and round-trips; it simply does not offer the other mode's buttons.

Tips and troubleshooting

• The guide folder has no menu commands. A field guide has to be a direct subfolder of the HTML root. A folder nested deeper, or one named images, videos, menus or style, gets the ordinary item menu instead.
• "This field guide has no map.html or index.html yet." The folder is empty — use Add Field Guide Template or New Page first.
• A new page did not appear in the reader's navigation. The reader reads the guide's structure; save the page, and check it is where you expect it in the Guide sidebar.
• A page shows a broken image. The image was referenced from outside the guide folder. Drag the file onto the page to bring a copy in.
• A stop is missing from the map. Only pages with a viewpoint have a place. Add one with Insert → VRGS Link → Get Viewpoint, or create the stop with Add Stop to Day, which captures the current view for you.
• Deleting the wrong thing. Pages, asset folders and whole guides all go to the project's RECYCLING folder rather than being destroyed.

See also

• Analysis Reports — the same editor, in report mode.
• Multiuser Virtual Field Trips — running a live trip through a guide.
• Flight Paths — the guided fly-throughs a guide page can start.
• Building and Delivering a Virtual Field Trip — how a guide fits with flight paths, media and a live session.