_elkjs

Functionality for the ELK data model and the call to elkjs.

Implementation of the data model and subprocess callers to check for elkjs binaries or deno support.

The ELKManager class is the manager for the ELK subprocess. It is responsible for spawning the subprocess, downloading the binary if necessary, and calling into the subprocess.

The elk_manager instance is the global instance of the ELKManager class. It can be used to call into 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 = (
    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",
    "spacing.edgeNode": 10,
    "spacing.edgeEdge": 10,
    "spacing.nodeNodeBetweenLayers": 5,
    "spacing.edgeNodeBetweenLayers": 5,
    "spacing.edgeEdgeBetweenLayers": 5,
}

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.

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.

ELKManager

ELKManager()

Source code in src/capellambse_context_diagrams/_elkjs.py

def __init__(self):
    self._proc = None
    self._lock = threading.Lock()

runtime_version property

runtime_version: str

The version of the elkjs runtime package to download.

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 src/capellambse_context_diagrams/_elkjs.py

def call_elkjs(self, 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
    """
    ELKInputData.model_validate(elk_model, strict=True)
    request = elk_model.model_dump_json(exclude_defaults=True) + "\n"
    with self.get_process() as (stdin, stdout):
        stdin.write(request)
        stdin.flush()
        response = stdout.readline()
    return ELKOutputData.model_validate_json(response, strict=True)

spawn_process

spawn_process() -> None

Spawn the elk.js process.

The preferenced order is: binary (downloaded) > deno > binary (needs download)

Source code in src/capellambse_context_diagrams/_elkjs.py

def spawn_process(self) -> None:
    """Spawn the elk.js process.

    The preferenced order is:
    binary (downloaded) > deno > binary (needs download)
    """

    if self.binary_path.exists() or shutil.which("deno") is None:
        self._spawn_process_binary()
    else:
        self._spawn_process_deno()

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.

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.

get_global_layered_layout_options

get_global_layered_layout_options() -> LayoutOptions

Return optimal ELKLayered configuration.

Source code in src/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]