Subsidence Gradient & Hazard Classifier

A single velocity number tells you how fast a point moves; it tells you nothing about whether the ground is differential moving — and differential movement is what damages highways, railways, pipelines and structures. Two points can both subside at 10 mm/yr and be perfectly harmless if they move together, while two points 20 metres apart moving at 0 and 15 mm/yr respectively represent a serious engineering problem. This tool turns a cloud of vertical velocity points into a spatial risk picture by computing the subsidence gradient — the velocity difference between neighbouring points divided by the distance between them — and classifying every point against transparent, screening-level criteria packages informed by published differential-settlement practice.

Use it after the LOS Converter (which supplies vertical rates through the Data Tray) and before the reporting step. Like everything on this site, the computation happens entirely in your browser, and the classified points can be exported as CSV for your records, as KML for Google Earth or QGIS, and as a 300-DPI risk map for the report.

When you should use this tool

You have converted vertical velocity points and need a defensible first-pass screening of where differential settlement concentrates.
You are comparing two processing campaigns or two tracks and need a consistent classification scheme applied to both.
You need to communicate InSAR results to non-specialists — the five-level colour scheme and the KML export make the spatial pattern legible in a client meeting or a GIS environment.

When NOT to use this tool

Your points are still LOS velocities — convert them first, or the gradients will mix geometric projection effects with real deformation differences.
You expect a verdict on structural safety. A hazard class here is a screening indicator derived from generic criteria; the governing design specification for your asset always takes precedence.
The point density is far below the neighbour radius you intend to use — every point will come out isolated and the classification degenerates to a velocity threshold exercise. Collect more points or widen the radius knowingly.

What the gradient actually measures

For every point the tool searches within a radius R (default 100 m, package-dependent) and computes the velocity difference to each neighbour, divided by their horizontal (great-circle) distance. The largest such value becomes the point's representative gradient, expressed in mm of differential motion per metre of distance. This mirrors how deformation damage actually accumulates: it is driven by relative displacement over a structural span, not by absolute settlement. Choosing R is an engineering decision, not a default to accept blindly: R should roughly match the span of the asset you care about — a bridge abutment spacing, a rail weld interval, a foundation footprint. A radius much larger than that dilutes real discontinuities; a radius much smaller than the point spacing leaves most points without neighbours, and they are then classified on velocity alone and marked isolated in the output.

On top of the gradient, the tool applies a velocity safeguard: points whose vertical rate exceeds the package's rapid-motion threshold are promoted regardless of gradient, because a fast-moving isolated point can be a genuine hazard even without a nearby reference point to differ from.

Criteria packages & their limits

Four built-in packages ship with the tool: highway (AASHTO-informed), railway embankment, open-pit mine slope and building foundation. Each defines four gradient boundaries that split the range into five classes — Stable, Low Concern, Moderate, High Hazard and Critical — plus the neighbour radius and the velocity safeguard thresholds. The thresholds are screening defaults drawn from published differential-settlement practice; they are deliberately conservative and deliberately transparent. They are not the numbers of any specific design clause, and this tool does not pretend to replace the governing specification for your asset. If your project specification defines limiting gradients or deflection ratios, use those numbers — the philosophy of the tool is to give you a defensible starting grid, not an authority claim.

Step-by-step usage

Convert your LOS points in the LOS Converter (the demo button there loads 87 points). They arrive here automatically through the Data Tray — no re-import, no column matching a second time.
Pick the criteria package that matches your asset type, and adjust the neighbour radius to your structural span if needed. The reference note under the selector states what each package assumes.
Run the classification. The table lists every point with its velocity, representative gradient, neighbour count and class; the map colours points by class; the bar chart summarises the distribution.
Export: the CSV preserves every column for your records; the KML carries the five-class colour scheme into Google Earth or QGIS for spatial context against imagery; the PNG is a print-ready 300-DPI risk map.

Output interpretation guide

Read the map before the table. Clusters of High Hazard and Critical points along a linear asset are the pattern that deserves follow-up; a single Critical point surrounded by stable neighbours is more often a processing artefact (an unwrapping error, a corner reflector, an atmospheric outlier) than a real hazard. Check the neighbour column: isolated points carry a marker and their class rests on the velocity safeguard alone. The gradient column is the number to quote when defending the classification in a review meeting — it is reproducible from your own dataset with nothing more than a ruler.

Common pitfalls & mistakes

Radius-annealing blindness. Running the tool once with the default radius and never asking whether that radius matches the asset. A 100 m radius is meaningless for a rail weld inspection and generous for a building foundation.
Cross-package comparison. A Moderate in the mine package is a different physical gradient than a Moderate in the railway package. Never quote class labels without naming the package.
Class inflation by velocity safeguard. Points promoted by the rapid-motion rule carry the same label as gradient-driven ones. Look at the gradient column to see which mechanism fired.
Treating Critical as a failure verdict. InSAR screening flags where to look; it does not condemn. Follow-up is a field programme, not a demolition order.

Frequently asked questions

Why does the point count differ between runs?: Changing the radius changes which points have neighbours and which gradients are the largest. Report the radius together with the results — they are part of the method.
Can I use my own thresholds?: The package structure is designed for it; custom criterion packages saved locally are on the roadmap. Until then, export the CSV and classify downstream if your specification differs.
Why great-circle distance instead of projected UTM distance?: At site scales (kilometres) the two differ by less than the point-spacing noise. The haversine form keeps the tool projection-free; use the Coordinate Converter if your workflow needs UTM coordinates for other purposes.
Does classification use atmospheric-corrected velocities?: It uses whatever velocities you give it. If atmospheric phase screens dominate your scene, the gradients inherit that error — apply your processor's atmospheric correction first.
Is the five-level scheme an industry standard?: The labels are this tool's, chosen for clarity. The gradient boundaries are informed by published practice but not part of any standard; name the package and thresholds whenever you publish results.

Demo dataset & related tools

The demo dataset (87 points across four deformation regimes) classifies into a distribution that matches its design — see the Sample dataset guideLOS Converter. Downstream: the GNSS Validation tool to check flagged zones against ground truth, and the Error Budget calculator to state the uncertainty behind every gradient.