mirror of
https://github.com/storytold/materialcraft.git
synced 2026-11-19 14:01:02 +01:00
Selecting a Levels node now shows a visual editor above its sliders: a histogram of the node's input (256 bins; red, green and blue overlaid for a color input; scaled to the tallest bin between pure black and white) with the clipped ranges shaded and the levels transfer curve on top, draggable input low/mid/high handles under it and output low/high handles under a black-to-white bar. Fixes in how Levels is edited: Level in mid is relative to the input range, and its handle now sits where it acts and moves with the range; the input low and high handles cannot cross. Parameters bound to inputs or driven by functions keep their handles locked. Every drag is a graph.node.param command, one undo step per handle. levels_fn no longer propagates NaN. Tests cover the histogram, the handle constraints and the remap math; the snapshots UI test renders the editor. Documented in docs/levels-editor.md. Clean-room implementation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
77 lines
4.3 KiB
Markdown
77 lines
4.3 KiB
Markdown
# The Levels editor
|
||
|
||
The **Levels** node remaps its input: it stretches the input range (*Level in low* to *Level in
|
||
high*), bends the midtones (*Level in mid*) and squeezes the result into the output range (*Level
|
||
out low* to *Level out high*). Select a Levels node and the **Specific parameters** section of the
|
||
properties panel shows a visual editor above the usual sliders. This is a clean-room
|
||
implementation.
|
||
|
||
<p align="center">
|
||
<img src="images/materialcraft-levels-editor.png" alt="The stone tiles material with a Levels node selected: in the properties panel, a histogram of the node's input with the levels curve over it, three input handles under it and two output handles under a black-to-white bar" width="100%">
|
||
<br><sub>The Levels editor: the input histogram, the transfer curve and the handles</sub>
|
||
</p>
|
||
|
||
## What it shows
|
||
|
||
- **The input histogram**: how many pixels of the image feeding the node have each value, in
|
||
256 bins over 0..1. A grayscale input shows one gray histogram; a color input shows red, green
|
||
and blue on top of each other. Values outside 0..1 count in the end bins. The bar heights scale
|
||
to the tallest bin *between* pure black and pure white, because masks pile up at the ends and
|
||
would flatten everything else. Without an input wire the editor says so.
|
||
- **The clipped areas**: the parts of the histogram outside the input range are darkened. Those
|
||
values all become the output low or high.
|
||
- **The transfer curve** (accent line): the output value for every input value, so the effect
|
||
of all five parameters can be read at a glance.
|
||
|
||
The histogram is computed once per cooked result of the input and reused until that result
|
||
changes.
|
||
|
||
## Handles
|
||
|
||
| Handle | Row | Parameter | Behavior |
|
||
|---|---|---|---|
|
||
| Black triangle | under the histogram | *Level in low* | Cannot pass the high handle |
|
||
| Gray triangle | under the histogram | *Level in mid* | Sits where the midtone acts: `in low + in mid × (in high − in low)`. It moves with the low and high handles and stays strictly inside the range (stored as 0.01..0.99) |
|
||
| White triangle | under the histogram | *Level in high* | Cannot pass the low handle |
|
||
| Black triangle | under the gradient bar | *Level out low* | Free |
|
||
| White triangle | under the gradient bar | *Level out high* | Free; dragging it left of the low handle inverts the output |
|
||
|
||
- Hovering a handle highlights it and shows its parameter and value.
|
||
- Dragging a handle sets its parameter live. One drag is one undo step.
|
||
- A parameter bound to a graph input or driven by a function shows its handle but cannot be
|
||
dragged; edit it where it is driven.
|
||
- The sliders below still give exact values and the right-click menu (reset, expose, bind,
|
||
function).
|
||
|
||
## What changed in the node
|
||
|
||
- *Level in mid* was always relative to the input range (0.5 = linear), but the only editor was
|
||
an absolute 0..1 slider, so its position meant nothing next to *Level in low* and *Level in
|
||
high*. The gray handle now shows where it really acts.
|
||
- Dragging the input low handle past the high one used to flip the remap without warning. The
|
||
editor keeps them apart. The sliders and commands still accept any values, so existing files
|
||
cook exactly as before.
|
||
- `levels_fn` no longer lets a NaN (from an input or a hostile parameter) spread through the
|
||
graph: it is treated as 0.
|
||
|
||
## For agents and scripts
|
||
|
||
The editor only sets the node's existing parameters, so there is nothing new to drive:
|
||
|
||
```json
|
||
{"id": 1, "method": "command.run", "params": {"id": "graph.node.param", "params": {"id": 42, "param": "in_mid", "value": 0.35}}}
|
||
```
|
||
|
||
`session.inspect` reports the parameters and the input's cooked `mean`; the 2D view's histogram
|
||
(`view.2d {"histogram": true}`) shows the node's output.
|
||
|
||
## Implementation and tests
|
||
|
||
- `crates/ui-egui/src/levels_editor.rs`: `histogram`, `values`, `mid_position`, `drag_value`
|
||
(the handle constraints) and the drawing; called from `properties.rs` for `levels` nodes.
|
||
- `crates/nodes/src/atomic.rs`: the NaN guard in `levels_fn`.
|
||
- Tests: `levels_editor::tests` (histogram counts, end bins and NaN; handle constraints and the
|
||
relative mid), `atomic::levels_tests` (identity, stretch and clip, the relative mid, output
|
||
range and inversion, threshold, NaN), and the `levels-editor` scene of the `snapshots` UI test,
|
||
which renders the screenshot above.
|