Guide

How to drive the simulator, what each control actually changes, and the mistakes that cost the most time.

On this page

Signing in
Finding your way around
Before you start
1 · Load and verify the DTM
2 · Area of interest
3 · Parameters
4 · Run and read the results
5 · Save and recall runs
6 · Barriers
7 · Objects and exposure
8 · Imagery and basemaps
9 · Slope kinematics
10 · Hydrology
11 · Flood screening
12 · Change detection
13 · Calibration
14 · Export
Keyboard and mouse
Common pitfalls

The hosted app asks for the team PIN. The session lasts twelve hours and is per browser, so you and a colleague can work on different DTMs at the same time without disturbing each other — each of you has your own loaded terrain and your own results.

Uploads go straight to storage, not through the app. That is why a multi-gigabyte DTM is practical, and why an interrupted upload picks up where it stopped rather than starting again. Leave the tab open while the bar advances.

If the service has been idle it takes a few seconds to wake, and restoring your terrain takes about a second more — it is rebuilt from a cached grid rather than re-read from the original file. If you are ever bounced to the login page mid-session, sign in again and reload the DTM; your uploads are untouched.

To change the team PIN, double-click Change PIN.bat in the project folder. It asks for the new PIN twice with the screen hidden, scrambles it on your own machine, and sends only the scrambled form — the PIN itself is never stored or transmitted. The old PIN stops working immediately.

Deleting an upload removes it from storage for everyone, and cannot be undone.

Finding your way around

The panel on the left has six tabs. They follow the order you work in:

Tab	What lives there
Terrain	Choose or upload a DTM, set the grid resolution, draw the area of interest.
Rockfall	Block and surface parameters, the run button, the results table, and barriers.
Layers	What is drawn over the terrain — imagery, hazard rasters, trajectories.
Analysis	Everything that is not the rockfall run itself: objects and exposure, kinematics, hydrology, flood, change detection, calibration.
Runs	Save what you have done, and bring an earlier version back.
Export	Download the GIS bundle.

The 3D view responds to the mouse throughout: drag to orbit, scroll to zoom, right-drag to pan. Reset view and Top view are in the top right.

Two tabs are two separate workspaces. You can open the app twice and work on two different DTMs side by side — they no longer interfere. Closing a tab ends its workspace; saved runs are unaffected, because they live in storage rather than in the tab.

Before you start

Use the DTM (bare earth), not the DSM. Rocks bounce and roll on the ground, not on vegetation or building tops. A DSM will invent launch ramps out of tree canopies.

Everything runs locally. Nothing is uploaded anywhere; three.js is vendored, so the app works with no internet connection.

1 · Load and verify the DTM

Choose DTM file… picks a GeoTIFF and streams it into uploads/ with a progress bar. Multi-gigabyte files are fine. Once uploaded, a file stays in the dropdown below, so you never have to send it twice. Delete selected upload removes it from disk — it asks first, and cannot be undone.
Check the table that appears. This is the step people skip and regret. Confirm the grid size, cell size, extent, elevation range and CRS are what you expect. If the extent is 0.05 × 0.03 or the elevations are nonsense, the georeferencing is wrong and every number downstream will be wrong with it.
Look at the terrain in 3D. Orbit with the left button, pan with the right, zoom with the wheel. Raise Vertical exaggeration if the site is low-relief. Holes in the mesh are nodata — the reference survey is only 38% covered, and that is drawn honestly rather than interpolated over.

If the terrain renders as a huge flat plane with a small strip of real ground, the file has undeclared nodata. Many exports write a constant — usually 0.0 — into unsurveyed cells without declaring it. The app detects that and says so in the DTM table (Fill detected), but if the guess is wrong, set Nodata value explicitly and reload. Setting it to the file's declared value disables the guess and keeps everything.

Grid resolution is the most consequential setting on the page. It is not your DTM's native pixel size — the file is resampled so its long side fits this number. A 12 cm survey runs at 5.24 m cells by default. Cell size drives detachment scar depth (block volume ÷ cell area), whether rocks ever become airborne, and how long a run takes (roughly with the square). Raise it and press Reload at this resolution.

2 · Area of interest

Click Draw polygon, then click corners on the terrain around the unstable face. Double-click or press Enter to close it. The release-cell count updates immediately, so you can see whether your polygon actually contains steep ground.

Rocks are released only inside the polygon but run out freely beyond it — the boundary constrains the source, never the runout.

3 · Parameters

Control	What it does
Rock density, block volume	Set the block mass. Volume also sets the collision radius and the volume moved per detachment.
R_n, R_t	Restitution at a genuine impact. On terrain where rocks mostly roll, these barely matter — see identifiability.
Rolling friction μ	The dominant control on runout. If you calibrate one thing, calibrate this.
Source slope threshold	Cells steeper than this can release.
Max source cells	Caps the release cells used; above this they are randomly subsampled.
Rocks per source	Monte-Carlo samples per cell — or real simultaneous blocks if collisions are on. The meaning changes.
Rocks to animate	How many trajectories come back for playback. The hazard rasters always use every rock.
Collisions between rocks	Switches the release model. Read the note in the panel before using it.

4 · Run and read the results

Playback starts automatically. Rocks move along their real trajectories, coloured by velocity, leaving velocity-coloured trails. Scrub the timeline, change speed, or press Space.

The rock markers are inflated so you can see them. A 0.42 m block is sub-pixel across a 5 km site. The playbar reports the factor for the nearest rock — ⌀0.83 m · nearest drawn 17×. At that inflation markers overlap on screen even when the blocks do not. Zoom in until it reads true size before judging whether two rocks are really in contact.

The Layers panel drapes rasters over the terrain: passing frequency, peak velocity, peak energy, elevation change, and the analysis layers from the sections below. Post-event swaps the mesh to the terrain the event left behind, from the same viewpoint, with a labelled change-exaggeration slider because a real 1 cm scar is invisible.

5 · Save and recall runs

In the Runs tab. After a simulation, give it a name and press Save current run. Everything is kept together: the parameters you used, the hazard rasters, the trajectories and the statistics.

Each save is a new version. Nothing is overwritten, so you can run the same site with a 0.5 m³ block and a 6 m³ block, save both, and switch between them to compare. That is the point — a study is a dozen simulations, not one.

Recall puts a saved run back on screen exactly as it was, including writing its parameters back into the form so the controls and the picture cannot disagree. If the run belongs to a different DTM, that DTM is reloaded first.

A run is tied to the grid resolution it was computed at. If you reload the DTM at a different resolution, an older run will refuse to be recalled rather than draw its rasters over a grid they do not fit. Reload at the original resolution and it will come back.

Name runs so you can tell them apart later — "2 m³, no barrier" beats "test 3". The list shows block volume, rock count, mean runout and peak energy for each.

6 · Barriers

Two distinct jobs, and it matters which one you are doing.

Sizing a fence — the measuring line

Draw an alignment across the runout. Rocks are measured as they cross, not stopped: you get crossing counts, impact energy, speed, bounce height and design values at the 95th percentile. Sizing from an unobstructed run is the right way round — you need to know what would arrive if nothing were there.

Check the "airborne at line" figure before trusting a fence height. If almost every rock crosses while rolling, the bounce height is not a design driver and the app says so. On the reference site rocks are airborne about 2% of the time, so height is meaningless there while the energy figure is solid.

Testing a fence — the obstacle

Tick Fence stops rocks, set a capacity, and run again. Now the fence acts: rocks are retained, overtopped, or breach it. Compare the hazard rasters with and without it — that difference is the mitigation benefit.

7 · Objects and exposure

In the Analysis tab. Upload a DSM covering the same ground as the DTM and press Build nDSM: the difference between the two is the height of everything standing on the ground.

Exposure register — after a simulation, lists which structures the rockfall reaches, how many passes each takes, and the impact energy. This is the output to put in front of a client.
Structures stop rocks — buildings arrest a block arriving below roof height; vegetation bleeds speed over the distance travelled through canopy. Without it the model runs over bare earth as though the ground were empty, which over-predicts runout anywhere built up.

Watch the DSM/DTM shift row. If the two surfaces are not registered to each other, the misalignment turns into fake object height on every slope. The app measures and corrects it, and says so.

Classification is a heuristic: near-constant height above ground reads as a building, broken variable tops as vegetation. Check it against the imagery — walls, scaffolding and dense scrub are genuinely ambiguous, and a DSM-derived "building" is a blob of raised cells, not a footprint survey.

8 · Imagery and basemaps

In the Layers tab, the Imagery section drapes a picture over the terrain and lays a wider basemap around it.

Orthophoto — upload a georeferenced RGB GeoTIFF from the same survey and drape it. This is the better option whenever you have one: your own ground sample distance, no internet, no licence question. It must be in the same CRS as the DTM.
Web basemap — Esri World Imagery, OpenStreetMap, or your own XYZ URL template. Needs an internet connection; the terms of the tile service you pick are yours to comply with. Tiles are cached on disk, so re-fetching the same area works offline afterwards.
Context margin — how far the surrounding ground plane extends, in DTM widths each side. Set 0 to drape the survey only.

Imagery opacity and Relief shading control the mix. Relief is composited with an overlay blend, so hillshade adds shading without greying the picture out. If roads and features line up across the edge of the survey onto the context plane, your georeferencing is right.

9 · Slope kinematics

Markland tests for planar, wedge and toppling failure, plus a stereonet. Set the friction angle for your rock type and the minimum face dip worth testing.

A "yes" is not a factor of safety. It means the geometry does not prevent that failure mode. And the joint sets estimated from the DTM assume the exposed face is the joint plane — true on clean rock, meaningless on talus or soil cover. Replace them with mapped orientations for anything that matters.

10 · Hydrology

Sink fill → flow routing → accumulation → streams. No geotechnical input at all, so this is the most directly defensible module in the app. Optionally pick an outlet on the terrain for a watershed; it is snapped to the nearest channel, because one cell off the thalweg gives you the wrong catchment entirely.

Lower the stream threshold for a denser network, raise it for main channels only.

11 · Flood screening

In the Analysis tab, under Hydrology. It maps inundation from the terrain using HAND — the height of every cell above the channel it drains to. Run hydrology first, or it will derive a drainage network for you.

Channel stage — geometric and the more defensible of the two. "What does the terrain flood if the channel rises N metres?" Nothing is assumed beyond the DTM.
Rainfall → discharge — a screening estimate. Rational method for peak flow, Manning's equation for normal depth, then HAND for extent. Rainfall intensity, runoff coefficient, roughness and channel width are all your inputs, and all four are reported back with the result.

This is not a hydraulic model. There is no timing, no momentum, no backwater, and no culverts, bridges or embankments. It cannot tell you when water arrives or how fast it moves. Treat the output as a first-pass map of where terrain concentrates water, not as a flood study.

Watch the "never reaches a channel" figure in the note. On a fragmented survey footprint a large share of ground drains off the edge before meeting a channel; that ground is left unmapped rather than assigned a depth.

12 · Change detection

Difference two survey epochs to find real scars and deposits. Load a second DTM (it is resampled onto the first grid automatically) or generate a synthetic one.

Synthetic epochs are for testing the pipeline, not for calibrating the model. Fitting rockfall parameters to change our own simulator produced would recover exactly what was put in and tell you nothing about the slope. Use them to check the pipeline recovers a known volume, to measure your noise floor, and for twin experiments.

Two numbers to read first: the co-registration residual (surveys must align to roughly 0.1 m for volumes to be trustworthy) and the detection limit. Volumes are a lower bound — material spread thinner than the limit is invisible.

13 · Calibration

Fits R_n, R_t and μ so simulated runout matches observed deposits. Observations come from change detection, from deposits you mark by clicking the terrain (this works from a single survey — existing talus and boulder fields are past events already recorded in your DTM), or from a twin experiment against known truth.

Read the identifiability rows, not just the best fit. A parameter reported as "not identifiable" has a best-fit value that is noise: the misfit barely changes across the whole tested range. On the reference site that is true of both restitution parameters.

14 · Export

Download GIS bundle gives you a zip of georeferenced GeoTIFF rasters and GeoJSON vectors in the DTM's own CRS, plus a README recording the app version, the CRS, the grid actually simulated, every parameter, every result, and the caveat that the surface parameters are uncalibrated. They drop straight into QGIS or ArcGIS aligned with the survey.

Keyboard and mouse

Input	Action
Left drag	Orbit
Right drag	Pan
Wheel	Zoom
Left click (in a draw mode)	Place a point — a drag orbits instead, so a click only registers if the pointer barely moves
Double-click / `Enter`	Close a polygon or finish a barrier
`Esc`	Leave the current draw mode
`Space`	Play / pause the animation

Common pitfalls

Symptom	Cause
Rocks appear in only part of the polygon	You are animating fewer rocks than there are release cells. Raise Rocks to animate — the rasters already cover everything.
Rocks look like they pass through each other	Marker inflation at wide zoom. Zoom until the playbar reads "true size".
Post-event terrain looks identical	A 0.3 m³ block on a 5.5 m grid is a 1 cm change. Use a finer grid, a bigger block, or the change-exaggeration slider.
Change detection finds nothing	The change is spread thinner than the detection limit. That is a real result, not a failure.
Change detection finds change everywhere	Co-registration residual is too large. Check the residual RMSE row against the detection limit.
Calibration returns odd values	Check identifiability first. Also check the seed-to-seed noise floor — too few rocks and sampling noise swamps everything.
A DTM refuses to load (HTTP 400)	Read the message under the file picker — it is shown in red. A compressed GeoTIFF needs `imagecodecs`: `.venv\Scripts\python -m pip install imagecodecs`.
Terrain is a huge flat plane with a strip of real ground	Undeclared nodata written as a constant. Check Fill detected in the DTM table; set Nodata value if the guess is wrong.
Velocities or runouts look absurd	Check the CRS and cell size in the DTM table. A geographic DTM read as metres is the classic cause; the app converts it, but verify the reported cell size is plausible.

See Methodology for what the model assumes and where it stops being valid.

The 3D view looks wrong

If the terrain draws as slivers, bands or holes, first check the Valid cells figure in the terrain panel — a survey that covers an irregular footprint is mostly nodata, and those areas are genuine holes, not a fault.

If it still looks broken, press F12, open the Console, and type __RF.diag(). It reports what your graphics card supports and how many vertices the current mesh needs. Lowering 3D mesh detail is the quickest workaround, and it changes only the picture, never the results.

Press Ctrl+F5 if a fix has just been released and the page still behaves the old way.