update readme and add icons
This commit is contained in:
331
docs/plugins.md
Normal file
331
docs/plugins.md
Normal file
@@ -0,0 +1,331 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user