mirror of
https://github.com/gumyr/build123d.git
synced 2025-12-05 18:20:46 -08:00
Docs reorganization
This commit is contained in:
Roger Maitland
parent
121951e8f8
commit
ca1c45b2a4
15 changed files with 161 additions and 108 deletions
11
docs/advanced.rst
Normal file
11
docs/advanced.rst
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
###############
|
||||
Advanced Topics
|
||||
###############
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
assemblies.rst
|
||||
center.rst
|
||||
custom.rst
|
||||
debugging_logging.rst
|
||||
|
|
@ -1,13 +1,9 @@
|
|||
##########
|
||||
Advantages
|
||||
##########
|
||||
|
||||
As mentioned previously, the most significant advantage is that build123d is more pythonic.
|
||||
Specifically:
|
||||
|
||||
*******************************
|
||||
Standard Python Context Manager
|
||||
*******************************
|
||||
===============================
|
||||
|
||||
The creation of standard instance variables, looping and other normal python operations
|
||||
is enabled by the replacement of method chaining (fluent programming) with a standard
|
||||
python context manager.
|
||||
|
|
@ -40,9 +36,9 @@ statement anywhere in the code without impacting functionality. Simple python
|
|||
`for` loops can be used to repetitively create objects instead of forcing users
|
||||
into using more complex `lambda` and `iter` operations.
|
||||
|
||||
********************
|
||||
Instantiated Objects
|
||||
********************
|
||||
====================
|
||||
|
||||
Each object and operation is now a class instantiation that interacts with the
|
||||
active context implicitly for the user. These instantiations can be assigned to
|
||||
an instance variable as with standard python programming for direct use.
|
||||
|
|
@ -54,9 +50,9 @@ an instance variable as with standard python programming for direct use.
|
|||
print(r.Area())
|
||||
...
|
||||
|
||||
*********
|
||||
Operators
|
||||
*********
|
||||
=========
|
||||
|
||||
New operators have been created to extract information from objects created previously
|
||||
in the code. The `@` operator extracts the position along an Edge or Wire while the
|
||||
`%` operator extracts the tangent along an Edge or Wire. The position parameter are float
|
||||
|
|
@ -75,9 +71,8 @@ features to these points without knowing their numeric values.
|
|||
Spline(l5 @ 1, l6 @ 0, tangents=(l5 % 1, l6 % 0))
|
||||
|
||||
|
||||
**********************
|
||||
Last Operation Objects
|
||||
**********************
|
||||
======================
|
||||
All of the `vertices()`, `edges()`, `faces()`, and `solids()` methods of the builders
|
||||
can either return all of the objects requested or just the objects changed during the
|
||||
last operation. This allows the user to easily access features for further refinement,
|
||||
|
|
@ -86,25 +81,24 @@ by the last operation and fillets them. Such a selection would be quite difficul
|
|||
otherwise.
|
||||
|
||||
.. literalinclude:: ../examples/intersecting_pipes.py
|
||||
:lines: 29, 37-48
|
||||
|
||||
|
||||
**********
|
||||
Extensions
|
||||
**********
|
||||
==========
|
||||
Extending build123d is relatively simple in that custom objects or operations
|
||||
can be created as new classes without the need to monkey patch any of the
|
||||
core functionality. These new classes will be seen in IDEs which is not
|
||||
possible with monkey patching the core CadQuery classes.
|
||||
|
||||
*****
|
||||
Enums
|
||||
*****
|
||||
=====
|
||||
|
||||
All `Literal` strings have been replaced with `Enum` which allows IDEs to
|
||||
prompt users for valid options without having to refer to documentation.
|
||||
|
||||
***************************
|
||||
Selectors replaced by Lists
|
||||
***************************
|
||||
===========================
|
||||
String based selectors have been replaced with standard python filters and
|
||||
sorting which opens up the fully functionality of python list functionality.
|
||||
To aid the user, common operations have been optimized as shown here along with
|
||||
|
|
|
|||
3
docs/build_part.rst
Normal file
3
docs/build_part.rst
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
#########
|
||||
BuildPart
|
||||
#########
|
||||
3
docs/build_sketch.rst
Normal file
3
docs/build_sketch.rst
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
###########
|
||||
BuildSketch
|
||||
###########
|
||||
12
docs/builders.rst
Normal file
12
docs/builders.rst
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
########
|
||||
Builders
|
||||
########
|
||||
|
||||
The following sections describe each of the build123d stateful context builders.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
build_line.rst
|
||||
build_sketch.rst
|
||||
build_part.rst
|
||||
3
docs/center.rst
Normal file
3
docs/center.rst
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
##################
|
||||
CAD Object Centers
|
||||
##################
|
||||
|
|
@ -48,6 +48,7 @@ extensions = [
|
|||
"sphinx.ext.inheritance_diagram",
|
||||
"sphinx.ext.viewcode",
|
||||
"sphinx_design",
|
||||
"sphinx_copybutton",
|
||||
]
|
||||
|
||||
# Napoleon settings
|
||||
|
|
|
|||
3
docs/custom.rst
Normal file
3
docs/custom.rst
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
###################################
|
||||
Custom Builder Objects & Operations
|
||||
###################################
|
||||
3
docs/debugging_logging.rst
Normal file
3
docs/debugging_logging.rst
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
###################
|
||||
Debugging & Logging
|
||||
###################
|
||||
|
|
@ -89,13 +89,12 @@ Table Of Contents
|
|||
|
||||
introduction.rst
|
||||
installation.rst
|
||||
cheat_sheet.rst
|
||||
key_concepts.rst
|
||||
buildline.rst
|
||||
assemblies.rst
|
||||
introductory_examples.rst
|
||||
tutorials.rst
|
||||
builders.rst
|
||||
advanced.rst
|
||||
cheat_sheet.rst
|
||||
external.rst
|
||||
advantages.rst
|
||||
builder_api_reference.rst
|
||||
direct_api_reference.rst
|
||||
|
||||
|
|
|
|||
|
|
@ -2,13 +2,16 @@
|
|||
Introduction
|
||||
############
|
||||
|
||||
***********
|
||||
Key Aspects
|
||||
***********
|
||||
|
||||
The following sections describe some of the key aspects of build123d and illustrate
|
||||
why one might choose this open source system over proprietary options like SolidWorks,
|
||||
OnShape, Fusion 360, or even other open source systems like Blender, or OpenSCAD.
|
||||
|
||||
****************************************
|
||||
Boundary Representation (BREP) Modelling
|
||||
****************************************
|
||||
========================================
|
||||
|
||||
Boundary representation (BREP) and mesh-based CAD systems are both used to
|
||||
create and manipulate 3D models, but they differ in the way they represent and
|
||||
|
|
@ -50,9 +53,8 @@ Advantages of Mesh-based CAD systems (e.g. Blender, OpenSCAD):
|
|||
large datasets such as point clouds, as they can be easily converted into a mesh
|
||||
representation.
|
||||
|
||||
********************
|
||||
Parameterized Models
|
||||
********************
|
||||
====================
|
||||
|
||||
Parametrized CAD systems are more effective than non-parametric CAD systems in
|
||||
several ways:
|
||||
|
|
@ -83,9 +85,8 @@ systems because they provide a more efficient and flexible way to create and
|
|||
modify designs, and can be easily integrated into the design, manufacturing, and
|
||||
documentation process.
|
||||
|
||||
***************************
|
||||
Python Programming Language
|
||||
***************************
|
||||
===========================
|
||||
|
||||
Python is a popular, high-level programming language that has several advantages
|
||||
over other programming languages:
|
||||
|
|
@ -118,9 +119,8 @@ over other programming languages:
|
|||
connecting to web servers, reading and modifying files, and connecting to
|
||||
databases.
|
||||
|
||||
********************
|
||||
Open Source Software
|
||||
********************
|
||||
====================
|
||||
|
||||
Open source and proprietary software systems are different in several ways: B
|
||||
Licensing: Open source software is licensed in a way that allows users to view,
|
||||
|
|
@ -156,9 +156,8 @@ software may have a larger community of users who can provide support, while
|
|||
proprietary software may have a smaller community and relies on the company for
|
||||
support.
|
||||
|
||||
***************************
|
||||
Source Code Control Systems
|
||||
***************************
|
||||
===========================
|
||||
|
||||
Most GUI based CAD systems provide version control systems which represent the
|
||||
CAD design and its history. They allows developers to see changes made to the design
|
||||
|
|
@ -196,9 +195,8 @@ easier to use, while source code control systems like Git offer more flexibility
|
|||
and control over the code. Both can be used to achieve the same goal, but they
|
||||
cater to different types of users and use cases.
|
||||
|
||||
*****************
|
||||
Automated Testing
|
||||
*****************
|
||||
=================
|
||||
|
||||
Users of source based CAD systems can benefit from automated testing which improves
|
||||
their source code by:
|
||||
|
|
@ -234,10 +232,8 @@ process, it helps to improve the quality of the code by detecting bugs early,
|
|||
documenting code behavior, and reducing the cost of maintaining and updating the
|
||||
code.
|
||||
|
||||
|
||||
***********************
|
||||
Automated Documentation
|
||||
***********************
|
||||
=======================
|
||||
|
||||
The Sphinx automated documentation system was used to create the page you are
|
||||
reading now and can be used for user design documentation as well. Such systems
|
||||
|
|
@ -273,3 +269,15 @@ comments. They save time and effort compared to manual documentation, and can be
|
|||
customized to match the look and feel of your company's documentation. They also
|
||||
provide multiple output formats, support for multiple languages and can be
|
||||
integrated with code management tools.
|
||||
|
||||
**********************
|
||||
Build123d Key Concepts
|
||||
**********************
|
||||
|
||||
.. include:: key_concepts.rst
|
||||
|
||||
************************
|
||||
Advantages Over CadQuery
|
||||
************************
|
||||
|
||||
.. include:: advantages.rst
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
#################
|
||||
General Tutorials
|
||||
#################
|
||||
#####################
|
||||
Introductory Examples
|
||||
#####################
|
||||
|
||||
The examples on this page can help you learn how to build objects with Build123d, and are intended as a general overview of Build123d.
|
||||
|
||||
|
|
@ -45,7 +45,7 @@ A rectangular box, but with a hole added. In this case we are using ``Mode.SUBTR
|
|||
3. An extruded prismatic solid
|
||||
---------------------------------------------------
|
||||
|
||||
Build a prismatic solid using extrusion. This time we can first create a 2D ``BuildSketch`` with a
|
||||
Build a prismatic solid using extrusion. This time we can first create a 2D ``BuildSketch`` with a
|
||||
subtracted Rectangle and then use BuildPart's ``Extrude`` feature.
|
||||
|
||||
.. image:: assets/general_ex3.svg
|
||||
|
|
@ -83,7 +83,7 @@ Using ``Locations`` we can place one (or multiple) objects at one (or multiple)
|
|||
6. Using Point Lists
|
||||
---------------------------------------------------
|
||||
|
||||
Sometimes you need to create a number of features at various locations. You can use a list of
|
||||
Sometimes you need to create a number of features at various locations. You can use a list of
|
||||
points to construct multiple objects at once.
|
||||
|
||||
.. image:: assets/general_ex6.svg
|
||||
|
|
@ -108,7 +108,7 @@ You can create regular polygons for each stack point if you would like.
|
|||
8. Polylines
|
||||
---------------------------------------------------
|
||||
|
||||
``Polyline`` allows creating a shape from a large number of chained points connected by
|
||||
``Polyline`` allows creating a shape from a large number of chained points connected by
|
||||
lines. This example uses a polyline to create one half of an i-beam shape, which is mirrored to create the final profile.
|
||||
|
||||
.. image:: assets/general_ex8.svg
|
||||
|
|
@ -121,11 +121,11 @@ lines. This example uses a polyline to create one half of an i-beam shape, which
|
|||
9. Selectors, Fillets, and Chamfers
|
||||
---------------------------------------------------
|
||||
|
||||
This example introduces multiple useful and important concepts. Firstly ``Chamfer``
|
||||
This example introduces multiple useful and important concepts. Firstly ``Chamfer``
|
||||
and ``Fillet`` can be used to "bevel" and "round" edges respectively.
|
||||
|
||||
Secondly, these two methods require an edge or a list of edges to operate on. To
|
||||
select all edges, you could simply pass-in ``*ex9.edges()``. Note that the star (\*) unpacks the list.
|
||||
Secondly, these two methods require an edge or a list of edges to operate on. To
|
||||
select all edges, you could simply pass-in ``*ex9.edges()``. Note that the star (\*) unpacks the list.
|
||||
|
||||
``group_by(Axis.Z)`` returns a list of lists that is grouped by their z-position.
|
||||
|
||||
|
|
@ -142,7 +142,7 @@ In this case we want to use the ``[-1]`` group which, by convention, will be the
|
|||
10. Select Last and Hole
|
||||
---------------------------------------------------
|
||||
|
||||
Using ``Select.LAST`` you can select the most recently modified edges. It is used to perform a ``Fillet`` in
|
||||
Using ``Select.LAST`` you can select the most recently modified edges. It is used to perform a ``Fillet`` in
|
||||
this example. This example also makes use of ``Hole`` which automatically cuts through the entire part.
|
||||
|
||||
.. image:: assets/general_ex10.svg
|
||||
|
|
@ -171,7 +171,7 @@ Lastly, ``Extrude`` can be used with a negative amount and Mode.SUBTRACT to cut
|
|||
12. Defining an Edge with a Spline
|
||||
---------------------------------------------------
|
||||
|
||||
This example defines a side using a spline curve through a collection of points. Useful when you have an
|
||||
This example defines a side using a spline curve through a collection of points. Useful when you have an
|
||||
edge that needs a complex profile.
|
||||
|
||||
The star (\*) operator is again used to unpack the list.
|
||||
|
|
@ -186,7 +186,7 @@ The star (\*) operator is again used to unpack the list.
|
|||
13. CounterBoreHoles, CounterSinkHoles and PolarLocations
|
||||
-------------------------------------------------------------
|
||||
|
||||
We use a face to establish a location for ``Workplanes``. ``PolarLocations`` creates a list of
|
||||
We use a face to establish a location for ``Workplanes``. ``PolarLocations`` creates a list of
|
||||
points that are radially distributed.
|
||||
|
||||
Counter-sink and counter-bore holes are useful for creating recessed areas for fasteners.
|
||||
|
|
@ -202,18 +202,18 @@ Counter-sink and counter-bore holes are useful for creating recessed areas for f
|
|||
14. Position on a line with '\@', '\%' and introduce Sweep
|
||||
------------------------------------------------------------
|
||||
|
||||
Build123d includes a feature for finding the position along a line segment. This is normalized
|
||||
Build123d includes a feature for finding the position along a line segment. This is normalized
|
||||
between 0 and 1 and can be accessed using the '\@' operator.
|
||||
|
||||
Similarly the '%' operator returns the line direction at a given point.
|
||||
Similarly the '%' operator returns the line direction at a given point.
|
||||
|
||||
These two features are very powerful for chaining line segments together without having to repeat
|
||||
These two features are very powerful for chaining line segments together without having to repeat
|
||||
dimensions again and again, which is error prone, time consuming, and more difficult to maintain.
|
||||
|
||||
It is also possible to use ``Vector`` addition (and other vector math operations) as seen in
|
||||
It is also possible to use ``Vector`` addition (and other vector math operations) as seen in
|
||||
the ``l3`` variable.
|
||||
|
||||
The ``Sweep`` method takes any pending faces and sweeps them through the provided path. ``Sweep`` requires a
|
||||
The ``Sweep`` method takes any pending faces and sweeps them through the provided path. ``Sweep`` requires a
|
||||
single connected wire.
|
||||
|
||||
.. image:: assets/general_ex14.svg
|
||||
|
|
@ -226,7 +226,7 @@ single connected wire.
|
|||
15. Mirroring Symmetric Geometry
|
||||
---------------------------------------------------
|
||||
|
||||
Here mirror is used on the BuildLine to create a symmetric shape with fewer line segment commands.
|
||||
Here mirror is used on the BuildLine to create a symmetric shape with fewer line segment commands.
|
||||
Additionally the '@' operator is used to simplify the line segment commands.
|
||||
|
||||
``(l4 @ 1).Y`` is used to extract the y-component of the ``l4 @ 1`` vector.
|
||||
|
|
@ -241,7 +241,7 @@ Additionally the '@' operator is used to simplify the line segment commands.
|
|||
16. Mirroring 3D Objects
|
||||
---------------------------------------------------
|
||||
|
||||
Mirror can also be used with BuildPart (and BuildSketch) to mirror 3D objects. The ``Plane.offset()``
|
||||
Mirror can also be used with BuildPart (and BuildSketch) to mirror 3D objects. The ``Plane.offset()``
|
||||
method shifts the plane in the normal direction (+ve or -ve).
|
||||
|
||||
.. image:: assets/general_ex16.svg
|
||||
|
|
@ -254,7 +254,7 @@ method shifts the plane in the normal direction (+ve or -ve).
|
|||
17. Mirroring From Faces
|
||||
---------------------------------------------------
|
||||
|
||||
Here we select the farthest face in the Y-direction and turn it into a ``Plane`` using the
|
||||
Here we select the farthest face in the Y-direction and turn it into a ``Plane`` using the
|
||||
``Plane()`` class.
|
||||
|
||||
.. image:: assets/general_ex17.svg
|
||||
|
|
@ -267,7 +267,7 @@ Here we select the farthest face in the Y-direction and turn it into a ``Plane``
|
|||
18. Creating Workplanes on Faces
|
||||
---------------------------------------------------
|
||||
|
||||
Here we start with an earlier example, select the top face, draw a rectangle and then use Extrude
|
||||
Here we start with an earlier example, select the top face, draw a rectangle and then use Extrude
|
||||
with a negative distance and Mode.SUBTRACT to cut it out from the main body.
|
||||
|
||||
.. image:: assets/general_ex18.svg
|
||||
|
|
@ -280,12 +280,12 @@ with a negative distance and Mode.SUBTRACT to cut it out from the main body.
|
|||
19. Locating a Workplane on a vertex
|
||||
---------------------------------------------------
|
||||
|
||||
Here a face is selected and passed to ``Workplanes``, and two different strategies are used to select vertices.
|
||||
Here a face is selected and passed to ``Workplanes``, and two different strategies are used to select vertices.
|
||||
Firstly ``vtx`` uses ``group_by`` and ``Axis.X`` to select a particular vertex. The second strategy uses a custom
|
||||
defined Axis ``vtx2Axis`` that is pointing roughly in the direction of a vertex to select, and then ``sort_by``
|
||||
this custom Axis. Then the X and Y positions of these vertices are selected and passed to ``Locations``
|
||||
as the center points for a ``BuildSketch`` which is used to place two circles that cuts through the main part.
|
||||
Note that if you passed the variable ``vtx`` directly to ``Locations`` then the part would be offset from
|
||||
this custom Axis. Then the X and Y positions of these vertices are selected and passed to ``Locations``
|
||||
as the center points for a ``BuildSketch`` which is used to place two circles that cuts through the main part.
|
||||
Note that if you passed the variable ``vtx`` directly to ``Locations`` then the part would be offset from
|
||||
the Workplane by the vertex z-position.
|
||||
|
||||
.. image:: assets/general_ex19.svg
|
||||
|
|
@ -310,7 +310,7 @@ The ``pln`` variable is set to be coincident with the farthest face in the negat
|
|||
21. Create a Workplanes in the center of another shape
|
||||
-------------------------------------------------------
|
||||
|
||||
One cylinder is created, and then the origin and z_dir of that part are used to create a new Plane for
|
||||
One cylinder is created, and then the origin and z_dir of that part are used to create a new Plane for
|
||||
positioning another cylinder perpendicular and halfway along the first.
|
||||
|
||||
.. image:: assets/general_ex21.svg
|
||||
|
|
@ -323,10 +323,10 @@ positioning another cylinder perpendicular and halfway along the first.
|
|||
22. Rotated Workplanes
|
||||
---------------------------------------------------
|
||||
|
||||
It is also possible to create a rotated workplane, building upon some of the concepts in an earlier
|
||||
example with the ``rotated()`` method.
|
||||
It is also possible to create a rotated workplane, building upon some of the concepts in an earlier
|
||||
example with the ``rotated()`` method.
|
||||
|
||||
GridLocations places 4 Circles on 4 points on this rotated workplane, and then the Circles are
|
||||
GridLocations places 4 Circles on 4 points on this rotated workplane, and then the Circles are
|
||||
extruded in the "both" (+ve and -ve) normal direction.
|
||||
|
||||
.. image:: assets/general_ex22.svg
|
||||
|
|
@ -339,12 +339,12 @@ extruded in the "both" (+ve and -ve) normal direction.
|
|||
23. Revolve
|
||||
---------------------------------------------------
|
||||
|
||||
Here we build a sketch with a Polyline, Line, and a Circle. It is absolutely critical that the sketch
|
||||
Here we build a sketch with a Polyline, Line, and a Circle. It is absolutely critical that the sketch
|
||||
is only on one side of the axis of rotation before Revolve is called.
|
||||
|
||||
To that end, Split is used with Plane.ZY to keep only one side of the Sketch.
|
||||
|
||||
It is highly recommended to view your sketch before you attempt to call revolve. In CQ-editor this
|
||||
It is highly recommended to view your sketch before you attempt to call revolve. In CQ-editor this
|
||||
can be accomplished e.g. like this: ``show_object(ex23_sk.sketch)``.
|
||||
|
||||
.. image:: assets/general_ex23.svg
|
||||
|
|
@ -357,7 +357,7 @@ can be accomplished e.g. like this: ``show_object(ex23_sk.sketch)``.
|
|||
24. Loft
|
||||
---------------------------------------------------
|
||||
|
||||
Loft is a very powerful tool that can be used to join dissimilar shapes. In this case we make a
|
||||
Loft is a very powerful tool that can be used to join dissimilar shapes. In this case we make a
|
||||
conical-like shape from a rectangle and a circle.
|
||||
|
||||
.. image:: assets/general_ex24.svg
|
||||
|
|
@ -370,7 +370,7 @@ conical-like shape from a rectangle and a circle.
|
|||
25. Offset Sketch
|
||||
---------------------------------------------------
|
||||
|
||||
BuildSketch faces can be transformed with a 2D ``Offset``. They can be offset inwards or outwards,
|
||||
BuildSketch faces can be transformed with a 2D ``Offset``. They can be offset inwards or outwards,
|
||||
and with different techniques for extending the corners (see ``kind`` in the Offset docs).
|
||||
|
||||
.. image:: assets/general_ex25.svg
|
||||
|
|
@ -383,8 +383,8 @@ and with different techniques for extending the corners (see ``kind`` in the Off
|
|||
26. Offset Part To Create Thin features
|
||||
---------------------------------------------------
|
||||
|
||||
BuildPart parts can also be transformed using an offset, but in this case with a 3D ``Offset``. Also
|
||||
commonly known as a shell, this allows creating thin walls using very few operations. This can also be
|
||||
BuildPart parts can also be transformed using an offset, but in this case with a 3D ``Offset``. Also
|
||||
commonly known as a shell, this allows creating thin walls using very few operations. This can also be
|
||||
offset inwards or outwards. Faces can be selected to be "deleted" using the ``openings`` parameter of ``Offset``.
|
||||
|
||||
.. image:: assets/general_ex26.svg
|
||||
|
|
@ -397,7 +397,7 @@ offset inwards or outwards. Faces can be selected to be "deleted" using the ``op
|
|||
27. Splitting an Object
|
||||
---------------------------------------------------
|
||||
|
||||
You can split an object using a plane, and retain either or both halves. In this case we select
|
||||
You can split an object using a plane, and retain either or both halves. In this case we select
|
||||
a face and offset half the width of the box.
|
||||
|
||||
.. image:: assets/general_ex27.svg
|
||||
|
|
@ -410,8 +410,8 @@ a face and offset half the width of the box.
|
|||
28. Locating features based on Faces
|
||||
---------------------------------------------------
|
||||
|
||||
We create a triangular prism with ``Mode.PRIVATE`` and then later use the faces of this object to
|
||||
cut holes in a sphere. We are able to create multiple Workplanes at the same time by unpacking the
|
||||
We create a triangular prism with ``Mode.PRIVATE`` and then later use the faces of this object to
|
||||
cut holes in a sphere. We are able to create multiple Workplanes at the same time by unpacking the
|
||||
list of faces.
|
||||
|
||||
.. image:: assets/general_ex28.svg
|
||||
|
|
@ -424,8 +424,8 @@ list of faces.
|
|||
29. The Classic OCC Bottle
|
||||
---------------------------------------------------
|
||||
|
||||
Build123d is based on the OpenCascade.org (OCC) modeling Kernel. Those who are familiar with OCC
|
||||
know about the famous ‘bottle’ example. We use a 3D Offset and the openings parameter to create
|
||||
Build123d is based on the OpenCascade.org (OCC) modeling Kernel. Those who are familiar with OCC
|
||||
know about the famous ‘bottle’ example. We use a 3D Offset and the openings parameter to create
|
||||
the bottle opening.
|
||||
|
||||
.. image:: assets/general_ex29.svg
|
||||
|
|
@ -447,11 +447,11 @@ These two together create a closed line that is made into a face and extruded.
|
|||
.. literalinclude:: general_examples.py
|
||||
:start-after: [Ex. 30]
|
||||
:end-before: [Ex. 30]
|
||||
|
||||
|
||||
31. Nesting Locations
|
||||
---------------------------------------------------
|
||||
|
||||
Locations contexts can be nested to create groups of shapes. Here 24 triangles, 6 squares, and
|
||||
Locations contexts can be nested to create groups of shapes. Here 24 triangles, 6 squares, and
|
||||
1 hexagon are created and then extruded. Notably ``PolarLocations`` rotates any "children" groups by default.
|
||||
|
||||
.. image:: assets/general_ex31.svg
|
||||
|
|
@ -460,7 +460,7 @@ Locations contexts can be nested to create groups of shapes. Here 24 triangles,
|
|||
.. literalinclude:: general_examples.py
|
||||
:start-after: [Ex. 31]
|
||||
:end-before: [Ex. 31]
|
||||
|
||||
|
||||
32. Python For-Loop
|
||||
---------------------------------------------------
|
||||
|
||||
|
|
@ -479,7 +479,7 @@ until the for-loop.
|
|||
33. Python Function and For-Loop
|
||||
---------------------------------------------------
|
||||
|
||||
Building on the previous example, a standard python function is used to return a BuildSketch as a function
|
||||
Building on the previous example, a standard python function is used to return a BuildSketch as a function
|
||||
of several inputs to progressively modify the size of each square.
|
||||
|
||||
.. image:: assets/general_ex33.svg
|
||||
|
|
@ -492,9 +492,9 @@ of several inputs to progressively modify the size of each square.
|
|||
34. Embossed and Debossed Text
|
||||
---------------------------------------------------
|
||||
|
||||
The text "Hello" is placed on top of a rectangle and embossed (raised) by placing a BuildSketch on the
|
||||
top face (``topf``). Note that ``halign`` and ``valign`` are used to control the text placement. We re-use
|
||||
the ``topf`` variable to select the same face and deboss (indented) the text "World". Note that if we simply
|
||||
The text "Hello" is placed on top of a rectangle and embossed (raised) by placing a BuildSketch on the
|
||||
top face (``topf``). Note that ``halign`` and ``valign`` are used to control the text placement. We re-use
|
||||
the ``topf`` variable to select the same face and deboss (indented) the text "World". Note that if we simply
|
||||
ran ``BuildSketch(ex34.faces().sort_by(Axis.Z)[-1])`` for both ``ex34_sk1&2`` it would incorrectly locate
|
||||
the 2nd "World" text on the top of the "Hello" text.
|
||||
|
||||
|
|
@ -521,8 +521,8 @@ arc for two instances of ``SlotArc``.
|
|||
36. Extrude Until
|
||||
---------------------------------------------------
|
||||
|
||||
Sometimes you will want to extrude until a given face that can be not planar or where you might
|
||||
not know easily the distance you have to extrude to. In such cases you can use ``Extrude`` until
|
||||
Sometimes you will want to extrude until a given face that can be not planar or where you might
|
||||
not know easily the distance you have to extrude to. In such cases you can use ``Extrude`` until
|
||||
with ``Until.NEXT`` or ``Until.LAST``.
|
||||
|
||||
.. image:: assets/general_ex36.svg
|
||||
|
|
@ -1,12 +1,7 @@
|
|||
########
|
||||
Concepts
|
||||
########
|
||||
|
||||
The following key concepts will help new users understand build123d quickly.
|
||||
|
||||
********
|
||||
Builders
|
||||
********
|
||||
========
|
||||
|
||||
The three builders, ``BuildLine``, ``BuildSketch``, and ``BuildPart`` are tools to create
|
||||
new objects - not the objects themselves. Each of the objects and operations applicable
|
||||
|
|
@ -39,9 +34,33 @@ instance variable. For example:
|
|||
|
||||
show_object(my_line.line)
|
||||
|
||||
******************
|
||||
Implicit Builder Instance Variables
|
||||
===================================
|
||||
|
||||
One might expect to have to reference a builder's instance variable when using
|
||||
objects or operations that impact that builder like this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
with BuildPart() as part_builder:
|
||||
Box(part_builder, 10,10,10)
|
||||
|
||||
Instead, build123d determines from the scope of the object or operation which
|
||||
builder it applies to thus eliminating the need for the user to provide this
|
||||
information - as follows:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
with BuildPart() as part_builder:
|
||||
Box(10,10,10)
|
||||
with BuildSketch() as sketch_builder:
|
||||
Circle(2)
|
||||
|
||||
In this example, ``Box`` is in the scope of ``part_builder`` while ``Circle``
|
||||
is in the scope of ``sketch_builder``.
|
||||
|
||||
Workplane Contexts
|
||||
******************
|
||||
==================
|
||||
|
||||
As build123d is a 3D CAD package one must be able to position objects anywhere. As one
|
||||
frequently will work in the same plane for a sequence of operations, a workplane is used
|
||||
|
|
@ -92,9 +111,8 @@ This is the result:
|
|||
.. image:: boxes_on_faces.svg
|
||||
:align: center
|
||||
|
||||
****************
|
||||
Location Context
|
||||
****************
|
||||
================
|
||||
|
||||
When positioning objects or operations within a builder Location Contexts are used. These
|
||||
function in a very similar was to the builders in that they create a context where one or
|
||||
|
|
@ -140,9 +158,8 @@ to retrieve the global locations relative to the current workplane(s) as follows
|
|||
Location(p=(0.50,0.00,0.50), o=(90.00,-0.00,0.00))
|
||||
|
||||
|
||||
****************
|
||||
Operation Inputs
|
||||
****************
|
||||
================
|
||||
|
||||
When one is operating on an existing object, e.g. adding a fillet to a part,
|
||||
a sequence of objects is often required. A python sequence of objects is
|
||||
|
|
@ -172,9 +189,9 @@ followed by a fillet radius as follows:
|
|||
Here the list of edges from the last operation of the ``pipes`` builder are converted
|
||||
to a sequence and a radius is provided as a keyword argument.
|
||||
|
||||
*****************
|
||||
Combination Modes
|
||||
*****************
|
||||
=================
|
||||
|
||||
Almost all objects or operations have a ``mode`` parameter which is defined by the
|
||||
``Mode`` Enum class as follows:
|
||||
|
||||
|
|
@ -202,15 +219,13 @@ 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
|
||||
**********************************
|
||||
==================================
|
||||
|
||||
build123d stores points (to be specific ``Locations``) internally to be used as
|
||||
positions for the placement of new objects. By default, a single location
|
||||
|
|
@ -251,9 +266,8 @@ combine rotations with the `*` operator like this:
|
|||
``Rotation`` is a subclass of ``Location`` and therefore will also accept
|
||||
a position component.
|
||||
|
||||
*************************
|
||||
Builder's Pending Objects
|
||||
*************************
|
||||
=========================
|
||||
|
||||
When a builder exits, it will push the object created back to its parent if
|
||||
there was one. Here is an example:
|
||||
|
|
|
|||
|
|
@ -9,7 +9,6 @@ as later tutorials build on the concepts introduced in earlier ones.
|
|||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
tutorial_general.rst
|
||||
tutorial_selectors.rst
|
||||
tutorial_lego.rst
|
||||
tutorial_joints.rst
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue