### Setup Distance From Example

Source: https://github.com/gumyr/build123d/blob/dev/docs/topology_selection/sort_examples.rst

Provides the setup for sorting objects by their distance from a reference object. The example uses an empty Vertex at the origin as the reference.

```build123d
from build123d import *

# Setup for distance from examples
```

```build123d
from build123d import *

# Setup for distance from examples
```

--------------------------------

### Create a Line and Arc with BuildLine

Source: https://github.com/gumyr/build123d/blob/dev/docs/build_line.rst

This example demonstrates creating a simple line and a three-point arc within the BuildLine context. The arc connects the start and end points of the line.

```build123d
from build123d import *

with BuildLine() as example_1:
    Line((0,0), (2,0))
    ThreePointArc((0,0), (2,0), (1,1))
```

--------------------------------

### Install Development and Docs Dependencies

Source: https://github.com/gumyr/build123d/blob/dev/CONTRIBUTING.md

Install additional dependencies required for development and documentation building.

```bash
pip install -e ".[development]"
pip install -e ".[docs]"
```

--------------------------------

### build123d Selectors Reference

Source: https://github.com/gumyr/build123d/blob/dev/docs/selectors.rst

A quick reference guide to the selectors available in build123d, detailing their applicability, description, and example usage.

```APIDOC
## build123d Selectors

Selectors are Python methods used to isolate features from a design. They can be applied to different build123d objects like BuildLine, BuildSketch, and BuildPart.

### Selector Methods

| Selector    | Applicability                     | Description       | Example           |
|-------------|-----------------------------------|-------------------|-------------------|
| vertices()  | BuildLine, BuildSketch, BuildPart | Vertex extraction | `part.vertices()` |
| edges()     | BuildLine, BuildSketch, BuildPart | Edge extraction   | `part.edges()`    |
| wires()     | BuildLine, BuildSketch, BuildPart | Wire extraction   | `part.wires()`    |
| faces()     | BuildSketch, BuildPart            | Face extraction   | `part.faces()`    |
| solids()    | BuildPart                         | Solid extraction  | `part.solids()`   |

### Selector Operators and Methods

| Operator | Operand               | Method             | Description                                           | Example                                               |
|----------|-----------------------|--------------------|-------------------------------------------------------|-------------------------------------------------------|
| >        | SortBy, Axis          | sort_by            | Sort ShapeList by operand                             | `part.vertices() > Axis.Z`                            |
| <        | SortBy, Axis          | sort_by            | Reverse sort ShapeList by operand                     | `part.faces() < Axis.Z`                               |
| >>       | SortBy, Axis          | group_by           | Group ShapeList by operand and return last value      | `part.solids() >> Axis.X`                             |
| <<       | SortBy, Axis          | group_by           | Group ShapeList by operand and return first value     | `part.faces() << Axis.Y`                              |
| |        | Axis, Plane, GeomType | filter_by          | Filter and sort ShapeList by Axis, Plane, or GeomType | `part.faces() | Axis.Z`                                |
| []       |                       |                    | Standard python list indexing and slicing             | `part.faces()[-2:]`                                   |
|          | Axis                  | filter_by_position | Filter ShapeList by Axis & mix / max values           | `part.faces()..filter_by_position(Axis.Z, 1, 2, inclusive=(False, True))`

### Operand Types

The operand types for selectors include: Axis, Plane, SortBy, and GeomType. An Axis is a base object with an origin.
```

--------------------------------

### Install build123d using pip

Source: https://github.com/gumyr/build123d/blob/dev/docs/installation.rst

The standard method to install build123d for most users. Ensure pip is up-to-date for best results.

```bash
pip install build123d
```

--------------------------------

### Maker Coin Example

Source: https://github.com/gumyr/build123d/blob/dev/docs/examples_1.rst

This example demonstrates the use of DoubleTangentArc for smooth transitions and embossing text with even depth.

```build123d
from build123d import *

# [Code]
with BuildPart() as maker_coin:
    with BuildSketch() as dish_sketch:
        Circle(10)
        with BuildLine(True) as arc_line:
            Line(10, 0)
            RadiusArc(10, 180)
        with BuildLine(True) as tangent_arc_line:
            DoubleTangentArc(arc_line.line, RadiusArc(10, 180))
        with BuildLine(True) as inner_arc_line:
            RadiusArc(10, 180)
        with BuildLine(True) as outer_arc_line:
            DoubleTangentArc(inner_arc_line.line, RadiusArc(10, 180))
        with BuildLine(True) as inner_tangent_arc_line:
            DoubleTangentArc(arc_line.line, RadiusArc(10, 180))
        with BuildLine(True) as outer_tangent_arc_line:
            DoubleTangentArc(inner_arc_line.line, RadiusArc(10, 180))

    with BuildSketch(mode=Mode.EXTUDE) as dish_body:
        add(dish_sketch.sketch)
        extrude(amount=2)

    with BuildSketch(mode=Mode.PROJECT) as text_sketch:
        Text("build123d", height=2, size=5)

    with BuildPart() as text_emboss:
        add(dish_body.part)
        add(text_sketch.sketch.moved(
            (0, 0, 2.1)
        ))
        fillet(maker_coin.edges().filter_by(Axis.Z))

    with BuildSketch(mode=Mode.PROJECT) as outer_arc_sketch:
        with BuildLine(True) as arc_line:
            Line(10, 0)
            RadiusArc(10, 180)
        with BuildLine(True) as tangent_arc_line:
            DoubleTangentArc(arc_line.line, RadiusArc(10, 180))
        with BuildLine(True) as inner_arc_line:
            RadiusArc(10, 180)
        with BuildLine(True) as outer_arc_line:
            DoubleTangentArc(inner_arc_line.line, RadiusArc(10, 180))
        with BuildLine(True) as inner_tangent_arc_line:
            DoubleTangentArc(arc_line.line, RadiusArc(10, 180))
        with BuildLine(True) as outer_tangent_arc_line:
            DoubleTangentArc(inner_arc_line.line, RadiusArc(10, 180))

    with BuildPart() as outer_arc_body:
        add(outer_arc_sketch.sketch)
        extrude(amount=2)

    add(text_emboss.part)
    add(outer_arc_body.part)

# [End]
```

--------------------------------

### Clone and Install build123d

Source: https://github.com/gumyr/build123d/blob/dev/CONTRIBUTING.md

Clone the build123d repository and install it in editable mode. Ensure pip is up-to-date before proceeding.

```bash
git clone https://github.com/gumyr/build123d.git
cd build123d
pip install -e .
```

--------------------------------

### Complete Bracket Design Example in Build123d

Source: https://github.com/gumyr/build123d/blob/dev/docs/tutorial_design.rst

This comprehensive example shows the full process of designing a bracket, including setting up parameters, sketching, extruding, mirroring, filleting, and adding holes and slots. It requires build123d and ocp_vscode libraries.

```build123d
from build123d import *
from ocp_vscode import show_all

thickness = 3 * MM
width = 25 * MM
length = 50 * MM
height = 25 * MM
hole_diameter = 5 * MM
bend_radius = 5 * MM
fillet_radius = 2 * MM

with BuildPart() as bracket:
    with BuildSketch() as sketch:
        with BuildLine() as profile:
            FilletPolyline(
                (0, 0), (length / 2, 0), (length / 2, height), radius=bend_radius
            )
            offset(amount=thickness, side=Side.LEFT)
        make_face()
        mirror(about=Plane.YZ)
    extrude(amount=width / 2)
    mirror(about=Plane.XY)
    corners = bracket.edges().filter_by(Axis.X).group_by(Axis.Y)[-1]
    fillet(corners, fillet_radius)
    with Locations(bracket.faces().sort_by(Axis.X)[-1]):
        Hole(hole_diameter / 2)
    with BuildSketch(bracket.faces().sort_by(Axis.Y)[0]):
        SlotOverall(20 * MM, hole_diameter)
    extrude(amount=-thickness, mode=Mode.SUBTRACT)

show_all()
```

--------------------------------

### Install build123d in development mode

Source: https://github.com/gumyr/build123d/blob/dev/docs/installation.rst

Installs build123d in editable mode from a local clone. Changes made to the source code will be immediately reflected without reinstallation.

```bash
cd build123d
python3 -m pip install -e .
```

--------------------------------

### Tea Cup Example (Builder Mode)

Source: https://github.com/gumyr/build123d/blob/dev/docs/examples_1.rst

Demonstrates the creation of a tea cup, serving as an example of constructing complex, non-flat geometrical shapes programmatically.

```build123d
from build123d import *

# [Code]
with BuildPart() as tea_cup:
    with BuildSketch(Plane.YZ) as cup_profile:
        with BuildLine(True) as bottom_line:
            Line(0, 0)
        with BuildLine(True) as side_line:
            Line(0, 50)
        with BuildLine(True) as top_line:
            Line(30, 50)
        with BuildLine(True) as inner_top_line:
            Line(28, 48)
        with BuildLine(True) as inner_side_line:
            Line(28, 2)
        with BuildLine(True) as inner_bottom_line:
            Line(0, 2)
        with BuildLine(True) as handle_start_line:
            Line(30, 40)
        with BuildLine(True) as handle_arc:
            RadiusArc(15, -90)
        with BuildLine(True) as handle_end_line:
            Line(45, 25)
        with BuildLine(True) as handle_inner_arc:
            RadiusArc(12, 90)
        with BuildLine(True) as handle_inner_end_line:
            Line(35, 30)
        with BuildLine(True) as handle_inner_start_line:
            Line(30, 35)

    revolve(revolution_angle=360)
    shell(radius=1)

# [End]
```

--------------------------------

### Setup for Grouping by Edge Length Keys

Source: https://github.com/gumyr/build123d/blob/dev/docs/topology_selection/group_examples.rst

This setup code initializes a bearing block and prepares it for adding fillets. It demonstrates grouping edges by their length and selecting specific groups using the lengths as keys.

```build123d
from build123d import *

# Create an incomplete bearing block
with BuildPart() as part:
    with BuildSketch(Plane.XY) as sk:
        with BuildLine():
            l1 = Line((0, 0), (10, 0))
            l2 = Line((10, 0), (10, 1))
            l3 = Line((10, 1), (0, 1))
            l4 = Line((0, 1), (0, 0))
        make_face()
    extrude(amount=10)

    with BuildSketch(Plane.YZ.offset(10)) as sk_rib:
        with BuildLine():
            l1 = Line((0, 0), (0, 1))
            l2 = Line((0, 1), (1, 1))
            l3 = Line((1, 1), (1, 0))
        make_face()
    extrude(amount=10)

    # Add fillets to the ribs and corners
    fillet(part.edges().filter_by(Axis.X), 0.5)
    fillet(part.edges().filter_by(Axis.Y), 0.5)

# Group edges by length and select by key
rib_edges = part.edges().filter_by(Axis.X)
rib_groups = rib_edges.group_by(Edge.Length)

# Example: Select edges with length 1.0
selected_ribs = rib_groups.group(1.0)
```

--------------------------------

### Build123d Log Stream Example

Source: https://github.com/gumyr/build123d/blob/dev/docs/debugging_logging.rst

This is an example of a build123d log stream as seen in cq-editor's Log viewer. It shows the sequence of operations during a build.

```bash
[18:43:44.678646] INFO: Entering BuildPart with mode=Mode.ADD which is in different scope as parent
[18:43:44.679233] INFO: WorkplaneList is pushing 1 workplanes: [Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, 0.00, 1.00))]
[18:43:44.679888] INFO: LocationList is pushing 1 points: [(p=(0.00, 0.00, 0.00), o=(-0.00, 0.00, -0.00))]
[18:43:44.681751] INFO: BuildPart context requested by Box
[18:43:44.685950] INFO: Completed integrating 1 object(s) into part with Mode=Mode.ADD
[18:43:44.690072] INFO: GridLocations is pushing 4 points: [(p=(-30.00, -20.00, 0.00), o=(-0.00, 0.00, -0.00)), (p=(-30.00, 20.00, 0.00), o=(-0.00, 0.00, -0.00)), (p=(30.00, -20.00, 0.00), o=(-0.00, 0.00, -0.00)), (p=(30.00, 20.00, 0.00), o=(-0.00, 0.00, -0.00))]
[18:43:44.691604] INFO: BuildPart context requested by Hole
[18:43:44.724628] INFO: Completed integrating 4 object(s) into part with Mode=Mode.SUBTRACT
[18:43:44.728681] INFO: GridLocations is popping 4 points
[18:43:44.747358] INFO: BuildPart context requested by chamfer
[18:43:44.762429] INFO: Completed integrating 1 object(s) into part with Mode=Mode.REPLACE
[18:43:44.765380] INFO: LocationList is popping 1 points
[18:43:44.766106] INFO: WorkplaneList is popping 1 workplanes
[18:43:44.766729] INFO: Exiting BuildPart
```

--------------------------------

### Setup for Grouping by Axis and Length

Source: https://github.com/gumyr/build123d/blob/dev/docs/topology_selection/group_examples.rst

This setup code is used to prepare the geometry for grouping edges by their z-axis position and then by length. It imports necessary modules and defines the initial part.

```build123d
from build123d import *

# Create a heatsink component with fins
with BuildPart() as part:
    with BuildSketch(Plane.XY) as sk:
        with BuildLine():
            l1 = Line((0, 0), (10, 0))
            l2 = Line((10, 0), (10, 1))
            l3 = Line((10, 1), (0, 1))
            l4 = Line((0, 1), (0, 0))
        make_face()
    extrude(amount=10)

    with BuildSketch(Plane.YZ.offset(10)) as sk_fin:
        with BuildLine():
            l1 = Line((0, 0), (0, 1))
            l2 = Line((0, 1), (1, 1))
            l3 = Line((1, 1), (1, 0))
        make_face()
    extrude(amount=10)

    # Add fillets to the ends of the fins
    fillet(part.edges().filter_by(Axis.Z), 0.5)
```

--------------------------------

### Setup SortBy Enum

Source: https://github.com/gumyr/build123d/blob/dev/docs/topology_selection/sort_examples.rst

Demonstrates the setup for using SortBy enums, which act as shorthands for shape properties and are used for sorting and grouping.

```build123d
from build123d import *

# Setup for SortBy examples
```

```build123d
from build123d import *

# Setup for SortBy examples
```

--------------------------------

### BuildPart and BuildSketch Example

Source: https://github.com/gumyr/build123d/blob/dev/docs/key_concepts_builder.rst

Demonstrates how BuildSketch transfers its created sketch to BuildPart as pending faces, allowing subsequent operations like extrude.

```python
height, width, thickness, f_rad = 60, 80, 20, 10

with BuildPart() as pillow_block:
    with BuildSketch() as plan:
        Rectangle(width, height)
        fillet(plan.vertices(), radius=f_rad)
    extrude(amount=thickness)
```

--------------------------------

### Install build123d from GitHub (Windows)

Source: https://github.com/gumyr/build123d/blob/dev/docs/installation.rst

Installs the latest non-released version of build123d directly from its GitHub repository on Windows. Recommended for developers needing the most recent code.

```bash
python -m pip install git+https://github.com/gumyr/build123d
```

--------------------------------

### Basic BuildPart Example

Source: https://github.com/gumyr/build123d/blob/dev/docs/build_part.rst

Demonstrates creating a 3D object using BuildPart. A Box is created, and a Cylinder is subtracted from it using Mode.SUBTRACT.

```build123d
from build123d import *

with BuildPart() as ex2:
    with BuildSketch() as s:
        Rectangle(10, 10)
        with BuildPart(mode=Mode.SUBTRACT):
            Cylinder(radius=2, height=10)
    extrude(distance=10)

part = ex2.part
```

--------------------------------

### Stud Wall Example (Algebra Mode)

Source: https://github.com/gumyr/build123d/blob/dev/docs/examples_1.rst

Demonstrates creating custom Part objects (Stud) and assembling them into a StudWall using RigidJoints.

```build123d
from build123d import *

# [Code]
class Stud(Part):
    def __init__(self, length=90, width=38, thickness=8.9, **kwargs):
        super().__init__(**kwargs)
        with BuildPart() as stud_builder:
            with BuildSketch() as stud_profile:
                Rectangle(width, thickness)
            extrude(length)
            with BuildSketch(Plane.YZ.offset(length/2)) as joint_plane:
                Circle(2)
            add(joint_plane.sketch)
            RigidJoint("center", (0,0,0))
            RigidJoint("top", (0,0,length/2))
            RigidJoint("bottom", (0,0,-length/2))
        self.part = stud_builder.part


class StudWall(Part):
    def __init__(self, studs=3, **kwargs):
        super().__init__(**kwargs)
        stud_length = 90
        stud_width = 38
        stud_thickness = 8.9
        stud_spacing = 400

        with BuildPart() as wall_builder:
            for i in range(studs):
                stud = Stud(length=stud_length, width=stud_width, thickness=stud_thickness)
                add(stud.moved(Vector(i * stud_spacing, 0, 0)))
                RigidJoint(f"stud_{i}_center", stud.center)
                RigidJoint(f"stud_{i}_top", stud.top)
                RigidJoint(f"stud_{i}_bottom", stud.bottom)
        self.part = wall_builder.part


wall = StudWall(studs=3)

# [End]
```

--------------------------------

### Install build123d from GitHub (Linux/MacOS)

Source: https://github.com/gumyr/build123d/blob/dev/docs/installation.rst

Installs the latest non-released version of build123d directly from its GitHub repository. Recommended for developers needing the most recent code.

```bash
python3 -m pip install git+https://github.com/gumyr/build123d
```

--------------------------------

### Install build123d Development Branch using Git

Source: https://github.com/gumyr/build123d/blob/dev/README.md

Install the latest development version of build123d directly from its GitHub repository using pip.

```bash
pip install git+https://github.com/gumyr/build123d
```

--------------------------------

### Test build123d installation

Source: https://github.com/gumyr/build123d/blob/dev/docs/installation.rst

A simple test to verify that build123d is installed correctly and can be imported. It creates a basic box shape and displays its topology.

```python
from build123d import *
print(Solid.make_box(1,2,3).show_topology(limit_class="Face"))
```

--------------------------------

### Multi-Sketch Loft Example (Algebra Mode)

Source: https://github.com/gumyr/build123d/blob/dev/docs/examples_1.rst

Demonstrates lofting a set of sketches, selecting top and bottom by type, and shelling in Algebra Mode.

```build123d
from build123d import *

# [Code]
bottom_sketch = Rectangle(10, 10)

top_sketch = Circle(5)

loft_part = Loft(bottom_sketch, top_sketch.moved(Vector(0,0,5)))

shell_part = Shell(loft_part, 1)

# [End]
```

--------------------------------

### Multi-Sketch Loft Example (Builder Mode)

Source: https://github.com/gumyr/build123d/blob/dev/docs/examples_1.rst

Demonstrates lofting a set of sketches, selecting top and bottom by type, and shelling in Builder Mode.

```build123d
from build123d import *

# [Code]
with BuildPart() as sp:
    with BuildSketch(Plane.XY) as bottom_sketch:
        Rectangle(10, 10)
    with BuildSketch(Plane.XY.offset(5)) as top_sketch:
        Circle(5)
    loft(bottom_sketch.sketch, top_sketch.sketch)
    shell(radius=1)

# [End]
```

--------------------------------

### Teacup Example in build123d

Source: https://github.com/gumyr/build123d/blob/dev/docs/index.rst

Demonstrates creating a teacup model using build123d. This example showcases the framework's capabilities for generating complex shapes with concise code.

```build123d
from build123d import *

# Teacup Example
with BuildPart() as teacup:
    with BuildSketch() as base:
        Circle(10)
        with BuildLine(radius=10) as handle_base:
            Line((0,0), (0,20))
        with BuildLine(radius=10) as handle_top:
            Line((0,20), (20,20))
        with BuildLine(radius=10) as handle_side:
            Line((20,20), (20,0))
        with BuildLine(radius=10) as handle_return:
            Line((20,0), (0,0))
        with BuildSketch(handle_base, handle_top, handle_side, handle_return) as handle:
            pass
    with BuildSketch(base) as body:
        extrude(amount=20)
    with BuildSketch(handle) as handle_solid:
        extrude(amount=5)
    with BuildSketch(base) as top:
        Circle(10)
        with BuildLine(radius=10) as handle_base:
            Line((0,0), (0,20))
        with BuildLine(radius=10) as handle_top:
            Line((0,20), (20,20))
        with BuildLine(radius=10) as handle_side:
            Line((20,20), (20,0))
        with BuildLine(radius=10) as handle_return:
            Line((20,0), (0,0))
        with BuildSketch(handle_base, handle_top, handle_side, handle_return) as handle:
            pass
    with BuildSketch(top) as top_solid:
        extrude(amount=5)
    with BuildSketch(base) as inner_hole:
        Circle(8)
    with BuildSketch(inner_hole) as hole:
        extrude(amount=20)

    union(teacup.part, handle_solid.part, top_solid.part)
    subtract(hole.part)


# Export the teacup to a file
# teacup.part.export_stl("teacup.stl")

```

--------------------------------

### Setup Along Wire Sorting

Source: https://github.com/gumyr/build123d/blob/dev/docs/topology_selection/sort_examples.rst

Provides the setup code for sorting vertices along a wire. This is useful when the default order of vertices is not suitable for subsequent operations.

```build123d
from build123d import *

# Setup for along wire examples
```

```build123d
from build123d import *

# Setup for along wire examples
```

--------------------------------

### Dependency Chaining Example

Source: https://github.com/gumyr/build123d/wiki/Lazy-Evaluation

Demonstrates how users expect dependency chaining to work seamlessly, where the result of one operation is used in a subsequent one.

```python
with BuildLine() as drawing:
    l1 = Line((0, 0), (1, 0))
    print(l1 @ 1)                         # query point on line
    l2 = Line(l1 @ 1, (2, 2))             # use it in next primitive
```

--------------------------------

### Install OCP stubs for development

Source: https://github.com/gumyr/build123d/blob/dev/docs/installation.rst

Installs the necessary stubs for the OpenCascade 'OCP' layer, which may be required when working directly with the OCP API during development.

```bash
python3 -m pip install git+https://github.com/CadQuery/OCP-stubs@7.7.0
```

--------------------------------

### Install build123d using pip

Source: https://github.com/gumyr/build123d/blob/dev/README.md

Install the latest stable release of build123d from PyPI using pip. It is recommended to upgrade pip first if dependency errors occur.

```bash
pip install build123d
```

```bash
pip install --upgrade pip
```

--------------------------------

### Combine Object and Placement Arithmetic

Source: https://github.com/gumyr/build123d/blob/dev/docs/key_concepts_algebra.rst

Example combining object fusion with placement operations on different planes.

```build123d
b = Plane.XZ * Rot(X=30) * Box(1, 2, 3) + Plane.YZ * Pos(X=-1) * Cylinder(0.2, 5)
```

--------------------------------

### Platonic Solids Example (Algebra Mode)

Source: https://github.com/gumyr/build123d/blob/dev/docs/examples_1.rst

Creates custom Part objects for the five Platonic solids using algebraic operations.

```build123d
from build123d import *

# [Code]

def platonic_solid(solid_type: str = "tetrahedron", radius: float = 10) -> Part:
    if solid_type == "tetrahedron":
        return Tetrahedron(radius=radius)
    elif solid_type == "cube":
        return Cube(size=radius * 2)
    elif solid_type == "octahedron":
        return Octahedron(radius=radius)
    elif solid_type == "dodecahedron":
        return Dodecahedron(radius=radius)
    elif solid_type == "icosahedron":
        return Icosahedron(radius=radius)
    else:
        raise ValueError(f"Unknown solid type: {solid_type}")


tetrahedron = platonic_solid("tetrahedron")
cube = platonic_solid("cube")
octahedron = platonic_solid("octahedron")
dodecahedron = platonic_solid("dodecahedron")
icosahedron = platonic_solid("icosahedron")

# [End]
```

--------------------------------

### Tea Cup Example (Algebra Mode)

Source: https://github.com/gumyr/build123d/blob/dev/docs/examples_1.rst

Demonstrates the creation of a tea cup using algebraic operations for complex, non-flat geometrical shapes.

```build123d
from build123d import *

# [Code]
profile = Line(0, 0) +
          Line(0, 50) +
          Line(30, 50) +
          Line(28, 48) +
          Line(28, 2) +
          Line(0, 2) +
          Line(30, 40) +
          RadiusArc(15, -90) +
          Line(45, 25) +
          RadiusArc(12, 90) +
          Line(35, 30) +
          Line(30, 35)

tea_cup = profile.revolve(revolution_angle=360)
shelled_tea_cup = Shell(tea_cup, 1)

# [End]
```

--------------------------------

### Add build123d using Poetry

Source: https://github.com/gumyr/build123d/blob/dev/docs/installation.rst

Installs build123d using the Poetry package manager. This is a convenient method for projects managed with Poetry.

```bash
poetry add build123d
```

--------------------------------

### Playing Cards Example (Builder Mode)

Source: https://github.com/gumyr/build123d/blob/dev/docs/examples_1.rst

Creates custom Sketch objects for card suits and a playing card box with suit cutouts in the lid.

```build123d
from build123d import *

# [Code]
with BuildPart() as playing_cards:
    with BuildSketch() as club_sketch:
        with BuildLine(True) as line1:
            Line(0, 10)
        with BuildLine(True) as arc1:
            RadiusArc(5, 180)
        with BuildLine(True) as line2:
            Line(0, -10)
        with BuildLine(True) as arc2:
            RadiusArc(5, -180)
        with BuildLine(True) as stem:
            Line(0, -5)
        with BuildLine(True) as stem_arc:
            RadiusArc(2.5, 180)
        with BuildLine(True) as stem_line:
            Line(0, 5)
        with BuildLine(True) as stem_arc2:
            RadiusArc(2.5, -180)

    with BuildSketch() as spade_sketch:
        with BuildLine(True) as line1:
            Line(0, 10)
        with BuildLine(True) as arc1:
            RadiusArc(5, 180)
        with BuildLine(True) as line2:
            Line(0, -10)
        with BuildLine(True) as arc2:
            RadiusArc(5, -180)
        with BuildLine(True) as stem:
            Line(0, -5)
        with BuildLine(True) as stem_arc:
            RadiusArc(2.5, 180)
        with BuildLine(True) as stem_line:
            Line(0, 5)
        with BuildLine(True) as stem_arc2:
            RadiusArc(2.5, -180)
        mirror(Plane.YZ)

    with BuildSketch() as heart_sketch:
        with BuildLine(True) as line1:
            Line(0, 10)
        with BuildLine(True) as arc1:
            RadiusArc(5, 180)
        with BuildLine(True) as line2:
            Line(0, -10)
        with BuildLine(True) as arc2:
            RadiusArc(5, -180)
        with BuildLine(True) as stem:
            Line(0, -5)
        with BuildLine(True) as stem_arc:
            RadiusArc(2.5, 180)
        with BuildLine(True) as stem_line:
            Line(0, 5)
        with BuildLine(True) as stem_arc2:
            RadiusArc(2.5, -180)
        mirror(Plane.YZ)
        mirror(Plane.XZ)

    with BuildSketch() as diamond_sketch:
        with BuildLine(True) as line1:
            Line(0, 10)
        with BuildLine(True) as arc1:
            RadiusArc(5, 180)
        with BuildLine(True) as line2:
            Line(0, -10)
        with BuildLine(True) as arc2:
            RadiusArc(5, -180)
        mirror(Plane.YZ)

    with BuildPart() as box_lid:
        with BuildSketch() as lid_sketch:
            Rectangle(50, 70)
        extrude(amount=5)
        with BuildSketch(Plane.XY.offset(5)) as cutout_sketch:
            with BuildLine(True) as line1:
                Line(0, 10)
            with BuildLine(True) as arc1:
                RadiusArc(5, 180)
            with BuildLine(True) as line2:
                Line(0, -10)
            with BuildLine(True) as arc2:
                RadiusArc(5, -180)
            with BuildLine(True) as stem:
                Line(0, -5)
            with BuildLine(True) as stem_arc:
                RadiusArc(2.5, 180)
            with BuildLine(True) as stem_line:
                Line(0, 5)
            with BuildLine(True) as stem_arc2:
                RadiusArc(2.5, -180)
            scale(2)
            center(Vector(20, 0))
            add(club_sketch.sketch)
            center(Vector(-20, 0))
            add(spade_sketch.sketch)
            center(Vector(0, 35))
            add(heart_sketch.sketch)
            center(Vector(0, -35))
            add(diamond_sketch.sketch)
        cut(cutout_sketch.sketch)

    with BuildPart() as box_base:
        with BuildSketch() as base_sketch:
            Rectangle(50, 70)
        extrude(amount=10)
        with BuildSketch(Plane.XY.offset(10)) as inner_cutout:
            Rectangle(48, 68)
        cut(inner_cutout.sketch)

    add(box_lid.part)
    add(box_base.part)

# [End]
```

--------------------------------

### Creating a Box at the Origin

Source: https://github.com/gumyr/build123d/blob/dev/docs/key_concepts_builder.rst

A basic example showing how to create a Box at the default origin (0,0,0) with specified dimensions and rotation. By default, objects are centered.

```build123d
with BuildPart() as pipes:
    Box(10, 10, 10, rotation=(10, 20, 30))
```

--------------------------------

### Example Output of GridLocations

Source: https://github.com/gumyr/build123d/blob/dev/docs/key_concepts_builder.rst

Illustrates the typical output format for Location objects generated by GridLocations, showing their position (p) and orientation (o).

```text
Location(p=(-0.50,-0.50,0.00), o=(0.00,-0.00,0.00))
Location(p=(-0.50,0.50,0.00), o=(0.00,-0.00,0.00))
Location(p=(0.50,-0.50,0.00), o=(0.00,-0.00,0.00))
Location(p=(0.50,0.50,0.00), o=(0.00,-0.00,0.00))
Location(p=(-0.50,-0.00,-0.50), o=(90.00,-0.00,0.00))
Location(p=(-0.50,0.00,0.50), o=(90.00,-0.00,0.00))
Location(p=(0.50,0.00,-0.50), o=(90.00,-0.00,0.00))
Location(p=(0.50,0.00,0.50), o=(90.00,-0.00,0.00))
```

--------------------------------

### Peg Board Hook Example (Algebra Mode)

Source: https://github.com/gumyr/build123d/blob/dev/docs/examples_1.rst

Creates a J-shaped pegboard hook using algebraic operations, defining a path and sweeping a profile.

```build123d
from build123d import *

# [Code]
profile = Rectangle(10, 2)

path = Line(0, 10) + RadiusArc(10, 180) + Line(0, -10) + RadiusArc(10, -180)

hook = profile.sweep(path.moved(Vector(0,0,10)))

flat_plane = Rectangle(20, 20).moved(Vector(0,0,10))

flat_hook = hook.intersect(flat_plane)

# [End]
```

--------------------------------

### Example Workflow with BuildPart and BuildSketch

Source: https://github.com/gumyr/build123d/blob/dev/docs/key_concepts_builder.rst

Demonstrates creating a 3D part by first defining a base sketch, extruding it, and then subtracting a cylinder from a face. Use this to build complex parts incrementally.

```build123d
from build123d import *

# Using BuildPart to create a 3D model
with BuildPart() as example_part:
    with BuildSketch() as base_sketch:
        Rectangle(20, 20)
    extrude(amount=10)  # Create a base block
    with BuildSketch(Plane(example_part.faces().sort_by(Axis.Z).last)) as cut_sketch:
        Circle(5)
    extrude(amount=-5, mode=Mode.SUBTRACT)  # Subtract a cylinder

# Access the final part
result_part = example_part.part
```

--------------------------------

### Standard Python List Slicing

Source: https://github.com/gumyr/build123d/blob/dev/docs/selectors.rst

Apply standard Python list indexing and slicing to a ShapeList. For example, get the last two faces.

```python
part.faces()[-2:]
```

--------------------------------

### Find Available Fonts and Styles

Source: https://github.com/gumyr/build123d/blob/dev/docs/objects/text.rst

Use `available_fonts()` to list all fonts installed on the system and their available styles. The output shows font names and a tuple of their styles.

```build123d
from pprint import pprint
pprint(available_fonts())
```

```text
[ 
 ... 
 Font(name='Arial', styles=('REGULAR', 'BOLD', 'BOLDITALIC', 'ITALIC')),
 Font(name='Arial Black', styles=('REGULAR',)),
 Font(name='Arial Narrow', styles=('REGULAR', 'BOLD', 'BOLDITALIC', 'ITALIC')),
 Font(name='Arial Rounded MT Bold', styles=('REGULAR',)),
 ... 
 ]
```

--------------------------------

### Group by Axis and get first using group_by()

Source: https://github.com/gumyr/build123d/blob/dev/docs/selectors.rst

Group a ShapeList by a specified Axis and return the first element of each group. For example, group faces by their Y-coordinate.

```python
part.faces() << Axis.Y
```

--------------------------------

### Build Documentation on Windows

Source: https://github.com/gumyr/build123d/blob/dev/CONTRIBUTING.md

Build the project documentation locally on Windows systems.

```bash
./docs/make.bat html
```

--------------------------------

### Group by Axis and get last using group_by()

Source: https://github.com/gumyr/build123d/blob/dev/docs/selectors.rst

Group a ShapeList by a specified Axis and return the last element of each group. For example, group solids by their X-coordinate.

```python
part.solids() >> Axis.X
```

--------------------------------

### Constrain Arc to Line Ends with BuildLine

Source: https://github.com/gumyr/build123d/blob/dev/docs/build_line.rst

This example shows how to use the '@' operator to constrain the start and end points of a ThreePointArc to the ends of a Line object, improving design robustness.

```build123d
from build123d import *

with BuildLine() as example_2:
    l1 = Line((0,0), (2,0))
    ThreePointArc(l1 @ 0, l1 @ 1, (1,1))
```

--------------------------------

### Add latest build123d from GitHub using Poetry

Source: https://github.com/gumyr/build123d/blob/dev/docs/installation.rst

Installs the latest commit from the 'dev' branch of the build123d GitHub repository using Poetry. This ensures you get the most recent development version.

```bash
poetry add git+https://github.com/gumyr/build123d.git@dev
```

--------------------------------

### Build Documentation on Linux/macOS

Source: https://github.com/gumyr/build123d/blob/dev/CONTRIBUTING.md

Build the project documentation locally on Linux or macOS systems.

```bash
./docs/make html
```

--------------------------------

### Example Deferable Primitives

Source: https://github.com/gumyr/build123d/wiki/Lazy-Evaluation

Defines example primitives like Line and Rectangle that are decorated with `@deferable`, allowing them to be created lazily.

```python
# --- Example primitives ---

@deferable
def Line(p1, p2):
    return Edge.make_line(Vector(p1), Vector(p2))

@deferable
def Rectangle(w, h):
    return Face.make_rect(w, h)
```

--------------------------------

### Upgrade pip to the latest version

Source: https://github.com/gumyr/build123d/blob/dev/docs/installation.rst

Upgrades the pip package installer to its latest version. This is recommended to resolve potential dependency conflicts during installation.

```bash
python3 -m pip install --upgrade pip
```

--------------------------------

### Sort by Distance Example

Source: https://github.com/gumyr/build123d/blob/dev/docs/topology_selection/sort_examples.rst

Shows how to sort shapes by their distance from a reference object, using SortBy.DISTANCE. The example sorts boxes by their distance from the origin.

```build123d
from build123d import *

# Sort by distance from origin
with BuildPart() as bp:
    Box(1, 1, 1)
    Box(2, 2, 2)
    Box(3, 3, 3)
    sorted_boxes = bp.sorted_by(SortBy.DISTANCE)

print(f"Sorted by distance: {sorted_boxes}")
```

--------------------------------

### Using Location Contexts for Object Placement

Source: https://github.com/gumyr/build123d/blob/dev/docs/key_concepts_builder.rst

Demonstrates how to use BuildPart, Locations, and GridLocations contexts to position multiple objects within a builder. Locations define specific points, while GridLocations create a grid of positions.

```build123d
with BuildPart():
    with Locations((0,10),(0,-10)):
        Box(1,1,1)
        with GridLocations(x_spacing=5, y_spacing=5, x_count=2, y_count=2):
            Sphere(1)
        Cylinder(1,1)
```

--------------------------------

### BuildLine to BuildSketch for Face Creation

Source: https://github.com/gumyr/build123d/blob/dev/docs/build_line.rst

This example demonstrates how a BuildLine context manager, when within a BuildSketch context, transfers its generated line to BuildSketch for face creation.

```build123d
from build123d import *

with BuildSketch(Plane.XY) as example_6:
    with BuildLine(Plane.XY) as line_builder:
        l1 = Line((0,0), (2,0))
        ThreePointArc(l1 @ 0, l1 @ 1, (1,1))
    make_face()
    # The line_builder.line is now a Wire in the BuildSketch context
```

--------------------------------

### Build Complex Profiles with Lines and Arcs (Builder Mode)

Source: https://github.com/gumyr/build123d/blob/dev/docs/introductory_examples.rst

Constructs a prismatic solid from a complex 2D profile made of lines and arcs using BuildSketch and BuildLine in builder mode. Requires 'from build123d import *'.

```build123d
from build123d import *

# [Ex. 4]
with BuildPart() as ex4:
    with BuildSketch() as profile:
        with BuildLine():
            l1 = Line((0,0),(5,0))
            l2 = Line((5,0),(5,5))
            l3 = Line((5,5),(0,5))
            l4 = Line((0,5),(0,0))
        make_face()
    extrude(distance=2)
plate = ex4.part
```

--------------------------------

### Filleted Box Example in build123d

Source: https://github.com/gumyr/build123d/blob/dev/docs/tutorial_stl_reconstruction.rst

This snippet shows the creation of a filleted box using the build123d library. It serves as a controlled example for demonstrating STL reconstruction output.

```build123d
fillet(Box(1, 1, 1).edges(), 0.1)
```

--------------------------------

### Place Box on XY Plane at (0, 1, 0)

Source: https://github.com/gumyr/build123d/blob/dev/docs/key_concepts_algebra.rst

Demonstrates placing a Box on the XY plane at a specific location (0, 1, 0). Multiple equivalent syntaxes are shown.

```build123d
Plane.XY * Pos(0, 1, 0) * Box(1, 2, 3)
```

```build123d
Pos(0, 1, 0) * Box(1, 2, 3)
```

```build123d
Pos(Y=1) * Box(1, 2, 3)
```

--------------------------------

### Setup Axis Sorting

Source: https://github.com/gumyr/build123d/blob/dev/docs/topology_selection/sort_examples.rst

Contains the setup code for sorting shapes along specific axes. This is useful for selecting faces or edges based on their position relative to the coordinate system.

```build123d
from build123d import *

# Setup for axis sorting
```

```build123d
from build123d import *

# Setup for axis sorting
```

--------------------------------

### Define Wing Dimensions and Guide Curves

Source: https://github.com/gumyr/build123d/blob/dev/docs/tutorial_spitfire_wing_gordon.rst

Sets up the overall dimensions and elliptic leading/trailing edge guide curves for the Spitfire wing. This is the initial step for Gordon surface construction.

```build123d
from build123d import *

wing_span = 10.0
root_chord = 2.0
tip_chord = 1.0

# Elliptic leading and trailing edges
leading_edge = Ellipse(radius1=wing_span / 2.0, radius2=root_chord / 2.0)
trailing_edge = Ellipse(radius1=wing_span / 2.0, radius2=tip_chord / 2.0)

# Rotate the ellipses to align with the wing span
leading_edge = leading_edge.rotated((90, 0, 0))
trailing_edge = trailing_edge.rotated((90, 0, 0))

# Move the trailing edge to its correct position
trailing_edge = trailing_edge.moved((0, 0, wing_span / 2.0))

# Create guide curves by offsetting the leading edge to the trailing edge
# This creates a smooth transition for the wing surface
leading_guide = Polyline(leading_edge.sample(20))
trailing_guide = Polyline(trailing_edge.sample(20))

# Ensure the guides are oriented correctly for the Gordon surface
leading_guide = leading_guide.rotated((0, 90, 0))
trailing_guide = trailing_guide.rotated((0, 90, 0))
```

--------------------------------

### Grow Curves from Start Conditions

Source: https://github.com/gumyr/build123d/blob/dev/docs/tutorial_constraints.rst

Construct parabolas or hyperbolas from a starting point and grow them until they intersect with a line or axis. This method is effective for non-symmetric sketches requiring local constructions.

```build123d
p1 = ParabolicCenterArc((0, 0), 0.5, 0, arc_size=Line((0, 1), (5, 1)))
h1 = HyperbolicCenterArc((0, 0), 2, 1, 0, arc_size=Axis((0, 1), (1, 0)))
```

--------------------------------

### Setup for Grouping by Hole Area

Source: https://github.com/gumyr/build123d/blob/dev/docs/topology_selection/group_examples.rst

This setup code prepares a model with inner wires to demonstrate grouping faces by their area. It converts the inner wire to a face and calculates its area for grouping.

```build123d
from build123d import *

# Create a part with a hole
with BuildPart() as part:
    with BuildSketch(Plane.XY) as sk:
        with BuildLine():
            l1 = Line((0, 0), (10, 0))
            l2 = Line((10, 0), (10, 1))
            l3 = Line((10, 1), (0, 1))
            l4 = Line((0, 1), (0, 0))
        make_face()
        with BuildLine():
            l5 = Line((2, 0.5), (8, 0.5))
            l6 = Line((8, 0.5), (8, 0.5))
            l7 = Line((8, 0.5), (2, 0.5))
        make_face()
    extrude(amount=10)
```