Saving and Recovering a Project
A project is a .vgpx file and a data folder beside it;
The project directory structure
says what is where. This page covers what a save does, what VRGS asks when a
project opens or closes, and what to do when something has gone wrong. Dated
backups and the Recover a project command are in
Managing backups.
Saving
File → Save, or Ctrl+S, writes the project file, the database and every model file with changes. The messages panel then says Project saved, or Project not saved. See messages for reason. with the reason above it. In a report, field guide or Python script window, Ctrl+S saves that window's own file instead.
File → Save As copies the whole data folder to the new location, after a warning that this can take a long time. VRGS then carries on in the copy.
Three settings under Saving & Backup in Project Properties save for you:
| Setting | Default | What it does |
|---|---|---|
| Enable Auto Save | Off | Saves every Autosave interval minutes (10 by default). An autosave is skipped while background work runs or a project is loading. |
| Save After SfM Stage | On | Saves as a photogrammetry run starts and as each stage finishes, because the interval autosave skips the whole of a run. |
| Backup On Save | On | Before a save, writes a zip of the project file and the database, at most as often as Backup Interval says (Daily by default). Model files are not in the zip. |
A Viewer licence cannot save.
Closing or replacing a project
Every route that closes or replaces the open project offers to save first: Close, Open, the recent list, a double-click in Explorer and a drop onto an empty window. Close and the open routes ask one question, which reads, for example, Save it, then open 'Quarry'?
| Answer | What happens |
|---|---|
| Yes | Saves, then goes on. If the save fails, the project stays open and a box points you to the messages panel for the reason. |
| No | Goes on without saving. |
| Cancel | Stays as you are. |
With nothing to save it is a plain yes or no. New and Exit ask you to confirm first and then ask about saving. Cancelling the Open or New file dialog closes nothing and asks nothing. Answering Cancel when Windows shuts down or End task asks about saving keeps VRGS open.
Opening a project
File → Open takes a .vgpx, or a .vgp from an older VRGS. Double-clicking
either in Explorer opens that project by the same route, with the same questions.
A .vgp with a .vgpx beside it opens through the .vgpx.
The recent projects list names each project with its folder and treats a .vgp
and its .vgpx as one entry. If a recent project's file cannot be found, VRGS asks
before taking it off the list, because the drive may just not be connected.
The reload question
A project saved with meshes or point clouds showing asks whether to load them: Reload Point Clouds & Mesh Data? It lists the models, or counts them when there are more than five, and gives what they will take against what is free, for example About 14.2 GB to load; 30.1 GB of memory free. When the total is more than is free it adds That is more than is free: the models that do not fit will be skipped.
- Yes loads them. Meshes load in the background, at most four at a time, so peak memory depends on the largest few and not on the sum of them all. A model that does not fit when its turn comes is skipped with a warning in the messages panel, and stays hidden.
- No hides every mesh and point cloud. The project is open, and you can tick what you want.
See Memory in Working with Large Models.
Projects from other versions
An earlier project is upgraded as it opens, and VRGS asks first, before anything changes.
| Project | What happens, once you have agreed |
|---|---|
A .vgp from an earlier VRGS | VRGS writes a new .vgpx and database beside the .vgp, which is left unchanged, and converts the data files. |
A .vgpx from an earlier VRGS | VRGS writes a backup zip to VGP_BACKUP, with a GeoJSON export of every interpretation in it, then saves the project in the current version and converts the data files. If the backup cannot be written, the project opens but is neither upgraded nor converted, and the next open asks again. |
A .vgp from a later VRGS does not open: a box says which version the file is for
and which you are running, and VRGS stays running with no project.
Opening a .vgp can also find orientation objects with a dip outside 0–90 or an
azimuth outside 0–360. They are listed together in one Invalid objects box,
the first twelve by name with their values. Yes deletes them all; No keeps
them.
Upgrading an older project
A project last saved by an earlier VRGS may hold its models in older files. When you open one, the Upgrade project box appears before anything changes. It says what would be upgraded: the project file, with the two version numbers, and how many point clouds, meshes and orthopanels would be converted. It warns that earlier versions may not open the project afterwards.
| Button | What happens |
|---|---|
| Back up, then upgrade | You choose a folder, and VRGS copies the project file and the whole data folder into a new folder there, named <project> backup <date time>, then upgrades and opens the project. The copy has a progress row with a Cancel button. |
| Upgrade without a backup | Asks you to confirm first (below), then upgrades and opens the project without a backup. |
| Ask me next time | Opens the project and leaves its point clouds, meshes and orthopanels in their older format. Saves leave them as they are for the rest of the session, edits to them included, and the next open asks again. Only offered when there are older models to convert. The project file itself is still saved in the current version, as for any project from an earlier version. |
| Cancel | Does not open the project, and nothing in it changes. A project you already had open stays open. |
Upgrade without a backup opens a second box. Its Upgrade button stays greyed out until you tick I have my own backup of this project, or I accept that the upgrade cannot be undone. Go back returns to the first box.
If you cancel the folder choice, or the backup is cancelled or cannot finish, the Upgrade project box comes back, so you can choose another folder or cancel. A backup that does not finish removes its partial copy. The backup cannot go inside the project's own data folder, and the destination needs the size of the project plus 1 GB free.
A viewer-only session does not ask, because it cannot save: the project opens as it
is. A database that is only behind on its table layout, with nothing else to
upgrade, is brought up to date without asking, after a backup zip to VGP_BACKUP.
An earlier VRGS looks for point clouds, splats and orthopanels only in their older format and place, so it cannot load converted ones, even where the project itself opens. If anyone still opens this project in an older VRGS, choose Back up, then upgrade and keep the backup.
The conversion has one progress row, Converting Cliff (3 of 12), and it runs to the end once started. A model that is not in memory is loaded, written and released again, so a large project does not have to fit in memory all at once, and a hidden model stays hidden. Each new file is written before the old one is deleted, so the drive needs room for both while it runs. Texture images are copied unchanged. A model that cannot be read or written stays in its old file, with a warning in the messages panel, and opening the project does not ask about it again.
Older files that arrive later
Older files can reach a project after it has opened, from Recover from data folder or from importing an older project. The first manual save that would convert them shows the Convert project data box, with the same choices: Back up, then save, Save without a backup (confirmed in a second box, as above), and Ask me next time, which saves without converting them. After Ask me next time later saves do not ask, and the next open does. Cancel there does not save, and the next save asks again.
An autosave or an SfM stage save has nobody to ask. Until you have answered, it leaves the older files as they are and says so once in the messages panel. It does not write edits to an older point cloud, splat or orthopanel either, so save by hand to keep them.
Upgrading from the command line
VRGS.exe -upgrade "<project file>" [-upgrade_backup "<folder>"] [-upgrade_report "<file>"]
This opens the project, upgrades and saves it, and exits, asking nothing. Quote any
path with a space in it. -upgrade_backup makes the same copy as Back up, then
upgrade, before anything changes. -upgrade_report writes the result as JSON: what the project
needed before the run, and what it still needs after it. A project that is already
current is left alone and counts as a success.
| Exit code | Meaning |
|---|---|
| 0 | Upgraded, or nothing to do. |
| 1 | The project could not be opened or saved. |
| 2 | There is no such project file. |
| 3 | This session cannot save, because the licence is viewer-only. |
| 4 | The backup did not complete. The project has not been touched. |
| 5 | The project was saved, but something in it could not be upgraded. |
| 6 | The project is from a later VRGS. It has not been touched. |
The run writes its own log, VRGSUpgrade.LOG, in
%LOCALAPPDATA%\VRGeoscience\VRGS.
Recovering models from a data folder
File → Recover from data folder is for a project whose .vgpx or database is
lost or corrupt. It copies the point clouds and meshes that the damaged project's
data folder still holds into the open project, so create a new project first, with
File → New. If the database itself is still good, or a backup holds it, try
Recover a project
first: that brings the interpretations back as well.
Choose the <project> Data folder. VRGS then says what it found and how large it
is, and what it cannot recover. On OK it copies the models across and adds them
to the tree, hidden, named after their files. Tick a model to load it, then save the
project. The damaged project's folder is only read.
| In the data folder | What happens |
|---|---|
POINTCLOUDS\*.ply | Recovered: points, attribute layers and scan orientation. |
*.pcl at the root | Recovered. It is an older file, so the next save asks to convert it. |
TRIMESH\*.tin_v3, and every other file in TRIMESH | Recovered: the meshes, and the textures they name. |
Mesh files at the root (.tin and similar) | Not recoverable. Counted in the prompt. |
ORTHOPANELS\*.orthopanel | Not recoverable: their placement was only in the database. Counted in the prompt. |
| A damaged file, or a mesh saved by a newer VRGS | Skipped. Counted in the prompt and named in the messages panel. |
GAUSSIANSPLATS and RECYCLING | Not looked in. |
Interpretations, tree folders and display settings lived in the database and cannot be rebuilt from files. Recovery refuses to run, and says why, when:
- the folder is the open project's own data folder;
- the folder holds none of
POINTCLOUDS,TRIMESH,ORTHOPANELSorDATABASES; - it finds nothing it can recover;
- the open project already has a different texture of the same name, in which case recover into a new, empty project;
- the project's drive does not have room for the copy plus 1 GB.
The copy has a progress row with a Cancel button; what was copied before you cancel stays in the project. The command is greyed out with no project open and with a Viewer licence.
Recycling unused data files
File → Recycle unused data files finds model files in the data folder that the
project no longer uses, says how many there are and how large, by folder, and on
OK moves them to the RECYCLING folder. Nothing is deleted: move a file back
to use it, or empty RECYCLING to get the disk space back; see
Recycle.
A file counts as unused only when neither the database nor any model in the project names it. These are the files it considers:
| Folder | Files |
|---|---|
| The data folder itself | .pcl, .gsplat, .tin, .tin_v1, .tin_v3, and the .dxt and .povl files of an old mesh that has gone |
POINTCLOUDS | .ply |
GAUSSIANSPLATS | .ply, .gsplat |
TRIMESH | .tin_v3 |
ORTHOPANELS | .orthopanel |
Texture images are left alone. A hidden mesh's texture names are inside its mesh
file, which is not read until the mesh is shown, so a texture can be in use with
nothing in memory or in the database naming it. An old mesh's .dxt and .povl
files stay for as long as the mesh does.
The command refuses to run when:
- the project has unsaved changes, because it compares the data folder with the saved project. Save first;
- the project has not yet been saved to its database, as with one just opened from
an old
.vgp. Save first; - the database cannot be read.
It is greyed out with no project open and with a Viewer licence.
File → Cleanup Database is an older and narrower command. It moves .tin,
.pcl and .gsplat files in the data folder, and .ply and .gsplat files in
POINTCLOUDS and GAUSSIANSPLATS, into RECYCLING\UNLINKED when no model in the
open project names them. It does not look at the database or check that the project
is saved, so prefer Recycle unused data files. Its warning speaks of permanently
deleting files, but it moves them.
Work running in the background
Stopping a job
Each running job has a progress row in the messages panel, with a Cancel button. The button changes to Cancelling… and the job stops at its next check. Right-clicking the row and choosing Terminate Process does the same. On any row of a photogrammetry run, it stops the run.
A job that cannot be stopped from the panel changes the button to Cannot cancel, and the messages panel says to wait for it. Poisson meshing, kriging and plane growing run to the end once started, and so does the conversion of older data files.
Cancel Operation on a mesh's or point cloud's right-click menu stops the work on that model. Reading a current mesh file, a LAS or LAZ file or an E57 file can be stopped this way. Nothing of the partial model is kept, and the messages panel says 'Cliff' was not loaded: cancelled. It has been hidden; show it again to retry.
Closing with work running
Closing or replacing the project frees what running jobs are working on, so VRGS asks first. The Processes still running box names the jobs and offers to cancel them:
| Answer | What happens |
|---|---|
| Yes | Asks the jobs to stop and waits for them, for up to two minutes, with the main window disabled, then goes on. If a job has not stopped by then, VRGS tells you to wait for it and try again, and the project stays open. |
| No | Leaves the work running and stays as you are. |
Close, New and every route that opens a project ask this. Exit, or closing the main window, asks it for a drone survey, a slope stability run, a StraboSpot import, field guide sharing or an Outcrop.io upload. For other background jobs, such as a mesh loading, it says VRGS will wait for them to finish and then exit: OK waits, Cancel returns to VRGS. That wait does not stop them, so cancel a long job from its progress row first.
See also
- The project directory structure — what is in the data folder.
- Managing backups — dated backup zips, and Recover a project.
- Project Properties — the autosave and backup settings.
- Working with Large Models — what happens when a model will not fit in memory.