_elkjs

ELK data model implemented as typings.TypedDicts and subprocess callers to check if elkjs can be installed via npm. The high level function is call_elkjs.

EDGE_STRAIGHTENING_LAYOUT_OPTIONS module-attribute

EDGE_STRAIGHTENING_LAYOUT_OPTIONS: LayoutOptions = {'layered.priority.straightness': '10'}

Options for increasing the edge straightness priority.

ELKOutputChild module-attribute

ELKOutputChild = Union[ELKOutputEdge, ELKOutputJunction, ELKOutputLabel, ELKOutputNode, ELKOutputPort]

Type alias for ELK output.

LABEL_LAYOUT_OPTIONS module-attribute

LABEL_LAYOUT_OPTIONS: LayoutOptions = {'nodeLabels.placement': 'OUTSIDE, V_BOTTOM, H_CENTER'}

Options for labels to configure ELK layouting.

LAYOUT_OPTIONS module-attribute

LAYOUT_OPTIONS: ImmutableLayoutOptions = {'algorithm': 'layered', 'edgeRouting': 'ORTHOGONAL', 'elk.direction': 'RIGHT', 'hierarchyHandling': 'INCLUDE_CHILDREN', 'layered.edgeLabels.sideSelection': 'ALWAYS_DOWN', 'layered.nodePlacement.strategy': 'BRANDES_KOEPF', 'spacing.labelNode': '0.0'}

Available (and possibly useful) Global Options to configure ELK layouting.

See Also

get_global_layered_layout_options : A function that instantiates this class with well-tested settings.

REQUIRED_NPM_PKG_VERSIONS module-attribute

REQUIRED_NPM_PKG_VERSIONS: Dict[str, str] = {'elkjs': '0.9.2'}

npm package names and versions required by this Python module.

BaseELKModel

Bases: BaseModel

Base class for ELK models.

ELKInputChild

Bases: ELKInputData

Children of either ELKInputData or ELKInputChild.

ELKInputData

Bases: BaseELKModel

Data that can be fed to ELK.

ELKInputEdge

Bases: BaseELKModel

Exchange data that can be fed to ELK.

ELKInputLabel

Bases: BaseELKModel

Label data that can be fed to ELK.

ELKInputPort

Bases: BaseELKModel

Connector data that can be fed to ELK.

ELKOutputData

Bases: ELKOutputElement

Data that comes from ELK.

ELKOutputDiagramElement

Bases: ELKOutputElement

Class for positioned and sized elements that come out of ELK.

ELKOutputEdge

Bases: ELKOutputElement

Edge that comes out of ELK.

ELKOutputElement

Bases: BaseELKModel

Base class for all elements that comes out of ELK.

ELKOutputJunction

Bases: ELKOutputElement

Exchange-Junction that comes out of ELK.

ELKOutputLabel

Bases: ELKOutputDiagramElement

Label that comes out of ELK.

ELKOutputNode

Bases: ELKOutputDiagramElement

Node that comes out of ELK.

ELKOutputPort

Bases: ELKOutputDiagramElement

Port that comes out of ELK.

ELKPoint

Bases: BaseELKModel

Point data in ELK.

ELKSize

Bases: BaseELKModel

Size data in ELK.

ExecutableNotFoundError

Bases: NodeJSError, FileNotFoundError

The required executable could not be found in the PATH.

NodeInstallationError

Bases: NodeJSError

Installation of the node.js package failed.

NodeJSError

Bases: RuntimeError

An error happened during node execution.

PORT_LABEL_POSITION

Bases: Enum

Position of port labels.

ATTRIBUTE	DESCRIPTION
OUTSIDE	The label is placed outside the port.
INSIDE	The label is placed inside the port owner box.
NEXT_TO_PORT_IF_POSSIBLE	The label is placed next to the port if space allows.
ALWAYS_SAME_SIDE	The label is always placed on the same side of the port.
ALWAYS_OTHER_SAME_SIDE	The label is always placed on the opposite side, but on the same axis.
SPACE_EFFICIENT	The label is positioned in the most space-efficient location.

call_elkjs

call_elkjs(elk_model: ELKInputData) -> ELKOutputData

Call into elk.js to auto-layout the diagram.

PARAMETER	DESCRIPTION
elk_model	The diagram data, sans layouting information TYPE: ELKInputData

RETURNS	DESCRIPTION
layouted_diagram	The diagram data, augmented with layouting information

Source code in capellambse_context_diagrams/_elkjs.py

def call_elkjs(elk_model: ELKInputData) -> ELKOutputData:
    """Call into elk.js to auto-layout the ``diagram``.

    Parameters
    ----------
    elk_model
        The diagram data, sans layouting information

    Returns
    -------
    layouted_diagram
        The diagram data, augmented with layouting information
    """
    _find_node_and_npm()
    _install_required_npm_pkg_versions()

    ELKInputData.model_validate(elk_model, strict=True)
    proc = subprocess.run(
        ["node", str(PATH_TO_ELK_JS)],
        executable=shutil.which("node"),
        capture_output=True,
        check=False,
        input=elk_model.model_dump_json(exclude_defaults=True),
        text=True,
        env={**os.environ, "NODE_PATH": str(NODE_HOME)},
    )
    if proc.returncode or proc.stderr:
        log.getChild("node").error("%s", proc.stderr.splitlines()[0])
        raise NodeJSError("elk.js process failed")

    return ELKOutputData.model_validate_json(proc.stdout, strict=True)

get_global_layered_layout_options

get_global_layered_layout_options() -> LayoutOptions

Return optimal ELKLayered configuration.

Source code in capellambse_context_diagrams/_elkjs.py

def get_global_layered_layout_options() -> LayoutOptions:
    """Return optimal ELKLayered configuration."""
    return copy.deepcopy(LAYOUT_OPTIONS)  # type: ignore[arg-type]