Surfalize documentation
Surfalize is a browser-based surface-topography analyser. It loads measurement files from most common profilometers and microscopes, lets you preprocess them with a chain of non-destructive operators, and computes the full ISO 25178 areal and ISO 21920 profile parameter sets, entirely inside your browser. This page explains how the app is put together and what each part does. For a quick, hands-on introduction, open Help ▸ Guided tour in the app.
Overview
Surfalize is powered by a pure-JavaScript port of the open-source surfalize library. Every computation (loading, levelling, filtering, spectra and parameters) runs client-side. There is no server and nothing to install.
The engine uses 64-bit-addressed typed arrays, streaming algorithms and a background Web Worker, so it comfortably handles very large height maps (tens of megapixels) that would exhaust a conventional in-browser tool.
Getting started
index.html directly.File ▸ Load file…. See supported formats.Analysis group.
A new session auto-runs the guided tour once. You can replay it any time
from Help ▸ Guided tour, and run the interactive
example analysis (a full pipeline on a synthetic surface) from
Help ▸ Example analysis.
The interface
The work tree
The work tree is the heart of Surfalize. Each loaded file becomes a root; every operator you apply adds a child node holding the transformed result. Analyses, profiles, geometry and volume studies attach as their own nodes too. Selecting a node focuses it (its plots come to the front and tools act on it) without hiding the others.
Non-destructive editing & apply modes
Operators never overwrite your data. When you apply one you can either update the current state (replace the focused result in place) or spawn a new result that branches off, leaving the input untouched. Because the whole history is preserved, you can revisit any earlier step, edit an operator's parameters, or branch a different processing path at any time.
The Edit menu steps through this history: Undo (Ctrl+Z) and Redo (Ctrl+Shift+Z) reverse or replay operators, deletions and other work-tree changes, and Delete (Del) removes the selected node or panel.
Operators
Operators preprocess the height map. They are chainable in any order; each produces a new work-tree node.
Analysis panels
The Analysis group opens visualisations and computations as panels beside your height map.
Tools
Tools live on the left rail and annotate the focused surface without changing its height data. One canvas tool is active at a time and owns the mouse on the focused panel.
Extract: profiles
Draw a line across the surface to extract a cross-section profile into its own panel, with optional averaging over parallel lines. Extracted profiles carry the full ISO 21920 / 4287 R-parameter set. FFT and ACF maps can host profiles too.
Measure & Construct: geometry metrology
Place points, measure distances and angles, and fit circles (three-point) to features. Autodetect fits a circle or an edge line by sampling the full-resolution surface (caliper sampling → robust fit with outlier rejection). Constructions such as perpendicular, parallel and intersection reference existing line items, and committed items are draggable.
Volume
Draw a rectangular, circular or polygonal region to compute the material volume above, or the void volume below, a reference plane (the region mean by default). The 2D plot overlays the evaluated area (amber above the plane, blue below), and small disconnected regions can be excluded by area.
Parameters
Surfalize computes the areal (S) parameter families of ISO 25178-2:2021, validated against reference software, plus the ISO 21920 profile (R) set on any extracted profile. This section explains what each supported parameter measures and how it is defined. All areal parameters are evaluated over the area A of the scale-limited surface, that is, the surface after your chosen levelling and filtering. Heights z(x,y) are measured from the mean plane unless noted. Each S-parameter has a 1D profile analogue (Sa ↔ Ra, Sq ↔ Rq, and so on), available on extracted profiles.
Height (amplitude) parameters
Height parameters describe the statistical distribution of the ordinate values, that is, how far the surface departs vertically from its mean plane. They say nothing about the lateral arrangement of the texture: two very different-looking surfaces can share the same Sa.
The mean absolute deviation from the mean plane. The most widely used, most robust roughness number: stable, easy to interpret, but insensitive to the shape of the texture (it cannot tell peaks from valleys, or a few big features from many small ones).
The standard deviation of the heights (RMS roughness). Equivalent to Sa for a Gaussian surface (Sq ≈ 1.25 Sa) but weights large excursions more heavily, so it is more sensitive to outliers. Sq is the natural scale for statistical and optical work.
Sp is the single highest peak above the mean plane, Sv the depth of the single lowest pit (a positive number), and Sz their sum, the total peak-to-valley height. These are extreme-value parameters: informative about the worst-case feature, but sensitive to noise and single spikes, so they pair well with outlier removal beforehand.
The asymmetry of the height distribution (a pure number). Ssk < 0: a full, plateau-like surface with valleys cut into it, typical of a good bearing or sealing surface. Ssk > 0: a surface dominated by peaks or spikes standing above the bulk. Ssk ≈ 0: symmetric (a Gaussian surface).
The peakedness of the height distribution. Sku = 3 for a Gaussian surface; Sku > 3 means a spiky surface with heavy tails (sharp peaks or deep pits standing out); Sku < 3 means a bumpy, evenly-distributed, flat-topped surface.
Spatial parameters
Spatial parameters describe the lateral texture, its length scale and directionality, from the surface autocorrelation function (ACF). The ACF is computed in the app's ACF panel; both parameters use a default correlation threshold s = 0.2.
The shortest lateral distance over which the surface decorrelates (the ACF first drops to s). A small Sal means fine, quickly-varying texture; a large Sal means long-wavelength, gently-varying texture. It is the dominant lateral wavelength of the roughness.
The ratio of the shortest to the longest decay length, between 0 and 1. Str → 1: isotropic texture, the same in every direction (for example bead-blasted or electropolished surfaces). Str → 0: strongly anisotropic, lay-dominated texture (for example turned, ground or rolled surfaces). By convention Str > 0.5 is called isotropic, < 0.3 anisotropic.
Hybrid parameters
Hybrid parameters combine height and lateral information through the surface slope. Because they involve derivatives they are sensitive to short-wavelength content and to the sampling interval, so they are best compared between surfaces measured and filtered the same way.
The RMS of the local surface slope. A dimensionless (or radian) measure of how steep the texture is: relevant to sealing, adhesion, wetting, gloss and optical scattering. Two surfaces with equal Sa but different Sdq feel and behave differently: higher Sdq means sharper, steeper features.
The percentage of extra surface area contributed by the texture, relative to a perfectly flat area of the same footprint. A flat surface has Sdr = 0; Sdr = 10 % means the true surface area exceeds its projection by 10 %. It matters wherever the real contact area drives behaviour: coating adhesion, catalysis, cell attachment, heat transfer.
Functional parameters (Abbott–Firestone)
The functional parameters come from the areal material ratio curve (the Abbott–Firestone curve): for every height c, it plots the fraction of the surface that lies above c. Reading from the top down, the curve sweeps from 0 % (above the highest peak) to 100 % (below the deepest pit). Following ISO 25178-2 Annex B, a straight equivalent line is fitted to the flattest 40 %-wide window of the curve (the core). Where that line meets 0 % and 100 % material ratio defines the core band, and the regions outside it define the peaks and valleys.
The peak-to-valley height of the core (the working part of the surface), read as the vertical extent of the equivalent line. Sk is the roughness that remains once the removable peaks and valleys are set aside: it governs load-bearing behaviour and wear in the running-in state.
The mean height of the protruding peaks above the core, as the height of the equal-area triangle over area A1. These are the tips that are worn away first during running-in and that carry initial contact. Low Spk is wanted on sliding or sealing surfaces.
The mean depth of the valleys below the core, as the equal-area triangle over area A2. Deep valleys act as reservoirs and debris traps, so a controlled Svk is desirable for lubricant retention on cylinder liners and similar surfaces.
The material ratios at the upper and lower limits of the core. Smr1 is the small fraction of the area occupied by the peaks above the core; Smr2 is the material ratio at the top of the valleys (so 100 − Smr2 is the fraction taken up by valleys). They locate where peaks end and valleys begin.
The height difference between the 2.5 % and 50 % material-ratio levels, where Smc(p) is the inverse material ratio (the height at ratio p). It quantifies how far the extreme peaks rise above the median level, a peak-oriented complement to the core parameters.
Volume parameters
Volume parameters also come from the material ratio curve, but integrate it to give volumes per unit area (reported in µm³/µm² = µm). The curve is split at two material ratios, by default p = 10 % and q = 80 %, into peak, core and valley zones. The area to the left of the curve is material; the area to the right is void.
The material volume contained in the peaks (above the 10 % material-ratio height). Small and worn off early; a large Vmp signals a peaky surface that will lose material during running-in.
The material volume of the core zone, the bulk that carries the load once the peaks are worn. A stable, functionally important quantity for contact and stiffness.
The void volume of the core zone, the space available to hold and transport lubricant across the working surface.
The void volume in the deep valleys (below the 80 % material-ratio height). These reservoirs retain lubricant and trap wear debris, so a controlled Vvv is beneficial on sealing and sliding surfaces.
Feature parameters
Feature parameters do not come from a single formula; they are computed by segmenting the surface into hills and dales with a watershed algorithm, then keeping only significant features via Wolf pruning (small features whose local height is below a threshold, by default 5 % of Sz, are merged away). Statistics are then taken over the surviving peaks and pits. This makes them robust to noise but dependent on the pruning threshold.
The number of significant peaks (Spd) or pits (Svd) per unit area. High peak density means many small asperities sharing the contact load; it correlates with real contact area and, for example, friction and electrical contact behaviour.
The mean principal (local mean) curvature at the peak summits (Spc) or pit bottoms (Svc). Sharp peaks give a large Spc; rounded, blunt peaks give a small one. Sharp asperities concentrate stress and deform or wear faster under load.
S5p is the mean height of the five highest significant peaks, S5v the mean depth of the five deepest significant pits, and S10z their sum. Like Sz they characterise extreme features, but averaging five of each makes them far more robust to a single spurious spike than the single-point Sp, Sv and Sz.
Defaults follow ISO 25178-3 and surfalize: material ratios p = 10 %, q = 80 % for the volume parameters, Sxp at 2.5 % and 50 %, an ACF threshold s = 0.2 for Sal and Str, and Wolf pruning at 5 % of Sz for the feature parameters. Note that Std, Smr and Smc are not part of surfalize's batch parameter set.
Batch processing
Open File ▸ Batch… to work over many files at once. There are two modes:
- Analyze & export: replay the current workflow (its operators and selected parameters) across a set of files and export the combined parameter tables as CSV/TSV or an Excel workbook, plus per-panel images. A pinned colour range keeps the images comparable across files.
- Convert format: re-save each input file as a different output format, downloading a single file directly or several as one zip.
Export & PDF
Export a file
File ▸ Export file… saves any work-tree state (the raw file or any transformed
result) to another format, with per-format options: compression, embedded image layers,
binary/ASCII and comments. Writers are available for .sur, .sflz,
.sdf, .tmd and .al3d.
Export the view as PDF
File ▸ Export view as PDF… renders the on-screen panel grid to a multi-page A4
landscape PDF that preserves the layout. Plots are embedded as high-resolution images;
parameter tables, headers and cards stay as selectable vector text. Pages follow the app
theme.
Workflows
A workflow captures your whole session structure (the node tree, every operator and its
parameters, view settings, profiles, geometry items, volume settings and parameter
selections) as a small .surfflow.json file. The topography itself is
not included, so the file stays tiny and shareable.
Save with File ▸ Save workflow…. To restore, use File ▸ Load workflow…
and select the .surfflow.json together with the topography file(s) it
references; Surfalize reloads them and replays every step.
Layout & themes
The View menu (mirrored by the grid toolbar) controls the viewport: the number
of columns (1–4), whether the empty grid cells stay visible, and
Reset layout to return every panel to its default place. Panel sizes and
positions persist between sessions.
Switch between the Dark and Light themes from the same menu. The whole UI, including the canvas plots and this documentation page, follows the choice, which is remembered for next time.
Supported formats
Read:
Write:
Tips & FAQ
Nothing shows after I load a file
Make sure the file is a supported format and not corrupted. Errors appear in a dialog; the file's metadata (if read) is shown in the Metadata dock.
How do I compare several measurements?
Just load them one after another. Each file gets its own panels in the shared grid; increase the column count in View to see more at once, or use Batch for a table across files.
Are the parameters standard-compliant?
Every areal and profile parameter is validated against reference software to within numerical tolerance. This tool is provided without warranty; verify independently before use in safety-critical work.
Where can I learn more about the maths?
The surfalize library documentation covers the underlying algorithms and parameter definitions in detail.