Frequently asked questions

3D Cave Viewer is an open source web application for exploring three-dimensional cave surveys straight from the browser, with nothing to install. It is developed by Davide Brugnoni for Buio Verticale, the CAI Gubbio caving group, and released under the GNU GPL v3 licence.

No published model is an artistic reconstruction: each one is the real survey of a real cave, georeferenced on the map and faithful in its proportions.

No. A recent browser is enough: Chrome or Edge from version 90, Firefox from 85, Safari from 14, phone browsers included. There is nothing to download and nothing to configure.

It is also a Progressive Web App: you can install it as if it were an application, and caves you have already visited stay available offline. That is a real convenience in the mountains, where the network often does not reach.

GLB, which is the recommended one because it packs geometry and textures into a single compact file; GLTF with external assets; and OBJ with its material files, supported but less efficient.

The viewer reads three-dimensional models — meshes — not the project files of cave surveying software. If your survey starts life in a surveying package or in CAD, export it to a mesh first; if it comes from a LiDAR scan or from photogrammetry, it is usually already in the right shape.

Models exported with Z as the vertical axis instead of Y — which typically happens with CloudCompare — can be straightened by writing a rotation in degrees into the cave’s metadata file, without touching the 3D file again.

The project includes two optimisation tools, both open source and ready to use: a small Node.js server that takes files dropped into the browser, handy for working through several models in a row or for keeping a shared instance within a group, and a single HTML page that does exactly the same job inside the browser, with no server and no dependencies to install.

Both apply Draco compression to the geometry, weld duplicate vertices, prune unused resources and compress textures to WebP or JPEG. They also convert straight from OBJ: drop the .obj file, the .mtl files and the texture images together.

The server version handles surveys up to 5 GB: OBJ conversion runs through a parser that reads the file one piece at a time, and meshes with tens of millions of vertices are split automatically before compression, without changing the visual result.

Create a folder for the cave, put the 3D model in it along with a small JSON metadata file carrying the name, the folder, the file, the latitude and the longitude. Description and rotation are optional.

The catalogue updates itself by reading the folders that are there: no admin panel to learn, no database to manage. The cave appears on the map and in the list, and its marker opens the viewer.

Three, in increasing order of immersion. In orbit mode you move around the survey, rotate it and zoom in as you would with a model on a table; on a phone one finger rotates and two fingers zoom and pan.

In first person you are inside the cave, moving with the WASD keys or a virtual joystick, while collision detection stops you from walking through the walls: this is the mode that gives back the physical sense of the space.

In virtual reality you enter the cave at 1:1 scale: you move with the controller sticks, turn in 45-degree steps for comfort, and reach a distant point with a double-trigger teleport. During faster movements the edges of your vision darken gently, to reduce the risk of motion sickness.

For the virtual reality mode, yes: you need a headset with a WebXR-capable browser. You do not need any dedicated software, though, nor a store to download anything from: open the cave’s address in the headset’s browser and you are in.

The other two modes, orbit and first person, work on any recent computer or phone. The headset adds true scale; it is not the required way to look at a cave.

You can measure: place points on the model and get three-dimensional distances in real time, with automatic snapping to mesh vertices for precision, eight colours to keep several measurements apart, units formatted on their own in centimetres, metres or kilometres, the option to move an endpoint you have already placed, and CSV export of the list.

You can cut: section planes along the X, Y and Z axes are set with sliders and can be flipped, and six preset orthogonal views — plan, from below, front and side — let you jump from one perspective to another. A scale bar adapts to the zoom level so there is always a metric reference.

You can annotate and export: labelled points of interest are saved per model and can be exported and reimported as JSON, while the camera button saves the current view as a PNG with sections, measurements, scale bar and logo already composited, ready for a technical report.

Yes, and that is the whole point of it being free software. The GNU GPL v3 licence lets any group or organisation install it, customise it — name, logo, colours and texts are all configurable — and publish its own surveys. There are two obligations: keep the original author credited, and distribute any modifications under the same licence.

On the server side you need PHP 7.4 or later and Apache with mod_rewrite: the most common and cheapest infrastructure there is, the kind any shared hosting provides. There is no build step to run, so the project stays maintainable even by a group with no developers.

There is no central service to hand your surveys over to: each group installs the application on its own server and publishes what it decides to publish. The files stay where their owner puts them.

The single-page version of the optimiser works entirely inside the browser: models are never uploaded to any external server, not even to be compressed. That is the route to prefer when a survey must not leave the computer.

Annotations added to a model are saved in the browser of whoever writes them, cave by cave, and have to be exported as JSON to be shared: they do not travel on their own.