matei/tono
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

adding more nodes

Browse Source
This commit is contained in:
matei jordache
2026-04-03 23:11:52 -07:00
parent 5d4c6dfcea
commit 7747c1c7bc
146 changed files with 4950 additions and 145 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
docs/nodes/Affine Correction.md Normal file
View File

@@ -0,0 +1,31 @@
# Affine Correction
Fix geometric distortions from scanner nonlinearity by applying an affine transformation. Corrects shear, anisotropic scaling, and rotation. Equivalent to Gwyddion's correct_affine.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field with geometric distortion |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| corrected | DATA_FIELD | Affine-corrected field |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| shear_x | FLOAT | 0.0 | Horizontal shear factor |
| shear_y | FLOAT | 0.0 | Vertical shear factor |
| scale_x | FLOAT | 1.0 | Horizontal scale factor |
| scale_y | FLOAT | 1.0 | Vertical scale factor |
| angle | FLOAT | 0.0 | Rotation angle in degrees |
## Notes
- An identity transform (shear=0, scale=1, angle=0) returns the original data unchanged.
- The output shape matches the input; pixels outside the transformed region are filled by nearest-edge interpolation.
- For simple rotation without scaling/shear, use the Rotate node instead.

31
docs/nodes/Deconvolution.md Normal file
View File

@@ -0,0 +1,31 @@
# Deconvolution
Restore an image via regularised deconvolution. Assumes the image was blurred by a Gaussian PSF with the given sigma. Equivalent to Gwyddion's deconvolve.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input blurred field |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| restored | DATA_FIELD | Deconvolved (sharpened) field |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| method | dropdown | wiener | Deconvolution method: wiener or richardson_lucy |
| sigma | FLOAT | 2.0 | Gaussian PSF sigma in pixels (0.1–50.0) |
| regularisation | FLOAT | 0.01 | Regularisation parameter for Wiener filter (1e-6–1.0) |
| iterations | INT | 10 | Number of iterations (Richardson-Lucy only, 1–200) |
## Notes
- **Wiener**: Fast, single-pass frequency-domain filter. The regularisation parameter controls the noise/sharpness tradeoff — smaller values sharpen more but amplify noise.
- **Richardson-Lucy**: Iterative method that preserves positivity. More iterations = sharper result but risk of ringing artifacts.
- The PSF sigma should match the actual blur in the image. If unknown, start with sigma=1–3 and adjust.
- For tip-shape deconvolution (non-Gaussian PSF), use Tip Deconvolution instead.

28
docs/nodes/Drift Correction.md Normal file
View File

@@ -0,0 +1,28 @@
# Drift Correction
Compensate for thermal or piezo drift between scan lines. Estimates inter-row displacement via cross-correlation and shifts rows to align them. Equivalent to Gwyddion's drift.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field with drift artifacts |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| corrected | DATA_FIELD | Drift-corrected field |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| reference | dropdown | previous_row | Reference for drift estimation: previous_row (local) or mean_row (global average) |
| direction | dropdown | horizontal | Drift direction to correct: horizontal or vertical |
## Notes
- Use previous_row for slow, cumulative drift. Use mean_row when drift is more random row-to-row.
- Apply after Line Correction for best results.
- Vertical direction transposes the correction axis — useful for column-scanned data.

32
docs/nodes/Extend Pad.md Normal file
View File

@@ -0,0 +1,32 @@
# Extend Pad
Add configurable borders around a DATA_FIELD using various padding methods. Useful for preparing data for FFT-based operations that suffer from edge artifacts, or for aligning fields of different sizes. Equivalent to Gwyddion's `extend.c` module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field to pad |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| padded | DATA_FIELD | Field with added borders |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| left | INT | 0 | Number of pixels to add on the left edge (0–1024) |
| right | INT | 0 | Number of pixels to add on the right edge (0–1024) |
| top | INT | 0 | Number of pixels to add on the top edge (0–1024) |
| bottom | INT | 0 | Number of pixels to add on the bottom edge (0–1024) |
| method | dropdown | mirror | Padding method: mean (fill with field mean), edge (replicate border pixels), mirror (reflect across edge), periodic (tile the field), or zero (fill with zeros) |
## Notes
- Mirror and periodic padding avoid sharp discontinuities at the border and are recommended before FFT-based filtering.
- Edge padding replicates the outermost row/column of pixels into the border region.
- Zero padding fills borders with 0.0 and can introduce step artifacts; consider mean padding as an alternative.
- The output field's physical dimensions are extended proportionally to the added pixels.

29
docs/nodes/Facet Analysis.md Normal file
View File

@@ -0,0 +1,29 @@
# Facet Analysis
Compute the facet orientation distribution of a surface. Outputs a 2D histogram (stereographic projection) where the x-axis is the azimuthal angle and y-axis is the inclination. Equivalent to Gwyddion's facet_analysis.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input surface |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| facet_map | DATA_FIELD | 2D histogram of facet orientations (phi vs theta) |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| n_bins | INT | 180 | Number of azimuthal bins; theta bins = n_bins/4 (30–720) |
| kernel_size | INT | 3 | Sobel gradient kernel size in pixels (3–9, odd) |
## Notes
- The output is a normalised probability density — it sums to 1.0.
- X-axis: azimuthal angle phi (0–360°). Y-axis: inclination theta (0° = flat, max = steepest facet).
- A flat surface produces a single bright spot near theta=0. A surface with distinct facets shows multiple peaks.
- Larger kernel_size smooths the gradient estimate, reducing noise sensitivity.

34
docs/nodes/Feature Detection.md Normal file
View File

@@ -0,0 +1,34 @@
# Feature Detection
Detect edges or corners in a surface using Canny edge detection or Harris corner detection. Outputs a feature map and a table of detected feature locations. Equivalent to Gwyddion's edge/corner detection in filters.c.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input surface |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| result | DATA_FIELD | Feature map (binary edges or corner response) |
| features | RECORD_TABLE | Table of detected feature statistics and locations |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| method | dropdown | canny | Detection method: canny (edges) or harris (corners) |
| sigma | FLOAT | 1.0 | Gaussian smoothing sigma in pixels (0.1–20.0) |
| low_threshold | FLOAT | 0.1 | Canny low hysteresis threshold (0–1) |
| high_threshold | FLOAT | 0.2 | Canny high hysteresis threshold (0–1) |
| harris_k | FLOAT | 0.05 | Harris detector sensitivity parameter (0.01–0.5) |
| min_distance | INT | 5 | Minimum distance between detected corners in pixels (1–100) |
## Notes
- **Canny**: Multi-stage edge detector with non-maximum suppression and hysteresis thresholding. Output is a binary edge map. Reports edge pixel count and edge fraction.
- **Harris**: Corner detector based on the structure tensor eigenvalues. Output is the corner response map. Reports up to 20 strongest corner locations with physical coordinates.
- Increase sigma to detect larger-scale features and suppress noise.
- For basic edge detection (Sobel, Prewitt, Laplacian), use the Edge Detect node instead.

28
docs/nodes/Flatten Base.md Normal file
View File

@@ -0,0 +1,28 @@
# Flatten Base
Level the flat base of a surface that has raised features (particles, grains). Uses a height percentile threshold to identify base pixels, fits a polynomial to those pixels, and subtracts it. Unlike plane level, this ignores tall features that would bias the fit. Equivalent to Gwyddion's flatten_base.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field with raised features on a tilted base |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| leveled | DATA_FIELD | Field with base leveled |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| threshold_percentile | FLOAT | 30.0 | Height percentile below which pixels are considered base (5–80) |
| poly_degree | INT | 2 | Polynomial degree for base fit: 0 = constant, 1 = plane, 2 = quadratic (0–5) |
## Notes
- Set the threshold percentile so that it includes most of the base but excludes the features. For sparse particles on a flat substrate, 20–40% typically works well.
- poly_degree=1 is equivalent to plane leveling on the base only. Use 2–3 for curved substrates.
- If the features dominate the surface (>50% coverage), this node may not give good results — consider Median Background instead.

29
docs/nodes/Fractal Interpolation.md Normal file
View File

@@ -0,0 +1,29 @@
# Fractal Interpolation
Fill masked regions using fractal interpolation. Matches the spectral characteristics of the surrounding surface to produce natural-looking infill that preserves texture. Better than Laplace for rough surfaces. Equivalent to Gwyddion's fraccor.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field with regions to fill |
| mask | IMAGE | Yes | Binary mask where white (255) marks pixels to interpolate |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| filled | DATA_FIELD | Field with masked regions filled by fractal interpolation |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| iterations | INT | 200 | Number of boundary relaxation iterations (10–5000) |
## Notes
- Fractal interpolation synthesizes fill data whose power spectrum matches the surrounding surface. This produces a more realistic appearance than Laplace interpolation for textured or rough surfaces.
- The fill region boundaries are smoothed via relaxation to ensure continuity.
- For very smooth surfaces, Laplace Interpolation may produce cleaner results.
- The seed for random synthesis is fixed for reproducibility.

29
docs/nodes/Frequency Split.md Normal file
View File

@@ -0,0 +1,29 @@
# Frequency Split
Separate a DATA_FIELD into low-frequency and high-frequency components using an FFT-based Gaussian filter. The low-pass output contains smooth, large-scale variations while the high-pass output contains fine detail and noise. Equivalent to Gwyddion's `freq_split.c` module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field to split |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| low_pass | DATA_FIELD | Low-frequency (smoothed) component |
| high_pass | DATA_FIELD | High-frequency (detail) component |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| cutoff | FLOAT | 0.1 | Cutoff frequency as a fraction of Nyquist (0.001–0.5) |
## Notes
- The cutoff is relative to the Nyquist frequency. A value of 0.5 effectively passes everything (no filtering), while 0.001 aggressively removes nearly all spatial frequencies from the low-pass output.
- The two outputs always sum to the original field: low_pass + high_pass = input.
- Useful for separating roughness from waviness, or for removing long-range background while preserving features.
- The filter operates in the frequency domain via FFT, so it handles periodic boundaries naturally.

33
docs/nodes/Grain Cross.md Normal file
View File

@@ -0,0 +1,33 @@
# Grain Cross
Correlate grain properties between two fields using a shared grain mask. Reports per-grain property pairs and the Pearson correlation coefficient. Equivalent to Gwyddion's grain_cross.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field_a | DATA_FIELD | Yes | First height field |
| field_b | DATA_FIELD | Yes | Second height field |
| mask | IMAGE | Yes | Binary grain mask (white = grain) |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| correlation | RECORD_TABLE | Per-grain property pairs and Pearson correlation coefficient |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| property_a | dropdown | mean_height | Property to compute from field_a: area, mean_height, max_height, or volume |
| property_b | dropdown | max_height | Property to compute from field_b: area, mean_height, max_height, or volume |
| min_size | INT | 10 | Minimum grain area in pixels; smaller grains are excluded (1–100000) |
## Notes
- Grains are identified by connected-component labelling (`scipy.ndimage.label`) on the binary mask.
- The **area** property uses physical pixel area (dx * dy). **Volume** integrates height above the mean of non-grain pixels.
- Each table row contains one grain's property pair formatted as "value_a / value_b".
- The final row reports the Pearson correlation coefficient r between the two property vectors (requires at least 2 grains).
- Both fields must have the same pixel dimensions as the mask.

31
docs/nodes/Grain Distributions.md Normal file
View File

@@ -0,0 +1,31 @@
# Grain Distributions
Compute a histogram distribution of a grain property from a labeled mask. Supported properties: area, equivalent diameter, mean height, max height, volume, and boundary length. Equivalent to Gwyddion's grain_dist.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input surface data |
| mask | IMAGE | Yes | Binary mask defining grain regions |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| distribution | LINE_DATA | Histogram of the selected grain property |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| property | dropdown | area | Grain property to plot: area, equiv_diameter, mean_height, max_height, volume, boundary_length |
| n_bins | INT | 30 | Number of histogram bins (5–200) |
| min_size | INT | 10 | Minimum grain size in pixels to include (1–100000) |
## Notes
- Volume is computed relative to the mean height of the non-grain (background) region.
- Boundary length is estimated by counting boundary pixels and multiplying by the pixel size.
- For per-grain statistics (not histograms), use Grain Analysis instead.
- For aggregate summary statistics, use Grain Summary.

29
docs/nodes/Grain Edge.md Normal file
View File

@@ -0,0 +1,29 @@
# Grain Edge
Detect grain boundaries from a binary grain mask. Outputs a mask of pixels at grain/non-grain borders using 4-neighbour connectivity. Width controls the boundary thickness in pixels. Equivalent to Gwyddion's grain_edge.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input height field (used for dimension reference) |
| mask | IMAGE | Yes | Binary grain mask (white = grain) |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| edge_mask | IMAGE | Binary mask with grain boundary pixels marked |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| width | INT | 1 | Boundary thickness in pixels; values greater than 1 dilate the edge outward (1–10) |
## Notes
- A grain pixel is on the boundary if at least one of its 4-connected neighbours (up, down, left, right) is not a grain pixel.
- When width > 1, the boundary is expanded using binary dilation with a square structuring element of size (2*width - 1).
- Dilation is masked to stay within the original grain region, so boundaries never extend into non-grain areas.
- The field and mask must have the same pixel dimensions.

33
docs/nodes/Grain Mark.md Normal file
View File

@@ -0,0 +1,33 @@
# Grain Mark
Mark grains by thresholding height, slope magnitude, or curvature. Thresholds are relative (0–1) to the data range. Small regions below min_size pixels are removed. Equivalent to Gwyddion's grain_mark.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input surface |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| mask | IMAGE | Binary mask of marked grains |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| criterion | dropdown | height | What to threshold: height, slope, or curvature |
| threshold_low | FLOAT | 0.3 | Lower bound of the normalized threshold range (0–1) |
| threshold_high | FLOAT | 1.0 | Upper bound of the normalized threshold range (0–1) |
| min_size | INT | 10 | Minimum grain size in pixels; smaller regions are removed (1–100000) |
| inverted | BOOLEAN | False | Invert the mask to mark valleys instead of peaks |
## Notes
- Thresholds are relative to the data range: 0.0 = minimum value, 1.0 = maximum value.
- "slope" uses Sobel gradient magnitude — useful for marking edges and steep features.
- "curvature" uses the Laplacian — useful for marking bumps or pits regardless of absolute height.
- Use inverted=True to mark valleys, pores, or depressions instead of raised features.
- For Otsu-based automatic thresholding, use the Threshold Mask node instead.

28
docs/nodes/Grain Summary.md Normal file
View File

@@ -0,0 +1,28 @@
# Grain Summary
Compute aggregate statistics for all grains in a mask: count, density, coverage fraction, mean/median area, total volume, and height statistics. Equivalent to Gwyddion's grain_summary.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input surface data |
| mask | IMAGE | Yes | Binary mask defining grain regions |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| summary | RECORD_TABLE | Table of aggregate grain statistics |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| min_size | INT | 10 | Minimum grain size in pixels to include (1–100000) |
## Notes
- Reported statistics: grain count, grain density (count per unit area), coverage fraction, mean area, median area, total volume, mean height, median height, max area, min area.
- Volume is computed relative to the mean height of the non-grain background.
- Use Grain Analysis for per-grain statistics, or Grain Distributions for histograms.

32
docs/nodes/Hough Transform.md Normal file
View File

@@ -0,0 +1,32 @@
# Hough Transform
Detect lines or circles in images using the Hough transform. Returns an accumulator image and a table of detected features. Equivalent to Gwyddion's hough.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field (edge-detected images work best) |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| accumulator | DATA_FIELD | Hough accumulator space |
| detections | RECORD_TABLE | Table of detected lines or circles |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| mode | dropdown | lines | Detection mode: lines or circles |
| n_peaks | INT | 3 | Number of strongest features to report (1–50) |
| threshold | FLOAT | 1.0 | Minimum accumulator value relative to peak (0.1–10.0) |
| min_radius | INT | 10 | Minimum circle radius in pixels (circles mode only) |
| max_radius | INT | 30 | Maximum circle radius in pixels (circles mode only) |
## Notes
- For line detection, apply Edge Detect first for best results. Lines are reported as (angle, distance) pairs.
- For circle detection, min/max radius constrains the search range. Circles are reported as (center_x, center_y, radius).
- The accumulator image visualises the parameter space — bright spots correspond to detected features.

30
docs/nodes/Image Stitch.md Normal file
View File

@@ -0,0 +1,30 @@
# Image Stitch
Combine two overlapping scans into a single image. Uses cross-correlation to align the images and blends the overlap region. Equivalent to Gwyddion's merge.c / stitch.c modules.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field_a | DATA_FIELD | Yes | First (reference) field |
| field_b | DATA_FIELD | Yes | Second field to stitch onto field_a |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| stitched | DATA_FIELD | Combined field |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| direction | dropdown | auto | How field_b is positioned relative to field_a: right, below, or auto (determined by cross-correlation) |
| blend | dropdown | linear | Overlap blending: linear (smooth transition) or none (hard cut) |
## Notes
- Auto direction uses cross-correlation to determine whether field_b is to the right or below field_a.
- Linear blending produces a smooth transition in the overlap region, avoiding visible seams.
- Both fields should have the same pixel size (dx, dy) for correct physical dimensions in the output.
- The output field's physical dimensions are updated to reflect the combined area.

29
docs/nodes/Immerse Detail.md Normal file
View File

@@ -0,0 +1,29 @@
# Immerse Detail
Overlay a high-resolution detail scan onto a lower-resolution overview image. Uses sliding-window cross-correlation (coarse + fine search) to automatically locate the detail within the overview. Equivalent to Gwyddion's immerse.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| overview | DATA_FIELD | Yes | Lower-resolution overview field |
| detail | DATA_FIELD | Yes | Higher-resolution detail field to place into the overview |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| combined | DATA_FIELD | Overview field with the detail region replaced or blended in |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| blend | dropdown | replace | How to combine the detail with the overview: replace (overwrite) or average (mean of both) |
## Notes
- If the detail has a different pixel size than the overview, it is resampled (via `scipy.ndimage.zoom`) to match the overview pixel spacing before placement.
- Alignment uses a two-pass normalized cross-correlation: a coarse search with stride, followed by a fine pixel-by-pixel search around the best coarse position.
- If the detail is larger than the overview in either dimension, the overview is returned unchanged.
- The output retains the overview's physical dimensions and metadata.

15
docs/nodes/Journal.md Normal file
View File

@@ -0,0 +1,15 @@
# Journal
A rich-text note for recording experimental observations, analysis notes, or workflow documentation. Content is saved as part of the workflow.
## Outputs
| Name | Type | Description |
|------|------|-------------|
| text | STRING | The journal text content |
## Notes
- The Journal node provides a text area for free-form notes within your workflow.
- Content persists when the workflow is saved and loaded.
- Use it to document sample preparation details, measurement parameters, or analysis decisions alongside your processing pipeline.

29
docs/nodes/Laplace Interpolation.md Normal file
View File

@@ -0,0 +1,29 @@
# Laplace Interpolation
Fill masked (missing) regions by solving the Laplace equation with Dirichlet boundary conditions from surrounding pixels. Produces a smooth, harmonic interpolation without overshooting. Equivalent to Gwyddion's laplace.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field with regions to fill |
| mask | IMAGE | Yes | Binary mask where white (255) marks pixels to interpolate |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| filled | DATA_FIELD | Field with masked regions filled by Laplace interpolation |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| iterations | INT | 500 | Number of Jacobi relaxation iterations; more iterations = smoother result (10–10000) |
## Notes
- Laplace interpolation produces the smoothest possible fill — it minimizes the integral of the squared gradient within the masked region.
- For small holes (<50 px diameter), 200–500 iterations is usually sufficient. Larger holes may need 1000+.
- Use a Draw Mask or Threshold Mask node to create the mask input.
- For surfaces with texture, consider Fractal Interpolation instead, which preserves surface roughness characteristics.

29
docs/nodes/Lattice Measurement.md Normal file
View File

@@ -0,0 +1,29 @@
# Lattice Measurement
Detect and measure periodic lattice structures from ACF or FFT peak positions. Reports lattice vectors and angles. Equivalent to Gwyddion's measure_lattice.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field with periodic structure |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| correlation | DATA_FIELD | ACF or FFT magnitude used for detection |
| measurements | RECORD_TABLE | Detected lattice vectors, spacings, and angle |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| method | dropdown | acf | Detection method: acf (autocorrelation) or fft (Fourier transform) |
## Notes
- ACF method finds the strongest off-center peaks in the 2D autocorrelation. Works well for real-space periodic structures.
- FFT method finds peaks in the power spectrum. Better for weak periodicity or noisy data.
- Reports up to two lattice vectors (a, b), their magnitudes, and the angle between them.
- For best results, the field should contain at least 3–4 complete periods in each direction.

29
docs/nodes/Level Grains.md Normal file
View File

@@ -0,0 +1,29 @@
# Level Grains
Shift individual grain regions so they all share a common baseline. Uses the selected reference statistic (mean, median, or minimum) per grain to compute the offset. Useful for consistent grain height comparisons. Equivalent to Gwyddion's level_grains.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input surface data |
| mask | IMAGE | Yes | Binary mask defining grain regions |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| leveled | DATA_FIELD | Field with grains shifted to a common baseline |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| reference | dropdown | mean | Per-grain reference: mean, median, or minimum height |
## Notes
- Each connected region in the mask is treated as a separate grain.
- The target baseline is the average of all per-grain reference values.
- Use "minimum" reference when grains sit on different substrate heights and you want to align their bases.
- Combine with Grain Analysis to verify height distributions after leveling.

30
docs/nodes/Log-Polar PSDF.md Normal file
View File

@@ -0,0 +1,30 @@
# Log-Polar PSDF
Compute the power spectral density function in log-polar coordinates. The x-axis is the azimuthal angle (0-360 degrees) and the y-axis is log(frequency). Better than Cartesian PSDF for anisotropy analysis. Equivalent to Gwyddion's psdf_logphi.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input spatial-domain field |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| psdf | DATA_FIELD | Power spectral density in log-polar coordinates (domain=frequency) |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| n_phi | INT | 180 | Number of azimuthal angle bins (36–720) |
| n_r | INT | 100 | Number of radial (log-frequency) bins (20–500) |
## Notes
- The mean value is subtracted before computing the 2D FFT, and the power spectrum is shifted so DC is at the centre.
- Bilinear interpolation is used when sampling the Cartesian power spectrum onto the log-polar grid.
- The output is log-scaled via `log1p` for better visual contrast.
- Output xreal is 360.0 (degrees) and yreal is log(r_max) where r_max is half the shorter image dimension.
- Anisotropic surfaces produce bright bands at specific azimuthal angles; isotropic surfaces appear uniform along the angle axis.

30
docs/nodes/MFM Analysis.md Normal file
View File

@@ -0,0 +1,30 @@
# MFM Analysis
Magnetic Force Microscopy analysis: convert between MFM phase/force gradient and magnetic field quantities using Fourier-domain transfer functions. Equivalent to Gwyddion's mfm_*.c modules.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input MFM data (phase, force gradient, or field) |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| result | DATA_FIELD | Converted MFM quantity |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| operation | dropdown | phase_to_force_gradient | Conversion: phase_to_force_gradient, force_gradient_to_field, charge_density, magnetisation |
| lift_height | FLOAT | 50e-9 | Tip-sample separation in metres |
## Notes
- **phase_to_force_gradient**: Convert MFM phase shift to force gradient using the cantilever spring constant relationship.
- **force_gradient_to_field**: Recover the magnetic field from force gradient data via Fourier-domain deconvolution. Output unit: A/m.
- **charge_density**: Compute effective magnetic charge density. Output unit: A/m².
- **magnetisation**: Recover magnetisation from field data.
- All operations use the lift height to set the correct spatial frequency transfer function.

29
docs/nodes/Median Background.md Normal file
View File

@@ -0,0 +1,29 @@
# Median Background
Extract background using a local median filter and subtract it. The radius controls the filter window — larger values capture broader background variations. More robust than polynomial leveling for surfaces with sparse tall features. Equivalent to Gwyddion's median-bg.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| result | DATA_FIELD | Background-subtracted field or extracted background |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| radius | INT | 20 | Half-size of the median filter window in pixels; the full window is (2×radius+1)² (2–500) |
| output | dropdown | subtracted | Output mode: subtracted (original minus background) or background (extracted background) |
## Notes
- The median filter is robust to outliers — tall features (particles, grains) do not bias the background estimate.
- Choose a radius larger than your largest feature but smaller than the background curvature scale.
- For polynomial background removal, use Plane Level or Polynomial Level instead.
- Processing time increases with radius; for very large fields, consider downsampling first.

31
docs/nodes/Multiple Profiles.md Normal file
View File

@@ -0,0 +1,31 @@
# Multiple Profiles
Extract and compare line profiles from two fields along a chosen row or column. Supports overlay, mean, and difference modes. Equivalent to Gwyddion's multiprofile.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field_a | DATA_FIELD | Yes | First input field |
| field_b | DATA_FIELD | Yes | Second input field |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| profile | LINE_DATA | Resulting line profile |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| row | INT | -1 | Row (horizontal) or column (vertical) index to extract; -1 uses the centre row/column (-1–10000) |
| direction | dropdown | horizontal | Profile direction: horizontal (extract a row) or vertical (extract a column) |
| mode | dropdown | overlay | Combination mode: overlay (field_a profile only), mean (average of both), or difference (field_a minus field_b) |
## Notes
- When the two fields have different sizes, profiles are truncated to the shorter length so they can be compared element-wise.
- The x-axis of the output profile uses physical spacing (dx for horizontal, dy for vertical) from field_a.
- The output y-unit inherits field_a's z-unit.
- Difference mode is useful for visualising drift, processing artefacts, or changes between sequential scans.

28
docs/nodes/Mutual Crop.md Normal file
View File

@@ -0,0 +1,28 @@
# Mutual Crop
Align two images using FFT cross-correlation and crop both to their overlapping region. Useful for comparing images acquired at different times or with slight position offsets. Equivalent to Gwyddion's mcrop.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field_a | DATA_FIELD | Yes | First input field |
| field_b | DATA_FIELD | Yes | Second input field |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| cropped_a | DATA_FIELD | Field A cropped to the overlapping region |
| cropped_b | DATA_FIELD | Field B cropped to the overlapping region |
## Controls
This node has no user-adjustable controls. Alignment is fully automatic.
## Notes
- Both fields are zero-padded to a common shape, mean-subtracted, and cross-correlated in the frequency domain to find the optimal shift.
- The overlap region is computed from the detected shift; both output fields are cropped to identical pixel dimensions.
- If no valid overlap is found (e.g. completely non-overlapping images), the original fields are returned unchanged.
- Physical dimensions (xreal, yreal) of the outputs are updated to reflect the cropped size using field_a's pixel spacing.

29
docs/nodes/Outlier Mask.md Normal file
View File

@@ -0,0 +1,29 @@
# Outlier Mask
Create a mask marking pixels that deviate more than N standard deviations from the mean. Quick way to identify noise spikes and defects. Equivalent to Gwyddion's outliers.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input surface |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| mask | IMAGE | Binary mask of outlier pixels |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| sigma_threshold | FLOAT | 3.0 | Number of standard deviations beyond which a pixel is an outlier (1.0–10.0) |
| mode | dropdown | both | Which outliers to flag: both (high and low), high only, or low only |
## Notes
- A pixel is flagged if its z-score (data - mean) / std exceeds the threshold.
- 3σ catches ~0.3% of pixels in a Gaussian distribution. Use 2σ for aggressive filtering or 5σ for conservative.
- The resulting mask can be fed to Laplace Interpolation or Fractal Interpolation to fill the defects.
- For a uniform (constant) field, no pixels are flagged regardless of threshold.

35
docs/nodes/Perspective Correction.md Normal file
View File

@@ -0,0 +1,35 @@
# Perspective Correction
Fix perspective distortion in a DATA_FIELD via a projective (homography) transform. Each corner can be shifted by a fractional offset to map a distorted quadrilateral back to a rectangle. Equivalent to Gwyddion's `correct_perspective.c` module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field with perspective distortion |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| corrected | DATA_FIELD | Perspective-corrected field |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| top_left_x | FLOAT | 0.0 | Horizontal offset of the top-left corner as a fraction of image width (-0.5–0.5) |
| top_left_y | FLOAT | 0.0 | Vertical offset of the top-left corner as a fraction of image height (-0.5–0.5) |
| top_right_x | FLOAT | 0.0 | Horizontal offset of the top-right corner as a fraction of image width (-0.5–0.5) |
| top_right_y | FLOAT | 0.0 | Vertical offset of the top-right corner as a fraction of image height (-0.5–0.5) |
| bottom_left_x | FLOAT | 0.0 | Horizontal offset of the bottom-left corner as a fraction of image width (-0.5–0.5) |
| bottom_left_y | FLOAT | 0.0 | Vertical offset of the bottom-left corner as a fraction of image height (-0.5–0.5) |
| bottom_right_x | FLOAT | 0.0 | Horizontal offset of the bottom-right corner as a fraction of image width (-0.5–0.5) |
| bottom_right_y | FLOAT | 0.0 | Vertical offset of the bottom-right corner as a fraction of image height (-0.5–0.5) |
## Notes
- All offsets are given as fractions of the image dimensions (0.0 = no shift, 0.1 = 10% shift). Positive x shifts right, positive y shifts down.
- The transform uses bilinear interpolation to resample pixel values at non-integer locations.
- For trapezoidal distortions (common in tilted AFM scans), typically only two corners need adjustment.
- Set all offsets to 0.0 to pass the field through unchanged.

29
docs/nodes/Pixel Binning.md Normal file
View File

@@ -0,0 +1,29 @@
# Pixel Binning
Downsample a DATA_FIELD by grouping pixels into NxN blocks and reducing each block to a single value. Supports mean, sum, and median reduction methods. Equivalent to Gwyddion's `binning.c` module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field to downsample |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| binned | DATA_FIELD | Downsampled field |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| bin_size | INT | 2 | Side length of the square binning block in pixels (2–64) |
| method | dropdown | mean | Reduction method per block: mean (average), sum (total), or median (middle value) |
## Notes
- Pixels at the right and bottom edges that do not fill a complete block are trimmed and discarded.
- The output dimensions are floor(width / bin_size) x floor(height / bin_size).
- Mean binning improves signal-to-noise ratio by a factor of bin_size. Sum binning preserves total signal (useful for count data). Median binning is robust to outlier pixels within each block.
- Physical dimensions (real-space size) of the output field are updated to reflect the trimmed area.

33
docs/nodes/Polynomial Distortion.md Normal file
View File

@@ -0,0 +1,33 @@
# Polynomial Distortion
Correct nonlinear scanner distortions by applying polynomial coordinate warping independently in the x and y directions. Each axis has three polynomial coefficients controlling linear, quadratic, and cubic distortion terms. Equivalent to Gwyddion's `polydistort.c` module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field with scanner distortion |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| corrected | DATA_FIELD | Distortion-corrected field |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| k1_x | FLOAT | 0.0 | Linear distortion coefficient for the x axis (-1.0–1.0) |
| k2_x | FLOAT | 0.0 | Quadratic distortion coefficient for the x axis (-1.0–1.0) |
| k3_x | FLOAT | 0.0 | Cubic distortion coefficient for the x axis (-1.0–1.0) |
| k1_y | FLOAT | 0.0 | Linear distortion coefficient for the y axis (-1.0–1.0) |
| k2_y | FLOAT | 0.0 | Quadratic distortion coefficient for the y axis (-1.0–1.0) |
| k3_y | FLOAT | 0.0 | Cubic distortion coefficient for the y axis (-1.0–1.0) |
## Notes
- k1 controls linear stretching/compression, k2 controls barrel/pincushion-like quadratic distortion, and k3 controls cubic (S-shaped) distortion.
- Coefficients for x and y are independent, allowing correction of anisotropic scanner nonlinearities.
- Small values (0.01–0.1) are typical for real scanner corrections; large values produce extreme warping.
- Set all coefficients to 0.0 to pass the field through unchanged.

31
docs/nodes/Rank Filter.md Normal file
View File

@@ -0,0 +1,31 @@
# Rank Filter
Apply a general rank-order (morphological) filter to a DATA_FIELD. Selects the k-th smallest value within a local window, encompassing erosion, dilation, median, and arbitrary percentile operations. Equivalent to Gwyddion's `rank-filter.c` module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field to filter |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| filtered | DATA_FIELD | Rank-filtered field |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| radius | INT | 3 | Radius of the circular filter window in pixels (1–50) |
| operation | dropdown | median | Filter operation: erosion (local minimum), dilation (local maximum), median (50th percentile), or percentile (custom rank) |
| percentile | FLOAT | 50.0 | Custom percentile rank, used only when operation is percentile (0.0–100.0) |
## Notes
- Erosion (local min) shrinks bright features and expands dark ones. Dilation (local max) does the opposite.
- Median is equivalent to percentile = 50 and provides edge-preserving smoothing.
- The percentile parameter is ignored unless operation is set to percentile. A percentile of 0 is equivalent to erosion, and 100 is equivalent to dilation.
- The filter uses a circular (disc-shaped) kernel; the actual window diameter is 2*radius + 1 pixels.
- Combining erosion followed by dilation (opening) or dilation followed by erosion (closing) can be achieved by chaining two Rank Filter nodes.

34
docs/nodes/Relate Fields.md Normal file
View File

@@ -0,0 +1,34 @@
# Relate Fields
Fit a functional relationship between two data fields: b = f(a). Outputs the predicted field_b from the fit and a table of fitted parameters with R-squared goodness-of-fit. Equivalent to Gwyddion's relate.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field_a | DATA_FIELD | Yes | Independent variable field |
| field_b | DATA_FIELD | Yes | Dependent variable field |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| predicted | DATA_FIELD | Predicted field_b values from the fitted function |
| fit_params | RECORD_TABLE | Fitted coefficients and R-squared statistic |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| function | dropdown | linear | Functional form to fit: linear, quadratic, cubic, power, or logarithmic |
## Notes
- **Linear**: b = slope * a + intercept. Reports slope and intercept.
- **Quadratic**: b = a2*a^2 + a1*a + a0. Reports a2, a1, a0.
- **Cubic**: b = a3*a^3 + a2*a^2 + a1*a + a0. Reports a3, a2, a1, a0.
- **Power**: b = c * a^n (fitted via log-log regression). Reports exponent and coefficient. Requires positive values in both fields.
- **Logarithmic**: b = log_coeff * log(a) + intercept. Requires positive values in field_a.
- R-squared is always reported as the last row: values near 1.0 indicate a good fit.
- Both fields are flattened and truncated to the shorter length when they differ in total pixel count.
- The predicted output retains field_b's shape and metadata.

28
docs/nodes/Scan Line Reorder.md Normal file
View File

@@ -0,0 +1,28 @@
# Scan Line Reorder
Fix scan line ordering artifacts from meander (serpentine) scanning, interlacing, or inverted scan direction. Equivalent to Gwyddion's reorder.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field with scan line artifacts |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| result | DATA_FIELD | Field with corrected scan line order |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| operation | dropdown | reverse_odd | Operation: reverse_odd, reverse_even, deinterlace_odd, deinterlace_even, flip_vertical |
## Notes
- **reverse_odd / reverse_even**: Reverse alternate rows to correct meander (serpentine/boustrophedon) scanning. Most SPM controllers scan left-to-right on odd lines and right-to-left on even lines; reversing odd rows fixes this.
- **deinterlace_odd / deinterlace_even**: Keep only odd or even rows and stretch to fill the original height. Useful when alternate scan lines were acquired under different conditions.
- **flip_vertical**: Reverse the row order (top becomes bottom). Useful when the scan direction is inverted.
- Apply this node before Line Correction for best results.

30
docs/nodes/Shade.md Normal file
View File

@@ -0,0 +1,30 @@
# Shade
Render a DATA_FIELD as a directional hillshade image using Lambertian reflectance. Surface normals are estimated from Sobel gradients, and shading intensity is computed from the dot product with a configurable light direction. Equivalent to Gwyddion's `shade.c` module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input surface field to shade |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| shaded | DATA_FIELD | Shaded surface rendering |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| azimuth | FLOAT | 0.0 | Light direction in degrees: 0 = north, 90 = east, 180 = south, 270 = west (0–360) |
| elevation | FLOAT | 45.0 | Light elevation angle above the horizon in degrees (0–90) |
| blend | FLOAT | 0.5 | Blend factor between original data and shading: 0.0 = original data only, 1.0 = shading only (0.0–1.0) |
## Notes
- Surface normals are computed using Sobel gradient operators, providing good noise resilience compared to simple finite differences.
- An azimuth of 315° (northwest illumination) is a common choice that produces natural-looking topographic shading.
- Elevation of 90° gives flat, uniform lighting; lower angles emphasize surface texture and fine features.
- The blend parameter controls how much shading modulates the original height data. Use 0.5 for a balanced view, or 1.0 for pure shaded relief.

30
docs/nodes/Shape Fitting.md Normal file
View File

@@ -0,0 +1,30 @@
# Shape Fitting
Fit a geometric primitive (sphere, paraboloid, or cylinder) to the surface data. Outputs either the fitted surface or the residual. Reports fitted parameters including radius of curvature, centre position, etc. Equivalent to Gwyddion's fit-shape.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input surface |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| result | DATA_FIELD | Fitted surface or residual (original minus fit) |
| parameters | RECORD_TABLE | Fitted parameters and RMS residual |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| shape | dropdown | sphere | Geometric primitive: sphere, paraboloid, or cylinder |
| output | dropdown | residual | Output mode: residual (deviations from fit) or fitted (the fit itself) |
## Notes
- **Sphere**: Fits z = z0 - sqrt(R² - (x-cx)² - (y-cy)²). Reports centre (cx, cy), apex height (z0), and radius R.
- **Paraboloid**: Fits z = z0 + a(x-cx)² + b(y-cy)². Reports centre, apex, and curvature coefficients a, b.
- **Cylinder**: Fits a parabolic profile along one axis. Reports radius, curvature, and cylinder orientation angle.
- The residual output is useful for evaluating fit quality — a good fit produces small, random residuals.

32
docs/nodes/Straighten Path.md Normal file
View File

@@ -0,0 +1,32 @@
# Straighten Path
Extract a cross-section along an arbitrary curved path defined by control points. The path is interpolated between points and data is sampled along it using `scipy.ndimage.map_coordinates`. Equivalent to Gwyddion's straighten_path.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input height field |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| straightened | DATA_FIELD | Straightened cross-section; width = n_samples, height = thickness |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| points_x | STRING | "0.25, 0.5, 0.75" | Comma-separated fractional x-coordinates of control points (0.0–1.0) |
| points_y | STRING | "0.5, 0.3, 0.5" | Comma-separated fractional y-coordinates of control points (0.0–1.0) |
| thickness | INT | 1 | Width of the sampled strip perpendicular to the path, in pixels (1–100) |
| n_samples | INT | 256 | Number of sample points along the path (10–2048) |
## Notes
- Control points are specified as fractions of the image dimensions (0 = left/top edge, 1 = right/bottom edge). At least 2 points are required.
- Points are connected by linear interpolation; the path is sampled at n_samples evenly spaced positions.
- When thickness > 1, samples are taken along the local normal direction at each path position, producing a 2D strip rather than a single line.
- The output xreal equals the physical path length (computed from pixel spacing), and yreal equals thickness times the pixel size.
- Bilinear interpolation (order=1) is used with nearest-edge boundary handling.

37
docs/nodes/Synthetic Surface.md Normal file
View File

@@ -0,0 +1,37 @@
# Synthetic Surface
Generate synthetic test surfaces for development, calibration, and algorithm testing. Equivalent to Gwyddion's *_synth.c modules.
## Outputs
| Name | Type | Description |
|------|------|-------------|
| surface | DATA_FIELD | Generated synthetic surface |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| pattern | dropdown | fbm | Pattern type: fbm, white_noise, lattice, steps, particles, flat |
| xres | INT | 256 | Horizontal resolution in pixels (16–2048) |
| yres | INT | 256 | Vertical resolution in pixels (16–2048) |
| xreal | FLOAT | 1e-6 | Physical width in metres |
| yreal | FLOAT | 1e-6 | Physical height in metres |
| amplitude | FLOAT | 1e-9 | Peak-to-peak amplitude in metres |
| seed | INT | 42 | Random seed for reproducibility (0–999999) |
| hurst_exponent | FLOAT | 0.7 | FBM roughness exponent: 0 = rough, 1 = smooth (fbm only) |
| lattice_spacing | FLOAT | 100e-9 | Lattice period in metres (lattice only) |
| lattice_angle | FLOAT | 90.0 | Angle between lattice vectors in degrees (lattice only) |
| n_steps | INT | 5 | Number of step terraces (steps only) |
| n_particles | INT | 20 | Number of particles (particles only) |
| particle_radius_px | INT | 10 | Particle radius in pixels (particles only) |
## Notes
- **fbm**: Fractional Brownian motion via spectral synthesis. Hurst exponent controls roughness.
- **white_noise**: Gaussian random noise.
- **lattice**: Two-axis sinusoidal grid with configurable spacing and angle.
- **steps**: Terraced step structure with equal step heights.
- **particles**: Random spherical particles on a flat background.
- **flat**: Zero surface (useful as a baseline).
- All patterns are normalised to the specified amplitude range.

31
docs/nodes/Terrace Fit.md Normal file
View File

@@ -0,0 +1,31 @@
# Terrace Fit
Segment a surface into flat terraces separated by atomic steps, fit a polynomial to each terrace, and extract step heights. Set n_terraces=0 for automatic detection via histogram clustering. Equivalent to Gwyddion's terracefit.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input surface with step/terrace features |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| result | DATA_FIELD | Residual, fitted surface, or label map |
| step_heights | RECORD_TABLE | Per-terrace heights and step height differences |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| n_terraces | INT | 0 | Number of terraces to fit; 0 = auto-detect from histogram peaks (0–50) |
| broadening | FLOAT | 1.0 | Smoothing factor for terrace detection; larger values merge noisy pixels (0.1–20.0) |
| poly_degree | INT | 0 | Polynomial degree per terrace: 0 = constant (flat), 1 = linear, 2 = quadratic, 3 = cubic (0–3) |
| output | dropdown | residual | Output mode: residual (original minus fit), fitted (fit surface), or labels (terrace assignment map) |
## Notes
- Use poly_degree=0 for ideal crystalline surfaces with perfectly flat terraces. Higher degrees compensate for sample curvature within each terrace.
- Auto-detection works best when terraces are well-separated in height. For noisy surfaces, increase broadening to improve terrace segmentation.
- The labels output assigns integer IDs (0, 1, 2, ...) to each terrace, ordered by height.

30
docs/nodes/Tilt.md Normal file
View File

@@ -0,0 +1,30 @@
# Tilt
Apply or remove a linear tilt (planar slope) from a DATA_FIELD. The tilt is defined by slope values in data units per physical unit along the x and y directions. Equivalent to Gwyddion's `tilt.c` module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| tilted | DATA_FIELD | Field with tilt applied or removed |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| slope_x | FLOAT | 0.0 | Slope along the x axis in data units per physical unit (e.g. nm/um) |
| slope_y | FLOAT | 0.0 | Slope along the y axis in data units per physical unit (e.g. nm/um) |
| mode | dropdown | subtract | Operation mode: subtract (remove tilt) or add (apply tilt) |
## Notes
- In subtract mode the specified planar slope is removed from the field, useful for compensating known sample tilt.
- In add mode the slope is added, useful for simulating a tilted surface or restoring a previously subtracted tilt.
- The slope values are in data-unit per physical-unit (e.g. nm/um). The actual z-change per pixel depends on the field's physical pixel size.
- For leveling an unknown tilt, consider Plane Level instead, which automatically fits and removes the best-fit plane.

29
docs/nodes/Trimmed Mean.md Normal file
View File

@@ -0,0 +1,29 @@
# Trimmed Mean
Apply a local trimmed-mean filter to a DATA_FIELD. Within each circular window, the lowest and highest fraction of pixel values are excluded before computing the mean. This provides smoothing that is more robust to outliers than a plain Gaussian or mean filter. Equivalent to Gwyddion's `trimmed-mean.c` module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field to filter |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| filtered | DATA_FIELD | Trimmed-mean filtered field |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| radius | INT | 3 | Radius of the circular filter window in pixels (1–50) |
| trim_fraction | FLOAT | 0.1 | Fraction of values to exclude from each end of the sorted window (0.0–0.49) |
## Notes
- A trim_fraction of 0.0 gives a plain local mean (no trimming). A trim_fraction approaching 0.5 converges to the local median.
- Typical values of 0.05–0.2 effectively suppress outlier spikes while preserving smooth features better than a median filter.
- The filter uses a circular (disc-shaped) kernel; the actual window diameter is 2*radius + 1 pixels.
- More computationally expensive than a Gaussian filter due to the sorting step within each window.

30
docs/nodes/Wrap Value.md Normal file
View File

@@ -0,0 +1,30 @@
# Wrap Value
Rewrap periodic values in a DATA_FIELD to a specified angular or custom range. Commonly used for phase images where values should lie within a well-defined interval. Equivalent to Gwyddion's `wrapvalue.c` module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input field with periodic values to wrap |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| wrapped | DATA_FIELD | Field with values wrapped to the target range |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| preset | dropdown | 0-360 | Wrapping range preset: 0-360 (degrees), pm180 (±180°), 0-2pi (radians), pm_pi (±π), or custom |
| custom_min | FLOAT | 0.0 | Lower bound of the wrapping range (used only when preset is custom) |
| custom_max | FLOAT | 360.0 | Upper bound of the wrapping range (used only when preset is custom) |
## Notes
- Preset ranges: 0-360 wraps to [0, 360], pm180 wraps to [-180, 180], 0-2pi wraps to [0, 2π], pm_pi wraps to [-π, π].
- custom_min and custom_max are ignored unless preset is set to custom.
- This node applies modular arithmetic so that all output values fall within the chosen interval. It does not scale or rescale values.
- Particularly useful for MFM phase channels, Kelvin probe contact potential images, and interferometric phase maps.

29
docs/nodes/Zero Crossing.md Normal file
View File

@@ -0,0 +1,29 @@
# Zero Crossing
Detect edges by finding zero crossings of the Laplacian of Gaussian (LoG). Sigma controls the Gaussian smoothing scale. Threshold filters out weak edges relative to the LoG range. Equivalent to Gwyddion's zero_crossing.c module.
## Inputs
| Name | Type | Required | Description |
|------|------|----------|-------------|
| field | DATA_FIELD | Yes | Input height field |
## Outputs
| Name | Type | Description |
|------|------|-------------|
| edges | DATA_FIELD | Binary edge map (1.0 at edges, 0.0 elsewhere) |
## Controls
| Name | Type | Default | Description |
|------|------|---------|-------------|
| sigma | FLOAT | 2.0 | Gaussian smoothing scale for the LoG operator (0.5–20.0) |
| threshold | FLOAT | 0.0 | Minimum edge strength as a fraction of the maximum LoG contrast; filters weak edges (0.0–1.0) |
## Notes
- The algorithm computes the Laplacian of Gaussian (via `scipy.ndimage.gaussian_laplace`), then marks pixels where adjacent values change sign (horizontal and vertical neighbours).
- Larger sigma values detect coarser features and suppress noise; smaller values pick up finer detail but are noisier.
- Threshold = 0.0 keeps all zero crossings. Increasing it towards 1.0 retains only the strongest edges.
- The output z-unit is cleared (dimensionless binary mask).