332 lines
9.8 KiB
Markdown
332 lines
9.8 KiB
Markdown
# Writing plugins
|
||
|
||
Plugins are plain Python files dropped into the `plugins/` directory. Each file registers one or more nodes that appear in the Add Node menu immediately — no restart required if uploaded via UI upload.
|
||
|
||
A complete, annotated example is at [plugins/example_normalize.py](../plugins/example_normalize.py).
|
||
|
||
> **Note:** The plugin system is enabled on native desktop builds and disabled on web deployments by default. Override with the `TONO_PLUGINS=1` environment variable.
|
||
|
||
---
|
||
|
||
## Minimal plugin
|
||
|
||
```python
|
||
# plugins/my_filter.py
|
||
import numpy as np
|
||
from backend.node_registry import register_node
|
||
from backend.data_types import DataField
|
||
|
||
@register_node(display_name="My Filter")
|
||
class MyFilter:
|
||
CATEGORY = "Plugins"
|
||
|
||
@classmethod
|
||
def INPUT_TYPES(cls):
|
||
return {
|
||
"required": {
|
||
"field": ("DATA_FIELD",),
|
||
"strength": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 10.0}),
|
||
}
|
||
}
|
||
|
||
OUTPUTS = (("DATA_FIELD", "result"),)
|
||
FUNCTION = "process"
|
||
|
||
def process(self, field: DataField, strength: float) -> tuple:
|
||
scaled = field.data * strength
|
||
return (field.replace(data=scaled),)
|
||
```
|
||
|
||
Drop this file into `plugins/` and the node appears under **Plugins → My Filter** in the Add Node menu.
|
||
|
||
---
|
||
|
||
## Node class attributes
|
||
|
||
| Attribute | Required | Description |
|
||
|---|---|---|
|
||
| `INPUT_TYPES` | Yes | Classmethod returning `{"required": {...}, "optional": {...}}` |
|
||
| `OUTPUTS` | Yes | Tuple of `(type, name)` or `(type, name, meta)` entries |
|
||
| `FUNCTION` | Yes | Name of the method to call on execution |
|
||
| `CATEGORY` | No | Menu category; defaults to `"Unsorted"` if omitted |
|
||
| `DESCRIPTION` | No | Human-readable description shown in the UI |
|
||
| `OUTPUT_NODE` | No | Set `True` to mark this node as a terminal output node |
|
||
| `MANUAL_TRIGGER` | No | Set `True` to require the user to click Run manually |
|
||
|
||
---
|
||
|
||
## Input types
|
||
|
||
### Data types (socket connections)
|
||
|
||
These appear as connectable sockets on the node. They cannot be set inline by the user — they must be wired from another node.
|
||
|
||
| Type string | Python type received | Description |
|
||
|---|---|---|
|
||
| `"DATA_FIELD"` | `DataField` | 2D spatial/height data with physical metadata |
|
||
| `"IMAGE"` | `np.ndarray` (uint8) | Greyscale (H×W) or RGB (H×W×3) image or mask |
|
||
| `"LINE"` | `LineData` | 1D profile data with optional X axis and units |
|
||
| `"RECORD_TABLE"` | `RecordTable` (list of dicts) | Named scalar measurements |
|
||
| `"MESH_MODEL"` | `MeshModel` | 3D triangle mesh |
|
||
|
||
### Widget types (inline controls)
|
||
|
||
These appear as UI controls on the node body. They can also be connected from another node's output socket.
|
||
|
||
#### FLOAT
|
||
|
||
```python
|
||
"sigma": ("FLOAT", {
|
||
"default": 1.0,
|
||
"min": 0.0, # optional
|
||
"max": 10.0, # optional
|
||
"step": 0.1, # optional, default step for dragging
|
||
})
|
||
```
|
||
|
||
Add `"socket_only": True` in the optional dict to suppress the widget and show only a socket:
|
||
|
||
```python
|
||
# optional section:
|
||
"value": ("FLOAT", {"socket_only": True}),
|
||
```
|
||
|
||
#### INT
|
||
|
||
```python
|
||
"count": ("INT", {
|
||
"default": 5,
|
||
"min": 1,
|
||
"max": 100,
|
||
"step": 1,
|
||
})
|
||
```
|
||
|
||
#### Dropdown / choice list
|
||
|
||
Pass a list as the first element of the spec tuple:
|
||
|
||
```python
|
||
"method": (["nearest", "bilinear", "bicubic"],),
|
||
# or with a default:
|
||
"method": (["nearest", "bilinear", "bicubic"], {"default": "bilinear"}),
|
||
```
|
||
|
||
#### STRING
|
||
|
||
```python
|
||
"label": ("STRING", {
|
||
"default": "",
|
||
"placeholder": "Enter text...", # optional
|
||
"multiline": False, # optional
|
||
})
|
||
```
|
||
|
||
### Optional inputs
|
||
|
||
Declare inputs under `"optional"` to make them not required for execution. Your `process()` method receives `None` for any unconnected optional input, so guard against it:
|
||
|
||
```python
|
||
@classmethod
|
||
def INPUT_TYPES(cls):
|
||
return {
|
||
"required": {"field": ("DATA_FIELD",)},
|
||
"optional": {"mask": ("IMAGE",)},
|
||
}
|
||
|
||
def process(self, field, mask=None):
|
||
if mask is not None:
|
||
# use mask
|
||
...
|
||
```
|
||
|
||
---
|
||
|
||
## Output types
|
||
|
||
Each entry in `OUTPUTS` is `(type_string, display_name)` or `(type_string, display_name, meta_dict)`.
|
||
|
||
| Type string | Python value to return | Description |
|
||
|---|---|---|
|
||
| `"DATA_FIELD"` | `DataField` | 2D spatial data |
|
||
| `"IMAGE"` | `np.ndarray` (uint8) | Greyscale or RGB image / mask |
|
||
| `"LINE"` | `LineData` | 1D profile |
|
||
| `"RECORD_TABLE"` | `RecordTable` | Named scalar measurement table |
|
||
| `"FLOAT"` | `float` | Scalar number |
|
||
|
||
The return value of `process()` must be a **tuple** with one item per `OUTPUTS` entry, in the same order:
|
||
|
||
```python
|
||
OUTPUTS = (
|
||
("DATA_FIELD", "result"),
|
||
("RECORD_TABLE", "stats"),
|
||
("FLOAT", "mean"),
|
||
)
|
||
|
||
def process(self, field):
|
||
...
|
||
return (result_field, table, mean_value) # must be a tuple
|
||
```
|
||
|
||
### Accepting multiple input types on one output slot
|
||
|
||
Use `accepted_types` in the output metadata to allow wiring from additional types:
|
||
|
||
```python
|
||
OUTPUTS = (
|
||
("DATA_FIELD", "output", {"accepted_types": ["IMAGE"]}),
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## Data types reference
|
||
|
||
### DataField
|
||
|
||
The main SPM data container. Mirrors Gwyddion's `GwyDataField`.
|
||
|
||
```python
|
||
@dataclass
|
||
class DataField:
|
||
data: np.ndarray # shape (yres, xres), dtype float64
|
||
xres: int # pixel count in X (set automatically from data)
|
||
yres: int # pixel count in Y (set automatically from data)
|
||
xreal: float # physical width in metres
|
||
yreal: float # physical height in metres
|
||
xoff: float # X position offset in metres
|
||
yoff: float # Y position offset in metres
|
||
si_unit_xy: str # lateral unit, e.g. "m"
|
||
si_unit_z: str # value unit, e.g. "m", "V", "A"
|
||
domain: str # "spatial" or "frequency"
|
||
colormap: str | dict # colormap name or custom dict
|
||
display_offset: float # normalized display window offset
|
||
display_scale: float # normalized display window scale
|
||
overlays: list # list of overlay dicts (annotations etc.)
|
||
|
||
# Computed properties:
|
||
field.dx # physical pixel size X = xreal / xres (metres)
|
||
field.dy # physical pixel size Y = yreal / yres (metres)
|
||
```
|
||
|
||
**Always use `field.replace()` instead of constructing a new `DataField`** — it copies all metadata and only substitutes what you specify:
|
||
|
||
```python
|
||
# Good: physical dimensions, units, colormap all preserved
|
||
result = field.replace(data=new_data)
|
||
|
||
# Also valid: change data and units together
|
||
result = field.replace(data=fft_data, si_unit_z="1/m", domain="frequency")
|
||
```
|
||
|
||
Available built-in colormaps: `viridis`, `gray`, `hot`, `jet`, `plasma`, `inferno`, `terrain`, `cividis`, `magma`, `copper`, `afmhot`.
|
||
|
||
### LineData
|
||
|
||
1D profile data.
|
||
|
||
```python
|
||
@dataclass
|
||
class LineData:
|
||
data: np.ndarray # 1D float64 array of Y values
|
||
x_axis: np.ndarray | None # optional 1D float64 array of X positions
|
||
x_unit: str # unit label for X axis
|
||
y_unit: str # unit label for Y axis
|
||
|
||
# Supports NumPy interface transparently:
|
||
np.asarray(line) # → line.data
|
||
len(line) # → len(line.data)
|
||
line[i] # → line.data[i]
|
||
```
|
||
|
||
### MeshModel
|
||
|
||
3D triangle mesh for the 3D view node.
|
||
|
||
```python
|
||
@dataclass
|
||
class MeshModel:
|
||
vertices: np.ndarray # shape (N, 3), float32 — XYZ positions
|
||
faces: np.ndarray # shape (M, 3), int32 — triangle vertex indices
|
||
colors: np.ndarray | None # shape (N, 3), uint8 — per-vertex RGB (optional)
|
||
```
|
||
|
||
### RecordTable
|
||
|
||
A measurement table: a plain list of `{"quantity", "value", "unit"}` dicts. Can be wired to the **Print Table** or **Save** nodes.
|
||
|
||
```python
|
||
from backend.data_types import RecordTable
|
||
|
||
table = RecordTable([
|
||
{"quantity": "RMS roughness", "value": 2.34e-9, "unit": "m"},
|
||
{"quantity": "Mean", "value": 0.12e-9, "unit": "m"},
|
||
{"quantity": "Pixel count", "value": 4096, "unit": ""},
|
||
])
|
||
```
|
||
|
||
Use `field.si_unit_z` for the physical Z unit of the input field. Use `""` for dimensionless quantities.
|
||
|
||
---
|
||
|
||
## Execution context: emit functions
|
||
|
||
Import from `backend.execution_context` to send data to the frontend during execution — for example, to show a preview chart or a warning message.
|
||
|
||
```python
|
||
from backend.execution_context import emit_preview, emit_table, emit_warning, emit_value
|
||
```
|
||
|
||
| Function | Description |
|
||
|---|---|
|
||
| `emit_preview(data_uri)` | Push a preview image (base64 data URI string) to the preview panel |
|
||
| `emit_table(rows)` | Push a list of dicts as a table update |
|
||
| `emit_value(payload)` | Push a scalar value (or `{"value": v, "unit": "m"}` dict) |
|
||
| `emit_warning(message)` | Show a warning banner in the UI |
|
||
|
||
These functions are no-ops if called outside an active execution context, so they are safe to call unconditionally.
|
||
|
||
```python
|
||
from backend.execution_context import emit_warning
|
||
|
||
def process(self, field, threshold):
|
||
if threshold > field.data.max():
|
||
emit_warning("Threshold is above the data maximum — result will be empty.")
|
||
...
|
||
```
|
||
|
||
---
|
||
|
||
## Multi-file plugins
|
||
|
||
A directory with an `__init__.py` is treated as a plugin package. Private helpers (names starting with `_`) are ignored by the loader.
|
||
|
||
```
|
||
plugins/
|
||
my_suite/
|
||
__init__.py # registers nodes with @register_node
|
||
_helpers.py # private helpers, not auto-loaded
|
||
```
|
||
|
||
In `__init__.py`:
|
||
|
||
```python
|
||
from backend.node_registry import register_node
|
||
from backend.data_types import DataField
|
||
from my_suite._helpers import compute_something
|
||
|
||
@register_node(display_name="Suite Node A")
|
||
class SuiteNodeA:
|
||
...
|
||
```
|
||
|
||
---
|
||
|
||
## Uploading plugins via the web interface
|
||
|
||
On native builds, plugins can be uploaded without restarting via the toolbar.
|
||
|
||
The server saves the file, hot-reloads all plugins, and broadcasts a `nodes_updated` WebSocket message so the frontend refreshes the node list automatically.
|
||
|
||
> **Security note:** Uploading a `.py` file is equivalent to executing arbitrary code inside the server process. Only expose this endpoint on trusted local networks.
|