Skip to content

compas_cem.ghpython ¤

Grasshopper components and scene objects that draw diagrams inside Rhino.

Classes¤

AuxiliaryTrailSettings dataclass ¤

AuxiliaryTrailSettings(
    length: float = 1.0,
    state: float = -1.0,
    vector: tuple[float, float, float] = (-1.0, -1.0, -1.0),
)

The length, state and direction of every auxiliary trail in a topology.

Parameters:

  • length (float, default: 1.0 ) –

    The length of every auxiliary trail edge.

  • state (float, default: -1.0 ) –

    The sign of the force in every auxiliary trail edge: positive for tension, negative for compression.

  • vector (tuple[float, float, float], default: (-1.0, -1.0, -1.0) ) –

    The direction from a node to its auxiliary support in the topology.

Notes

The settings are a dataclass rather than a named tuple, because Grasshopper unpacks a tuple output into its items. The vector places the auxiliary supports in the topology only: the solver places each one along the residual force of its node, and the state decides on which side.

Attributes¤

signed_length property ¤
signed_length: float

The length of every auxiliary trail edge, signed by its state.

DiagramObject ¤

A scene object that draws a diagram in Grasshopper.

Notes

Every draw method takes an explicit selection, because the Grasshopper components expose the selection as a component input. Drawing returns bare Rhino geometry and carries no color, so the coloring is left to whatever consumes the geometry downstream.

Node positions are read from the scene object rather than from the diagram, so a transformation set on the object applies to everything it draws.

Attributes¤

diagram property ¤
diagram

The diagram this object draws.

Methods:¤

draw_edges ¤
draw_edges(edges=None)

Draw a selection of edges.

Parameters:

  • edges –

    The edges to draw. If None, every edge is drawn.

Returns:

  • lines –

    One Rhino line per drawn edge.

Source code in src/compas_cem/ghpython/scene_objects.py
def draw_edges(self, edges=None):
    """
    Draw a selection of edges.

    Parameters
    ----------
    edges :
        The edges to draw. If `None`, every edge is drawn.

    Returns
    -------
    lines :
        One Rhino line per drawn edge.
    """
    edges = self.diagram.edges() if edges is None else edges
    node_xyz = self.node_xyz

    return [line_to_rhino((node_xyz[u], node_xyz[v])) for u, v in edges]
draw_loads ¤
draw_loads(nodes=None, scale=1.0, gap=0.0, min_load=0.001)

Draw the loads applied to a selection of nodes.

Parameters:

  • nodes –

    The nodes to draw the loads of. If None, every node is taken.

  • scale –

    The factor to scale the load vectors by.

  • gap –

    The offset between a node and the load drawn at it.

  • min_load –

    The smallest load magnitude worth drawing.

Returns:

  • lines –

    One Rhino line per drawn load.

Notes

A load ends at its node, so the head of the line touches the node it loads, as in every other drawing of the diagram.

Source code in src/compas_cem/ghpython/scene_objects.py
def draw_loads(self, nodes=None, scale=1.0, gap=0.0, min_load=1e-3):
    """
    Draw the loads applied to a selection of nodes.

    Parameters
    ----------
    nodes :
        The nodes to draw the loads of. If `None`, every node is taken.
    scale :
        The factor to scale the load vectors by.
    gap :
        The offset between a node and the load drawn at it.
    min_load :
        The smallest load magnitude worth drawing.

    Returns
    -------
    lines :
        One Rhino line per drawn load.

    Notes
    -----
    A load ends at its node, so the head of the line touches the node it
    loads, as in every other drawing of the diagram.
    """
    nodes = list(self.diagram.nodes()) if nodes is None else list(nodes)
    shift = {node: True for node in nodes}

    return self._draw_forces(
        nodes=nodes,
        attr_names=["qx", "qy", "qz"],
        scale=scale,
        shift=shift,
        gap=gap,
        tol=min_load,
    )
draw_nodes ¤
draw_nodes(nodes=None)

Draw a selection of nodes.

Parameters:

  • nodes –

    The nodes to draw. If None, every node is drawn.

Returns:

  • points –

    One Rhino point per drawn node.

Source code in src/compas_cem/ghpython/scene_objects.py
def draw_nodes(self, nodes=None):
    """
    Draw a selection of nodes.

    Parameters
    ----------
    nodes :
        The nodes to draw. If `None`, every node is drawn.

    Returns
    -------
    points :
        One Rhino point per drawn node.
    """
    nodes = self.diagram.nodes() if nodes is None else nodes
    node_xyz = self.node_xyz

    return [point_to_rhino(node_xyz[node]) for node in nodes]
draw_nodes_support ¤
draw_nodes_support(nodes=None)

Draw a selection of the support nodes of the diagram.

Parameters:

  • nodes –

    The nodes to draw, of which only the supports are kept. If None, every support node is drawn.

Returns:

  • points –

    One Rhino point per drawn support node.

Source code in src/compas_cem/ghpython/scene_objects.py
def draw_nodes_support(self, nodes=None):
    """
    Draw a selection of the support nodes of the diagram.

    Parameters
    ----------
    nodes :
        The nodes to draw, of which only the supports are kept. If `None`,
        every support node is drawn.

    Returns
    -------
    points :
        One Rhino point per drawn support node.
    """
    nodes = self._selected_keys("support_nodes", "is_node_support", nodes)

    return self.draw_nodes(nodes)

FormDiagramObject ¤

A scene object that draws a form diagram in Grasshopper.

Attributes¤

form property ¤
form

The form diagram this object draws.

Methods:¤

draw_reactions ¤
draw_reactions(nodes=None, scale=1.0, gap=0.0, min_force=0.001)

Draw the reaction forces at a selection of support nodes.

Parameters:

  • nodes –

    The nodes to draw the reaction forces of. If None, every node is taken.

  • scale –

    The factor to scale the reaction forces by.

  • gap –

    The offset between a node and the reaction force drawn at it.

  • min_force –

    The smallest reaction force magnitude worth drawing.

Returns:

  • lines –

    One Rhino line per drawn reaction force.

Source code in src/compas_cem/ghpython/scene_objects.py
def draw_reactions(self, nodes=None, scale=1.0, gap=0.0, min_force=1e-3):
    """
    Draw the reaction forces at a selection of support nodes.

    Parameters
    ----------
    nodes :
        The nodes to draw the reaction forces of. If `None`, every node is
        taken.
    scale :
        The factor to scale the reaction forces by.
    gap :
        The offset between a node and the reaction force drawn at it.
    min_force :
        The smallest reaction force magnitude worth drawing.

    Returns
    -------
    lines :
        One Rhino line per drawn reaction force.
    """
    nodes = list(self.form.nodes()) if nodes is None else list(nodes)

    return self._draw_forces(
        nodes=nodes,
        attr_names=["rx", "ry", "rz"],
        scale=scale,
        shift=self._reaction_shifts(nodes),
        gap=gap,
        tol=min_force,
    )

FormDisplaySettings dataclass ¤

FormDisplaySettings(
    arrow_min: float = 0.001,
    arrow_scale: float = 1.0,
    width_min: float = 1.0,
    width_max: float = 8.0,
    radius_min: float = 0.01,
    radius_max: float = 0.1,
    thick_sides: int = 8,
    show_loads: bool = True,
    show_reactions: bool = True,
    show_forces: bool = False,
    show_keys: bool = False,
    decompose: bool = True,
)

The settings to draw a form diagram with in Grasshopper.

Parameters:

  • arrow_min (float, default: 0.001 ) –

    The smallest load or reaction magnitude to draw as an arrow, or the smallest component when the forces are decomposed. It is compared before arrow_scale applies, so the scale never hides an arrow.

  • arrow_scale (float, default: 1.0 ) –

    The factor that turns a load or reaction force into its arrow length.

  • width_min (float, default: 1.0 ) –

    The width in pixels of the edge with the smallest absolute force.

  • width_max (float, default: 8.0 ) –

    The width in pixels of the edge with the largest absolute force.

  • radius_min (float, default: 0.01 ) –

    The pipe radius in model units of the edge with the smallest absolute force, when the edges are thickened into pipes.

  • radius_max (float, default: 0.1 ) –

    The pipe radius in model units of the edge with the largest absolute force, when the edges are thickened into pipes. It is also the radius of the thickened nodes, so a node covers every pipe meeting it.

  • thick_sides (int, default: 8 ) –

    The number of faces around every thickened pipe, arrow and node sphere.

  • show_loads (bool, default: True ) –

    Whether to draw the loads.

  • show_reactions (bool, default: True ) –

    Whether to draw the reaction forces.

  • show_forces (bool, default: False ) –

    Whether to label every drawn edge with its force.

  • show_keys (bool, default: False ) –

    Whether to label every drawn node and edge with its key.

  • decompose (bool, default: True ) –

    Whether to draw every load and reaction force as its x, y and z components, an arrow each, rather than as one arrow.

Notes

The settings are a dataclass rather than a named tuple, because Grasshopper unpacks a tuple output into its items. Draw Form sets decompose and the visibility toggles from its own inputs.

FormDrawing ¤

A form diagram styled for drawing.

FormPreview ¤

FormPreview(drawing, is_thickened=False, thick_sides=8)

The Rhino geometry of a styled form diagram, ready to draw and to output.

Parameters:

  • drawing –

    The styled form diagram.

  • is_thickened –

    Whether the nodes are spheres, the edges pipes and the forces solid arrows, all meshes, rather than points and lines.

  • thick_sides –

    The number of faces around every thickened pipe, arrow and sphere.

Attributes:

  • node_objects –

    One model object per node: a colored point, or a colored sphere mesh when thickened.

  • support_objects –

    One model object per support node: a colored point, or a colored sphere mesh when thickened.

  • edge_objects –

    One model object per edge: a line with its color and plot weight, or a colored pipe mesh when thickened.

  • load_objects –

    One model object per load: a line with its color and plot weight, or a colored arrow mesh when thickened.

  • reaction_objects –

    One model object per reaction force: a line with its color and plot weight, or a colored arrow mesh when thickened.

  • clipping_box –

    The box that holds everything the preview draws.

Notes

The geometry is converted once per solution, so a viewport redraw only loops over Rhino objects; thickened meshes are merged into one mesh per color for drawing. The model objects carry the color and the plot weight of what is drawn, so baking them reproduces the preview, except for the arrowheads of force lines: Rhino 8 model objects drop curve decorations.

Source code in src/compas_cem/ghpython/diagram_preview.py
def __init__(self, drawing, is_thickened=False, thick_sides=8):
    document = Rhino.RhinoDoc.ActiveDoc
    styled_lines = drawing.edges + drawing.loads + drawing.reactions
    self._drawing = drawing
    self._is_thickened = is_thickened
    self._thick_sides = thick_sides

    self._lines = []
    self._points = []
    self._meshes = []
    if is_thickened:
        sides = thick_sides
        node_meshes = [_sphere_mesh(item, sides) for item in drawing.nodes]
        support_meshes = [
            _sphere_mesh(item, sides) for item in drawing.support_nodes
        ]
        edge_meshes = [_pipe_mesh(item, sides) for item in drawing.edges]
        load_meshes = [_arrow_mesh(item, sides) for item in drawing.loads]
        reaction_meshes = [_arrow_mesh(item, sides) for item in drawing.reactions]

        self.node_objects = _model_meshes(document, drawing.nodes, node_meshes)
        self.support_objects = _model_meshes(
            document, drawing.support_nodes, support_meshes
        )
        self.edge_objects = _model_meshes(document, drawing.edges, edge_meshes)
        self.load_objects = _model_meshes(document, drawing.loads, load_meshes)
        self.reaction_objects = _model_meshes(
            document, drawing.reactions, reaction_meshes
        )

        styled_items = drawing.nodes + styled_lines
        meshes = node_meshes + edge_meshes + load_meshes + reaction_meshes
        self._meshes = _preview_meshes(styled_items, meshes)
    else:
        self.node_objects = [_model_point(document, item) for item in drawing.nodes]
        self.support_objects = [
            _model_point(document, item) for item in drawing.support_nodes
        ]
        self.edge_objects = [_model_line(document, item) for item in drawing.edges]
        self.load_objects = [_model_line(document, item) for item in drawing.loads]
        self.reaction_objects = [
            _model_line(document, item) for item in drawing.reactions
        ]

        self._lines = [_preview_line(item) for item in styled_lines]
        self._points = [_preview_point(item) for item in drawing.nodes]

    self._labels = [_preview_label(item) for item in drawing.labels]

    self.clipping_box = _bounding_box(
        self._lines, self._meshes, self._points, self._labels
    )

Methods:¤

bake ¤
bake(document)

Add what the preview draws to a Rhino document, one sublayer per category under COMPAS CEM::Form.

Parameters:

  • document –

    The Rhino document to bake into.

Returns:

  • ids –

    The ids of the baked objects.

Notes

Lines bake with their colors and plot weights, and force lines with an arrowhead; thickened meshes bake with their colors. The support nodes, which repeat nodes, and the labels are not baked.

Source code in src/compas_cem/ghpython/diagram_preview.py
def bake(self, document):
    """
    Add what the preview draws to a Rhino document, one sublayer per
    category under `COMPAS CEM::Form`.

    Parameters
    ----------
    document :
        The Rhino document to bake into.

    Returns
    -------
    ids :
        The ids of the baked objects.

    Notes
    -----
    Lines bake with their colors and plot weights, and force lines with an
    arrowhead; thickened meshes bake with their colors. The support nodes,
    which repeat nodes, and the labels are not baked.
    """
    drawing = self._drawing
    groups = [
        ("Nodes", drawing.nodes),
        ("Edges", drawing.edges),
        ("Loads", drawing.loads),
        ("Reactions", drawing.reactions),
    ]
    if self._is_thickened:
        records = _mesh_records(groups, self._thick_sides)
    else:
        records = _line_records(groups)
    ids = _bake_records(document, "COMPAS CEM::Form", records)

    return ids
draw_meshes ¤
draw_meshes(display, selected_material=None)

Draw the thickened meshes of the preview in a viewport, shaded.

Parameters:

  • display –

    The display pipeline of the viewport.

  • selected_material –

    The material that marks a selected component. If None, every mesh is shaded in its own color.

Source code in src/compas_cem/ghpython/diagram_preview.py
def draw_meshes(self, display, selected_material=None):
    """
    Draw the thickened meshes of the preview in a viewport, shaded.

    Parameters
    ----------
    display :
        The display pipeline of the viewport.
    selected_material :
        The material that marks a selected component. If `None`, every
        mesh is shaded in its own color.
    """
    for mesh, material in self._meshes:
        shade = material if selected_material is None else selected_material
        display.DrawMeshShaded(mesh, shade)
draw_wires ¤
draw_wires(display, selected_color=None)

Draw the lines, their arrowheads, the nodes and the labels of the preview in a viewport.

Parameters:

  • display –

    The display pipeline of the viewport.

  • selected_color –

    The color that marks a selected component. If None, everything is drawn in its own color.

Notes

A force line ends in Rhino's own arrowhead, sized on screen, as Grasshopper draws a vector.

Source code in src/compas_cem/ghpython/diagram_preview.py
def draw_wires(self, display, selected_color=None):
    """
    Draw the lines, their arrowheads, the nodes and the labels of the
    preview in a viewport.

    Parameters
    ----------
    display :
        The display pipeline of the viewport.
    selected_color :
        The color that marks a selected component. If `None`, everything
        is drawn in its own color.

    Notes
    -----
    A force line ends in Rhino's own arrowhead, sized on screen, as
    Grasshopper draws a vector.
    """
    _draw_wires(display, self._lines, self._points, self._labels, selected_color)

StyledLine ¤

A line to draw, with its color, its width in pixels, its pipe radius in model units, whether it ends in an arrowhead, how far a thickened arrow moves along its own direction to clear the sphere of its node, whether it is dashed, and how far a thickened pipe stops short of each end.

StyledPoint ¤

A point to draw, with its color and its sphere radius in model units when thickened.

StyledPolyline ¤

A polyline to draw, with its color and its width in pixels.

TextLabel ¤

A text to draw at a point.

TopologyDiagramObject ¤

A scene object that draws a topology diagram in Grasshopper.

Attributes¤

topology property ¤
topology

The topology diagram this object draws.

Methods:¤

draw_edges_deviation ¤
draw_edges_deviation(edges=None)

Draw a selection of the deviation edges of the topology diagram.

Parameters:

  • edges –

    The edges to draw, of which only the deviations are kept. If None, every deviation edge is drawn.

Returns:

  • lines –

    One Rhino line per drawn deviation edge.

Source code in src/compas_cem/ghpython/scene_objects.py
def draw_edges_deviation(self, edges=None):
    """
    Draw a selection of the deviation edges of the topology diagram.

    Parameters
    ----------
    edges :
        The edges to draw, of which only the deviations are kept. If
        `None`, every deviation edge is drawn.

    Returns
    -------
    lines :
        One Rhino line per drawn deviation edge.
    """
    edges = self._selected_keys("deviation_edges", "is_deviation_edge", edges)

    return self.draw_edges(edges)
draw_edges_trail ¤
draw_edges_trail(edges=None)

Draw a selection of the trail edges of the topology diagram.

Parameters:

  • edges –

    The edges to draw, of which only the trails are kept. If None, every trail edge is drawn.

Returns:

  • lines –

    One Rhino line per drawn trail edge.

Source code in src/compas_cem/ghpython/scene_objects.py
def draw_edges_trail(self, edges=None):
    """
    Draw a selection of the trail edges of the topology diagram.

    Parameters
    ----------
    edges :
        The edges to draw, of which only the trails are kept. If `None`,
        every trail edge is drawn.

    Returns
    -------
    lines :
        One Rhino line per drawn trail edge.
    """
    edges = self._selected_keys("trail_edges", "is_trail_edge", edges)

    return self.draw_edges(edges)
draw_nodes_origin ¤
draw_nodes_origin(nodes=None)

Draw a selection of the origin nodes of the topology diagram.

Parameters:

  • nodes –

    The nodes to draw, of which only the origins are kept. If None, every origin node is drawn.

Returns:

  • points –

    One Rhino point per drawn origin node.

Source code in src/compas_cem/ghpython/scene_objects.py
def draw_nodes_origin(self, nodes=None):
    """
    Draw a selection of the origin nodes of the topology diagram.

    Parameters
    ----------
    nodes :
        The nodes to draw, of which only the origins are kept. If `None`,
        every origin node is drawn.

    Returns
    -------
    points :
        One Rhino point per drawn origin node.
    """
    nodes = self._selected_keys("origin_nodes", "is_node_origin", nodes)

    return self.draw_nodes(nodes)
draw_trails ¤
draw_trails()

Draw the trails of the topology diagram.

Returns:

  • curves –

    One Rhino polyline curve per trail.

Notes

A polyline curve is drawn rather than a polyline, because Grasshopper unpacks a bare polyline output into its points.

Source code in src/compas_cem/ghpython/scene_objects.py
def draw_trails(self):
    """
    Draw the trails of the topology diagram.

    Returns
    -------
    curves :
        One Rhino polyline curve per trail.

    Notes
    -----
    A polyline curve is drawn rather than a polyline, because Grasshopper
    unpacks a bare polyline output into its points.
    """
    node_xyz = self.node_xyz

    curves = []
    for trail in self.topology.trails():
        points = [node_xyz[node] for node in trail]
        curves.append(polyline_to_rhino_curve(points))

    return curves

TopologyDrawing ¤

A topology diagram styled for drawing.

TopologyPreview ¤

TopologyPreview(drawing)

The Rhino geometry of a styled topology diagram, ready to draw and to output.

Parameters:

  • drawing –

    The styled topology diagram.

Attributes:

  • node_objects –

    One model object per node, as a colored point.

  • origin_objects –

    One model object per origin node, as a colored point.

  • support_objects –

    One model object per support node, as a colored point.

  • edge_objects –

    One model object per edge, as a line with its color and plot weight.

  • trail_edge_objects –

    One model object per trail edge, as a line with its color and plot weight.

  • deviation_edge_objects –

    One model object per deviation edge, as a line with its color and plot weight.

  • trail_objects –

    One model object per trail, as a polyline with its color and plot weight.

  • load_objects –

    Two model objects per loaded node, the lines of its cross.

  • clipping_box –

    The box that holds everything the preview draws.

Notes

The preview draws the nodes, the edges, the load crosses and the labels; the subsets in the other outputs repeat them. Deviation edges are dashed in the viewport only, since baking a dashed linetype would add one to the document.

Source code in src/compas_cem/ghpython/diagram_preview.py
def __init__(self, drawing):
    document = Rhino.RhinoDoc.ActiveDoc
    self._drawing = drawing

    self.node_objects = [_model_point(document, item) for item in drawing.nodes]
    self.origin_objects = [
        _model_point(document, item) for item in drawing.origin_nodes
    ]
    self.support_objects = [
        _model_point(document, item) for item in drawing.support_nodes
    ]
    self.edge_objects = [_model_line(document, item) for item in drawing.edges]
    self.trail_edge_objects = [
        _model_line(document, item) for item in drawing.trail_edges
    ]
    self.deviation_edge_objects = [
        _model_line(document, item) for item in drawing.deviation_edges
    ]
    self.trail_objects = [
        _model_polyline(document, item) for item in drawing.trails
    ]
    self.load_objects = [_model_line(document, item) for item in drawing.loads]

    self._lines = [_preview_line(item) for item in drawing.edges]
    self._crosses = [_preview_line(item) for item in drawing.loads]
    self._points = [_preview_point(item) for item in drawing.nodes]
    self._labels = [_preview_label(item) for item in drawing.labels]

    box_lines = self._lines + self._crosses
    self.clipping_box = _bounding_box(box_lines, [], self._points, self._labels)

Methods:¤

bake ¤
bake(document)

Add what the preview draws to a Rhino document, one sublayer per category under COMPAS CEM::Topology.

Parameters:

  • document –

    The Rhino document to bake into.

Returns:

  • ids –

    The ids of the baked objects.

Notes

Lines bake with their colors and plot weights, and deviation edges with Rhino's dashed linetype. The origin and support nodes, which repeat nodes, the trails, which repeat trail edges, and the labels are not baked.

Source code in src/compas_cem/ghpython/diagram_preview.py
def bake(self, document):
    """
    Add what the preview draws to a Rhino document, one sublayer per
    category under `COMPAS CEM::Topology`.

    Parameters
    ----------
    document :
        The Rhino document to bake into.

    Returns
    -------
    ids :
        The ids of the baked objects.

    Notes
    -----
    Lines bake with their colors and plot weights, and deviation edges with
    Rhino's dashed linetype. The origin and support nodes, which repeat
    nodes, the trails, which repeat trail edges, and the labels are not
    baked.
    """
    drawing = self._drawing
    groups = [
        ("Nodes", drawing.nodes),
        ("Trail Edges", drawing.trail_edges),
        ("Deviation Edges", drawing.deviation_edges),
        ("Loads", drawing.loads),
    ]
    records = _line_records(groups)
    ids = _bake_records(document, "COMPAS CEM::Topology", records)

    return ids
draw_wires ¤
draw_wires(display, selected_color=None)

Draw the edges, the nodes, the labels and the load crosses of the preview in a viewport.

Parameters:

  • display –

    The display pipeline of the viewport.

  • selected_color –

    The color that marks a selected component. If None, everything is drawn in its own color.

Notes

The crosses are drawn last, over the nodes they mark, as the topology plotter draws them over its node markers.

Source code in src/compas_cem/ghpython/diagram_preview.py
def draw_wires(self, display, selected_color=None):
    """
    Draw the edges, the nodes, the labels and the load crosses of the
    preview in a viewport.

    Parameters
    ----------
    display :
        The display pipeline of the viewport.
    selected_color :
        The color that marks a selected component. If `None`, everything
        is drawn in its own color.

    Notes
    -----
    The crosses are drawn last, over the nodes they mark, as the topology
    plotter draws them over its node markers.
    """
    _draw_wires(display, self._lines, self._points, self._labels, selected_color)
    for item in self._crosses:
        line_color = item.color if selected_color is None else selected_color
        display.DrawLine(item.line, line_color, item.width)

Functions:¤

cross_lines ¤

cross_lines(diagram, nodes)

The two lines of the cross that marks every given node.

Parameters:

  • diagram –

    The diagram the nodes belong to, whose extent sizes the crosses.

  • nodes –

    The nodes to mark.

Returns:

  • lines –

    Two start and end point pairs per node, at right angles in the XY plane, each reaching LOAD_CROSS_SIZE of the diagram's bounding-box diagonal from the node.

Notes

Every engine that crosses the loaded nodes of a topology draws these lines, so the crosses match across them.

Source code in src/compas_cem/ghpython/diagram_display.py
def cross_lines(diagram, nodes):
    """
    The two lines of the cross that marks every given node.

    Parameters
    ----------
    diagram :
        The diagram the nodes belong to, whose extent sizes the crosses.
    nodes :
        The nodes to mark.

    Returns
    -------
    lines :
        Two start and end point pairs per node, at right angles in the XY
        plane, each reaching `LOAD_CROSS_SIZE` of the diagram's bounding-box
        diagonal from the node.

    Notes
    -----
    Every engine that crosses the loaded nodes of a topology draws these lines,
    so the crosses match across them.
    """
    diagonal = _diagram_diagonal(diagram)
    reach = LOAD_CROSS_SIZE * diagonal / sqrt(2.0)

    lines = []
    for node in nodes:
        x, y, z = diagram.node_coordinates(node)
        for sign in (1.0, -1.0):
            start = [x - reach, y - sign * reach, z]
            end = [x + reach, y + sign * reach, z]
            lines.append((start, end))

    return lines

edge_radii ¤

edge_radii(form, radius_min, radius_max)

The pipe radius to thicken every edge of a form diagram with.

Parameters:

  • form –

    The form diagram.

  • radius_min –

    The radius of the edge with the smallest absolute force.

  • radius_max –

    The radius of the edge with the largest absolute force.

Returns:

  • radii –

    A mapping of every edge to its radius.

Notes

The radii follow the same linear spread over the absolute edge forces as the widths do.

Source code in src/compas_cem/ghpython/diagram_display.py
def edge_radii(form, radius_min, radius_max):
    """
    The pipe radius to thicken every edge of a form diagram with.

    Parameters
    ----------
    form :
        The form diagram.
    radius_min :
        The radius of the edge with the smallest absolute force.
    radius_max :
        The radius of the edge with the largest absolute force.

    Returns
    -------
    radii :
        A mapping of every edge to its radius.

    Notes
    -----
    The radii follow the same linear spread over the absolute edge forces as
    the widths do.
    """
    ratios = _force_ratios(form)
    radii = _spread_ratios(ratios, radius_min, radius_max)

    return radii

edge_widths ¤

edge_widths(form, width_min, width_max)

The width to draw every edge of a form diagram with.

Parameters:

  • form –

    The form diagram.

  • width_min –

    The width of the edge with the smallest absolute force.

  • width_max –

    The width of the edge with the largest absolute force.

Returns:

  • widths –

    A mapping of every edge to its width.

Notes

The absolute edge forces are spread linearly over the width bounds across the whole diagram, so a selection keeps the widths it has in the full drawing. When every force has the same magnitude, every edge takes the largest width, as the plotter does.

Source code in src/compas_cem/ghpython/diagram_display.py
def edge_widths(form, width_min, width_max):
    """
    The width to draw every edge of a form diagram with.

    Parameters
    ----------
    form :
        The form diagram.
    width_min :
        The width of the edge with the smallest absolute force.
    width_max :
        The width of the edge with the largest absolute force.

    Returns
    -------
    widths :
        A mapping of every edge to its width.

    Notes
    -----
    The absolute edge forces are spread linearly over the width bounds across
    the whole diagram, so a selection keeps the widths it has in the full
    drawing. When every force has the same magnitude, every edge takes the
    largest width, as the plotter does.
    """
    ratios = _force_ratios(form)
    widths = _spread_ratios(ratios, width_min, width_max)

    return widths

form_drawing ¤

form_drawing(form, node_keys, edge_keys, settings)

Style a selection of a form diagram for drawing.

Parameters:

  • form –

    The form diagram to draw.

  • node_keys –

    The nodes to draw, with their loads and reaction forces. If None, every node is drawn.

  • edge_keys –

    The edges to draw. If None, every edge is drawn.

  • settings –

    The display settings.

Returns:

  • drawing –

    The styled nodes, support nodes, edges, loads, reaction forces, and the labels. A category the settings hide is empty.

Notes

Every node is colored by whether it is a support, so the support nodes are drawn twice, once among the nodes and once on their own. A load arrow always ends at its node, so its head touches the node it loads; a reaction ends at its support only when it pushes into it. An edge shown with both its key and its force gets one label, u-v: force, so the two never overlap.

Source code in src/compas_cem/ghpython/diagram_display.py
def form_drawing(form, node_keys, edge_keys, settings):
    """
    Style a selection of a form diagram for drawing.

    Parameters
    ----------
    form :
        The form diagram to draw.
    node_keys :
        The nodes to draw, with their loads and reaction forces. If `None`,
        every node is drawn.
    edge_keys :
        The edges to draw. If `None`, every edge is drawn.
    settings :
        The display settings.

    Returns
    -------
    drawing :
        The styled nodes, support nodes, edges, loads, reaction forces, and the
        labels. A category the settings hide is empty.

    Notes
    -----
    Every node is colored by whether it is a support, so the support nodes are
    drawn twice, once among the nodes and once on their own. A load arrow
    always ends at its node, so its head touches the node it loads; a reaction
    ends at its support only when it pushes into it. An edge shown with both
    its key and its force gets one label, `u-v: force`, so the two never
    overlap.
    """
    nodes = list(form.nodes()) if node_keys is None else list(node_keys)
    edges = list(form.edges()) if edge_keys is None else list(edge_keys)
    supports = [node for node in nodes if form.is_node_support(node)]

    sphere_radius = settings.radius_max
    node_points = [_styled_node(form, node, sphere_radius) for node in nodes]
    support_points = [_styled_node(form, node, sphere_radius) for node in supports]

    ratios = _force_ratios(form)
    widths = _spread_ratios(ratios, settings.width_min, settings.width_max)
    radii = _spread_ratios(ratios, settings.radius_min, settings.radius_max)
    edge_lines = []
    for edge in edges:
        key = tuple(edge)
        line = _styled_edge(form, edge, widths[key], radii[key], sphere_radius)
        edge_lines.append(line)

    loads = []
    if settings.show_loads:
        load_shifts = {node: True for node in nodes}
        loads = _force_lines(form, nodes, "load", load_shifts, settings)

    reactions = []
    if settings.show_reactions:
        shifts = reaction_shifts(form, nodes)
        reactions = _force_lines(form, nodes, "support_force", shifts, settings)

    labels = _form_labels(form, nodes, edges, settings)

    drawing = FormDrawing(
        nodes=node_points,
        support_nodes=support_points,
        edges=edge_lines,
        loads=loads,
        reactions=reactions,
        labels=labels,
    )

    return drawing

reaction_shifts ¤

reaction_shifts(form, nodes)

Whether the reaction force at every node points back into its trail.

Parameters:

  • form –

    The form diagram.

  • nodes –

    The nodes to decide the shift of.

Returns:

  • shifts –

    A mapping of nodes to whether the reaction force is shifted.

Notes

A reaction is shifted when the strongest edge meeting the node is in compression, so the force reads as pushing against the support rather than pulling away from it. A node with no connected edge is never shifted, which also keeps the strongest-edge search off an empty set.

TODO: needs a more robust check for orientation. What is wanted is to know whether the force needs a full shift.

Source code in src/compas_cem/ghpython/diagram_display.py
def reaction_shifts(form, nodes):
    """
    Whether the reaction force at every node points back into its trail.

    Parameters
    ----------
    form :
        The form diagram.
    nodes :
        The nodes to decide the shift of.

    Returns
    -------
    shifts :
        A mapping of nodes to whether the reaction force is shifted.

    Notes
    -----
    A reaction is shifted when the strongest edge meeting the node is in
    compression, so the force reads as pushing against the support rather
    than pulling away from it. A node with no connected edge is never
    shifted, which also keeps the strongest-edge search off an empty set.

    TODO: needs a more robust check for orientation. What is wanted is to
    know whether the force needs a full shift.
    """
    shifts = {}
    for node in nodes:
        forces = [form.edge_force(edge) for edge in form.node_connected_edges(node)]
        if not forces:
            shifts[node] = False
            continue
        shifts[node] = max(forces, key=fabs) < 0.0

    return shifts

topology_drawing ¤

topology_drawing(topology, node_keys, edge_keys, show_keys)

Style a selection of a topology diagram for drawing.

Parameters:

  • topology –

    The topology diagram to draw.

  • node_keys –

    The nodes to draw, with the crosses of the loaded ones. If None, every node is drawn.

  • edge_keys –

    The edges to draw. If None, every edge is drawn.

  • show_keys –

    Whether to label the drawn nodes and edges with their keys.

Returns:

  • drawing –

    The styled nodes, origin nodes, support nodes, edges, trail edges, deviation edges, trails, load crosses, and the key labels when shown.

Notes

The colors follow the topology plotter's defaults: nodes by type, and edges by the state their length or force sets, with auxiliary trails apart. Deviation edges are always dashed. A loaded node is marked with a cross of two lines at right angles in the XY plane, each reaching LOAD_CROSS_SIZE of the diagram's bounding-box diagonal from the node. Every trail is drawn whole, whatever the edge selection.

Source code in src/compas_cem/ghpython/diagram_display.py
def topology_drawing(topology, node_keys, edge_keys, show_keys):
    """
    Style a selection of a topology diagram for drawing.

    Parameters
    ----------
    topology :
        The topology diagram to draw.
    node_keys :
        The nodes to draw, with the crosses of the loaded ones. If `None`,
        every node is drawn.
    edge_keys :
        The edges to draw. If `None`, every edge is drawn.
    show_keys :
        Whether to label the drawn nodes and edges with their keys.

    Returns
    -------
    drawing :
        The styled nodes, origin nodes, support nodes, edges, trail edges,
        deviation edges, trails, load crosses, and the key labels when shown.

    Notes
    -----
    The colors follow the topology plotter's defaults: nodes by type, and
    edges by the state their length or force sets, with auxiliary trails
    apart. Deviation edges are always dashed. A loaded node is marked with a
    cross of two lines at right angles in the XY plane, each reaching
    `LOAD_CROSS_SIZE` of the diagram's bounding-box diagonal from the node.
    Every trail is drawn whole, whatever the edge selection.
    """
    nodes = list(topology.nodes()) if node_keys is None else list(node_keys)
    edges = list(topology.edges()) if edge_keys is None else list(edge_keys)

    node_points = [_topology_node(topology, node) for node in nodes]
    node_styles = list(zip(nodes, node_points))
    origin_points = [
        point for node, point in node_styles if topology.is_node_origin(node)
    ]
    support_points = [
        point for node, point in node_styles if topology.is_node_support(node)
    ]

    auxiliary_trails = {tuple(trail) for trail in topology.auxiliary_trails()}
    edge_lines = [_topology_edge(topology, edge, auxiliary_trails) for edge in edges]
    edge_styles = list(zip(edges, edge_lines))
    trail_lines = [line for edge, line in edge_styles if topology.is_trail_edge(edge)]
    deviation_lines = [
        line for edge, line in edge_styles if topology.is_deviation_edge(edge)
    ]
    trails = _topology_trails(topology, auxiliary_trails)

    loaded_nodes = set(topology.loaded_nodes())
    crossed_nodes = [node for node in nodes if node in loaded_nodes]
    crosses = _load_crosses(topology, crossed_nodes)

    labels = []
    if show_keys:
        labels = _key_labels(topology, nodes, edges)

    drawing = TopologyDrawing(
        nodes=node_points,
        origin_nodes=origin_points,
        support_nodes=support_points,
        edges=edge_lines,
        trail_edges=trail_lines,
        deviation_edges=deviation_lines,
        trails=trails,
        loads=crosses,
        labels=labels,
    )

    return drawing