Flat¶

Statically typed 2D shape constructors and backend-neutral flat shape facade

Statically typed 2D shape constructors and backend-neutral flat shape facade.

class pybosl2.flat.Flat(*args, **kwargs)[source]¶

Bases: Shape, Protocol

A 2-D shape: Shape plus what only two dimensions can do.

Everything shared with solids — the backend tag, the boolean operators, the transforms, bounds() and show() — is declared once on Shape (SPEC C-15, C-18). What is left here is the way up into three dimensions (SPEC C-17).

bounds()[source]¶

Return the 2-D axis-aligned bounding box (SPEC S-2b).

Return type:¶: Bounds2D

rotate(a)[source]¶

Rotate this shape a degrees about Z.

Parameters:¶

a : float | Sequence[float]¶: The rotation angle in degrees.

Return type:¶

Flat

linear_extrude(height, **kwargs)[source]¶

Extrude this 2-D shape into a 3-D solid.

Parameters:¶

height : float¶: Height of the extrusion.
**kwargs : Any¶: Options the active backend’s extruder declares.

Return type:¶

Solid

rotate_extrude(*args, **kwargs)[source]¶

Revolve this 2-D shape about the Z axis into a solid.

Parameters:¶

args : Any¶
kwargs : Any¶

Return type:¶

Solid

offset(*args, **kwargs)[source]¶

Return this outline grown or shrunk by a distance.

Parameters:¶

args : Any¶
kwargs : Any¶

Return type:¶

Self

hull(*others, **kwargs)[source]¶

Return the convex hull of this shape and any others.

Parameters:¶

others : Any¶
kwargs : Any¶

Return type:¶

Self

fill()[source]¶

Return this outline with its interior holes closed.

Declared because both 2-D implementations have it (SPEC C-20). Note that fill is listed in CSG_ONLY_FEATURES while the SDF implementation meshes the field, crosses to CSG and comes back — a refusal that never fires (SPEC §12.2, PLAN B-P4).

Return type:¶: Self

xflip(*args, **kwargs)[source]¶

Mirror this shape across the YZ plane.

Parameters:¶

args : Any¶
kwargs : Any¶

Return type:¶

Self

yflip(*args, **kwargs)[source]¶

Mirror this shape across the XZ plane.

Parameters:¶

args : Any¶
kwargs : Any¶

Return type:¶

Self

pybosl2.flat.circle(radius=None, diameter=None, *, points=None, corner=None, anchor=Anchor.CENTER, spin=0, placement=None, fn=None, fa=None, fs=None, res=None)[source]¶

Return a circle on the active backend.

Creates a 2D circle with the specified parameters.

Parameters:¶

radius : float | None¶: Radius of the circle.
diameter : float | None¶: Diameter of the circle.
points : Path2D | None¶: Three 2-D points the circle should pass through.
corner : Sequence[Sequence[float]] | None¶: Three 2-D points defining a path the circle should be tangent to.
anchor : Anchor | Sequence[float]¶: Anchor point.
spin : float¶: Z-axis rotation in degrees after anchor.
placement : Placement | None¶: Anchor and spin as one reusable value (SPEC G-1). A placement that also sets orient raises here: the plane has no third axis to turn a face towards (SPEC E-5).
fn : int | None¶: Arc smoothness overrides (CSG backend only). Omitted, the ambient use_defaults(fn=...) value applies; fn=0 opts back out to fa/fs.
fa : float | None¶: Arc smoothness overrides (CSG backend only). Omitted, the ambient use_defaults(fa=...) value applies.
fs : float | None¶: Arc smoothness overrides (CSG backend only). Omitted, the ambient use_defaults(fs=...) value applies.
res : int | None¶: SDF backend’s resolution (SDF backend only). Omitted, the ambient use_defaults(res=...) value applies.

Returns:¶

A 2-D flat shape representing a circle.

Return type:¶

Flat

Examples

from pybosl2.flat import circle
circle(radius=15).linear_extrude(height=5).show()

Loading 3-D preview…

⬇ Download STL mesh

pybosl2.flat.ellipse(radius=None, diameter=None, *, realign=False, anchor=Anchor.CENTER, spin=0, placement=None, fn=None, fa=None, fs=None, res=None)[source]¶

Return an ellipse on the active backend.

Parameters:¶

radius : float | Sequence[float] | None¶: Radius, or a per-axis pair.
diameter : float | Sequence[float] | None¶: Diameter, or a per-axis pair.
realign : bool¶: Rotate by half a segment so a flat faces +X (CSG backend only).
anchor : Anchor | Sequence[float]¶: Anchor point.
spin : float¶: Z-axis rotation in degrees after anchor (CSG backend only).
placement : Placement | None¶: Anchor and spin as one reusable value (SPEC G-1). A placement that also sets orient raises here: the plane has no third axis to turn a face towards (SPEC E-5).
fn : int | None¶: Arc smoothness override (CSG backend only). Omitted, the ambient use_defaults(fn=...) value applies; fn=0 opts back out to fa/fs.
fa : float | None¶: Arc smoothness override (CSG backend only). Omitted, the ambient use_defaults(fa=...) value applies.
fs : float | None¶: Arc smoothness override (CSG backend only). Omitted, the ambient use_defaults(fs=...) value applies.
res : int | None¶: Sampling resolution (SDF backend only). Omitted, the ambient use_defaults(res=...) value applies.

Returns:¶

A 2-D shape on whichever backend is active.

Return type:¶

Flat

Examples

from pybosl2.flat import ellipse
ellipse(radius=[20, 10]).linear_extrude(height=4).show()

Loading 3-D preview…

⬇ Download STL mesh

pybosl2.flat.regular_ngon(sides=6, radius=None, *, diameter=None, outer_radius=None, outer_diameter=None, rounding=0, realign=False, anchor=Anchor.CENTER, spin=0, placement=None, fn=None, fa=None, fs=None, res=None)[source]¶

Return a regular polygon on the active backend.

Parameters:¶

sides : int¶: Number of sides.
radius : float | None¶: Radius to a vertex.
diameter : float | None¶: Diameter to a vertex, instead of radius.
outer_radius : float | None¶: Radius of the circumscribed circle.
outer_diameter : float | None¶: Diameter of the circumscribed circle.
rounding : float¶: Corner rounding radius (CSG backend only).
realign : bool¶: Rotate by half a side (CSG backend only).
anchor : Anchor | Sequence[float]¶: Anchor point.
spin : float¶: Z-axis rotation in degrees after anchor (CSG backend only).
placement : Placement | None¶: Anchor and spin as one reusable value (SPEC G-1). A placement that also sets orient raises here: the plane has no third axis to turn a face towards (SPEC E-5).
fn : int | None¶: Fragment count for the rounded corners; ambient default when omitted. Omitted, the ambient use_defaults(fn=...) value applies; fn=0 opts back out to fa/fs.
fa : float | None¶: Minimum fragment angle for the rounded corners. Omitted, the ambient use_defaults(fa=...) value applies.
fs : float | None¶: Minimum fragment size for the rounded corners. Omitted, the ambient use_defaults(fs=...) value applies.
res : int | None¶: Sampling resolution (SDF backend only). Omitted, the ambient use_defaults(res=...) value applies.

Returns:¶

A 2-D shape on whichever backend is active.

Raises:¶

UnsupportedByBackendError – If rounding is asked for on the SDF backend, which has no rounded-corner ngon.

Return type:¶

Flat

Examples

from pybosl2.flat import regular_ngon
regular_ngon(sides=7, radius=15).linear_extrude(height=4).show()

Loading 3-D preview…

⬇ Download STL mesh

pybosl2.flat.star(tips=5, radius=None, inner_radius=None, *, diameter=None, inner_diameter=None, step=None, realign=False, anchor=Anchor.CENTER, spin=0, placement=None, res=None)[source]¶

Return a star on the active backend.

Parameters:¶

tips : int¶: Number of points.
radius : float | None¶: Outer radius (to the tips).
inner_radius : float | None¶: Inner radius (to the valleys).
diameter : float | None¶: Outer diameter, instead of radius.
inner_diameter : float | None¶: Inner diameter, instead of inner_radius.
step : int | None¶: Skip-count star form, instead of an inner radius (CSG backend only).
realign : bool¶: Rotate by half a point (CSG backend only).
anchor : Anchor | Sequence[float]¶: Anchor point.
spin : float¶: Z-axis rotation in degrees after anchor (CSG backend only).
placement : Placement | None¶: Anchor and spin as one reusable value (SPEC G-1). A placement that also sets orient raises here: the plane has no third axis to turn a face towards (SPEC E-5).
res : int | None¶: Sampling resolution (SDF backend only). Omitted, the ambient use_defaults(res=...) value applies.

Returns:¶

A 2-D shape on whichever backend is active.

Return type:¶

Flat

Examples

from pybosl2.flat import star
star(tips=6, radius=20, inner_radius=9).linear_extrude(height=4).show()

Loading 3-D preview…

⬇ Download STL mesh

pybosl2.flat.trapezoid(height=None, width1=None, width2=None, *, angle=None, shift=0, anchor=Anchor.CENTER, spin=0, placement=None, res=None)[source]¶

Return a trapezoid on the active backend.

Give exactly three of height, width1, width2 and angle.

Parameters:¶

height : float | None¶: Height of the trapezoid.
width1 : float | None¶: Width of the bottom edge.
width2 : float | None¶: Width of the top edge.
angle : float | None¶: Base angle in degrees.
shift : float¶: Shift of the top edge along X.
anchor : Anchor | Sequence[float]¶: Anchor point.
spin : float¶: Z-axis rotation in degrees after anchor (CSG backend only).
placement : Placement | None¶: Anchor and spin as one reusable value (SPEC G-1). A placement that also sets orient raises here: the plane has no third axis to turn a face towards (SPEC E-5).
res : int | None¶: Sampling resolution (SDF backend only). Omitted, the ambient use_defaults(res=...) value applies.

Returns:¶

A 2-D shape on whichever backend is active.

Raises:¶

ValueError – If other than three of height/width1/width2/angle are given.

Return type:¶

Flat

Examples

from pybosl2.flat import trapezoid
trapezoid(height=10, width1=20, width2=12).linear_extrude(height=4).show()

Loading 3-D preview…

⬇ Download STL mesh

pybosl2.flat.polygon(points, *, anchor=Anchor.CENTER, spin=0, placement=None, res=None)[source]¶

Return a polygon on the active backend.

Creates a 2D polygon from list of points.

Parameters:¶

points : Path2D¶: The outline, as a Path2D (SPEC C-7a).
anchor : Anchor | Sequence[float]¶: Anchor point.
spin : float¶: Z-axis rotation in degrees after anchor.
placement : Placement | None¶: Anchor and spin as one reusable value (SPEC G-1). A placement that also sets orient raises here: the plane has no third axis to turn a face towards (SPEC E-5).
res : int | None¶: SDF backend’s resolution (SDF backend only). Omitted, the ambient use_defaults(res=...) value applies.

Returns:¶

A 2-D flat shape representing a polygon.

Return type:¶

Flat

Examples

from pybosl2 import Path2D
from pybosl2.flat import polygon
polygon(points=Path2D([[0, 0], [10, 0], [5, 10]])).linear_extrude(height=5).show()

Loading 3-D preview…

⬇ Download STL mesh

pybosl2.flat.rect(size=1, *, rounding=0, chamfer=0, treatment=None, anchor=Anchor.CENTER, spin=0, placement=None, fn=None, fa=None, fs=None, res=None)[source]¶

Return a rectangle on the active backend.

Creates a 2D rectangle with the specified dimensions and corner treatments.

Parameters:¶

size : float | Sequence[float]¶: Size of the rectangle (scalar or 2-element sequence).
rounding : float | Sequence[float]¶: Corner rounding radius.
chamfer : float | Sequence[float]¶: Corner chamfer distance.
treatment : EdgeTreatment | None¶: A rounding or a chamfer as one value (SPEC G-1). An edge is rounded or chamfered, never both, so this makes the pair unrepresentable rather than checked; giving it beside rounding= or chamfer= raises (SPEC G-3).
anchor : Anchor | Sequence[float]¶: Anchor point.
spin : float¶: Z-axis rotation in degrees after anchor.
placement : Placement | None¶: Anchor and spin as one reusable value (SPEC G-1). A placement that also sets orient raises here: the plane has no third axis to turn a face towards (SPEC E-5).
fn : int | None¶: Arc smoothness overrides (CSG backend only). Omitted, the ambient use_defaults(fn=...) value applies; fn=0 opts back out to fa/fs.
fa : float | None¶: Arc smoothness overrides (CSG backend only). Omitted, the ambient use_defaults(fa=...) value applies.
fs : float | None¶: Arc smoothness overrides (CSG backend only). Omitted, the ambient use_defaults(fs=...) value applies.
res : int | None¶: SDF backend’s resolution (SDF backend only). Omitted, the ambient use_defaults(res=...) value applies.

Returns:¶

A 2-D flat shape representing a rectangle.

Return type:¶

Flat

Examples

from pybosl2.flat import rect
rect(size=[30, 20], rounding=3).linear_extrude(height=5).show()

Loading 3-D preview…

⬇ Download STL mesh

pybosl2.flat.square(size=1, *, center=None, rounding=0, chamfer=0, treatment=None, anchor=Anchor.CENTER, spin=None, placement=None, fn=None, fa=None, fs=None, res=None)[source]¶

Return a square on the active backend.

Creates a 2D square with the specified size and corner treatments.

Parameters:¶

size : float | Sequence[float]¶: Size of the square (scalar or 2-element sequence).
center : bool | None¶: Whether to center the shape (CSG only).
rounding : float | Sequence[float]¶: Corner rounding radius.
chamfer : float | Sequence[float]¶: Corner chamfer distance.
treatment : EdgeTreatment | None¶: A rounding or a chamfer as one value (SPEC G-1). An edge is rounded or chamfered, never both, so this makes the pair unrepresentable rather than checked; giving it beside rounding= or chamfer= raises (SPEC G-3).
anchor : Anchor | Sequence[float]¶: Anchor point.
spin : float | None¶: Z-axis rotation in degrees after anchor.
placement : Placement | None¶: Anchor and spin as one reusable value (SPEC G-1). A placement that also sets orient raises here: the plane has no third axis to turn a face towards (SPEC E-5).
fn : int | None¶: Arc smoothness overrides (CSG backend only). Omitted, the ambient use_defaults(fn=...) value applies; fn=0 opts back out to fa/fs.
fa : float | None¶: Arc smoothness overrides (CSG backend only). Omitted, the ambient use_defaults(fa=...) value applies.
fs : float | None¶: Arc smoothness overrides (CSG backend only). Omitted, the ambient use_defaults(fs=...) value applies.
res : int | None¶: SDF backend’s resolution (SDF backend only). Omitted, the ambient use_defaults(res=...) value applies.

Returns:¶

A 2-D flat shape representing a square.

Return type:¶

Flat

Examples

from pybosl2.flat import square
square(size=20, rounding=2).linear_extrude(height=5).show()

Loading 3-D preview…

⬇ Download STL mesh

pybosl2.flat.text(text, *, size=10, font='Liberation Sans', halign=None, valign=None, spacing=1.0, direction='ltr', language='en', script='latin', anchor=None, spin=0, placement=None, fn=None, fa=None, fs=None)[source]¶

Return a text shape on the active backend.

Creates a 2D shape representing the given text.

Parameters:¶

text : str¶: The string content.
size : float¶: Text height.
font : str¶: Font family name.
halign : str | None¶: Horizontal alignment.
valign : str | None¶: Vertical alignment: “top”, “center”, “baseline” or “bottom” (default “baseline”).
spacing : float¶: Character spacing factor.
direction : str¶: Text direction.
language : str¶: Language code.
script : str¶: Script code.
anchor : Anchor | Sequence[float] | None¶: Where the finished text’s box lands, in the anchor language (SPEC C-10). None leaves it where halign/valign put it, which is the typographic placement and the usual answer for text.
spin : float¶: Z-axis rotation in degrees after anchor.
placement : Placement | None¶: Anchor and spin as one reusable value (SPEC G-1). A placement that also sets orient raises here: the plane has no third axis to turn a face towards (SPEC E-5).
fn : int | None¶: Arc smoothness overrides (CSG backend only). Omitted, the ambient use_defaults(fn=...) value applies; fn=0 opts back out to fa/fs.
fa : float | None¶: Arc smoothness overrides (CSG backend only). Omitted, the ambient use_defaults(fa=...) value applies.
fs : float | None¶: Arc smoothness overrides (CSG backend only). Omitted, the ambient use_defaults(fs=...) value applies.

Returns:¶

A 2-D flat shape representing text.

Return type:¶

Flat

Examples

from pybosl2.flat import text
text(text="BOSL2", size=10).linear_extrude(height=3).show()

Loading 3-D preview…

⬇ Download STL mesh