Add headings, demo images, section with basic usage and feature overview, slim down installation

CONTRIBUTING.md

@@ -1,13 +1,34 @@
-When writing code for inclusion in build123d please add docs and
+# Contributing
+
+When writing code for inclusion in build123d please add docstrings and
 tests, ensure they build and pass, and ensure that `pylint` and `mypy`
 are happy with your code.
 
-- Install `pip` following their [documentation](https://pip.pypa.io/en/stable/installation/).
-- Install development dependencies: `pip install -e ".[development]"`
-- Install docs dependencies: `pip install -e ".[docs]"`
-- Install `build123d` in editable mode from current dir:  `pip install -e .`
+## Setup
+
+Ensure `pip` is installed and [up-to-date](https://pip.pypa.io/en/stable/installation/#upgrading-pip).
+Clone the build123d repo and install in editable mode:
+
+```
+git clone https://github.com/gumyr/build123d.git
+cd build123d
+pip install -e .
+```
+
+Install development and docs dependencies:
+
+```
+pip install -e ".[development]"
+pip install -e ".[docs]"
+```
+
+## Before submitting a PR
+
 - Run tests with: `python -m pytest -n auto`
-- Build docs with: `cd docs && make html`
-- Check added files' style with: `pylint <path/to/file.py>` 
+- Check added files' style with: `pylint <path/to/file.py>`
 - Check added files' type annotations with: `mypy <path/to/file.py>`
-- Run black formatter against files' changed: `black --config pyproject.toml <path/to/file.py>` (where the pyproject.toml is from this project's repository)
+- Run black formatter against files' changed: `black <path/to/file.py>`
+
+To verify documentation changes build docs with:
+- Linux/macOS: `./docs/make html`
+- Windows: `./docs/make.bat html`

README.md

@@ -1,6 +1,6 @@
-<p align="center">
+<h1 align="left">
     <img alt="build123d logo" src="https://github.com/gumyr/build123d/raw/dev/docs/assets/build123d_logo/logo-banner.svg">
-</p>
+</h1>
 
 [![Documentation Status](https://readthedocs.org/projects/build123d/badge/?version=latest)](https://build123d.readthedocs.io/en/latest/?badge=latest)
 [![tests](https://github.com/gumyr/build123d/actions/workflows/test.yml/badge.svg)](https://github.com/gumyr/build123d/actions/workflows/test.yml)
@@ -18,63 +18,239 @@
 [![PyPI - Wheel](https://img.shields.io/pypi/wheel/build123d.svg)](https://pypi.org/project/build123d/)
 [![DOI](https://zenodo.org/badge/510925389.svg)](https://doi.org/10.5281/zenodo.14872322)
 
+[Documentation](https://build123d.readthedocs.io/en/latest/index.html) |
+[Cheat Sheet](https://build123d.readthedocs.io/en/latest/cheat_sheet.html) |
+[Discord](https://discord.com/invite/Bj9AQPsCfx) |
+[Discussions](https://github.com/gumyr/build123d/discussions) |
+[Issues](https://github.com/gumyr/build123d/issues ) |
+[Contributing]()
 
-Build123d is a Python-based, parametric [boundary representation (BREP)][BREP] modeling framework for 2D and 3D CAD. Built on the [Open Cascade] geometric kernel, it provides a clean, fully Pythonic interface for creating precise models suitable for 3D printing, CNC machining, laser cutting, and other manufacturing processes. Models can be exported to popular CAD tools such as [FreeCAD] and SolidWorks.
+build123d is a Python-based, parametric [boundary representation (BREP)][BREP] modeling framework for 2D and 3D CAD. Built on the [Open Cascade] geometric kernel, it provides a clean, fully Pythonic interface for creating precise models suitable for 3D printing, CNC machining, laser cutting, and other manufacturing processes.
+
+<div align="left">
+    <img style="height:200px" alt="bracket" src="https://github.com/gumyr/build123d/raw/dev/docs/assets/examples/toy_truck.png">
+    <img style="height:200px" alt="key cap" src="https://github.com/gumyr/build123d/raw/dev/docs/assets/examples/key_cap.png">
+    <img style="height:200px" alt="hangar" src="https://github.com/gumyr/build123d/raw/dev/docs/assets/ttt/ttt-23-02-02-sm_hanger_object.png">
+</div>
+
+## Features
 
 Designed for modern, maintainable CAD-as-code, build123d combines clear architecture with expressive, algebraic modeling. It offers:
 - Minimal or no internal state depending on mode,
 - Explicit 1D, 2D, and 3D geometry classes with well-defined operations,
 - Extensibility through subclassing and functional composition—no monkey patching,
 - Standards-compliant code (PEP 8, mypy, pylint) with rich pylance type hints,
-- Deep Python integration—selectors as lists, locations as iterables, and natural conversions (Solid(shell), tuple(Vector)),
-- Operator-driven modeling (obj += sub_obj, Plane.XZ * Pos(X=5) * Rectangle(1, 1)) for algebraic, readable, and composable design logic.
+- Deep Python integration—selectors as lists, locations as iterables, and natural conversions (`Solid(shell)`, `tuple(Vector)`),
+- Operator-driven modeling (`obj += sub_obj`, `Plane.XZ * Pos(X=5) * Rectangle(1, 1)`) for algebraic, readable, and composable design logic,
+- Export formats to popular CAD tools such as [FreeCAD] and SolidWorks.
 
-The result is a framework that feels native to Python while providing the full power of OpenCascade geometry underneath.
+## Usage
 
-The documentation for **build123d** can be found at [readthedocs](https://build123d.readthedocs.io/en/latest/index.html).
+Although wildcard imports are generally bad practice, build123d scripts are usually self contained and importing the large number of objects and methods into the namespace is common:
 
-There is a [***Discord***](https://discord.com/invite/Bj9AQPsCfx) server (shared with [CadQuery]) where you can ask for help in the build123d channel.
+```py
+from build123d import *
+```
 
-The recommended method for most users to install **build123d** is:
+### Constructing a 1D Shape
+
+Edges, Wires (multiple connected Edges), and Curves (a Compound of Edges and Wires) are the 1D Shapes available in build123d. A single Edge can be created from a Line object with two vector-like positions:
+
+```py
+line = Line((0, -3), (6, -3))
+```
+
+Additional Edges and Wires may be added to (or subtracted from) the initial line. These objects can reference coordinates along another line through the position (`@`) and tangent (`%`) operators to specify input Vectors:
+
+```py
+line += JernArc(line @ 1, line % 1, radius=3, arc_size=180)
+line += PolarLine(line @ 1, 6, direction=line % 1)
+```
+
+<div align="left">
+    <img style="max-height:150px" alt="create 1d" src="https://github.com/gumyr/build123d/raw/dev/docs/assets/readme/create_1d.png">
+</div>
+
+### Upgrading to 2D and 3D
+
+Faces, Shells (multiple connected Faces), and Sketches (a Compound of Faces and Shells) are the 2d Shapes available in build123d. The previous line is sufficiently defined to close the Wire and create a Face with `make_hull`:
+
+```py
+sketch = make_hull(line)
+```
+
+A Circle face is translated with `Pos`, a Location object like `Rot` for transforming Shapes, and subtracted from the sketch. This sketch face is then extruded into a Solid part:
+
+```py
+sketch -= Pos(6, 0, 0) * Circle(2)
+part = extrude(sketch, amount= 2)
+```
+
+<div align="left">
+    <img style="max-height:150px" alt="upgrade 2d" src="https://github.com/gumyr/build123d/raw/dev/docs/assets/readme/upgrade_2d.png">
+</div>
+
+### Adding to and modifying part
+
+Solids and Parts (a Compound of Solids) are the 1D Shapes available in build123d. A second part can be created from an additional Face. Planes can also be used for positioning and orienting Shape objects. Many objects offer an affordance for alignment relative to the object origin:
+
+```py
+plate_sketch = Plane.YZ * RectangleRounded(16, 6, 1.5, align=(Align.CENTER, Align.MIN))
+plate = extrude(plate_sketch, amount=-2)
+```
+
+Shape topology can be extracted from Shapes with selectors which return ShapeLists. ShapeLists offer methods for sorting, grouping, and filtering Shapes by Shape properties, such as finding a Face by area and selecting position along an Axis and specifying a target with a list slice. A Plane is created from the specified Face to locate an iterable of Locations to place multiple objects on the second part before it is added to the main part:
+
+```py
+plate_face = plate.faces().group_by(Face.area)[-1].sort_by(Axis.X)[-1]
+plate -= Plane(plate_face) *  GridLocations(13, 3, 2, 2) * CounterSinkHole(.5, 1, 2)
+
+part += plate
+```
+
+ShapeList selectors and operators offer powerful methods for specifying Shape features through properties such as length/area/volume, orientation relative to an Axis or Plane, and geometry type:
+
+```py
+part = fillet(part.edges().filter_by(lambda e: e.length == 2).filter_by(Axis.Z), 1)
+bore = part.faces().filter_by(GeomType.CYLINDER).filter_by(lambda f: f.radius == 2)
+part = chamfer(bore.edges(), .2)
+```
+
+<div align="left">
+    <img style="max-height:150px" alt="modify part" src="https://github.com/gumyr/build123d/raw/dev/docs/assets/readme/add_part.png">
+</div>
+
+### Builder Mode
+
+The previous construction is through the **Algebra Mode** interface, which follows a stateless paradigm where each object is explicitly tracked and mutated by algebraic operators.
+
+**Builder Mode** is an alternative build123d interface where state is tracked and structured in a design history-like way where each dimension is distinct. Operations are aware pending faces and edges from Build contexts and location transformations are applied to all child objects in Build and Locations contexts. Builder mode also introduces the `mode` affordance to objects to specify how new Shapes are combined with the context:
+
+```py
+with BuildPart() as part_context:
+    with BuildSketch() as sketch:
+        with BuildLine() as line:
+            l1 = Line((0, -3), (6, -3))
+            l2 = JernArc(l1 @ 1, l1 % 1, radius=3, arc_size=180)
+            l3 = PolarLine(l2 @ 1, 6, direction=l2 % 1)
+            l4 = Line(l1 @ 0, l3 @ 1)
+        make_face()
+
+        with Locations((6, 0, 0)):
+            Circle(2, mode=Mode.SUBTRACT)
+
+    extrude(amount=2)
+
+    with BuildSketch(Plane.YZ) as plate_sketch:
+        RectangleRounded(16, 6, 1.5, align=(Align.CENTER, Align.MIN))
+
+    plate = extrude(amount=-2)
+
+    with Locations(plate.faces().group_by(Face.area)[-1].sort_by(Axis.X)[-1]):
+        with GridLocations(13, 3, 2, 2):
+            CounterSinkHole(.5, 1)
+
+    fillet(edges().filter_by(lambda e: e.length == 2).filter_by(Axis.Z), 1)
+    bore = faces().filter_by(GeomType.CYLINDER).filter_by(lambda f: f.radius == 2)
+    chamfer(bore.edges(), .2)
+```
+
+### Extending objects
+
+New objects may be created for parametric reusability from base object classes:
+
+```py
+class Punch(BaseSketchObject):
+    def __init__(
+        self,
+        radius: float,
+        size: float,
+        blobs: float,
+        mode: Mode = Mode.ADD,
+    ):
+        with BuildSketch() as punch:
+            if blobs == 1:
+                Circle(size)
+            else:
+                with PolarLocations(radius, blobs):
+                    Circle(size)
+
+            if len(faces()) > 1:
+                raise RuntimeError("radius is too large for number and size of blobs")
+
+            add(Face(faces()[0].outer_wire()), mode=Mode.REPLACE)
+
+        super().__init__(obj=punch.sketch, mode=mode)
+
+tape = Rectangle(20, 5)
+for i, location in enumerate(GridLocations(5, 0, 4, 1)):
+    tape -= location * Punch(.8, 1, i + 1)
+```
+
+<div align="left">
+    <img style="max-height:150px" alt="extend" src="https://github.com/gumyr/build123d/raw/dev/docs/assets/readme/extend.png">
+</div>
+
+### Data interchange
+
+build123d can import and export a number data formats for interchange with 2d and 3d design tools, 3D printing slicers, and traditional CAM:
+
+```py
+svg = import_svg("spade.svg")
+step = import_step("nema-17-bracket.step")
+
+export_stl(part, "bracket.stl")
+export_step(part_context.part, "bracket.step")
+```
+
+### Further reading
+
+More [Examples](https://build123d.readthedocs.io/en/latest/introductory_examples.html) and [Tutorials](https://build123d.readthedocs.io/en/latest/tutorials.html) are found in the documentation.
+
+## Installation
+
+For additional installation options see [Installation](https://build123d.readthedocs.io/en/latest/installation.html)
+
+### Current release
+
+Installing build123d from `pip` is recommended for most users:
 
 ```
 pip install build123d
 ```
 
-To get the latest non-released version of **build123d** one can install from GitHub using one of the following two commands:
-
-Linux/MacOS:
+If you receive errors about conflicting dependencies, retry the installation after upgrading pip to the latest version:
 
 ```
-python3 -m pip install git+https://github.com/gumyr/build123d
+pip install --upgrade pip
 ```
 
-Windows:
+### Pre- release
+
+build123d is under active development and up-to-date features are found in the
+development branch:
 
 ```
-python -m pip install git+https://github.com/gumyr/build123d
+pip install git+https://github.com/gumyr/build123d
 ```
 
-If you receive errors about conflicting dependencies, you can retry the installation after having upgraded pip to the latest version with the following command:
-```
-python3 -m pip install --upgrade pip
-```
+### Viewers
 
-Development install:
+build123d is best used with a viewer. The most popular viewer is [ocp_vscode](https://github.com/bernhard-42/vscode-ocp-cad-viewer), a Python package with a standalone viewer and VS Code extension. Other [Editors & Viewers](https://build123d.readthedocs.io/en/latest/external.html#external) are found in the documentation.
 
-```
-git clone https://github.com/gumyr/build123d.git
-cd build123d
-python3 -m pip install -e .
-```
+## Contributing
 
-Further installation instructions are available (e.g. Poetry) see the [installation section on readthedocs](https://build123d.readthedocs.io/en/latest/installation.html).
+build123d is a rapidly growing project and we welcome all contributions. Whether you want to share ideas, report bugs, or implement new features, your contribution is welcome! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) file to get started.
 
-Attribution:
+## Attribution
 
-Build123d was originally derived from portions of the [CadQuery] codebase but has since been extensively refactored and restructured into an independent system.
+build123d is derived from portions of [CadQuery], but is extensively refactored and restructured into an independent framework over [Open Cascade].
+
+## License
+
+This project is licensed under the [Apache License 2.0](LICENSE).
 
 [BREP]: https://en.wikipedia.org/wiki/Boundary_representation
 [CadQuery]: https://cadquery.readthedocs.io/en/latest/index.html
 [FreeCAD]: https://www.freecad.org/
-[Open Cascade]: https://dev.opencascade.org/
+[Open Cascade]: https://dev.opencascade.org/

docs/assets/readme/readme.py

@@ -0,0 +1,95 @@
+import os
+from copy import copy
+
+from build123d import *
+from ocp_vscode import *
+
+working_path = os.path.dirname(os.path.abspath(__file__))
+
+with BuildPart() as part_context:
+    with BuildSketch() as sketch:
+        with BuildLine() as line:
+            l1 = Line((0, -3), (6, -3))
+            l2 = JernArc(l1 @ 1, l1 % 1, radius=3, arc_size=180)
+            l3 = PolarLine(l2 @ 1, 6, direction=l2 % 1)
+            l4 = Line(l1 @ 0, l3 @ 1)
+        make_face()
+
+        with Locations((6, 0, 0)):
+            Circle(2, mode=Mode.SUBTRACT)
+
+    extrude(amount=2)
+
+    with BuildSketch(Plane.YZ) as plate_sketch:
+        RectangleRounded(16, 6, 1.5, align=(Align.CENTER, Align.MIN))
+
+    plate = extrude(amount=-2)
+
+    with Locations(plate.faces().group_by(Face.area)[-1].sort_by(Axis.X)[-1]):
+        with GridLocations(13, 3, 2, 2):
+            CounterSinkHole(.5, 1)
+
+    fillet(edges().filter_by(lambda e: e.length == 2).filter_by(Axis.Z), 1)
+    bore = faces().filter_by(GeomType.CYLINDER).filter_by(lambda f: f.radius == 2)
+    chamfer(bore.edges(), .2)
+
+line = Line((0, -3), (6, -3))
+line += JernArc(line @ 1, line % 1, radius=3, arc_size=180)
+line += PolarLine(line @ 1, 6, direction=line % 1)
+
+sketch = make_hull(line.edges())
+sketch -= Pos(6, 0, 0) * Circle(2)
+part = extrude(sketch, amount= 2)
+part_before = copy(part)
+
+plate_sketch = Plane.YZ * RectangleRounded(16, 6, 1.5, align=(Align.CENTER, Align.MIN))
+plate = extrude(plate_sketch, amount=-2)
+plate_face = plate.faces().group_by(Face.area)[-1].sort_by(Axis.X)[-1]
+plate -= Plane(plate_face) *  GridLocations(13, 3, 2, 2) * CounterSinkHole(.5, 1, 2)
+
+part += plate
+part_before2 = copy(part)
+
+part = fillet(part.edges().filter_by(lambda e: e.length == 2).filter_by(Axis.Z), 1)
+bore = part.faces().filter_by(GeomType.CYLINDER).filter_by(lambda f: f.radius == 2)
+part = chamfer(bore.edges(), .2)
+
+class Punch(BaseSketchObject):
+    def __init__(
+        self,
+        radius: float,
+        size: float,
+        blobs: float,
+        rotation: float = 0,
+        mode: Mode = Mode.ADD,
+    ):
+        with BuildSketch() as punch:
+            if blobs == 1:
+                Circle(size)
+            else:
+                with PolarLocations(radius, blobs):
+                    Circle(size)
+
+            if len(faces()) > 1:
+                raise RuntimeError("radius is too large for number and size of blobs")
+
+            add(Face(faces()[0].outer_wire()), mode=Mode.REPLACE)
+
+        super().__init__(obj=punch.sketch, rotation=rotation, mode=mode)
+
+tape = Rectangle(20, 5)
+for i, location in enumerate(GridLocations(5, 0, 4, 1)):
+    tape -= location * Punch(.8, 1, i + 1)
+
+set_defaults(reset_camera=Camera.RESET)
+show(line)
+save_screenshot(os.path.join(working_path, "create_1d.png"))
+
+show(sketch, Pos(10, 10) * part_before)
+save_screenshot(os.path.join(working_path, "upgrade_2d.png"))
+
+show(plate, Pos(12, 12) * part_before2, Pos(24, 24) * part)
+save_screenshot(os.path.join(working_path, "add_part.png"))
+
+show(tape)
+save_screenshot(os.path.join(working_path, "extend.png"))