mirrors/build123d
1
Fork 0
mirror of https://github.com/gumyr/build123d.git synced 2025-12-15 15:20:37 -08:00
Code Issues Projects Releases Packages Wiki Activity Actions

Major documentation re-organization

Browse source
This commit is contained in:
Roger Maitland 2022-09-29 14:25:48 -04:00
parent edfa008a9e
commit 86ad1d3336
15 changed files with 419 additions and 140 deletions
Download patch file Download diff file Expand all files Collapse all files

138
docs/api_reference.rst Normal file
View file

@ -0,0 +1,138 @@
#############
API Reference
#############
******************************
Generic Objects and Operations
******************************
There are several objects and operations that apply to more than one type
of builder which are listed here. The builder that these operations apply
to is determined by context.
.. py:module:: build_generic
=======
Objects
=======
.. autoclass:: Add
==========
Operations
==========
.. autoclass:: BoundingBox
.. autoclass:: Chamfer
.. autoclass:: Fillet
.. autoclass:: Mirror
.. autoclass:: Offset
.. autoclass:: Scale
.. autoclass:: Split
.. _shape_list:
=========
ShapeList
=========
.. py:module:: build_common
.. autoclass:: ShapeList
:members:
*********
BuildLine
*********
.. py:module:: build_line
.. autoclass:: BuildLine
:members:
=======
Objects
=======
.. autoclass:: CenterArc
.. autoclass:: Helix
.. autoclass:: Line
.. autoclass:: PolarLine
.. autoclass:: Polyline
.. autoclass:: RadiusArc
.. autoclass:: SagittaArc
.. autoclass:: Spline
.. autoclass:: TangentArc
.. autoclass:: ThreePointArc
***********
BuildSketch
***********
.. py:module:: build_sketch
.. autoclass:: BuildSketch
:members:
=======
Objects
=======
.. autoclass:: Circle
.. autoclass:: Ellipse
.. autoclass:: Polygon
.. autoclass:: Rectangle
.. autoclass:: RegularPolygon
.. autoclass:: SlotArc
.. autoclass:: SlotCenterPoint
.. autoclass:: SlotCenterToCenter
.. autoclass:: SlotOverall
.. autoclass:: Text
.. autoclass:: Trapezoid
==========
Operations
==========
.. autoclass:: BuildFace
.. autoclass:: BuildHull
*********
BuildPart
*********
.. py:module:: build_part
.. autoclass:: BuildPart
:members:
=======
Objects
=======
.. autoclass:: Box
.. autoclass:: Cone
.. autoclass:: Cylinder
.. autoclass:: Sphere
.. autoclass:: Torus
.. autoclass:: Wedge
==========
Operations
==========
.. autoclass:: CounterBoreHole
.. autoclass:: CounterSinkHole
.. autoclass:: Extrude
.. autoclass:: Hole
.. autoclass:: Loft
.. autoclass:: Revolve
.. autoclass:: Sweep
*****************
Geometric Objects
*****************
.. py:module:: build_common
:noindex:
.. _axis:
.. autoclass:: Axis
.. autoclass:: Rotation
*************
Shape Objects
*************

25
docs/build_generic.rst
View file

@ -1,25 +0,0 @@
##############################
Generic Objects and Operations
##############################
There are several objects and operations that apply to more than one type
of builder which are listed here. The builder that these operations apply
to is determined by context.
.. py:module:: build_generic
=======
Objects
=======
.. autoclass:: Add
==========
Operations
==========
.. autoclass:: BoundingBox
.. autoclass:: Chamfer
.. autoclass:: Fillet
.. autoclass:: Mirror
.. autoclass:: Offset
.. autoclass:: Scale
.. autoclass:: Split

21
docs/build_line.rst
View file

@ -1,21 +0,0 @@
#########
BuildLine
#########
.. py:module:: build_line
.. autoclass:: BuildLine
:members:
=======
Objects
=======
.. autoclass:: CenterArc
.. autoclass:: Helix
.. autoclass:: Line
.. autoclass:: PolarLine
.. autoclass:: Polyline
.. autoclass:: RadiusArc
.. autoclass:: SagittaArc
.. autoclass:: Spline
.. autoclass:: TangentArc
.. autoclass:: ThreePointArc

30
docs/build_part.rst
View file

@ -1,30 +0,0 @@
#########
BuildPart
#########
.. py:module:: build_part
.. autoclass:: BuildPart
:members:
=======
Objects
=======
.. autoclass:: Box
.. autoclass:: Cone
.. autoclass:: Cylinder
.. autoclass:: Sphere
.. autoclass:: Torus
.. autoclass:: Wedge
==========
Operations
==========
.. autoclass:: CounterBoreHole
.. autoclass:: CounterSinkHole
.. autoclass:: Extrude
.. autoclass:: Hole
.. autoclass:: Loft
.. autoclass:: Revolve
.. autoclass:: Sweep

30
docs/build_sketch.rst
View file

@ -1,30 +0,0 @@
###########
BuildSketch
###########
.. py:module:: build_sketch
.. autoclass:: BuildSketch
:members:
=======
Objects
=======
.. autoclass:: Circle
.. autoclass:: Ellipse
.. autoclass:: Polygon
.. autoclass:: Rectangle
.. autoclass:: RegularPolygon
.. autoclass:: SlotArc
.. autoclass:: SlotCenterPoint
.. autoclass:: SlotCenterToCenter
.. autoclass:: SlotOverall
.. autoclass:: Text
.. autoclass:: Trapezoid
==========
Operations
==========
.. autoclass:: BuildFace
.. autoclass:: BuildHull

12
docs/index.rst
View file

@ -70,6 +70,7 @@ added to `my_part` once the sketch is complete.
As an example, consider the design of a simple bearing pillow block:
.. literalinclude:: ../examples/pillow_block.py
:lines: 28-47
#################
@ -79,15 +80,12 @@ Table Of Contents
.. toctree::
:maxdepth: 2
introduction.rst
installation.rst
tutorial.rst
selectors.rst
advantages.rst
tutorials.rst
key_concepts.rst
build_line.rst
build_sketch.rst
build_part.rst
build_generic.rst
advantages.rst
api_reference.rst
==================
Indices and tables

7
docs/installation.rst
View file

@ -6,3 +6,10 @@ Install from github:
.. doctest::
>>> python3 -m pip install git+https://github.com/gumyr/build123d.git#egg=build123d
In addition, cq_warehouse is a required dependency which will be removed in the
future. To install cq_warehouse:
.. doctest::
>>> python3 -m pip install git+https://github.com/gumyr/cq_warehouse.git#egg=cq_warehouse

3
docs/introduction.rst Normal file
View file

@ -0,0 +1,3 @@
============
Introduction
============

13
docs/key_concepts.rst
View file

@ -1,6 +1,6 @@
############
Key Concepts
############
########
Concepts
########
The following key concepts will help new users understand build123d quickly.
@ -95,6 +95,7 @@ This is the result:
A detailed description of `Workplanes` follows:
.. py:module:: build_common
:noindex:
.. autoclass:: Workplanes
@ -193,6 +194,12 @@ a volume from the part under normal circumstances. However, the `mode` used in
the `Hole` classes can be specified as `Mode.ADD` or `Mode.INTERSECT` to
help in inspection or debugging.
*********
Selectors
*********
.. include:: selectors.rst
**********************************
Using Locations & Rotating Objects
**********************************

53
docs/selector_example.py Normal file
View file

@ -0,0 +1,53 @@
"""
name: selector_example.py
by: Gumyr
date: September 28th 2022
desc:
This illustrates use of several selectors.
license:
Copyright 2022 Gumyr
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
"""
from build123d import *
from cadquery import exporters
svg_opts = {
"width": 500,
"height": 300,
"marginLeft": 60,
"marginTop": 30,
"showAxes": False,
"projectionDir": (1, 1, 0.7),
"showHidden": False,
}
with BuildPart() as example:
Cylinder(radius=10, height=3)
with Workplanes(example.faces() >> Axis.Z):
with BuildSketch():
RegularPolygon(radius=7, side_count=6)
Extrude(amount=-2, mode=Mode.SUBTRACT)
with BuildSketch():
Circle(radius=4)
Extrude(amount=-2, mode=Mode.ADD)
exporters.export(example.part, "selector_before.svg", opt=svg_opts)
Fillet((example.edges() % GeomType.CIRCLE > SortBy.RADIUS)[-2:] >> Axis.Z, radius=1)
exporters.export(example.part, "selector_after.svg", opt=svg_opts)
if "show_object" in locals():
show_object(example.part, name="part")

31
docs/selectors.rst
View file

@ -1,16 +1,11 @@
#########
Selectors
#########
When using a GUI based CAD system the user will often click on a feature to select
it for some operation. How does a user "click" when CAD is done entirely in code?
Selectors are recipes for how to isolate a feature from a design using python
filter and sorting methods typically implemented as a set of custom python
operations.
***************
Quick Reference
***************
---------------
The following tables describes the build123d selectors:
@ -46,36 +41,34 @@ The following tables describes the build123d selectors:
| [] | | Standard python list indexing and slicing | `part.faces()[-2:]` |
+----------+--------------+--------------------------------------------------+----------------------------------+
The operand types are described below:
The operand types are: Axis, SortBy, and GeomType. An Axis is a base object with an origin and a
direction with several predefined values such as ``Axis.X``, ``Axis.Y``, and ``Axis.Z``; however,
any Axis could be used as an operand (e.g. ``Axis((1,2,3),(0.5,0,-0.5))`` is valid) - see
:ref:`API Reference/Axis <axis>` for a complete description. SortBy and GeomType are python
Enum class described here:
.. py:module:: build_common
:noindex:
.. autoclass:: build_common.Axis
:members:
.. autoclass:: build_common.SortBy
:members:
:noindex:
.. autoclass:: build_common.GeomType
:members:
:noindex:
***************
ShapeList Class
***************
---------------
The builders include methods to extract Edges, Faces, Solids, Vertices, or Wires from the objects
they are building. All of these methods return objects of a subclass of `list`, a `ShapeList` with
custom filtering and sorting methods and operations as follows.
custom filtering and sorting methods and operations as follows. The full ShapeList API is can be
found in :ref:`API Reference/ShapeList <shape_list>`.
.. autoclass:: build_common.ShapeList
:members:
:exclude-members: axis_map
****************************
Custom Sorting and Filtering
****************************
----------------------------
It is important to note that standard list methods such as `sorted` or `filtered` can
be used to easily build complex selectors beyond what is available with the predefined

6
docs/tutorial.rst → docs/tutorial_lego.rst
View file

@ -1,6 +1,6 @@
########
Tutorial
########
#############
Lego Tutorial
#############
This tutorial provides a step by step guide to creating a script to build a parametric
Lego block.

173
docs/tutorial_selectors.rst Normal file
View file

@ -0,0 +1,173 @@
#################
Selector Tutorial
#################
This tutorial provides a step by step guide in using selectors as we create
this part:
.. image:: selector_after.svg
:align: center
*************
Step 1: Setup
*************
Before getting to the CAD operations, this selector script needs to import the build123d
environment.
.. literalinclude:: selector_example.py
:lines: 27
**********************************
Step 2: Create Base with BuildPart
**********************************
To start off, the part will be based on a cylinder so we'll use the ``Cylinder`` object
of ``BuildPart``:
.. literalinclude:: selector_example.py
:lines: 27,39-40
:emphasize-lines: 2-3
************************
Step 3: Create Workplane
************************
The remainder of the features in this design will be created on the top of the cylinder
so we'll create a workplane centered on the top of the cylinder. To locate this
workplane we'll use the cylinder's top Face as shown here:
.. literalinclude:: selector_example.py
:lines: 27,39-40,41
:emphasize-lines: 4
Here we're using selectors to find that top Face - let's break down
``example.faces() >> Axis.Z``:
Step 3a: Extract Faces from a part
----------------------------------
The first sub-step is the extraction of all of the Faces from the part that we're
building. The identifier of ``example`` was assigned when ``BuildPart`` when
it was instantiated so ``example.faces()`` will extract all of the Faces from
our part into a custom type of python ``list`` - a ``ShapeList`` (see
:ref:`API Reference/ShapeList <shape_list>` for a full description).
Step 3b: Get top Face
---------------------
The next sub-step is to sort the ShapeList of Faces by their position with
respect to the Z Axis. The ``>>`` operator will sort the list by relative position
of the object's center to the ``Axis.Z`` and also
select the last item on that list - or return the top Face of the ``example`` part.
*******************************
Step 4: Create a six sided hole
*******************************
The object has a hexagon hole in the top which we'll build on the previously created
workplane.
.. literalinclude:: selector_example.py
:lines: 27,39-40,41,42-44
:emphasize-lines: 5-7
Step 4a: Draw a hexagon on top of the part
------------------------------------------
``BuildSketch`` is the tool for drawing on planar surfaces so we'll create one
with the use of ``RegularPolygon`` with six sides.
Step 4b: Extrude the hexagon and create a hole
----------------------------------------------
To create the hole we'll extrude the sketch we created in the previous step
in a negative direction - i.e. down - and subtract this hexagon shape from the
``example`` part. Note the use of ``mode=Mode.SUBTRACT`` which is how we
instruct the builder to cut the hexagon from the part.
*********************************
Step 5: Create a central cylinder
*********************************
To create the internal cylindrical feature we'll repeat Step 4 but with
a ``Circle`` and ``mode=Mode.ADD`` (which is the default) which adds
the feature to the ``example`` part.
.. literalinclude:: selector_example.py
:lines: 27,39-40,41,42-44,45-47
:emphasize-lines: 8-10
At this point the part looks like:
.. image:: selector_before.svg
:align: center
*************************************
Step 6: Fillet the top perimeter Edge
*************************************
The final step is to apply a fillet to the top perimeter.
.. literalinclude:: selector_example.py
:lines: 27,39-40,41,42-44,45-47,49
:emphasize-lines: 11
Here we're using the ``Fillet`` operation which needs two things:
the edge(s) to fillet and the radius of the fillet. To provide
the edge, we'll use more selectors as described in the following
sub-steps.
Step 6a: Extract all the Edges
------------------------------
Much like selecting Faces in Step 3a, we'll select all of the ``example``
part's edges with ``example.edges()``.
Step 6b: Filter the Edges for circles
-------------------------------------
Since we know that the edge we're looking for is a circle, we can
filter the edges selected in Step 6a for just those that are of
geometric type ``CIRCLE`` with ``example.edges() % GeomType.CIRCLE``.
This step removes all of the Edges of the hexagon hole.
Step 6c: Sort the circles by radius
-----------------------------------
The perimeter are the largest circles - the central cylinder must be
excluded - so we'll sort all of the circles by their radius with:
``example.edges() % GeomType.CIRCLE > SortBy.RADIUS``.
Step 6d: Slice the list to get the two largest
----------------------------------------------
We know that the ``example`` part has two perimeter circles so we'll
select just the top two edges from the sorted circle list with:
``(example.edges() % GeomType.CIRCLE > SortBy.RADIUS)[-2:]``. The
syntax of this slicing operation is standard python list slicing.
Step 6e: Select the top Edge
----------------------------
The last sub-step is to select the top perimeter edge, the one with
the greatest Z value which we'll do with the ``>>`` operator just like
Step 3b - note that the operators work on all Shape objects (Edges, Wires,
Faces, Solids, and Compounds) - with:
``(example.edges() % GeomType.CIRCLE > SortBy.RADIUS)[-2:] >> Axis.Z``.
**********
Conclusion
**********
By using selectors as we have in this example we've used methods
of identifying features that are robust to features changing within
the part. We've also avoided the classic CAD "Topological naming problem"
by never referring to features with names or tags that could become obsolete
as the part changes.
When possible, avoid using static list indices to refer to features
extracted from methods like ``edges()`` as the order within the list
is not guaranteed to remain the same.

13
docs/tutorials.rst Normal file
View file

@ -0,0 +1,13 @@
#########
Tutorials
#########
There are several tutorials to help guide uses through the concepts of build123d
in a step by step way. Working through these tutorials in order is recommended
as later tutorials build on the concepts introduced in earlier ones.
.. toctree::
:maxdepth: 2
tutorial_selectors.rst
tutorial_lego.rst

4
src/build123d/build_common.py
View file

@ -1177,8 +1177,8 @@ class Workplanes(WorkplaneList):
Create workplanes from the given sequence of planes.
Args:
objs (Union[Face,PlaneLike]): sequence of faces or planes to use
as workplanes.
objs (Union[Face, PlaneLike, Location]): sequence of faces, planes, or
locations to use to define workplanes.
Raises:
ValueError: invalid input
"""