JSON Pipeline Format

Pipelines serialize to the SerializedPipeline v3 JSON format. This format is used by:

The VSCode extension (megane.json files)
The pipeline editor (import/export)
The TypeScript pipe.toObject() / pipe.toJSON() methods
The Python pipe.to_dict() method

JSON pipelines can be saved, shared, and version-controlled. You can write them by hand or generate them from Python or TypeScript.

For real-world examples, see the Gallery.

Format

{
  "version": 3,
  "nodes": [
    {
      "id": "s1",
      "type": "load_structure",
      "position": { "x": 0, "y": 0 },
      "fileName": "protein.pdb",
      "fileUrl": "protein.pdb",
      "hasTrajectory": false,
      "hasCell": false
    },
    {
      "id": "ab1",
      "type": "add_bond",
      "position": { "x": 0, "y": 150 },
      "bondSource": "distance"
    },
    {
      "id": "v1",
      "type": "viewport",
      "position": { "x": 0, "y": 300 },
      "perspective": false,
      "cellAxesVisible": false,
      "pivotMarkerVisible": false
    }
  ],
  "edges": [
    { "source": "s1", "target": "ab1", "sourceHandle": "particle", "targetHandle": "particle" },
    { "source": "s1", "target": "v1", "sourceHandle": "particle", "targetHandle": "particle" },
    { "source": "ab1", "target": "v1", "sourceHandle": "bond", "targetHandle": "bond" }
  ]
}

Top-level Fields

Field	Type	Description
`version`	`number`	Always `3` for the current format
`nodes`	`array`	Array of node objects
`edges`	`array`	Array of edge objects connecting nodes

Node Fields

Every node has the following common fields:

Field	Type	Description
`id`	`string`	Unique node identifier
`type`	`string`	Node type (see below)
`position`	`{ x, y }`	Position in the pipeline editor canvas
`enabled`	`boolean?`	Optional. Set to `false` to bypass this node (default: `true`)

Node Types and Parameters

`load_structure`

Field	Type	Description
`fileName`	`string`	Display name of the file
`fileUrl`	`string`	Path or URL to the structure file
`hasTrajectory`	`boolean`	Whether the file contains trajectory data
`hasCell`	`boolean`	Whether the file contains unit cell data

`load_trajectory`

Field	Type	Description
`fileName`	`string`	Display name of the trajectory file
`fileUrl`	`string`	Path or URL to the trajectory file

`streaming`

No additional parameters.

`load_vector`

Field	Type	Description
`fileName`	`string`	Path to vector data file

`filter`

Field	Type	Description
`query`	`string`	Atom selection query
`bond_query`	`string?`	Bond selection query

`modify`

Field	Type	Description
`scale`	`number`	Atom sphere radius multiplier (0.1–2.0)
`opacity`	`number`	Transparency (0–1)

`color`

Per-stream coloring (Ovito-style). Accepts a particle input on the in handle and emits the recolored particle stream on out.

Field	Type	Description
`mode`	`string`	`"uniform"`, `"byElement"`, `"byResidue"`, `"byChain"`, `"byBFactor"`, or `"byProperty"`
`uniformColor`	`string`	Hex color used when `mode === "uniform"`
`range`	`[number, number]?`	Optional `[min, max]` for `byBFactor` / `byProperty`

`representation`

Per-stream representation override (Ovito-style). The Viewport reads the mode from the first connected particle stream that carries an override and falls back to "atoms" otherwise. Accepts a particle input on the in handle and emits the tagged particle stream on out.

Field	Type	Description
`mode`	`string`	`"atoms"` (default), `"licorice"`, `"cartoon"`, `"both"`, `"surface"`, or `"line"`

`add_bond`

Field	Type	Description
`bondSource`	`string`	`"distance"` or `"structure"`
`vdwScale`	`number`	Optional. Threshold scale for `"distance"` mode: atoms bond when their separation is `≤ (vdw_i + vdw_j) * vdwScale`. Higher loosens (more bonds), lower tightens. Defaults to `0.6`.

`label_generator`

Field	Type	Description
`source`	`string`	`"element"`, `"resname"`, or `"index"`

`polyhedron_generator`

Centers and ligands are auto-detected using VESTA-style heuristics. Use excludedCenters / excludedLigands to opt out specific atomic numbers.

Field	Type	Description
`excludedCenters`	`number[]`	Atomic numbers excluded from center detection (default `[]`)
`excludedLigands`	`number[]`	Atomic numbers excluded from ligand detection (default `[]`)
`cutoffTolerance`	`number`	Bond-length tolerance multiplier applied to VDW radii sum (default `1.15`)
`opacity`	`number`	Face transparency (0–1)
`showEdges`	`boolean`	Display wireframe edges
`edgeColor`	`string`	Wireframe edge color (hex)
`edgeWidth`	`number`	Wireframe edge width (px)

`surface_mesh`

Field	Type	Description
`alphaRadius`	`number`	Probe sphere radius in Å (alpha value). Larger = smoother surface, smaller = more detail.
`color`	`string`	Surface color (hex, e.g. `"#4488ff"`)
`opacity`	`number`	Surface transparency (0–1)

`load_volumetric`

Field	Type	Description
`fileName`	`string \| null`	Display name of the CUBE file. Volumetric data (`volumetricData`) is ephemeral and not serialized.

`isosurface`

Field	Type	Description
`isoLevel`	`number`	Contour value for the positive isosurface
`color`	`string`	Hex color for the positive isosurface
`opacity`	`number`	Surface transparency (0–1)
`showNegative`	`boolean`	Show a second isosurface at −isoLevel (dual-contour for ESP maps)
`negativeColor`	`string`	Hex color for the negative isosurface

`vector_overlay`

Field	Type	Description
`scale`	`number`	Vector arrow length multiplier

`viewport`

Field	Type	Description
`perspective`	`boolean`	Perspective / orthographic projection
`cellAxesVisible`	`boolean`	Show unit cell axes
`pivotMarkerVisible`	`boolean`	Show rotation pivot marker

Edge Fields

Field	Type	Description
`source`	`string`	Source node `id`
`target`	`string`	Target node `id`
`sourceHandle`	`string`	Output port name (e.g., `"particle"`, `"bond"`, `"mesh"`)
`targetHandle`	`string`	Input port name (e.g., `"particle"`, `"bond"`, `"in"`)

Example: Crystal with Polyhedra

{
  "version": 3,
  "nodes": [
    {
      "id": "s1",
      "type": "load_structure",
      "position": { "x": 0, "y": 0 },
      "fileName": "perovskite_srtio3_3x3x3.xyz",
      "fileUrl": "perovskite_srtio3_3x3x3.xyz",
      "hasTrajectory": false,
      "hasCell": true
    },
    {
      "id": "ab1",
      "type": "add_bond",
      "position": { "x": -170, "y": 310 },
      "bondSource": "distance"
    },
    {
      "id": "poly1",
      "type": "polyhedron_generator",
      "position": { "x": 170, "y": 310 },
      "excludedCenters": [38],
      "excludedLigands": [],
      "cutoffTolerance": 1.15,
      "opacity": 0.5,
      "showEdges": true,
      "edgeColor": "#dddddd",
      "edgeWidth": 2
    },
    {
      "id": "v1",
      "type": "viewport",
      "position": { "x": 0, "y": 615 },
      "perspective": false,
      "cellAxesVisible": true,
      "pivotMarkerVisible": true
    }
  ],
  "edges": [
    { "source": "s1", "target": "ab1", "sourceHandle": "particle", "targetHandle": "particle" },
    { "source": "s1", "target": "poly1", "sourceHandle": "particle", "targetHandle": "particle" },
    { "source": "s1", "target": "v1", "sourceHandle": "particle", "targetHandle": "particle" },
    { "source": "s1", "target": "v1", "sourceHandle": "cell", "targetHandle": "cell" },
    { "source": "ab1", "target": "v1", "sourceHandle": "bond", "targetHandle": "bond" },
    { "source": "poly1", "target": "v1", "sourceHandle": "mesh", "targetHandle": "mesh" }
  ]
}

Example: Atom Filter with Branching

{
  "version": 3,
  "nodes": [
    {
      "id": "s1",
      "type": "load_structure",
      "position": { "x": 170, "y": 0 },
      "fileName": "caffeine_water.pdb",
      "fileUrl": "caffeine_water.pdb",
      "hasTrajectory": false,
      "hasCell": false
    },
    {
      "id": "fc1",
      "type": "filter",
      "position": { "x": 0, "y": 150 },
      "query": "index < 24"
    },
    {
      "id": "mc1",
      "type": "modify",
      "position": { "x": 0, "y": 300 },
      "scale": 3.0,
      "opacity": 1.0
    },
    {
      "id": "fw1",
      "type": "filter",
      "position": { "x": 340, "y": 150 },
      "query": "index >= 24"
    },
    {
      "id": "mw1",
      "type": "modify",
      "position": { "x": 340, "y": 300 },
      "scale": 1.0,
      "opacity": 0.15
    },
    {
      "id": "v1",
      "type": "viewport",
      "position": { "x": 170, "y": 450 },
      "perspective": false,
      "cellAxesVisible": false,
      "pivotMarkerVisible": false
    }
  ],
  "edges": [
    { "source": "s1", "target": "fc1", "sourceHandle": "particle", "targetHandle": "in" },
    { "source": "fc1", "target": "mc1", "sourceHandle": "out", "targetHandle": "in" },
    { "source": "mc1", "target": "v1", "sourceHandle": "out", "targetHandle": "particle" },
    { "source": "s1", "target": "fw1", "sourceHandle": "particle", "targetHandle": "in" },
    { "source": "fw1", "target": "mw1", "sourceHandle": "out", "targetHandle": "in" },
    { "source": "mw1", "target": "v1", "sourceHandle": "out", "targetHandle": "particle" }
  ]
}

Format​

Top-level Fields​

Node Fields​

Node Types and Parameters​

load_structure​

load_trajectory​

streaming​

load_vector​

filter​

modify​

color​

representation​

add_bond​

label_generator​

polyhedron_generator​

surface_mesh​

load_volumetric​

isosurface​

vector_overlay​

viewport​

Edge Fields​

Example: Crystal with Polyhedra​

Example: Atom Filter with Branching​