CommunicationLayer

class CommunicationLayer

A CommunicationLayer acts as the primary interface between Shape Machine and another program. This allows Shape Machine to act as a black box not tied to any specific program.

A CommunicationLayer should keep track of all geometry currently included in the current design processed upon by Shape Machine. This allows the engine to modify all of the current design with delete_current_design() and with replace_current_design().

The data type of the current design should be program-specific, allowing for simple access for deletion and selection.

Attributes

dynamic_evaluation_context

Dictionary used as globals() when evaluating Evaluatable expressions and executing Executable scripts.

Methods

`delete_current_design`	Delete the current design tracked by this `CommunicationLayer`.
`delete_shape`	Delete a specific shape.
`get_user_choice`	Ask the user to select a choice from a list of choices.
`get_user_float`	Ask the user to provide a real number input.
`get_user_int`	Ask the user to provide an integer input.
`get_user_string`	Ask the user to provide a string input.
`import_program`	Import a `Program` that can then be used by the engine.
`import_rule`	Import a `Rule` that can then be used by the engine.
`import_rule_sequence`	Import a `RuleSequence` that can then be used by the engine.
`import_shape`	Import geometry from the program and convert it into a `Shape` to be used by Shape Machine.
`output_shape`	Output a `Shape` to the program.
`plot_shapes`	Output multiple `Shape` objects to the program.
`print_string`	Print a string to display to the user.
`recolor_shape`	Replace the color of each element in a `Shape` with a new color.
`replace_current_design`	Replaced the current design tracked by this `CommunicationLayer` with a new `Shape`.
`select_match`	Prompt the user to select a match during searching.

abstract delete_current_design(): Delete the current design tracked by this CommunicationLayer. The current design is updated by import_shape(), output_shape(), and plot_shapes().

abstract delete_shape(shape: Any): Delete a specific shape. The input parameter is the program-specific representation of the current design and geometry outputted by output_shape(), plot_shapes(), and replace_current_design().

abstract get_user_choice(message: str, choices: List[str], default: int = None) → int

Ask the user to select a choice from a list of choices.

Parameters:

message – Message to display to the user.
choices – List of options to choose from.
default – If provided, which choice’s index to use as the default.

Returns:

The index of the selected choice.

abstract get_user_float(message: str, default: float = None, minimum: float = None, maximum: float = None) → float

Ask the user to provide a real number input.

Parameters:

message – Message to display to the user.
default – If provided, a real number to use as the default.
minimum – If provided, a minimum value (inclusive) to restrict the input to.
maximum – If provided, a maximum value (inclusive) to restrict the input to.

Returns:

The real number provided by the user.

abstract get_user_int(message: str, default: int = None, minimum: int = None, maximum: int = None) → int

Ask the user to provide an integer input.

Parameters:

message – Message to display to the user.
default – If provided, an integer to use as the default.
minimum – If provided, a minimum value (inclusive) to restrict the input to.
maximum – If provided, a maximum value (inclusive) to restrict the input to.

Returns:

The integer provided by the user.

abstract get_user_string(message: str, default: str = None) → str

Ask the user to provide a string input.

Parameters:

message – Message to display to the user.
default – If provided, a string to use as the default.

Returns:

The string provided by the user.

abstract import_program() → Program: Import a Program that can then be used by the engine.

abstract import_rule() → Rule: Import a Rule that can then be used by the engine.

abstract import_rule_sequence() → RuleSequence: Import a RuleSequence that can then be used by the engine.

abstract import_shape(*, include_in_current_design: bool = True) → Shape

Import geometry from the program and convert it into a Shape to be used by Shape Machine.

Parameters:: include_in_current_design – If True, consider the included geometry as part of the current design so that it can be on by the engine using delete_current_design() and replace_current_design().
Returns:: The Shape representing the imported geometry.

abstract output_shape(shape: Shape, offset: ndarray[3] = array([0., 0., 0.]), *, select: bool = False, include_in_current_design: bool = True) → Any

Output a Shape to the program.

Parameters:

shape – The geometry to output.
offset – Any offset to apply to the shape prior to output. This could be applied directly to the shape itself or through functionality in the application.
select – If True, output the geometry and then select it (implementation-specific as to what “select it” means). Used in a SearchRule when separating found geometry from what’s left.
include_in_current_design – If True, consider the included geometry as part of the current design so that it can be on by the engine using delete_current_design() and replace_current_design().

Returns:

The program-specific representation of the outputted geometry. This can later be used by delete_shape().

abstract plot_shapes(shapes: Iterable[Shape], offset: ndarray[3] = array([0., 0., 0.]), *, include_in_current_design: bool = False) → Any

Output multiple Shape objects to the program. How to plot the shapes is implementation-specific. In a CAD software, you could output each shape in a grid; in a gif, you could output each shape as its own frame. This can be used after running a RuleSequence or Program to show the rule application history.

Parameters:

shapes – An iterable that provides geometry to output.
offset – Any uniform offset to apply to the shapes prior to output. This could be applied directly to the shapes themselves or through functionality in the application.
include_in_current_design – If True, consider the included geometry as part of the current design so that it can be on by the engine using delete_current_design() and replace_current_design().

Returns:

The program-specific representation of the outputted geometry. This can later be used by delete_shape().

abstract print_string(*objects, sep=' ', end='\n'): Print a string to display to the user.

abstract recolor_shape(shape: Shape, color: Tuple[int, int, int, int]) → Shape

Replace the color of each element in a Shape with a new color. Because ElementAttributes allows for CommunicationLayer-specific implementations, this allows for batch-recoloring by the engine.

The color is provided as an integer (0-255) RGBA tuple.

abstract replace_current_design(shape: Shape, offset: ndarray[3] = array([0., 0., 0.])) → Any

Replaced the current design tracked by this CommunicationLayer with a new Shape. The current design is updated by import_shape(), output_shape(), and plot_shapes().

Parameters:

shape – The shape to replace the current design with.
offset – Any offset to apply to the shape prior to output. This could be applied directly to the shape itself or through functionality in the application.

Returns:

The program-specific representation of the outputted geometry. This can later be used by delete_shape().

abstract select_match(distinct_matches: List[MatchData], to_design: ndarray = array([0., 0., 0.])) → Transformation | Literal['all', 'enum_matches'] | None

Prompt the user to select a match during searching.

Parameters:

distinct_matches – List of MatchData representing matches to choose from.
to_design – A vector representing the actual position of the design in the model file. See: to_design.

Returns:

The selected transformation, “all” (if all matches selected), “enum_matches” (if matches are to be enumerated), or None (if no match selected).

dynamic_evaluation_context: dict

Dictionary used as globals() when evaluating Evaluatable expressions and executing Executable scripts. This allows for variables set be dynamically executable code to be used during dynamic evaluation.

Some global variables are prepopulated:

communication_layer and comm are populated with this CommunicationLayer instance.
If this CommunicationLayer is provided to the constructor of ShapeMachine, engine is populated with that ShapeMachine instance.
print is replaced with this instance’s print_string().