mahautils.shapes.Canvas#

class mahautils.shapes.Canvas(*layers: Layer, name: str | None = None, print_multiline: bool = True)#

Bases: TypedListWithID[Layer]

An object for storing a set of layers

A Canvas is intended to store a set of related layers, allowing more complex, multi-shape geometries to be constructed. For instance, one potential application would be to use two Layer objects to store the disjoint polygons corresponding to the high-pressure ports and the low-pressure ports in an axial piston pump, and then to group these layers at each instant in time in a Canvas. Then, multiple Canvas objects could be used to store layers for every time step in the simulation.

The Canvas inherits from Python’s MutableSequence type, so most operations that can be performed for a Python list (append, pop, insert, etc.) are valid operations for a Canvas.

Attributes

`name`	A descriptive name to identify the canvas
`num_layers`	The number of layers in the canvas

Methods

`__init__`(*layers[, name, print_multiline])	Creates a new canvas to store layers
`plot`([units, figure, show, return_fig])	Plots the shapes in the canvas
`reflect`(pntA, pntB)	Reflects all shapes in all layers of the canvas about a line specified by two points
`reflect_x`()	Reflects all shapes in all layers of the canvas about the \(x\)-axis
`reflect_y`()	Reflects all shapes in all layers of the canvas about the \(y\)-axis
`rotate`(center, angle[, angle_units])	Rotates all shapes in all layers of the canvas a given angle in the \(xy\)-plane about a user-specified point
`translate`([x, y])	Translates all shapes in all layers of the canvas a user-specified distance in the \(x\)- and/or \(y\)-directions

Inherited Attributes

`id`	A unique class instance identification number
`list_type`	The required type of all items in the list
`multiline_padding`	The number of spaces on either side of the list of items in the list when displaying the list's string representation in multiline format
`print_multiline`	Whether to display the object's string representation in multiline format

Inherited Methods

`append`(value)	S.append(value) -- append value to the end of the sequence
`clear`()
`count`(value)
`extend`(values)	S.extend(iterable) -- extend sequence by appending elements from the iterable
`index`(value, [start, [stop]])	Raises ValueError if the value is not present.
`insert`(index, value)	Inserts a value at a given index in the list
`pop`([index])	Raise IndexError if list is empty or index is out of range.
`remove`(value)	S.remove(value) -- remove first occurrence of value.
`reverse`()	S.reverse() -- reverse IN PLACE

__init__(*layers: Layer, name: str | None = None, print_multiline: bool = True) → None#

Creates a new canvas to store layers

Creates a new Canvas object in which a set of Layer objects can be stored.

Parameters:

*layers (Layer, optional) – Layers to add to the canvas after the canvas is created (default is to add no layers)
name (str, optional) – A descriptive name to identify the canvas. If not provided, the canvas name is generated automatically
print_multiline (bool, optional) – Whether to return a printable string representation of the list in multiline format (default is True). Multiline format places each item in the list on its own line

property name: str#: A descriptive name to identify the canvas

property num_layers: int#: The number of layers in the canvas

plot(units: str | None = None, figure: Figure | None = None, show: bool = True, return_fig: bool = False) → Figure | None#

Plots the shapes in the canvas

Creates a Plotly figure illustrating the shapes in all layers of the canvas, or optionally appends traces for each shape to an existing figure. The figure can be opened in a browser (default behavior) and/or returned (to allow subsequent user-specific customizations).

Parameters:

units (str, optional) – If units are provided, it will be verified that all plotted shapes have these units in their Shape2D.units attribute (default is None, which performs no unit checks). Additionally, if the figure argument was not provided, the specified units will be included in the axis titles
figure (go.Figure, optional) – A Plotly figure. If provided, rather than creating a new figure from scratch, the layer’s shapes will be added as new traces in the provided figure (default is None, which creates a new figure from scratch)
show (bool, optional) – Whether to open the figure in a browser (default is True)
return_fig (bool, optional) – Whether to return the figure (default is False)

Returns:

A Plotly figure depicting the canvas. Returned if and only if return_fig is True

Return type:

go.Figure

Reflects all shapes in all layers of the canvas about a line specified by two points

Parameters:

pntA (list or tuple or CartesianPoint2D) – One point on the line across which the shape is to be reflected
pntB (list or tuple or CartesianPoint2D) – Another point on the line across which the shape is to be reflected

reflect_x() → None#: Reflects all shapes in all layers of the canvas about the \(x\)-axis

reflect_y() → None#: Reflects all shapes in all layers of the canvas about the \(y\)-axis

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

clear() → None -- remove all items from S#

count(value) → integer -- return number of occurrences of value#

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

property id: int#: A unique class instance identification number

index(value[, start[, stop]]) → integer -- return first index of value.#

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index: int, value: T)#: Inserts a value at a given index in the list

property list_type: Type[T]#: The required type of all items in the list

property multiline_padding: int#: The number of spaces on either side of the list of items in the list when displaying the list’s string representation in multiline format

pop([index]) → item -- remove and return item at index (default last).#: Raise IndexError if list is empty or index is out of range.

property print_multiline: bool#: Whether to display the object’s string representation in multiline format

remove(value)#: S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()#: S.reverse() – reverse IN PLACE

rotate(center: List[float] | Tuple[float, float] | ndarray | CartesianPoint2D, angle: float, angle_units: str = 'rad') → None#

Rotates all shapes in all layers of the canvas a given angle in the \(xy\)-plane about a user-specified point

Parameters:

center (list or tuple or CartesianPoint2D) – The center of rotation about which to rotate the shapes
angle (float) – The angle by which to rotate the shapes about center
angle_units (str, optional) – The units (radians or degrees) of the angle argument. Must be either 'rad' or 'deg' (default is 'rad')

translate(x: float = 0, y: float = 0) → None#

Translates all shapes in all layers of the canvas a user-specified distance in the \(x\)- and/or \(y\)-directions

Parameters:

x (float, optional) – The distance to translate the shapes in the \(x\)-direction (default is 0)
y (float, optional) – The distance to translate the shapes in the \(y\)-direction (default is 0)