capellambse.diagram package¶

Various diagramming related tools.

This module is used to create diagrams, which can then be exported in various formats (such as SVG).

class capellambse.diagram.Box¶

Bases: object

A Box.

Some may call it rectangle.

CHILD_MARGIN = 2¶

JSON_TYPE = 'box'¶

PORT_OVERHANG = 2¶

__init__(pos, size, *, label='', floating_labels=None, description=None, uuid=None, parent=None, collapsed=False, minsize=(0, 0), maxsize=(inf, inf), context=None, port=False, features=None, styleclass=None, styleoverrides=None, hidelabel=False, hidden=False)¶

Create a new box.

Parameters:

pos (tuple[float | int, float | int] | Sequence[float | int]) – A Vector2D describing the spatial position.
size (tuple[float | int, float | int] | Sequence[float | int]) – A Vector2D describing the box’ size. If one or both of its components are 0, it/they will be calculated based on the Box’ label text and contained children.
label (str) – This box’ label text.
floating_labels (MutableSequence[Box] | None) – Additional box labels.
description (str | None) – Optional label text used only by Representation Links.
uuid (str | None) – UUID of the semantic element this box represents.
parent (Box | None) – This box’ parent box.
collapsed (bool) – Collapse this box and hide all its children. Note that setting this flag does not change the box’ size.
minsize (tuple[float | int, float | int] | Sequence[float | int]) – When dynamically calculating Box size, the minimum size it should have. Default: zero.
maxsize (tuple[float | int, float | int] | Sequence[float | int]) – When dynamically calculating Box size, the maximum size it can have. Default: infinite.
context (Iterable[str] | None) – A list of UUIDs of objects in this box’ context. This includes children and associated edges.
port (bool) – Flag this box as a port. Affects how context is added.
features (MutableSequence[str] | None) – Certain classes of Box (like Class) have features, which is a list of strings that will be displayed inside the Box, separated from the label by a horizontal line.
styleclass (str | None) – The CSS style class to use.
styleoverrides (MutableMapping[str, str | RGB | MutableSequence[str | RGB]] | None) – A dict of CSS properties to override.
hidelabel (bool) – Set to True to skip drawing this box’ label.
hidden (bool) – Set to True to skip drawing this entire box.

Return type:

None

add_context(uuid)¶

Add a UUID as context for this box.

The context will bubble to the immediate parent if this box is a port.

Parameters:: uuid (str)
Return type:: None

property bounds: Box¶

Calculate the bounding box of this Box.

Notes

Labels with a text_transform in its styleoverrides are ignored during bounds calculation.

property center: Vector2D¶: Return the center point of this Box.

context: set[str]¶

create_portlabel(labeltext, margin=2)¶

Add a label to a port box.

The port that this is called for must be snapped to its parent’s left or right side.

Parameters:

labeltext (str) – The label text.
margin (float | int) – Space between the label text and the port Box.

Return type:

None

property hidden: bool¶: Return whether to skip this Box during rendering.

maxsize¶: A property that automatically converts 2-tuples into Vector2D.

minsize¶: A property that automatically converts 2-tuples into Vector2D.

move(offset, *, children=True)¶

Move the box by the specified offset.

Parameters:

offset (Vector2D) – The offset to move the box by.
children (bool) – Recursively move children as well. If False, the positions of children need to be adjusted separately.

Return type:

None

property padding: Vector2D¶: Return the horizontal and vertical padding of label text.

property parent: Box | None¶: Return the parent element of this Box.

pos¶: A property that automatically converts 2-tuples into Vector2D.

property size: Vector2D¶: Return the size of this Box.

snap_to_parent()¶

Snap this Box into the constraints set by its parent.

If this Box is a port, ensure it lines up with the parent’s border, keeping an overhang of 2px.

Otherwise, ensures that this Box will not overflow out of the parent’s border, keeping a padding of 2px.

Return type:: None

vector_snap(point, *, source=None, style=RoutingStyle.OBLIQUE)¶

Snap the point into this Box, coming from source.

Parameters:

point (tuple[float | int, float | int] | Sequence[float | int])
source (tuple[float | int, float | int] | Sequence[float | int] | None)
style (RoutingStyle)

Return type:

Vector2D

class capellambse.diagram.Circle¶

Bases: object

Represents a circle.

JSON_TYPE = 'circle'¶

__init__(center, radius, *, uuid=None, styleclass=None, styleoverrides=None, hidden=False, context=None)¶

Construct a Circle.

Parameters:

center (tuple[float | int, float | int] | Sequence[float | int]) – The Circle’s center point as Vector2D or 2-tuple.
radius (float | int) – The Circle radius in pixels.
uuid (str | None) – The Circle’s unique identifier.
styleclass (str | None) – The Circle’s CSS class.
styleoverrides (MutableMapping[str, str | RGB | MutableSequence[str | RGB]] | None) – Dict of CSS key/value pairs that override the class defaults.
hidden (bool) – True to skip drawing this Circle.
context (Iterable[str] | None) – A list of UUIDs of objects in this circle’s context.

add_context(uuid)¶

Add a UUID as context for this circle.

Parameters:: uuid (str)
Return type:: None

property bounds: Box¶: Calculate the bounding box of this Circle.

center¶: A property that automatically converts 2-tuples into Vector2D.

collapsed = False¶

context: set[str]¶

hidelabel = True¶

label = None¶

move(offset, *, children=True)¶

Move this Circle on the 2-dimensional plane.

Parameters:

offset (tuple[float | int, float | int] | Sequence[float | int])
children (bool)

Return type:

None

port = False¶

vector_snap(vector, *, source, style=RoutingStyle.OBLIQUE)¶

Snap the vector onto this Circle, preferably in direction.

Parameters:

vector (tuple[float | int, float | int] | Sequence[float | int])
source (tuple[float | int, float | int] | Sequence[float | int])
style (RoutingStyle)

Return type:

Vector2D

class capellambse.diagram.Diagram¶

Bases: object

A complete diagram, including all elements required by it.

__init__(name='Untitled Diagram', viewport=None, elements=None, *, uuid=None, styleclass=None, params=None)¶

Construct a new diagram.

Parameters:

name (str) – The diagram’s name.
viewport (Box | None) – A Box describing this diagram’s viewport.
elements (Sequence[Box | Edge | Circle] | None) – A list containing the diagram’s initial elements.
uuid (str | None) – The unique ID of this diagram.
styleclass (str | None) – The diagram class.
params (dict[str, Any] | None) – Additional parameters.

add_element(element, extend_viewport=True, *, force=False)¶

Add an element to this diagram.

Parameters:

element (Box | Edge | Circle) – The element to add.
extend_viewport (bool) – True to automatically extend the diagram viewport so that the added element is fully visible.
force (bool) – Normally an exception will be raised if another element with the same UUID as the new one already exists in the diagram. If this is set to True, the old element will be overwritten instead.

Return type:

None

calculate_viewport()¶

Recalculate the viewport so that all elements are contained.

Return type:: None

normalize_viewport(offset=0)¶

Normalize the viewport.

This function moves all elements contained within this diagram so that the top left corner of the viewport is at (0, 0) (or the specified offset, if given).

If a single value is given as offset, it is applied to both X and Y coordinates.

Parameters:: offset (float | int | tuple[float | int, float | int] | Sequence[float | int])
Return type:: None

class capellambse.diagram.DiagramJSONEncoder¶

Bases: JSONEncoder

JSON encoder that knows how to handle AIRD diagrams.

default(o)¶

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return super().default(o)

Parameters:: o (object)
Return type:: object

class capellambse.diagram.Edge¶

Bases: Vec2List

An edge in the diagram.

An Edge consists of a series of points that are traversed in order. Each point is given as Vector2D containing absolute coordinates. At least two points are required.

JSON_TYPE = 'edge'¶

__init__(points, *, labels=None, uuid=None, source=None, target=None, styleclass=None, styleoverrides=None, hidden=False, context=None)¶

Construct an Edge.

Parameters:

source (Box | Edge | Circle | None) – The source diagram element of this Edge.
target (Box | Edge | Circle | None) – The target diagram element of this Edge.
labels (MutableSequence[Box] | None) – Labels for this Edge. Each label is a Box with pos, size and a simple str label. Other configurations of Boxes are not supported. The hidden flag is honored during rendering calculations.
points (Iterable[tuple[float | int, float | int] | Sequence[float | int]]) – A list of Vector2Ds with the (absolute) points this edge follows.
uuid (str | None) – UUID of the semantic element this Edge represents.
styleclass (str | None) – The CSS style class to use.
styleoverrides (MutableMapping[str, str | RGB | MutableSequence[str | RGB]] | None) – A dict of CSS properties to override.
hidden (bool) – True to skip drawing this edge entirely.
context (Iterable[str] | None) – A list of UUIDs of objects in this edge’s context.

add_context(uuid)¶

Add a UUID as context for this edge.

Parameters:: uuid (str)
Return type:: None

property bounds: Box¶: Calculate the bounding Box of this Edge.

property center: Vector2D¶: Calculate the point in the middle of this edge.

collapsed = False¶

context: set[str]¶

property hidden: bool¶: Return whether to skip this Edge during rendering.

hidelabel = False¶

property length: float¶: Return length of this edge.

move(offset, *, children=True)¶

Move all points of this edge by the specified offset.

Parameters:

offset (Vector2D)
children (bool)

Return type:

None

property points: Vec2List¶: Return an iterable over this edge’s points.

port = False¶

vector_snap(vector, *, source, style=RoutingStyle.OBLIQUE)¶

Snap the vector onto this Edge.

Parameters:

vector (tuple[float | int, float | int] | Sequence[float | int])
source (tuple[float | int, float | int] | Sequence[float | int])
style (RoutingStyle)

Return type:

Vector2D

class capellambse.diagram.RGB¶

Bases: NamedTuple

A color.

Each color component (red, green, blue) is an integer in the range of 0..255 (inclusive). The alpha channel is a float between 0.0 and 1.0 (inclusive). If it is 1, then the str() form does not include transparency information.

a: float¶: Alias for field number 3

b: int¶: Alias for field number 2

classmethod fromcss(cssstring)¶

Create an RGB from a CSS color definition.

Examples of recognized color definitions and their equivalent constructor calls:

"rgb(10, 20, 30)" -> RGB(10, 20, 30)
"rgba(50, 60, 70, 0.5)" -> RGB(50, 60, 70, 0.5)
"#FF00FF" -> RGB(255, 0, 255)
"#ff00ff" -> RGB(255, 0, 255)
"#f0f" -> RGB(255, 0, 255)
"#FF00FF80" -> RGB(255, 0, 255, 0.5)
"#f0fa" -> RGB(255, 0, 255, 2/3)

Parameters:: cssstring (str | RGB)
Return type:: RGB

classmethod fromcsv(csvstring)¶

Create an RGB from a "r, g, b[, a]" string.

Parameters:: csvstring (str)
Return type:: RGB

classmethod fromhex(hexstring)¶

Create an RGB from a hexadecimal string.

The string can have 3, 4, 6 or 8 hexadecimal characters. In the cases of 3 and 6 characters, the alpha channel is set to 1.0 (fully opaque) and the remaining characters are interpreted as the red, green and blue components.

Parameters:: hexstring (str)
Return type:: RGB

g: int¶: Alias for field number 1

r: int¶: Alias for field number 0

tohex()¶

Return type:: str

class capellambse.diagram.RoutingStyle¶

Bases: Enum

MANHATTAN = 2¶

OBLIQUE = 1¶

TREE = 3¶

class capellambse.diagram.Vec2List¶

Bases: MutableSequence[Vector2D]

A list that automatically converts its elements into Vector2D.

__init__(values)¶

Parameters:: values (Iterable[tuple[float | int, float | int] | Sequence[float | int]])

append(value)¶

S.append(value) – append value to the end of the sequence

Parameters:: value (tuple[float | int, float | int] | Sequence[float | int])
Return type:: None

copy()¶

Create a copy of this Vec2List.

Return type:: Vec2List

extend(values)¶

S.extend(iterable) – extend sequence by appending elements from the iterable

Parameters:: values (Iterable[tuple[float | int, float | int] | Sequence[float | int]])
Return type:: None

insert(index, value)¶

S.insert(index, value) – insert value before index

Parameters:

index (int)
value (Vector2D)

Return type:

None

class capellambse.diagram.Vec2Property¶

Bases: object

A property that automatically converts 2-tuples into Vector2D.

__init__(default=None)¶

Parameters:: default (tuple[float | int, float | int] | Sequence[float | int] | None)

default: Vector2D | None¶

name: str | None¶

class capellambse.diagram.Vector2D¶

Bases: NamedTuple

A vector in 2-dimensional space.

angleto(other)¶

Calculate the angle to other.

This method calculates the angle that other was rotated by in order to have the same direction as self, in radians.

Notes

The returned angle will always constitute the shortest rotation possible, i.e. it can have values between \(-\pi\) and \(+\pi\).

Parameters:: other (tuple[float | int, float | int] | Sequence[float | int])
Return type:: float

boxsnap(corner1, corner2)¶

Snap this vector to the side of a box and return the result.

Parameters:

corner1 (tuple[float | int, float | int] | Sequence[float | int]) – A Vector2D describing the first corner of the target box.
corner2 (tuple[float | int, float | int] | Sequence[float | int]) – A Vector2D describing the second corner of the target box.
dirvec – Ignored.

Return type:

Vector2D

closestaxis()¶

Determine the axis closest to this Vector2D.

Return type:: Vector2D

property length: float¶: Calculate the length of this vector.

property normalized: Vector2D¶

Create a unit Vector2D with the same direction as this one.

Raises:: ZeroDivisionError – if this Vector2D has zero length

rotatedby(theta)¶

Rotate this Vector2D by theta radians.

Parameters:: theta (float | int)
Return type:: Vector2D

property sqlength: float¶: Calculate the squared length of this vector.

x: float | int¶: Alias for field number 0

y: float | int¶: Alias for field number 1

capellambse.diagram.get_style(diagramclass, objectclass)¶

Fetch the default style for the given drawtype and styleclass.

The style is returned as a dict with key-value pairs as used by CSS inside SVG graphics.

All values contained in this dict are either of type str, or of a class whose str() representation results in a valid CSS value for its respective key – with one exception: color gradients.

Flat colors are represented using the RGB tuple subclass. Gradients are returned as a two-element list of RGBs the first one is the color at the top of the object, the second one at the bottom.

Parameters:

diagramclass (str | None) – The style class of the diagram.
objectclass (str) –
A packed str describing the element’s type and style class in the form:
```
Type.StyleClass
```
The type can be: Box, Edge. The style class can be any known style class.

Return type:

dict[str, Any]

capellambse.diagram.get_styleclass(obj)¶

Return the styleclass for an individual model object.

Parameters:: obj (ModelObject) – An object received from querying the High-Level API.
Returns:: A string used for styling and decorating given obj in a diagram representation.
Return type:: str

capellambse.diagram.line_intersect(line1, line2)¶

Calculate the point where line1 and line2 intersect.

Both lines are straight lines with infinite length that are defined by the given points.

Notes

The implementation is based on https://mathworld.wolfram.com/Line-LineIntersection.html.

Parameters:

line1 (tuple[tuple[float | int, float | int] | Sequence[float | int], tuple[float | int, float | int] | Sequence[float | int]])
line2 (tuple[tuple[float | int, float | int] | Sequence[float | int], tuple[float | int, float | int] | Sequence[float | int]])

Return type:

Vector2D

Submodules¶

capellambse.diagram.capstyle module¶

The color palette and default style definitions used by Capella.

capellambse.diagram.capstyle.COLORS: dict[str, RGB] = {'_CAP_Activity_Border_Orange': (91, 64, 64, 1.0), '_CAP_Activity_Orange': (247, 218, 116, 1.0), '_CAP_Activity_Orange_min': (255, 255, 197, 1.0), '_CAP_Actor_Blue': (198, 230, 255, 1.0), '_CAP_Actor_Blue_label': (0, 0, 0, 1.0), '_CAP_Actor_Blue_min': (218, 253, 255, 1.0), '_CAP_Actor_Border_Blue': (74, 74, 151, 1.0), '_CAP_Association_Color': (0, 0, 0, 1.0), '_CAP_ChoicePseudoState_Border_Gray': (0, 0, 0, 1.0), '_CAP_ChoicePseudoState_Color': (168, 168, 168, 1.0), '_CAP_Class_Border_Brown': (123, 105, 79, 1.0), '_CAP_Class_Brown': (232, 224, 210, 1.0), '_CAP_CombinedFragment_Gray': (242, 242, 242, 1.0), '_CAP_Component_Blue': (150, 177, 218, 1.0), '_CAP_Component_Blue_min': (195, 230, 255, 1.0), '_CAP_Component_Border_Blue': (74, 74, 151, 1.0), '_CAP_Component_Label_Blue': (74, 74, 151, 1.0), '_CAP_ConfigurationItem_Gray': (242, 238, 225, 1.0), '_CAP_ConfigurationItem_Gray_min': (249, 248, 245, 1.0), '_CAP_Datatype_Border_Gray': (103, 103, 103, 1.0), '_CAP_Datatype_Gray': (225, 223, 215, 1.0), '_CAP_Datatype_LightBrown': (232, 224, 210, 1.0), '_CAP_Entity_Gray': (221, 221, 200, 1.0), '_CAP_Entity_Gray_border': (69, 69, 69, 1.0), '_CAP_Entity_Gray_label': (0, 0, 0, 1.0), '_CAP_Entity_Gray_min': (249, 248, 245, 1.0), '_CAP_ExchangeItem_Pinkkish': (246, 235, 235, 1.0), '_CAP_FCD': (233, 243, 222, 1.0), '_CAP_FCinFCD_Green': (148, 199, 97, 1.0), '_CAP_InterfaceDataPackage_LightGray': (250, 250, 250, 1.0), '_CAP_Interface_Border_Reddish': (124, 61, 61, 1.0), '_CAP_Interface_Pink': (240, 221, 221, 1.0), '_CAP_Lifeline_Gray': (128, 128, 128, 1.0), '_CAP_MSM_Mode_Gray': (195, 208, 208, 1.0), '_CAP_MSM_Mode_Gray_min': (234, 239, 239, 1.0), '_CAP_MSM_State_Gray': (208, 208, 208, 1.0), '_CAP_MSM_State_Gray_min': (239, 239, 239, 1.0), '_CAP_Mode_Gray': (165, 182, 180, 1.0), '_CAP_Node_Yellow': (255, 252, 183, 1.0), '_CAP_Node_Yellow_Border': (123, 105, 79, 1.0), '_CAP_Node_Yellow_Label': (0, 0, 0, 1.0), '_CAP_Node_Yellow_min': (255, 255, 220, 1.0), '_CAP_OperationalRole_Purple': (203, 174, 200, 1.0), '_CAP_Operational_Process_Reference_Orange': (250, 239, 203, 1.0), '_CAP_PhysicalPort_Yellow': (255, 244, 119, 1.0), '_CAP_StateMode_Border_Gray': (117, 117, 117, 1.0), '_CAP_StateTransition_Color': (0, 0, 0, 1.0), '_CAP_State_Gray': (228, 228, 228, 1.0), '_CAP_Unit_LightBrown': (214, 197, 171, 1.0), '_CAP_Unset_Gray': (205, 205, 205, 1.0), '_CAP_Unset_Gray_min': (234, 234, 234, 1.0), '_CAP_Value_LightBrown': (254, 253, 250, 1.0), '_CAP_xAB_Activity_Label_Orange': (91, 64, 64, 1.0), '_CAP_xAB_Function_Border_Green': (9, 92, 46, 1.0), '_CAP_xAB_Function_Green': (197, 255, 166, 1.0), '_CAP_xAB_Function_Label_Green': (9, 92, 46, 1.0), '_CAP_xBD_ControlNode': (223, 223, 223, 1.0), '_CAP_xDFB_Function_Border_Green': (77, 137, 20, 1.0), '_CAP_xDFB_Function_Green': (197, 255, 166, 1.0), '_CAP_xDFB_Function_Green_Label': (0, 0, 0, 1.0), '_CAP_xDFB_Function_Green_min': (244, 255, 224, 1.0), '_CAP_xDF_Activity_Label_Orange': (0, 0, 0, 1.0), 'black': (0, 0, 0, 1.0), 'dark_gray': (69, 69, 69, 1.0), 'dark_orange': (224, 133, 3, 1.0), 'dark_purple': (114, 73, 110, 1.0), 'gray': (136, 136, 136, 1.0), 'light_purple': (217, 196, 215, 1.0), 'light_yellow': (255, 245, 181, 1.0), 'red': (239, 41, 41, 1.0), 'white': (255, 255, 255, 1.0)}¶: This dict maps the color names used by Capella to RGB tuples.

capellambse.diagram.capstyle.CSSdef¶

This dict contains the default styles that Capella applies, grouped by the diagram class they belong to.

The first level of keys are the diagrams’ styleclasses. The special key “__GLOBAL__” applies to all diagrams.

The second level contains the style definitions for each element that can appear in the diagram. The keys work in the following way:

Type.Class

Type is the element type; one of “Box” or “Edge” (note casing!)
Class is the element’s styleclass, e.g. “LogicalComponent”

The Class and the preceding dot may be absent, in which case that styling applies to all elements of that Type regardless of their style class.

The order of precedence for the four possible cases is the following, from most to least important:

Diagram class specific, element type and class
__GLOBAL__, element type and class
Diagram class specific, only element type
__GLOBAL__, only element type

alias of int | str | RGB | List[RGB] | None

class capellambse.diagram.capstyle.RGB¶

Bases: NamedTuple

A color.

a: float¶: Alias for field number 3

b: int¶: Alias for field number 2

classmethod fromcss(cssstring)¶

Create an RGB from a CSS color definition.

Examples of recognized color definitions and their equivalent constructor calls:

"rgb(10, 20, 30)" -> RGB(10, 20, 30)
"rgba(50, 60, 70, 0.5)" -> RGB(50, 60, 70, 0.5)
"#FF00FF" -> RGB(255, 0, 255)
"#ff00ff" -> RGB(255, 0, 255)
"#f0f" -> RGB(255, 0, 255)
"#FF00FF80" -> RGB(255, 0, 255, 0.5)
"#f0fa" -> RGB(255, 0, 255, 2/3)

Parameters:: cssstring (str | RGB)
Return type:: RGB

classmethod fromcsv(csvstring)¶

Create an RGB from a "r, g, b[, a]" string.

Parameters:: csvstring (str)
Return type:: RGB

classmethod fromhex(hexstring)¶

Create an RGB from a hexadecimal string.

Parameters:: hexstring (str)
Return type:: RGB

g: int¶: Alias for field number 1

r: int¶: Alias for field number 0

tohex()¶

Return type:: str

capellambse.diagram.capstyle.get_style(diagramclass, objectclass)¶

Fetch the default style for the given drawtype and styleclass.

The style is returned as a dict with key-value pairs as used by CSS inside SVG graphics.

All values contained in this dict are either of type str, or of a class whose str() representation results in a valid CSS value for its respective key – with one exception: color gradients.

Flat colors are represented using the RGB tuple subclass. Gradients are returned as a two-element list of RGBs the first one is the color at the top of the object, the second one at the bottom.

Parameters:

diagramclass (str | None) – The style class of the diagram.
objectclass (str) –
A packed str describing the element’s type and style class in the form:
```
Type.StyleClass
```
The type can be: Box, Edge. The style class can be any known style class.

Return type:

dict[str, Any]