new interface for split()

[Paul8043]

The old interface of split() has some limitations, therefore a proposal for a new interface:

# old interface:

top  = split(part,plane,keep=Keep.TOP)       # keep only upper part
bot  = split(part,plane,keep=Keep.BOTTOM)    # keep only lower part
both = split(part,plane,keep=Keep.BOTH)      # keep both parts

# plane might have any orientation, TOP and BOTTOM are misleading names for the sub-parts
# BOTH contains both sub-parts un-glued, not so easy to access sub-parts individually


# new interface:

p1,p2 = split(part,plane)                    # return both sub-parts as a tuple

# p1 should hold the sub-part which belongs to the counter-normal of the plane (grey on the OCP-CAD-Viewer)
# p2 should hold the sub-part which belongs to the normal of the plane (pink on the OCP-CAD-Viewer)

[gumyr]

How would this work in Builder mode?

[Paul8043]

Good point, this question has to be asked. To be honest the BuilderMode has lost somehow my focus. I like concise and less indented code. For the first 20 introductory examples AlgebraMode is more compact (19% less). The problem of BuilderMode are the parameter-less function-calls (sweep() in example_14 or make_face() in example_15). Both functions need internally more parameters which are taken somehow from the nested with-contexts. And this is the problem, you cannot see what these functions take as parameters, some are implicit from the context, some are explictly listed. I would say there is some magic-ness associated with each BuilderMode-Objects, so BuilderMode-Code is more difficult to understand, because it is not clear which context-data is taken from which function. Because of that I think the fully explictly listed parameters in AlgebraMode are much simpler!
After writing this text I have some rough ideas what kind of implications my proposal would introduce to BuilderMode. It is just a proposal and your answer might help to understand BuilderMode better. Are there any simple rules how the functions take the implicit data from the context?

[gumyr]

Builder mode exists for many reasons and I still recommend that new users start with it for a few reasons:

• Avoiding Constructive Solid Geometry: Many of us (myself included) come from an OpenSCAD background and learnt how to construct objects with CSG. Generally this is not the most efficient and effective way of working, hence the name build123d implying 1->2->3D construction. Algebra tends to match the OpenSCAD/CSG style better which I suspect is why many users like it.
• Structure and readability: by clearly separating the 1, 2 and 3D operations it's much easier to understand what code is doing what. The indentation is a feature not a bug and I have little interest in making code compact (with IDEs one doesn't even have to type it anymore) at the cost of readability. I've found the black (https://github.com/psf/black) formatter really helps with this as I'm not attempting to keep everything on a line to avoid manual reformatting.
• Added functionality: the builders have extra functionality over Algebra mode, things like validation, keeping Faces aligned properly, positioning Sketches, extra selectors, etc. help users focus on their design and less on Python things like classes. Quite a few new users of build123d are new to Python or even programming in general so keeping things simple enables these users to make something without having to be experts.

There is more "magic" in Builder mode than Algebra mode but this was very carefully thought out. If you don't like the automatic determination of the "noun" for the operations you can explicitly provide it (i.e. split(my_builder.part, bisect_by=Plane.XY)- the same code is used for both Builder and Algebra so it can be used the same way. Builder mode attempts to limit the amount of redundant information the user has to provide.

Having said all that, build123d is better for having Algebra mode and I use it quite a bit.

[Paul8043]

Thanks for your explanations. I am still in the warm-up phase. I have also the OpenSCAD background, programming the objects, instead of drawing them, has very often more benefits, especially if similiar variants are needed.
Placing the objects in clearly separated 1->2->-3D-domains is a good choice and in general I like the architecture of Build123D. I fully understand where the name comes from. In a few projects I had trouble to find the right function to cross the dimension-boundaries, e.g. going from 3D to 2D with section() or adding a 1D-line to 2D-sketch which is a common problem that occurs very often. And sometimes the object classification by shape might be full of surprises (see the code blow):

"""
name: magic-cubes.py
"""
from build123d import *
from ocp_vscode import *

set_port(3939)

def findings(model):
    print(f"#solids={len(model.solids())}")
    for idx, solid in enumerate(model.solids()):
        print(f"solids[{idx}]={solid}")
    print(f"#faces={len(model.faces())}")    
    for idx, face in enumerate(model.faces()):
        print(f"faces[{idx}]={face}")
    print(f"#wires={len(model.wires())}")    
    for idx, wire in enumerate(model.wires()):
        print(f"wires[{idx}]={wire}")
    print(f"#edges={len(model.edges())}")
    for idx, edge in enumerate(model.edges()):
        print(f"edges[{idx}]={edge}")
    print(f"#vertices={len(model.vertices())}")    
    for idx, vertex in enumerate(model.vertices()):
        print(f"vertices[{idx}]={vertex}")
    return

# cube as a Box (solid)

def model_1(length):
    model = Part()+Box(length,length,length)
    return model

# cube as mounted faces (inside hollow, normal-vectors like model_1)

def model_2(length):
    el = 0.5*length
    l1 = Line((-el,-el),(+el,-el))
    l2 = Line((+el,-el),(+el,+el))
    l3 = Line((+el,+el),(-el,+el))
    l4 = Line((-el,+el),(-el,-el))
    f  = make_face([l1,l2,l3,l4])
    fxy      = f
    fxy      = Rot(0,0,0)*fxy
    f_bottom = Location((0,0,-el),(180,0,0))*fxy
    f_top    = Location((0,0,+el),(0,0,0))*fxy
    fzx      = f
    fzx      = Rot(90,0,0)*fzx
    f_front  = Location((0,+el,0),(180,0,0))*fzx
    f_back   = Location((0,-el,0),(0,0,0))*fzx
    fzy      = f
    fzy      = Rot(0,90,0)*fzy
    f_left   = Location((-el,0,0),(0,180,0))*fzy
    f_right  = Location((+el,0,0),(0,0,0))*fzy
    return Sketch()+[f_bottom,f_top,f_front,f_back,f_left,f_right]

# cube as mounted faces (inside hollow, normal-vector going to inside)

def model_3(length):
    el = 0.5*length
    l1 = Line((-el,-el),(+el,-el))
    l2 = Line((+el,-el),(+el,+el))
    l3 = Line((+el,+el),(-el,+el))
    l4 = Line((-el,+el),(-el,-el))
    f  = make_face([l1,l2,l3,l4])
    fxy      = f
    fxy      = Rot(0,0,0)*fxy
    f_bottom = Location((0,0,-el),(0,0,0))*fxy
    f_top    = Location((0,0,+el),(180,0,0))*fxy
    fzx      = f
    fzx      = Rot(90,0,0)*fzx
    f_front  = Location((0,+el,0),(0,0,0))*fzx
    f_back   = Location((0,-el,0),(180,0,0))*fzx
    fzy      = f
    fzy      = Rot(0,90,0)*fzy
    f_left   = Location((-el,0,0),(0,0,0))*fzy
    f_right  = Location((+el,0,0),(0,180,0))*fzy
    return Sketch()+[f_bottom,f_top,f_front,f_back,f_left,f_right]

m = model_3(100)
findings(m)
front  = m.faces().sort_by(Axis.Y)[0]
back   = m.faces().sort_by(Axis.Y)[-1]
left   = m.faces().sort_by(Axis.X)[0]
right  = m.faces().sort_by(Axis.X)[-1]
bottom = m.faces().sort_by(Axis.Z)[0]
top    = m.faces().sort_by(Axis.Z)[-1]

c =  Cylinder(20,30)

show_all()

m1 = model_1(10)
m2 = model_2(10)
m3 = model_3(10)

m1.export_stl("3D-Prints/m1.stl")
m2.export_stl("3D-Prints/m2.stl")
m3.export_stl("3D-Prints/m3.stl")

Good to know that the implict parameters can be given explictly. You know, as the designer and insider, how the implict parameters are picked from the context, for me, as an outsider, I see only the black box, I have to guess what might be taken. This is a very time-consuming process! So, I still hope that you can give the rules-of-the-game, how implicit parameters are picked! I can only advance quickly, if the rules-of-the-game are manifested in the NN of my brain. Maybe this occurs only after a more intensive training!

[gumyr]

By diving into Algebra I fear you've made things complex for yourself right from the start.

To understand the topology of an object you can do this:

print(Box(1, 1, 1).show_topology())

Compound                       at 0x7f4a8203d5f0, Center(0.0, 0.0, 0.0)
└── Solid                      at 0x7f4a8203d530, Center(0.0, 0.0, 0.0)
    └── Shell                  at 0x7f4a8203d6f0, Center(0.0, 0.0, 0.0)
        ├── Face               at 0x7f4a8203d4f0, Center(-0.5, 0.0, 0.0)
        │   └── Wire           at 0x7f4a8203d1f0, Center(-0.5, 0.0, 0.0)
        │       ├── Edge       at 0x7f4a8203d6b0, Center(-0.5, -0.5, 0.0)
        │       │   ├── Vertex at 0x7f4a8203deb0, Center(-0.5, -0.5, 0.5)
        │       │   └── Vertex at 0x7f4a8203d830, Center(-0.5, -0.5, -0.5)
        │       ├── Edge       at 0x7f4a8203d830, Center(-0.5, 0.0, 0.5)
        │       │   ├── Vertex at 0x7f4a8203dbb0, Center(-0.5, 0.5, 0.5)
        │       │   └── Vertex at 0x7f4a820406f0, Center(-0.5, -0.5, 0.5)
        │       ├── Edge       at 0x7f4a8203d3f0, Center(-0.5, 0.5, 0.0)
        │       │   ├── Vertex at 0x7f4a82040530, Center(-0.5, 0.5, 0.5)
        │       │   └── Vertex at 0x7f4a82040ab0, Center(-0.5, 0.5, -0.5)
        │       └── Edge       at 0x7f4a82040ab0, Center(-0.5, 0.0, -0.5)
        │           ├── Vertex at 0x7f4a820406f0, Center(-0.5, 0.5, -0.5)
        │           └── Vertex at 0x7f4a82040d30, Center(-0.5, -0.5, -0.5)
        ├── Face               at 0x7f4a8203d2b0, Center(0.5, 0.0, 0.0)
        │   └── Wire           at 0x7f4a583c3f70, Center(0.5, 0.0, 0.0)
        │       ├── Edge       at 0x7f4a820401f0, Center(0.5, -0.5, 0.0)
        │       │   ├── Vertex at 0x7f4a82040d30, Center(0.5, -0.5, 0.5)
        │       │   └── Vertex at 0x7f4a8206db30, Center(0.5, -0.5, -0.5)
        │       ├── Edge       at 0x7f4a82040630, Center(0.5, 0.0, 0.5)
        │       │   ├── Vertex at 0x7f4a8206de30, Center(0.5, 0.5, 0.5)
        │       │   └── Vertex at 0x7f4a8206db30, Center(0.5, -0.5, 0.5)
        │       ├── Edge       at 0x7f4a8206db30, Center(0.5, 0.5, 0.0)
        │       │   ├── Vertex at 0x7f4a8206df70, Center(0.5, 0.5, 0.5)
        │       │   └── Vertex at 0x7f4a82043330, Center(0.5, 0.5, -0.5)
        │       └── Edge       at 0x7f4a8206d7b0, Center(0.5, 0.0, -0.5)
        │           ├── Vertex at 0x7f4a82043cf0, Center(0.5, 0.5, -0.5)
        │           └── Vertex at 0x7f4a820439b0, Center(0.5, -0.5, -0.5)
        ├── Face               at 0x7f4a8206d7b0, Center(0.0, -0.5, 0.0)
        │   └── Wire           at 0x7f4a8203d1f0, Center(0.0, -0.5, 0.0)
        │       ├── Edge       at 0x7f4a82043330, Center(0.0, -0.5, -0.5)
        │       │   ├── Vertex at 0x7f4a820431b0, Center(0.5, -0.5, -0.5)
        │       │   └── Vertex at 0x7f4a82043ab0, Center(-0.5, -0.5, -0.5)
        │       ├── Edge       at 0x7f4a82043870, Center(0.5, -0.5, 0.0)
        │       │   ├── Vertex at 0x7f4a82043770, Center(0.5, -0.5, 0.5)
        │       │   └── Vertex at 0x7f4a82043430, Center(0.5, -0.5, -0.5)
        │       ├── Edge       at 0x7f4a820437b0, Center(0.0, -0.5, 0.5)
        │       │   ├── Vertex at 0x7f4a82043530, Center(0.5, -0.5, 0.5)
        │       │   └── Vertex at 0x7f4a82043130, Center(-0.5, -0.5, 0.5)
        │       └── Edge       at 0x7f4a82043bb0, Center(-0.5, -0.5, 0.0)
        │           ├── Vertex at 0x7f4a82043bf0, Center(-0.5, -0.5, 0.5)
        │           └── Vertex at 0x7f4a82036430, Center(-0.5, -0.5, -0.5)
        ├── Face               at 0x7f4a8203d1f0, Center(0.0, 0.5, 0.0)
        │   └── Wire           at 0x7f4a82043130, Center(0.0, 0.5, 0.0)
        │       ├── Edge       at 0x7f4a820362b0, Center(0.0, 0.5, -0.5)
        │       │   ├── Vertex at 0x7f4a820361b0, Center(0.5, 0.5, -0.5)
        │       │   └── Vertex at 0x7f4a82036530, Center(-0.5, 0.5, -0.5)
        │       ├── Edge       at 0x7f4a820360b0, Center(0.5, 0.5, 0.0)
        │       │   ├── Vertex at 0x7f4a82036030, Center(0.5, 0.5, 0.5)
        │       │   └── Vertex at 0x7f4a8203beb0, Center(0.5, 0.5, -0.5)
        │       ├── Edge       at 0x7f4a82036530, Center(0.0, 0.5, 0.5)
        │       │   ├── Vertex at 0x7f4a8203b4b0, Center(0.5, 0.5, 0.5)
        │       │   └── Vertex at 0x7f4a8203bf70, Center(-0.5, 0.5, 0.5)
        │       └── Edge       at 0x7f4a8203bf70, Center(-0.5, 0.5, 0.0)
        │           ├── Vertex at 0x7f4a8203b230, Center(-0.5, 0.5, 0.5)
        │           └── Vertex at 0x7f4a820a4d70, Center(-0.5, 0.5, -0.5)
        ├── Face               at 0x7f4a82043130, Center(0.0, 0.0, -0.5)
        │   └── Wire           at 0x7f4a82036e70, Center(0.0, 0.0, -0.5)
        │       ├── Edge       at 0x7f4a820a4030, Center(-0.5, 0.0, -0.5)
        │       │   ├── Vertex at 0x7f4a820a4e30, Center(-0.5, 0.5, -0.5)
        │       │   └── Vertex at 0x7f4a820645b0, Center(-0.5, -0.5, -0.5)
        │       ├── Edge       at 0x7f4a820a4cb0, Center(0.0, 0.5, -0.5)
        │       │   ├── Vertex at 0x7f4a82064930, Center(0.5, 0.5, -0.5)
        │       │   └── Vertex at 0x7f4a820645b0, Center(-0.5, 0.5, -0.5)
        │       ├── Edge       at 0x7f4a820645b0, Center(0.5, 0.0, -0.5)
        │       │   ├── Vertex at 0x7f4a82066a30, Center(0.5, 0.5, -0.5)
        │       │   └── Vertex at 0x7f4a82066bb0, Center(0.5, -0.5, -0.5)
        │       └── Edge       at 0x7f4a820a4af0, Center(0.0, -0.5, -0.5)
        │           ├── Vertex at 0x7f4a82066ab0, Center(0.5, -0.5, -0.5)
        │           └── Vertex at 0x7f4a82066e30, Center(-0.5, -0.5, -0.5)
        └── Face               at 0x7f4a82043bb0, Center(0.0, 0.0, 0.5)
            └── Wire           at 0x7f4a8203d9f0, Center(0.0, 0.0, 0.5)
                ├── Edge       at 0x7f4a82066f30, Center(-0.5, 0.0, 0.5)
                │   ├── Vertex at 0x7f4a583c61f0, Center(-0.5, 0.5, 0.5)
                │   └── Vertex at 0x7f4a583c6370, Center(-0.5, -0.5, 0.5)
                ├── Edge       at 0x7f4a583c6370, Center(0.0, 0.5, 0.5)
                │   ├── Vertex at 0x7f4a583c60f0, Center(0.5, 0.5, 0.5)
                │   └── Vertex at 0x7f4a583c6670, Center(-0.5, 0.5, 0.5)
                ├── Edge       at 0x7f4a583c6670, Center(0.5, 0.0, 0.5)
                │   ├── Vertex at 0x7f4a583c64f0, Center(0.5, 0.5, 0.5)
                │   └── Vertex at 0x7f4a583c6970, Center(0.5, -0.5, 0.5)
                └── Edge       at 0x7f4a583c6970, Center(0.0, -0.5, 0.5)
                    ├── Vertex at 0x7f4a583c67f0, Center(0.5, -0.5, 0.5)
                    └── Vertex at 0x7f4a583c6c70, Center(-0.5, -0.5, 0.5)

described here: https://build123d.readthedocs.io/en/latest/key_concepts.html#topology. Creating a 3D Sketch as done above is not how a Solid object is created (in-fact a Sketch is intended to be a planar object) . One can create the topological components and assemble them as: Vertices->Edges->Wires->Faces->Shells->Solids->Compounds. For example Solid(shell) will create a Solid object from the user provided Shell object. It is very rare that one would need to do this (it's used in advance complex geometry).

The rules for implicit in parameters are very simple - take any pending objects created by other builders.

with BuildPart() as box_builder:
    with BuildSketch() as square_builder:
        Rectangle(1, 1)
        # upon exit, BuildSketch transfers its object to BuildPart as a pending object
    extrude(amount=1)  # if no "to_extrude" is provided extrude the pending objects

[Paul8043]

Do not misunderstand me, the magic-cubes are not the normal way how I create cubes. I did some investigations with planes and therefore I needed a test-object where the normal-vector went in opposite direction. Sometimes, during the desgin of my regular models I got stuck, because I could not find a solution immediately. Often new questions arise, e.g. make_face() gets only a list points, but for the normal-vector there should be 2 choices, which one is taken (can be seen later with the coloring of grey or pink)?

Thanks for the given object-hierarchy, this helps. Initially it was not so clear what is the difference between a wire and an edge. Seems a wire is a collection of edges. I miss the explanation of a shape. It this the base-class for all the above? And some things do not appear in hierarchy at all, like lines, parts, sketches, etc. Objects are good to build more abstract entities. On HW-level this works well, it is very easy to use TTLs to build more complex circuits. There only a few rules which have to be obeyed. On SW-level this looks different, the objects appear as black-boxesas they should, but most of them look too much black, at least initially. The interfaces are much more complex. And the more is hidden inside, the more difficult is it to use these objects. Without some knowledge of the internal functionality of a black-box it is almost impossible to use it in the right way! If objects use implicit things, the situation is getting much worse. The implicit things have to be learned, otherwise you get lost. Yout still can do miraculous things, but you need to be wizard who knows how to swing the magic wand. Again, this is a very time consuming-process. We could make the learning-curve lower, if all these things would be collected in a Build123D-book. That would help new users a lot.

I have re-read the online-documentation that you have recommended. This section is more clearer now, but it is still not enough for doing real work. Please keep in mind, that a normal user has a totally different context. The implicit things are totally unknown. Initially it is unclear how the information flows from one object to the next. If you like, that Build123D gets broader acceptance, we have to explain the magic things, there is no other way around!

The BuilderMode-examples look nice and I am willing to learn the internal machinery. I would recommend to open a new discussion that takes care for the rules-of-BuilderMode (learn how the implict things work).

[Jojain]

I've re-read the https://build123d.readthedocs.io/en/latest/key_concepts.html and I think everything you need to know is written.
Of course you will have to learn that upon exit a builder pass the object it was building to its parent object.

You might think that it is bad because it is implicit but the reality is that this implicitness has been deeply thought and the reason it's here is that there is A LOT to know about BREP modelling to produce a model and by making some things implicit we can handle things for the user such as he doesn't have to care about some of the underlying complexity of building his model.

Basically we consider that we are smarter/more knowledgable than the new user and we will ease things for him by making some things implicit. Of course some time we aren't so smart and then it doesn't work like the user expects and so the user have to learn a bit more deeply how things are wired. But without that he would have to learn it right away (and as I said there is a lot of things to know ..) (That's why Builder mode is advised for newcomers)

[gumyr]

@Paul8043 I'm sorry that you find the documentation inadequate to do "real work". The section that specifically addresses the use of pending objects is here: https://build123d.readthedocs.io/en/latest/key_concepts.html#builder-s-pending-objects - would you describe what you think is missing?

What might help is actually doing each of the Introductory Examples here: https://build123d.readthedocs.io/en/latest/introductory_examples.html. These take the user through the process of making a very simple shape to covering many of the aspects of build123d.

[Paul8043]

Ok, this might be a good approach. Give me a few days to re-digest readthedocs to bring myself to the up-to-date level. BTW, I have read it already 3 or 4 times completely. "readthedoscs" is well written, without any doubts. I have run all the inductory examples, all of them run flaw-lessly. "readthedocs" and the inductory examples are always my starting-point. I take the one that seems to fit best to my "real work". Then I try to adapt the example to achieve the functionality I want to have. Even small changes result in a long list of errors. Most of them belong to wrong values, but some belong to a wrong trial. If the readthedocs does not have a solution, I have to open a discussion (like this one) or I have to ask on discord. The responsiveness was already very good and I have always good a solution. The solution was mostly simple, but totally different from my expection. For my other projects I can guess how the solution for a problem might look like. And my normal hit-rate is quite high. But this is not yet true for Build123D. There is simply too less information, especially in the area of the basic principles and key concepts. Another problem is the context-knowledge of the user. I am a newbie in the CAD-domain, but not in SW-engineering. I carry 45 years of experiences with me. Python is my programming language number 21 or so, I have stopped counting. Mostly, own experiences are very valuable, but sometimes they steer me in a wrong direction, especially if I enter into a new domain. And I am also biased by CadQuery. There was the same problem, trying to understand the implict things was too time-consuming and finally I have given that up. So, I am restarting with Build123D. With the AlgebraMode I could realize my first projects to supply my cutter and my 3D-printer. I can generate STL-files and SVG-files to drive both devices. I am quite happy with that. Now I want to go further and try more of the capabilities of Build123D.

You think, I don't need to know the implict things. Up to now, I think the opposite, and this is based on my new experience when I have tried to modify some inductory examples. So, I need much more examples to train the NN in my brain. Or, as a better alternative, I have to learn basic principles and key concepts first.

I will re-re-read the readthedocs and try to use BuilderMode. I will list all the questions that might come up during this adventure trip.

[Paul8043]

Re-reading of the recommended documentation is done. Again, it is well written! I have discovered a few new things that I did no had on my radar (relative positioning, how "add" is used, why a lot of functions have "mode"-parameter).

I have also read the small paragraph about Pending Objects. Pending has a negative touch, expressing that something is in bad repair or somehow incomplete. Pending things trigger an alarm for a not normal situation. And this is the reason why this troubles me so much! Maybe the wording leads me to the wrong direction. Maybe this is not so severe as I think at the moment. Build123D let me work with objects, where I cannot see whether they have pending things or not. I also do not understand, when or through what the pending-ness goes away. So, I cannot make any judgements, whether my objects are in pretty good shape or not! Maybe you simply want to say that some results of the current with-statement are automatically routed to the next higher with-statement. That would be a fine service. Can you give a simple example, where you make the pendings visible, just for a better understanding, otherwise my bad feelings in this area would not go away. I want to be sure that my with-statements are correctly designed. This looks impressive, because I have not write any code for the up-propagation, but it has still the smell of some magic-ness.

Below I have listed what needs more explanation. Maybe we can solve this first, before we go the real-work-example.

Releated to readthedoc:

Typo: Worklanes:

Second line should get "..." to indicate that a 3D-part is needed

 with BuildPart(Plane.XY) as example:
    ... # a 3D-part
    with BuildSketch(example.faces().sort_by(sort_by=Axis.Z)[0]) as bottom:
        ...
    with BuildSketch(Plane.XZ) as vertical:
        ...
    with BuildSketch(example.faces().sort_by(sort_by=Axis.Z)[-1]) as top:
        ...

Typo: Locations Context:

Third with-statement needs a colon at the end.

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)

Question: Locations

Some with-statements take care for a single entity, some others like Locations seems to organize a hidden loop. This is a great feature. I have to look into the source-code, just to see how this is implemented. Are there any further classes with this behavior?

Question: Combining Modes

Mode.REPLACE is unclear. I have a perception what will be added, but not which portion of the parent will be replaced? Can you give an example? Normally I try to melt the single parts together with the union-operator "+" or cut something away the intersection-operator "-". This works quite well for parts. I do not know whether this works also for 2D-objects. The much bigger questions is, when to use the mode-parameter and when the union and intersection-operators? For me, at the moment, it seems both relalize the same or simliar functionality. Is there a superposition of both mechanisms? What is the intended usage?

Question: Using Locations & Rotating Objects

A location consists of a position and a rotation. It seems that the rotation is executed first, even it is the second parameter. If some are chained together with the "*"-operator, in which sequence is the positioning executed? Rotations are not commutative, so the execution order is relvant. Locations from left to right, and whitin each location, the rotation first, then the translation? Is this correct? Can rotations be grouped by parenthesis?

Improvement & Question: Workplanes

All examples should use the same kind of importing, remove the bd, it distracts from the main subject. BuilderMode creates workplanes for all faces. For me left,right,front,back look fine, but top,bottom not, they appear flipped to me. I have already learned, the xdir has not the expected value. Is there an easy way to fix that?

with BuildPart() as bp:
    Box(3, 3, 3)
    with BuildSketch(*bp.faces()):
        Rectangle(1, 2, rotation=45)
    extrude(amount=0.1)

I have to re-address this subject in the next section again.

[Paul8043]

In this chapter I want to explain why the inductory examples are easy, and why "real_work" is much harder. This happens not because of the "real_work" is a more complicated model, but it happens as soon as you make some small modifications. As a newbie there is no alternative, you have to take the bottom-up approach. The inductory example is taken as a starting-point, and then you plan to add some refinements (additional extrusions or whatever).

The whole thing is advertized as follows: Instead of doing all work with 3D-objects, go to a face and there you only set up 2D-objects, and after that an extrusion will follow which gives the 2D-objects some thickness. And voila you have the wanted appearance (converting a rectangle (2D) into box (3d)). This approach seems to be reasonable.

We take the example above (cube with an extruded rectangle on each side). You run the code and you can only say: wow, such an object with just a 5-liner. There was no need to organize a loop, there was no need to specify any location. This is really amazing. A big bargain for a small amount of bucks! In the OCP-CAD-Viewer (a great and very valuable tool) you can inspect the model from every side.

Now you try to apply some refinements, may be adding a circle to be extruded in the opposite direction, just to see whether the material is taken away or not. Then you recognize very quickly, the refinements are no easy-doing, they are better characterized as a adventure-trip. Big hurdles enter the scene, they coming from totally unexpected directions. And sometimes I have felt myself as a reborn Odysseus. On some faces the refinements did appear on the right place, on some others they did not. This happens, even the exact same code has be run for all faces. This is a very strange and unexpected behavior, what went wrong, or what did I in a wrong way?

If you make such experiments as a newbie, it seems that my small modifications have turned the clear inductory example into one with magic-behavior! During the initial steps of this trip you will be faced with really big hurdles! No other chance, except to look deeper into the faces, also not an easy task.

Hurdle 1:

Never look into a specific face by using the index of an element! The faces may have any order, they have to be sorted first!

Then I was able to select a specific face. But the problem has not changed, on some faces the positions were correct, on others not. To fix the problem I had to exchange the x by y and vice versa. On another face, only the signs were wrong. The positioning was only correct, if I had made totally symmetrical modifications.

Hurdle 2: Never use the built-in looping over faces, if your modifcations are not fully symmetrical!

Such a behavior made me crazy and I made some considerations whether it would make sense to spend more time on this problem. I am not a person that likes to give up, normally I take the challenge and I will work until a solution has been found. But for this problem, that was clear to me, I cannot do this by myself, I need some assistance from persons who know where the root-cause might be located.

I would like to say thank you for all the help I got from you and I also appreciate your responsiveness.

Just to make it clear for other readers, the complex of problems described here, is not specific or introduced by Build123D. Other CAD-tools have to deal with these issues, too. The more interesting question would be, how such problems can be resolved inside Build123D.

Some deeper investigations led me to planes and how they are attached. I have found x_dir, y_dir, z_dir. It was totally unclear why they are needed, what they control, and what values should be assigned there. I had no perception what is going on here. This hurdle seems to be 5-times higher than the previous ones! In the meantime I have x_dir, y_dir and z_dir under full control. But this issue took me a few weeks to solve. Making own mistakes is a very precious experience, I never will forget the solution, it is now hard-wired in my brain.

Now I want to come back to our example. It is still difficult for me to convert BuilderMode-code to AlegebraMode-code and vice versa, espcially if some loops are involved. The code-snippet given below shows an AM-version where the loop is un-roled all items are named properly. In the viewer you can click on them indidually.

"""
name: ex1_am.py
"""

from build123d import *
from ocp_vscode import *

set_port(3939)

b = Box(3,3,3)

face_top    = b.faces().sort_by(Axis.Z)[-1]
face_bottom = b.faces().sort_by(Axis.Z)[0]
face_back   = b.faces().sort_by(Axis.Y)[-1]
face_front  = b.faces().sort_by(Axis.Y)[0]
face_right  = b.faces().sort_by(Axis.X)[-1]
face_left   = b.faces().sort_by(Axis.X)[0]

plane_top    = Plane(face_top,    x_dir=(0,+1,0)) # default
#plane_top    = Plane(face_top,    x_dir=(+1,0,0)) # my favorite

plane_bottom = Plane(face_bottom, x_dir=(0,+1,0)) # default
#plane_bottom = Plane(face_bottom, x_dir=(+1,0,0)) # my favorite

plane_back   = Plane(face_back,   x_dir=(-1,0,0))
plane_front  = Plane(face_front,  x_dir=(+1,0,0))
plane_right  = Plane(face_right,  x_dir=(0,+1,0))
plane_left   = Plane(face_left,   x_dir=(0,-1,0))

r_left   = plane_left * Rectangle(1, 2, rotation=45)
r_right  = plane_right * Rectangle(1, 2, rotation=45)
r_back   = plane_back * Rectangle(1, 2, rotation=45)
r_front  = plane_front * Rectangle(1, 2, rotation=45)
r_top    = plane_top * Rectangle(1, 2, rotation=45)
r_bottom = plane_bottom * Rectangle(1, 2, rotation=45)

e_left   = extrude(r_left, 0.1)
e_right  = extrude(r_right, 0.1)
e_back   = extrude(r_back, 0.1)
e_front  = extrude(r_front, 0.1)
e_top    = extrude(r_top, 0.1)
e_bottom = extrude(r_bottom, 0.1)

p = b +[e_left,e_right,e_back,e_front,e_top,e_bottom]   # melt things together

show_all()

Again, left, right, front and back look fine, but the orientation of top and bottom seem dancing out of sync. If the cube is rotated by the x-axis, so that top becomes the new front, the rectangle seems to have a wrong direction, it should go from lower-right to upper-left. Same applies for the bottom-side. If the cube is rotated by the y-axis the orientation of the rectangles seem to be correct. This is not a matter of right or wrong, it is a matter of what the final cube should get.

Hurdle 3:

There is a common agreement and the same expectation for left, right, back and front, but this is not true for top and bottom. Always check the orientation of the planes used by top and bottom. The default-value for x_dir is (0,+1,0), some models need that x_dir is set to (+1,0,0). This helps that you can iterate over all faces, exactly in the same way.

• Can you show how the AM-code should look like for the given example?
• Can you show how the AM-code with x-dir-control should look like?
• Can you show how x_dir-control should be implented in the given BM-example?

It seems that BM-code tries to avoid planes at all (that would also be my desire). This would really simplify the code a lot. However I need to know how the internally used x_dir can be adjusted, that top and bottom get the desired orientation?

Ok, this is enough for today.

[gumyr]

When creating a Plane from a Face there is insufficient information - specifically the direction of the x-axis is not known. If just the Face is provided, a guess is made by build123d/OCCT as to this x-axis direction but the guess isn't always correct. Therefore, the Plane constructor has an optional x_dir parameter which allows the user to provide a value for the x-axis. All of this applies to both Algebra and Builder mode.

[Paul8043]

I have already found the mentioned constructor. The code would look like this:

from build123d import *
from ocp_vscode import *

set_port(3939)

b = Box(3,3,3)

# make sure that the planes have to needed orientation

plane_top    = Plane(b.faces().sort_by(Axis.Z)[-1],x_dir=(+1,0,0))
plane_bottom = Plane(b.faces().sort_by(Axis.Z)[0],x_dir=(+1,0,0))
plane_back   = Plane(b.faces().sort_by(Axis.Y)[-1],x_dir=(-1,0,0))
plane_front  = Plane(b.faces().sort_by(Axis.Y)[0],x_dir=(+1,0,0))
plane_right  = Plane(b.faces().sort_by(Axis.X)[-1],x_dir=(0,+1,0))
plane_left   = Plane(b.faces().sort_by(Axis.X)[0],x_dir=(0,-1,0))

# do some work

extrusions = []
for plane in [plane_top,plane_bottom,plane_back,plane_front,plane_right,plane_left]:
    extrusions.append(extrude(plane*Rectangle(1,2,rotation=45),0.1))
b += extrusions

show_all()

The point here is, after this modification, I have to iterate over planes instead of faces. This is a solution, but it is not elegant. What is needed here:

• attach a plane with specific parameters to face
• the face should store this association internally
• then I can iterate over faces as usual
• the plane disappears from the work-code

Planes are trouble-makers all the time, I just want to spend some time to set up them correctly, and then they should leave the scene. I want to do some work on a face, just by providing x/y-positions for some objects, nothing else!

BM-code likes to iterate over faces, not over planes. I do not know how plane specific settings can be incorporated into BM-code. Please show how this should be done for the example above.

[Paul8043]

@gumyr can you help again:

• I would like to know how plane- specific settings should be incorporated in AM-code. How does the inventor would program that?
• I would also like to know how this should be done with BM-Code (it is too difficult for me at the moment, sorry)

Seems to me that x_dir is the most important parameter. If x_dir has got a wrong value, the impacts are totally fatal.

[gumyr]

I've already explained how x_dir works above. It would really be better to ask these questions on the support Discord where you'll find a whole community of people that can answer your questions.

[gumyr]

By the way - BM code does not "iterate over faces". When you create a Sketch with BuildSketch you are creating workplanes; however, this is optimized such that one can pass Faces which get converted to Planes automatically.

Within BuildPart the association between Faces and Planes is stored internally almost exactly as you describe. In Algebra mode the user needs to manage this.

[gumyr]

I've updated the docs to address the concerns here, including showing how pending objects can be accessed.

[Paul8043]

Ok, now I can see what kind of information is considered as pending. If the work for one Sketch is too complex, I am attempted to provide some Skecthes in a sequence, just putting one below the previous one (same with-nesting-level) as given here:

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

with BuildPart() as pillow_block:
    with BuildSketch() as plan1:
        Rectangle(width, height)
        fillet(plan1.vertices(), radius=f_rad)
    with BuildSketch() as plan2:
        Circle(5)

    pfs = pillow_block.pending_faces
    print(f"len(pfs)={len(pfs)}")
    for i,pf in enumerate(pfs):
        print(f"pfs[i]={pf}")
        
    extrude(amount=thickness)

For this scenario the hope would be that circle from plan2 is subtracted from the rounded rectangle from plan1, and after that the extrusion should take place to produce a centered hole in the middle of the pillow-block. But this is not the case. What does extrude() do, when it gets several pending-faces?

[gumyr]

As you can see from your code, two pending faces are now stored in pillow_block. Since extrude only uses one, it gets the first one and uses it.

As you've provided it, there is nothing to indicate that you want plan2 to be subtracted from plan1 and doing so would be introducing "magic". The separation can be done like this though:

with BuildPart() as pillow_block:
    with BuildSketch() as plan1:
        Rectangle(width, height)
        fillet(plan1.vertices(), radius=f_rad)
        with BuildSketch(mode=Mode.SUBTRACT) as plan2:
            Circle(5)

    pfs = pillow_block.pending_faces
    print(f"len(pfs)={len(pfs)}")
    for i, pf in enumerate(pfs):
        print(f"pfs[i]={pf}")

    extrude(amount=thickness)

len(pfs)=1
pfs[i]=<build123d.topology.Face object at 0x7f2fb9a30a60>

P.S. RectangleRounded (https://build123d.readthedocs.io/en/latest/objects.html#objects_sketch.RectangleRounded) replaces the two lines in plan1.

[Paul8043]

It behaves as always, the solution is simple and the code is concise, exactly as it should be. But how should I know that this has be done in exactly this way? You'll never figure it out, at least not from the given inductory examples.

Let me express this problem by using a metapher. Suppose Build123D is car. The car has super features and what the inventors can do with the car is really amazing. Then the wish arises in you to be able to drive a car like that. Then you try some pedals and knobs and you will be confronted with an unexpected, or even magic, behavior of the car. Then you regognize this car can only be driven best by their inventors, the others, like I, are excluded somehow, at least as long as they could not collect the needed information.

With a real car you can benefit from your experience. If you can drive a VW, then you can also drive a BWM, Audi or Mercedes with little additional effort. You can simply transfer your experience to the other car brand. The more car brands you have already gotten to know, the easier it will be to drive the new car brand.

For Build123D the situation looks different. All your experiences with some other programming languages do not count, you just can't extrapolate that. From whom or from what should I be able to find out which arrangements of the with-statements are needed? Initially, as a newbie, this is almost a mission impossible. The inductory examples give only small hints where the journey might go.

To make this story short: I am willing to work hard to get a drivers-license for Build123D. But this is not an easy task, I have to ask a lot of questions.

@gumyr, I hope is it clear now, where the problem is located, seems you are not aware of this difficulty.

At my current stage of knowledge I have to learn the with-statements by heart, until I can see some strategy behind all of this.

[gumyr]

Now suppose I gave you that car for free, no strings attached, you can do what you want with it (I've I was working during the time I've spent on build123d I could have purchased several very nice cars). Would that change how you feel?

Please start making contributions to the documents yourself if you think there are gaps. I can't know what is going to be helpful to everyone.

[jdegenstein]

But how should I know that this has be done in exactly this way? You'll never figure it out, at least not from the given inductory examples.

Example 3 from the intro docs could have been easily reworked for your application.
https://build123d.readthedocs.io/en/latest/introductory_examples.html#an-extruded-prismatic-solid

I suggest you spend more time reading the docs and less time pontificating about "metaphers" between cars and software. These concepts are covered at length in multiple places. I am surprised you didn't look at the signature for class BuildSketch(*workplanes: Union[Face, Plane, Location], mode: Mode = Mode.ADD) and the Mode enum (Mode.ADD INTERSECT PRIVATE REPLACE or SUBTRACT).

[mnesarco]

I don't see any more users spending so much time on such annoying complaints. Any good programmer can use build123d and create additional tools as needed if the provided API is not comfortable for its desires. I have tried cadquery, i didn't like it, so i tried build123d and i love it. In open source the rules are simple: use for free, contribute if you can, don't be a pain in the ass.