Skip to main content
Version: 3.3

Interpretation Version Control

Geology is interpretation, and interpretation is rarely unique — the same fault trace, horizon, or fracture set can often be picked in more than one defensible way. Interpretation Version Control (VC) lets you keep those alternatives in one project instead of scattering them across saved copies: you version an interpretation, fork it into competing variants, and use scenarios to choose which variant is "in use" at any moment. Every variant is a real, independent object with its own geometry, so editing one never disturbs another.

Once your interpretations are versioned, you can share them with your team through the cloud sync service. The version-controlled set — the variants, the scenarios, and each variant's geometry — is pushed to a central server (the Athos server, backed by a PostgreSQL database) and pulled back down by everyone who has access to the project, so a whole team can build up a shared library of interpretations without emailing project files around.

note

Version Control operates on interpretation objects in the Interpretation Tree. Today the versionable type is the polyline interpretation (traces, horizons, fault sticks digitised as polylines); more object types will be added over time. Everything below is reached by right-clicking a polyline interpretation in the Interpretation Tree.

Why version an interpretation?​

  • Keep alternatives, not copies. Two admissible picks of the same fault can live in the same project as sibling variants rather than as project_v1.vgp and project_v2.vgp.
  • Never lose the original by editing. A fork has its own geometry. Trying a bolder interpretation is a fork, not an edit, so the conservative one is always still there.
  • Present one story at a time. A scenario pins one variant per feature, so you can flip the whole model between "optimistic" and "pessimistic" interpretations without deleting anything.
  • Collaborate. The versioned set syncs to a shared cloud project, so colleagues see each other's variants and can add their own.

Key concepts​

  • Entity — the geological feature being interpreted (a particular fault, a particular horizon). An entity is an identity that several interpretations can attach to. You create one implicitly by versioning an interpretation.
  • Variant — one admissible interpretation of an entity. Variants of the same entity are siblings; they never merge — the whole point is that two interpretations coexist. Each variant is one or more real project objects with their own geometry.
  • Scenario — a named selection that pins one variant per entity. Applying a scenario is a view: it changes which variants are visible, it does not change or delete anything. A project can have several scenarios (e.g. "Base case", "High side"). VRGS auto-creates a default "Base case" scenario the first time you choose an interpretation to use.
  • Version badge — versioned items in the Interpretation Tree show a badge such as [v2 of 3], telling you which variant this is and how many there are.
  • Branch (optional) — a publication scope. New interpretations added on a branch stay scoped to that branch until it is merged; branches are useful for keeping draft work out of the shared model until it is ready. Branches no longer isolate geometry — see Branches.
  • Cloud project — the server-side home for a project's versioned interpretations. It has members with roles (owner / editor / viewer). Your desktop project is bound to one cloud project the first time you sync.

How interpretations are stored​

Version Control keeps geometry and version metadata in two places, both of which travel with your project:

WhatWhere it lives
Variant geometry (the actual vertices)In the normal project database — variants are ordinary project objects, saved by the usual save path.
Version metadata (entities, variants, scenarios, pins)In a sidecar database next to the project: <project> Data\DATABASES\InterpretationVC.db, alongside the main SQLDBv4.db.

Both are included in project backups and are copied by Save As. The sidecar is metadata-only and references project objects by a stable global identifier, which is also what makes cloud sync possible.

tip

Save the project at least once before using cloud sync. Object identities and the sidecar's sync state are written at save time; syncing unsaved work has nothing stable to push.

Versioning interpretations (local)​

All of these commands are on the Version Control submenu of a polyline interpretation's right-click menu in the Interpretation Tree.

1. Version this Interpretation​

Turns an ordinary interpretation into version 1 of a versioned feature (creates its entity and first variant).

  1. Right-click the interpretation → Version Control → Version this Interpretation.
  2. The tree item gains a version badge.
caution

Versioning does not snapshot the geometry. Editing the interpretation from now on changes this same version — there is no earlier state to roll back to. To try a different interpretation while keeping this one, fork first (below), then edit the fork.

2. Fork Variant​

Creates an alternative interpretation of an already-versioned feature.

  1. Right-click a versioned interpretation → Version Control → Fork Variant.
  2. A new object — named Variant 2, Variant 3, … — appears in the tree and the 3D scene. It is an exact copy of the source with its own geometry: editing the fork will not move the original.
  3. Re-pick / edit the fork to make it the alternative interpretation you want.

You must version an interpretation before you can fork it; forking an unversioned object prompts you to version it first.

3. Use This Interpretation / Show All Interpretations​

These control which variant of a feature is in use via a scenario.

  • Use This Interpretation — pins the selected variant in the active scenario and hides its siblings. The first time you use it, VRGS creates a default "Base case" scenario automatically and activates it. Alternatives are hidden, not deleted.
  • Show All Interpretations — clears the active scenario so every variant is shown side by side (the "compare" view). This is a view change only — your scenario and its pins are left untouched.
note

The active scenario is a session setting (it resets when you reopen the project, defaulting to "show all"), but the scenarios and their pins are saved. So your pinned choices persist; which one is currently applied is a per-session view.

Reading the tree​

  • A badge like [v2 of 3] means "variant 2 of 3 for this feature".
  • Under Show All Interpretations, sibling variants that share a location sit on top of one another — hide some, or apply a scenario, to see one clearly.
  • If a forked variant seems to be "missing", it is usually coincident with the interpretation it was forked from (an exact copy until you edit it).

Branches (optional)​

Branches let you scope new interpretations so they stay out of the shared model until you are ready. You manage them from the branch graph in the interpretation panel:

  • Create Branch From… — start a new branch from an existing one.
  • Merge — publish a branch's additions into the target branch. Because there is only ever one live geometry per object, branches cannot hold conflicting shapes — merging never asks you to resolve a geometry conflict.
  • Delete — deleting a branch keeps the interpretations: anything the branch had added becomes visible everywhere, and any deletions it made are undone. (Deleting a branch publishes its work; it does not discard it.)
note

Branches used to isolate geometry so you could "experiment and throw it away". That is no longer how they work — an edit on a branch is an edit everywhere. Re-interpreting differently is now a fork, not a branch edit. Branches are purely a publication scope: unpublished additions plus soft deletions, plus merge. You can combine the two — fork a variant on a branch to keep the alternative unpublished until the branch is merged.

Sharing with your team (cloud sync)​

Cloud sync pushes your versioned interpretations to a shared server and pulls back everyone else's. It is per project: each desktop project maps to one cloud project whose members you manage on the server.

What syncs​

  • Metadata — entities, variants, scenarios, and pins.
  • Geometry — each variant's vertices, sent as a per-variant package so colleagues who don't have that variant can import it.
  • Deletions — expressed as tombstones so a delete propagates without wiping work that someone else added in the meantime.

The model is merge-free by design: variants never merge — concurrent forks by two people are simply two admissible siblings, which is the correct converged result. The only fields that can truly conflict are scalar choices (a feature's default variant, a scenario's pins, a variant's status); those resolve last-writer-wins. Geometry is never overwritten on sync — "interpret it differently" is a fork, not a geometry update, so your local edits are safe.

First-time setup​

  1. Right-click a versioned interpretation → Version Control → Sync with Cloud….

  2. Fill in the Sync Interpretations with Cloud dialog:

    FieldWhat to enter
    Server URLThe base URL of your organisation's Athos / VC sync service.
    Auth0 domainYour sign-in tenant (e.g. your-tenant.eu.auth0.com).
    Auth0 client idThe VRGS desktop application's client id.
    Auth0 audienceThe API audience the VC service expects.
    Token (dev only)A pasted bearer token — a fallback for development servers only; leave blank when the Auth0 fields are set.

    These are remembered for next time. Ask your administrator for the correct values.

Signing in​

When the three Auth0 fields are set, VRGS signs you in with a device-code flow — no password is typed into VRGS:

  1. The Sign in to VRGS Cloud dialog shows a short code and opens your web browser.
  2. Approve the sign-in in the browser (confirm the code), then return to VRGS.
  3. You stay signed in afterwards — a refresh token is stored encrypted on your machine (Windows DPAPI), and VRGS refreshes access silently on later syncs.

Running a sync​

Once signed in, the sync runs in the background — a small Interpretation VC window appears and you can keep working while it talks to the server. On the first sync the project is registered on the server (you become its owner) and given a cloud identity. When it finishes, VRGS refreshes the tree and 3D view and shows a summary of what was pushed and pulled; any variants your teammates published that you didn't have are imported into your project (and persist on your next save).

Roles & permissions​

Access is granted per project. Members are added on the server, and each holds one role:

CapabilityViewerEditorOwner
See the project exists✓✓✓
Pull the snapshot & geometry✓✓✓
Push entities / variants / scenarios—✓✓
Publish variant geometry—✓✓
Apply deletions (tombstones)—✓✓
Add / remove members, set roles——✓
  • The person who registers a project (first sync) becomes its owner.
  • Non-members can't see the project at all — the server treats a non-member's request as "not found", so project existence is itself private.
  • owner outranks editor, which outranks viewer.

The remote interpretation database (for administrators)​

The cloud store is a module of the Athos server (the same Node/Express service used by the Athos AI assistant), mounted at /api/v1/vc and backed by its own PostgreSQL database. Desktops never talk to PostgreSQL directly — they speak HTTPS to this API, which enforces authentication and per-project authorization.

   VRGS desktop ─┐
   VRGS desktop ─┤   HTTPS  Authorization: Bearer <Auth0 JWT>     ┌── PostgreSQL
   VRGS desktop ─┼───────────────────────────────────────────────►│   (entities, variants,
   VRGS desktop ─┘        Athos server   /api/v1/vc                │    scenarios, pins,
                              │  ▲                                 │    tombstones, geometry
                              │  │ validate JWT (signature,        │    packages, members,
                              ▼  │  audience, issuer, expiry)      │    change log)
                            Auth0 ─────────────────────────────────┘
  • Authentication — every request carries an Auth0 bearer token; the server validates its signature, audience, issuer, and expiry. Auth0 only authenticates — it says who you are, not what you may access.
  • Authorization — a separate vc_project_member table maps each user (by their Auth0 subject) to a role in each project. Reads require viewer, writes editor, and member management owner.
  • Optimistic concurrency — every entity, variant, and scenario carries a server_version. A writer sends the version it last saw; if the server has moved on it returns 409 Conflict with the current state, and the desktop rebases and retries. This is how simultaneous edits stay safe without locking.
  • Object identity — objects are referenced by a global UUID (object_uuid), never a per-file integer id, so the same interpretation is recognised across machines. UUIDs are stored and compared as text.
  • Geometry packages — each variant's geometry is one content-hashed package; unchanged geometry is skipped on both sides, and deleting a variant (or its entity) removes its package.

Endpoints (summary)​

MethodPathRole
POST / GET/api/v1/vc/projectsany authenticated (register / list mine)
GET / POST / DELETE/api/v1/vc/projects/:p/members[…]viewer / owner
GET/api/v1/vc/projects/:p/snapshotviewer
GET/api/v1/vc/projects/:p/changes?since=viewer
PUT/api/v1/vc/projects/:p/entities/:entityUuideditor
PUT/api/v1/vc/projects/:p/scenarios/:scenarioUuideditor
POST/api/v1/vc/projects/:p/tombstoneseditor
PUT / GET/api/v1/vc/projects/:p/variants/:v/geometryeditor / viewer

Deployment notes​

  • The VC module has its own PostgreSQL pool (VC_DATABASE_URL), separate from the rest of the server, and can lift out into its own service unchanged.
  • Provision a least-privilege database role for the API; never ship database credentials to desktops.
  • Restrict the database to trusted sources (the server host), enable TLS (VC_PG_CA_CERT_PATH), and turn on automated backups / point-in-time recovery — the store holds interpretation history.
  • Use the same Auth0 tenant and audience as the rest of the Athos server; the VRGS desktop obtains tokens through its existing Auth0 flow.
  • Apply the schema with the module's idempotent migration (npm run vc:migrate).

What data is stored​

  • Locally: variant geometry in the project database; version metadata in the InterpretationVC.db sidecar beside it. Both are backed up and copied by Save As.
  • In the cloud: for each registered project — its entities, variants, scenarios, pins, tombstones, per-variant geometry packages, the member list (by Auth0 identity and role), and a change log. Set retention and backup policies to suit your organisation's requirements.

Troubleshooting​

SymptomLikely cause / fix
"Save the project before syncing."The project has never been saved, so there is no sidecar/sync state and no stable object identities yet. Save, then sync.
Menu says "already versioned"The interpretation is already an entity. Use Fork Variant to add an alternative.
Fork Variant says "not versioned yet"Run Version this Interpretation first — you can only fork a versioned feature.
A forked variant seems to be missingIt is an exact copy of its source and sits coincident with it until you edit it. Hide the source or apply a scenario.
Editing changed the "wrong" interpretationVersioning does not snapshot geometry — an edit changes the current version. Fork first, then edit the fork.
Sign-in never completesThe browser approval wasn't finished, or the code expired. Re-run Sync with Cloud… and approve promptly; check the Auth0 domain / client id / audience.
"Could not reach the sign-in service"Wrong Auth0 domain, or no network. Verify the domain with your administrator.
Sync reports nothing pushedOnly fully local variants (every member has geometry and a saved identity) are published — save the project, then sync.
Colleague can't see the projectThey aren't a member. The owner must add them (as viewer or editor) on the server; non-members get "not found".
A teammate's edit didn't overwrite mineBy design — geometry is never overwritten, and scalar conflicts are last-writer-wins. Their alternative arrives as a separate variant if they forked.