expose layout options

changelog.md

@@ -8,6 +8,8 @@
 
 * Allow visualization based only on relationship DataFrames, without specifying node DataFrames in `from_dfs`
 * Add relationship properties to `VisualizationGraph` when constructing via `from_gds`.
+* Allow setting `layout_options` for `VisualizationGraph::render`
+
 
 ## Bug fixes
 

docs/source/rendering.rst

@@ -35,8 +35,8 @@ You can provide these either as a percentage of the available space (eg. ``"80%"
 
 Further you can change the layout of the graph using the ``layout`` parameter, which can be set to one of the following values:
 
-* ``Layout.FORCE_DIRECTED`` - Nodes are arranged using the Force-Directed algorithm, which simulates physical forces
-* ``Layout.HIERARCHICAL`` - Arranges nodes by the directionality of their relationships, creating a tree-like structure
+* ``Layout.FORCE_DIRECTED`` - Nodes are arranged using the Force-Directed algorithm, which simulates physical forces. To customize the layout use `ForceDirectedOptions` via `layout_options`.`
+* ``Layout.HIERARCHICAL`` - Arranges nodes by the directionality of their relationships, creating a tree-like structure.  To customize the layout use `HierarchicalLayoutOptions` via `layout_options`.`
 * ``Layout.COORDINATE`` - Arranges nodes based on coordinates defined in `x` and `y` properties on each node.
 
 Another thing of note is the ``max_allowed_nodes`` parameter, which controls the maximum number of nodes that is allowed

python-wrapper/src/neo4j_viz/__init__.py

@@ -1,6 +1,25 @@
 from .node import Node
-from .options import CaptionAlignment, Layout, Renderer
+from .options import (
+    CaptionAlignment,
+    Direction,
+    ForceDirectedLayoutOptions,
+    HierarchicalLayoutOptions,
+    Layout,
+    Packing,
+    Renderer,
+)
 from .relationship import Relationship
 from .visualization_graph import VisualizationGraph
 
-__all__ = ["VisualizationGraph", "Node", "Relationship", "CaptionAlignment", "Layout", "Renderer"]
+__all__ = [
+    "VisualizationGraph",
+    "Node",
+    "Relationship",
+    "CaptionAlignment",
+    "Layout",
+    "Renderer",
+    "HierarchicalLayoutOptions",
+    "ForceDirectedLayoutOptions",
+    "Direction",
+    "Packing",
+]

python-wrapper/src/neo4j_viz/options.py

@@ -2,10 +2,10 @@
 
 import warnings
 from enum import Enum
-from typing import Any, Optional
+from typing import Any, Optional, Union
 
 import enum_tools.documentation
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
 
 
 @enum_tools.documentation.document_enum
@@ -33,6 +33,49 @@ class Layout(str, Enum):
     GRID = "grid"
 
 
+@enum_tools.documentation.document_enum
+class Direction(str, Enum):
+    """
+    The direction in which the layout should be oriented
+    """
+
+    LEFT = "left"
+    RIGHT = "right"
+    UP = "up"
+    DOWN = "down"
+
+
+@enum_tools.documentation.document_enum
+class Packing(str, Enum):
+    """
+    The packing method to be used
+    """
+
+    BIN = "bin"
+    STACK = "stack"
+
+
+class HierarchicalLayoutOptions(BaseModel):
+    """
+    The options for the hierarchical layout.
+    """
+
+    direction: Optional[Direction] = None
+    packaging: Optional[Packing] = None
+
+
+class ForceDirectedLayoutOptions(BaseModel):
+    """
+    The options for the force-directed layout.
+    """
+
+    gravity: Optional[float] = None
+    simulationStopVelocity: Optional[float] = None
+
+
+LayoutOptions = Union[HierarchicalLayoutOptions, ForceDirectedLayoutOptions]
+
+
 @enum_tools.documentation.document_enum
 class Renderer(str, Enum):
     """
@@ -72,6 +115,9 @@ class RenderOptions(BaseModel, extra="allow"):
     """
 
     layout: Optional[Layout] = None
+    layout_options: Optional[Union[HierarchicalLayoutOptions, ForceDirectedLayoutOptions]] = Field(
+        None, serialization_alias="layoutOptions"
+    )
     renderer: Optional[Renderer] = None
 
     pan_X: Optional[float] = Field(None, serialization_alias="panX")
@@ -84,5 +130,16 @@ class RenderOptions(BaseModel, extra="allow"):
     min_zoom: Optional[float] = Field(None, serialization_alias="minZoom", description="The minimum zoom level allowed")
     allow_dynamic_min_zoom: Optional[bool] = Field(None, serialization_alias="allowDynamicMinZoom")
 
+    @model_validator(mode="after")
+    def check_layout_options_match(self) -> RenderOptions:
+        if self.layout_options is None:
+            return self
+
+        if self.layout == Layout.HIERARCHICAL and not isinstance(self.layout_options, HierarchicalLayoutOptions):
+            raise ValueError("layout_options must be of type HierarchicalLayoutOptions for hierarchical layout")
+        if self.layout == Layout.FORCE_DIRECTED and not isinstance(self.layout_options, ForceDirectedLayoutOptions):
+            raise ValueError("layout_options must be of type ForceDirectedLayoutOptions for force-directed layout")
+        return self
+
     def to_dict(self) -> dict[str, Any]:
         return self.model_dump(exclude_none=True, by_alias=True)

python-wrapper/src/neo4j_viz/visualization_graph.py

@@ -11,7 +11,7 @@
 from .node import Node, NodeIdType
 from .node_size import RealNumber, verify_radii
 from .nvl import NVL
-from .options import Layout, Renderer, RenderOptions
+from .options import Layout, LayoutOptions, Renderer, RenderOptions
 from .relationship import Relationship
 
 
@@ -42,6 +42,7 @@ def __init__(self, nodes: list[Node], relationships: list[Relationship]) -> None
     def render(
         self,
         layout: Optional[Layout] = None,
+        layout_options: Optional[LayoutOptions] = None,
         renderer: Renderer = Renderer.CANVAS,
         width: str = "100%",
         height: str = "600px",
@@ -60,6 +61,8 @@ def render(
         ----------
         layout:
             The `Layout` to use.
+        layout_options:
+            The `LayoutOptions` to use.
         renderer:
             The `Renderer` to use.
         width:
@@ -94,6 +97,7 @@ def render(
 
         render_options = RenderOptions(
             layout=layout,
+            layout_options=layout_options,
             renderer=renderer,
             pan_X=pan_position[0] if pan_position is not None else None,
             pan_Y=pan_position[1] if pan_position is not None else None,

python-wrapper/tests/test_options.py

@@ -1,7 +1,24 @@
-from neo4j_viz.options import Layout, RenderOptions
+import pytest
+
+from neo4j_viz.options import Direction, HierarchicalLayoutOptions, Layout, RenderOptions
 
 
 def test_render_options() -> None:
-    options = RenderOptions(layout=Layout.FORCE_DIRECTED)
+    options = RenderOptions(layout=Layout.HIERARCHICAL)
+
+    assert options.to_dict() == {"layout": "hierarchical"}
+
+
+def test_render_options_with_layout_options() -> None:
+    options = RenderOptions(
+        layout=Layout.HIERARCHICAL, layout_options=HierarchicalLayoutOptions(direction=Direction.LEFT)
+    )
+
+    assert options.to_dict() == {"layout": "hierarchical", "layoutOptions": {"direction": "left"}}
+
 
-    assert options.to_dict() == {"layout": "forcedirected"}
+def test_layout_options_match() -> None:
+    with pytest.raises(
+        ValueError, match="layout_options must be of type ForceDirectedLayoutOptions for force-directed layout"
+    ):
+        RenderOptions(layout=Layout.FORCE_DIRECTED, layout_options=HierarchicalLayoutOptions(direction=Direction.LEFT))