@intact-ebi/cytoscape-lumina 0.1.0 → 1.0.0

package/LICENSE

@@ -1,15 +1,7 @@
-ISC License
+Copyright 2026 EMBL-EBI
 
-Copyright (c) 2026 EMBL-EBI
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
-LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
-OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-PERFORMANCE OF THIS SOFTWARE.
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,123 +1,169 @@
-# LUMINA: 
+# LUMINA
 
-## Usage
+**LUMINA** is a [Cytoscape.js](https://js.cytoscape.org/) layout extension that is **structure-aware**: instead of treating every node the same, it detects common substructures in your graph, collapses each one into a *virtual node*, lays out the virtual nodes with either a force-directed or a stress-majorization solver, and then expands every substructure back into a clean, purpose-built arrangement.
+
+Written in TypeScript. Registered under the layout name `lumina` (the legacy name `substructure-layout` is still registered as an alias).
+
+## Features
+
+- **Substructure detection**
+  - **Cycle** – laid out as a perfect circle
+  - **Chain** – a path hanging off a leaf, laid out as a ring with its leaf end in the middle
+  - **Star** – a hub with leaf neighbours, laid out in concentric rings
+  - **Parallel** – nodes sharing the same neighbours, laid out as an aligned grid between their shared endpoints
+  - Leaves that don't belong to a chain are placed on a circle around their parent
+- **Two interchangeable solvers** for the virtual-node graph: `force` and `stress`
+- **Multiple connected components** are each laid out independently, rotated to their minimum bounding box, and packed into rows that match the canvas aspect ratio
+- **Compound parents** (`.substructure-group`) are generated for each detected substructure
+- **Step-by-step mode** to inspect and replay every stage of the pipeline
+
+## How it works
 
-### Installation
+1. Split the graph into connected components.
+2. Detect cycles, chains, stars and parallel groups.
+3. Create one virtual node per substructure (single nodes become their own virtual node) and virtual edges between them.
+4. Compute a radius for each virtual node from its type and size.
+5. Run the selected solver (`force` or `stress`) on the virtual graph, then an anti-collision pass.
+6. Expand each virtual node into its real nodes using the substructure-specific arrangement.
+7. Rotate each component to its minimum-area bounding box and pack all components onto the canvas.
 
-```zsh
-npm install @intact-portal/sub-structure-cyto-layout cytoscape
+## Installation
+
+```bash
+npm install cytoscape @intact-ebi/cytoscape-lumina
 ```
 
-### Minimal import
+`cytoscape` (^3) is a peer dependency.
+
+## Usage
 
-```js
+```ts
 import cytoscape from 'cytoscape';
-import registerSubstructureLayout from '@intact-portal/sub-structure-cyto-layout';
+import registerLumina from '@intact-ebi/cytoscape-lumina';
 
-registerSubstructureLayout(cytoscape);
+registerLumina(cytoscape);
 
-const cy = cytoscape({
-container: document.getElementById('cy'),
-elements
-});
+const cy = cytoscape({ container: document.getElementById('cy'), elements: [/* ... */] });
 
 cy.layout({
-name: 'substructure-layout'
+  name: 'lumina',
+  layoutAlgorithm: 'stress',   // 'stress' (default) or 'force'
+
+  // shared by both algorithms
+  idealLength: 100,
+  iterations: 600,
+
+  // used only when layoutAlgorithm is 'force'
+  force: { repulsion: 300, springK: 0.15, useAngularForce: true },
+
+  // used only when layoutAlgorithm is 'stress'
+  stress: { weightExponent: 2 }
 }).run();
 ```
 
-### Demo project
-
-```js
-<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>Cytoscape LUMINA demo</title>
-  <style>
-    html,
-    body {
-      height: 100%;
-      margin: 0;
-      font-family: system-ui, sans-serif;
-    }
-
-    body {
-      display: grid;
-      grid-template-rows: auto 1fr;
-    }
-  </style>
-
-  <script type="importmap">
-    {
-      "imports": {
-        "cytoscape": "./node_modules/cytoscape/dist/cytoscape.esm.min.mjs",
-        "@intact-ebi/cytoscape-lumina": "./node_modules/@intact-ebi/cytoscape-lumina/dist/index.js"
-      }
-    }
-  </script>
-</head>
-<body>
-  <header>
-    <h1>LUMINA layout demo</h1>
-  </header>
-  <main id="cy" aria-label="Interactive network graph"></main>
-
-  <script type="module">
-    import cytoscape from 'cytoscape';
-    import registerSubstructureLayout from '@intact-ebi/cytoscape-lumina';
-
-    registerSubstructureLayout(cytoscape);
-
-    const elements = [
-      { data: { id: 'a' } },
-      { data: { id: 'b' } },
-      { data: { id: 'c' } },
-      { data: { id: 'd' } },
-      { data: { id: 'hub' } },
-      { data: { id: 'leaf-1' } },
-      { data: { id: 'leaf-2' } },
-      { data: { id: 'leaf-3' } },
-      { data: { id: 'chain-1' } },
-      { data: { id: 'chain-2' } },
-      { data: { id: 'ab', source: 'a', target: 'b' } },
-      { data: { id: 'bc', source: 'b', target: 'c' } },
-      { data: { id: 'cd', source: 'c', target: 'd' } },
-      { data: { id: 'da', source: 'd', target: 'a' } },
-      { data: { id: 'c-hub', source: 'c', target: 'hub' } },
-      { data: { id: 'hub-leaf-1', source: 'hub', target: 'leaf-1' } },
-      { data: { id: 'hub-leaf-2', source: 'hub', target: 'leaf-2' } },
-      { data: { id: 'hub-leaf-3', source: 'hub', target: 'leaf-3' } },
-      { data: { id: 'd-chain-1', source: 'd', target: 'chain-1' } },
-      { data: { id: 'chain-1-chain-2', source: 'chain-1', target: 'chain-2' } }
-    ];
-
-    const cy = cytoscape({
-      container: document.getElementById('cy'),
-      elements,
-      style: [
-        {
-          selector: 'node',
-          style: {
-            'label': 'data(id)',
-          }
-        },
-      ]
-    });
-
-    cy.layout({
-      name: 'substructure-layout',
-    }).run();
-  </script>
-</body>
-</html>
+Registration is idempotent, so it is safe to call more than once (e.g. with hot reload).
+
+## Options
+
+Options are split by who uses them:
+
+- **Shared** options are passed at the top level and apply to both algorithms.
+- **Force-only** options go under `force: { ... }` and are ignored when `layoutAlgorithm` is `'stress'`.
+- **Stress-only** options go under `stress: { ... }` and are ignored when `layoutAlgorithm` is `'force'`.
+
+Internally these map to upper-case constants (e.g. `idealLength` → `IDEAL_LENGTH`); `DEFAULT_PARAMS` and `resolveParams` are exported if you need them.
+
+### Algorithm
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `layoutAlgorithm` | `'stress'` | `'force'` or `'stress'`. |
+
+### Shared solver options (both algorithms)
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `idealLength` | `100` | Ideal surface-to-surface gap between connected virtual nodes. Spring rest length for `force`, base of the target distance for `stress`; also the radius of the initial radial placement of leaf virtual nodes in both. |
+| `iterations` | `600` | Maximum iterations of the main solver loop. |
+| `convergenceThreshold` | `0.5` | Stop early once the largest movement of any virtual node is below this many pixels. |
+| `collisionPadding` | `idealLength` | Extra gap enforced between virtual nodes in the anti-collision pass. |
+| `maxOverlapIterations` | `300` | Safety cap for the anti-collision loop (stress). |
+
+### Force-only options (`force: { ... }`)
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `repulsion` | `300` | Repulsion strength between virtual nodes. |
+| `springK` | `0.15` | Spring stiffness of virtual edges. |
+| `overlapRepulsionFactor` | `5` | Overlapping virtual nodes repel this many times harder. |
+| `coolingExponent` | `2` | Annealing: `cooling = (1 − iter / iterations) ^ coolingExponent`. |
+| `useAngularForce` | `false` | Spread leaf virtual nodes evenly in angle around their hub. |
+| `angularStrength` | `0.2` | Strength of the angular force (needs `useAngularForce`). |
+| `angularMaxForce` | `2.0` | Per-step cap on the angular force (needs `useAngularForce`). |
+
+### Stress-only options (`stress: { ... }`)
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `weightExponent` | `2` | Stress weights are `w_ij = 1 / d_ij ^ weightExponent`; `2` is classic stress majorization. |
+
+### Structure detection
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `minStarLeaves` | `3` | Minimum leaf neighbours for a node to become a star centre. |
+| `minCycleLength` | `3` | Minimum number of nodes in a detected cycle. |
+| `maxCycleLength` | `30` | Reserved. Currently **not enforced** by the cycle search. |
+| `minChainLength` | `2` | Minimum number of nodes in a chain. |
+| `minParallelNeighbors` | `2` | Minimum shared neighbours for nodes to count as a parallel group. |
+
+### Substructure spacing
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `cycleNodeSpacing` | `100` | Target spacing between neighbouring nodes on a cycle (also sizes chain rings and virtual node radii). |
+| `starRingSpacing` | `100` | Distance between concentric rings of a star. |
+| `starBaseNodesPerRing` | `6` | Nodes in the first star ring; each further ring holds this many more. |
+| `chainMinRadius` | `150` | Minimum radius of a chain ring. |
+| `leafNodeDistance` | `200` | Distance of non-chain leaves from their parent (only used when `substructureLayout` is `false`). |
+
+### Flags
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `randomizeInitialPositions` | `false` | Randomize node positions inside the bounding box before the layout starts. |
+| `spreadVNodes` | `true` | After solving, scatter real nodes slightly around their virtual node centre. |
+| `substructureLayout` | `false` | When `false` (default), each substructure is arranged internally (circle, rings, grid, ...). When `true`, that step is skipped. |
+| `stepByStep` | `false` | Record a snapshot after each stage (see below). |
+
+### Backward compatibility
+
+The old flat force options (`repulsion`, `springK`, `useAngularForce`, `angularStrength`) and the legacy upper-case `params: { ... }` object are still accepted. Nested `force` / `stress` objects take priority.
+
+## Step-by-step debugging
+
+Set `stepByStep: true`, keep a reference to the layout, and run it:
+
+```ts
+const layout = cy.layout({ name: 'lumina', stepByStep: true });
+layout.run();
+
+layout.listSteps();   // print and return all captured steps
+layout.goToStep(3);   // jump to a step
+layout.nextStep();
+layout.prevStep();
+layout.clearVirtualNodes();
 ```
 
-## Configuration
+Each step restores real-node positions and overlays the virtual nodes (translucent circles) and virtual edges (dashed lines) at that stage.
+
+## Which algorithm should I use?
 
-TODO
+- **`stress`** (default) – deterministic-looking, globally consistent distances, good for most graphs. Tune with `idealLength` and `weightExponent`. Cost grows with the number of virtual nodes (all-pairs shortest paths).
+- **`force`** – classic spring-and-repulsion with annealing, plus an optional angular force for evenly fanned-out leaves. Tune with `repulsion`, `springK` and `useAngularForce`.
 
-## Development
+## Notes
 
-TODO
+- Nodes with 8 or more neighbours are skipped during cycle search, for performance.
+- Self-loops and duplicate edges are ignored by the layout.
+- Generated compound parents have the class `substructure-group` and ids of the form `<componentIndex>_<groupId>`; they are removed and regenerated on each run.

package/dist/index.d.ts

@@ -1,115 +1,2 @@
-import cytoscape from 'cytoscape';
-export type LayoutAlgorithm = 'force' | 'stress';
-export interface LayoutParameters {
-    LAYOUT_ALGORITHM: LayoutAlgorithm;
-    IDEAL_LENGTH: number;
-    REPULSION: number;
-    SPRING_K: number;
-    ITERATIONS: number;
-    ANGULAR_STRENGTH: number;
-    CENTER_GRAVITY: number;
-    USE_ANGULAR_FORCE: boolean;
-    RANDOMIZE_INITIAL_POSITIONS: boolean;
-    MIN_STAR_LEAVES: number;
-    MIN_CYCLE_LENGTH: number;
-    MAX_CYCLE_LENGTH: number;
-    MIN_CHAIN_LENGTH: number;
-    MIN_PARALLEL_NEIGHBORS: number;
-    CYCLE_NODE_SPACING: number;
-    STAR_RING_SPACING: number;
-    STAR_BASE_NODES_PER_RING: number;
-    CHAIN_MIN_RADIUS: number;
-    PARALLEL_GAP: number;
-    LEAF_NODE_DISTANCE: number;
-    VNODE_RADIUS_MULTIPLIER: number;
-    VNODE_REPULSION: number;
-    VNODE_SPRING_K: number;
-    VNODE_ITERATIONS: number;
-    VNODE_ANGULAR_STRENGTH: number;
-    SPREAD_V_NODES: boolean;
-    SUBSTRUCTURE_LAYOUT: boolean;
-    ENABLE_INITIAL_FORCE_LAYOUT: boolean;
-    STEP_BY_STEP: boolean;
-    SHOW_ALL_EDGES: boolean;
-}
-export declare const DEFAULT_PARAMS: LayoutParameters;
-export interface LayoutStep {
-    stepNumber: number;
-    stepName: string;
-    description: string;
-    nodePositions: {
-        [nodeId: string]: {
-            x: number;
-            y: number;
-        };
-    };
-    virtualNodes?: VNode[];
-    virtualEdges?: VEdge[];
-    metadata?: any;
-}
-export type SubstructureType = 'Normal' | 'Cycle' | 'Chain' | 'Star-Center' | 'Star-Member' | 'Parallel' | 'LeafButNotChain';
-type Node = cytoscape.NodeSingular;
-declare class VNode {
-    id: string;
-    type: any;
-    center_x: number;
-    center_y: number;
-    radius: number;
-    rotate_angle: number;
-    nodes: Node[];
-    neighbors: VNode[];
-    _permanentOrder?: string[];
-    constructor(id: string, x: number, y: number, radius: number);
-    get position(): {
-        x: number;
-        y: number;
-    };
-    setPosition(x: number, y: number): void;
-    addNode(node: Node): void;
-    setPermanentOrder(order: string[]): void;
-    getPermanentOrder(): string[] | undefined;
-    toSnapshot(): {
-        id: string;
-        type: any;
-        center_x: number;
-        center_y: number;
-        radius: number;
-        rotate_angle: number;
-        nodeIds: cytoscape.NodeSingular[];
-    };
-}
-declare class VEdge {
-    source: VNode;
-    target: VNode;
-    weight: number;
-    constructor(source: VNode, target: VNode, weight?: number);
-    toSnapshot(): {
-        source: string;
-        target: string;
-        weight: number;
-    };
-}
-/**
- * Register this layout as a Cytoscape.js layout extension.
- *
- * Usage:
- *   import cytoscape from 'cytoscape';
- *   import substructureLayout from './cytoscape-substructure-layout';
- *
- *   substructureLayout(cytoscape);
- *
- *   cy.layout({
- *       name: 'substructure-layout',
- *       layoutAlgorithm: 'force',
- *       idealLength: 100,
- *       repulsion: 10000,
- *       springK: 0.15,
- *       iterations: 400
- *   }).run();
- */
-export default function register(cytoscapeInstance: any): void;
-export { SubstructureLayout };
-/**
- * Enhanced force-directed layout with structure awareness
- */
-declare function SubstructureLayout(this: any, options: any): void;
+export * from './lumina-layout.js';
+export { default } from './lumina-layout.js';