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.
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¤
Methods:¤
draw_edges
¤
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
draw_loads
¤
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
draw_nodes
¤
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
draw_nodes_support
¤
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
FormDiagramObject
¤
A scene object that draws a form diagram in Grasshopper.
Attributes¤
Methods:¤
draw_reactions
¤
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
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_scaleapplies, 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
¤
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
Methods:¤
bake
¤
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
draw_meshes
¤
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
draw_wires
¤
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
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¤
Methods:¤
draw_edges_deviation
¤
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
draw_edges_trail
¤
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
draw_nodes_origin
¤
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
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
TopologyDrawing
¤
A topology diagram styled for drawing.
TopologyPreview
¤
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
Methods:¤
bake
¤
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
draw_wires
¤
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
Functions:¤
cross_lines
¤
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_SIZEof 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
edge_radii
¤
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
edge_widths
¤
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
form_drawing
¤
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
reaction_shifts
¤
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
topology_drawing
¤
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.