low pri features

docs/nodes/Distribution Coercion.md

@@ -0,0 +1,31 @@
+# Distribution Coercion
+
+Transform pixel values so their distribution matches a target shape (uniform, Gaussian, or discrete levels) using rank-based reassignment. Equivalent to Gwyddion's coerce.c module.
+
+## Inputs
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| field | DATA_FIELD | Yes | Input field whose value distribution will be transformed |
+
+## Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| result | DATA_FIELD | Field with pixel values reassigned to match the target distribution |
+
+## Controls
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| distribution | dropdown | uniform | Target distribution shape: uniform, gaussian, or levels |
+| n_levels | INT | 4 | Number of discrete output levels (2–1000); visible only for levels mode |
+| processing | dropdown | field | Processing scope: field (entire array at once) or rows (line-by-line) |
+
+## Notes
+
+- The transformation is rank-based: pixels are sorted, then reassigned values drawn from the target distribution in sorted order. This preserves the relative ordering of all pixel values.
+- Uniform mode spreads values evenly between the original minimum and maximum.
+- Gaussian mode maps ranks to the inverse normal CDF, scaled to match the original mean and standard deviation.
+- Levels mode quantizes the data into a fixed number of evenly spaced discrete values, useful for terrace-like visualization or discrete height analysis.
+- Row mode applies the transformation independently to each scan line, which can correct line-to-line distribution variations in SPM data.