Difference Interference with attaching shapes

[NakedMoleRatScientist]

There is a problem I am working on in a real project but it has a lot of fiddly details that nobody needs to fight through to understand, so I made a toy example relevant to the issue I am having.

include <bols2/std.scad>


$fa = 1;
$fs = 0.1;

module hole()
{
    diff()
        cylinder(1,5,5,center = true) {
            attach(LEFT,RIGHT,inside=true)
                tag("") cuboid([5,10,1]);
            attach(CENTER,CENTER,inside=true)
                tag("remove") cylinder(1.1,2.5,2.5,center=true);
    }

}

module test()
{
    diff()
    {
        cuboid([10,10,2])
        {
            attach(CENTER,CENTER)
                tag("remove") cuboid([11,2,1.1]);
            attach(RIGHT,LEFT)
                tag_scope() hole();
        }
    }
}


test();

So, I get something like that:

Basically, I made a hole into the cuboid, which is good, but when I attach the module hole, it also get cut by the hole that was cutting through the cuboid.

So, roughly speaking, the hole shouldn't cut through the shape I am attaching, but there should still be a hole in the cuboid.

I can't exactly achieve this result, so this screenshot kinda illustrate what I am going for, except with the hole in the cuboid existing.

I have tried modularizing the cuboid into its own module in order to isolate the hole cutting, but for some reason it doesn't allow me to attach anything.

[pkriens]

This is the exact area I am struggling with ... The diff() seems designed to make component based designs but the results are often unexpected and hard to control.

I actually only last week figured out how diff worked (although it is well documented):

    union() {
      difference() {
         filter( tag != "keep" && tag != "remove") children();
         filter( tag = "remove") children();
      }
      filter( tag = "remove") children();
    }

Where filter would be a hypothetical module that could filter its children.

I think in this case the problem is that you scope the 'hole()', which really doesn't do anything except ensure that the cylinder it removes is not affecting anything else outside it. The tag_scope module ensures that the the result is a single shape and no longer that parts that constructed it.

This is how it looks now when you show the pseudo code of what happens:

    union() {
        difference() {
            cuboid([10,10,2]) attach(RIGHT,LEFT) tag_scope() hole(); // solid
            ... attach(CENTER,CENTER) cuboid([11,2,1.1]);                // 
        }
        //  filter( tag = "keep") children();
    }

It should be clear why the hole() is affected by the bar/pipe/tunnel that you run through the cube.

The tag_scope() is not a protection for the code that follows, it protects the code before by having it treated as a single object, its innards are hidden. In this case the cuboid with a tunnel should use tag_scope and be a component.

In this case I would make it a true attachable. It is always a bit of boilerplate to make something an attachable but you get a lot of behavior for free.

module hole() {
    tag_scope() diff() 
    cuboid([5,10,1]) 
    attach( RIGHT) ycyl(r=5,h=1) 
    tag("remove") ycyl(r=2,3);
}

module tunnel(anchor,spin,orient) {    
    attachable( size=[10,10,2], anchor=anchor,spin=spin, orient=orient) {
        //tag_scope() 
        diff()
        cuboid([10,10,2])
        attach(CENTER,CENTER) 
        tag("remove") 
        cuboid([16,2,1.1])
        ;
        children();
   }
}

tunnel() attach(RIGHT,LEFT) hole();

Good hygiene would mean also to make hole() an attachable ... It can now not have any children and that will bite you one day.

[NakedMoleRatScientist]

Hi. Thanks for the write-up. The reason why I use tag_scope is through experimentation and learning from example. I got good result from using it in another context, so I reused it in this context.

I am still not sure about the whole filter explanation. It appears to be an order of operation thing? Anything that's not a 'keep' or 'remove' get done first and then "remove", and then finally "remove" on the whole result. I don't know where the keep operation fits but I assumed that gets done first.

[pkriens]

I see I made a mistake ... the last filter operation was the "keep" and I said the "remove". Really sorry for that.

I think if you now reread the description of diff() again it might fall in its place. The documentation is excellent once you see it :-)

If not, let me try to explain how it works in more detail. Key is to recognize that each module must call its children, a module that does not call its children will break the chain. In OpenSCAD, the idea is that a module modifies the transformation matrix and then calls its children that will use this modified matrix as their world.

translate([10,15,20]) sphere(r=3) cube(3);

This example works because translate will modify the matrix to do a translation and then it calls children() while this new transformation matrix is in effect. In this case, the children for translate is only the call to sphere. I.e. if translate with do a echo($children) it would print 1, not 2. Sphere will render itself and then call its children. The same for cube. Ad nauseum. The reason that children() is plural is when you provide a block with multiple statements:

translate([10,15,20]) {
  sphere(r=3);
  cube(3);
}

In this case, when you do echo($children) it will be 2.

The key problem BOSL2 tries to solve with the attachments is to take the geometry of a shape into account. Unfortunately, you cannot call a module and get the geometry back and then act. There is absolutely no f***g way to return information upstream. Information can only be passed to the invocations downstream. This is a huge pita.

The most important function is therefore attachable(), this is where most of the magic happens. The general pattern is that a module sets some $ variables and then attachable() will do some magic when it sees variables set. $ variables are special because they will be accessible by the children of the module that sets them.

An attachable must have two children. The first child is the code that creates a shape and the second child are the children of the original function. When you invoke the attachable function, you specify a geom, a description of the geometry. This geometry is set in a $ variable so that the module downstream can use it.

module component() {
     attachable( ... ) {
         union() {   .... render object }
         children();
     }
}

Since the attachable() module always gets 2 children and it knows the first is the render child and the second are the children of the original module it can do lots of magic. This is where the attach magic happens. The attach(LEFT,RIGHT) module's first parameter sets the transformation to the first anchor, LEFT in this case. However, it cannot transform to handle the second parameter since for that the geometry of the next module invocation is needed. This is where attachable comes in. Since the attachable() gets the geometry as a parameter, it can do a transformation that uses the second anchor in attach() as well as the align parameter. It then calls child(0).

However, by not calling child(0), attachable can also hide the actual rendering of the module. This is used in diff(). The diff module will call the downstream modules three time.

• Once with the tags setup to hide keep or remove to get the solid body to difference with.
• Once with the tags set up to show only the children tagged with remove.
• And then after the difference operation once with the tags to only show modules tagged with keep.

I had a pretty strong misconception about keep. The idea is really about having a solid (untagged), clearing out a space in it (remove) and then decorate the empty void that remove created with modules tagged keep.

The following code is a simplified form of the diff() module.

module diff(remove="remove", keep="keep") {
    difference() {
        hide(keep,remove) children();
        show(remove) children();
    }
    show(keep) children();
}

The attachable module will look something like this:

module attachable(... ) {
          // setup transformation to handle any attach() etc.
          if (shown() ) child(0);
          children(1);
}

Again, read the documentation because it is quite well described. I missed a lot since I did not really understand some of the OpenSCAD language oddities.

[NakedMoleRatScientist]

I appreciate your effort in explaining how openscad and BOLS2 works.

Let's me see if I can understand the gist of your explanation.

My understanding is that behind every module is the "children". However, children cannot return information. It can only do operations(diff, union, intersect,etc) What you need is information from the parents level, and that is where attachable comes in, because it can access that information that children can then use.

The first operation is the initial shape of the object, and subsequent children modify that, first with removal operation and the finally adding to it.

Let me know where I am going wrong the explanation.

[pkriens]

You basically have the gist ... The first operation, however, does not have to set a shape. It can be echo(), up(), etc. as well. However, in BOSL2 it is crucial that every module calls its children after it has done its work.

Notice that ALL shapes in the BOSL2 library use attachable. The authors tried everything to make it as simple as possible to make a custom shape an attachable but it is still some boilerplate that programmers tend to hate. (Including me.) I often postpone making a shape an attachable but I usually regret this, just a hard learner.

Once you 'feel' the basic idea it grows on you. It stays a bit clumsy to have to prepare all the work beforehand so that the attachable has the proper information but I think BOSL2 shows you can do amazing things with this model.

The BOSL2 documentation is really excellent. I did severely miss a good explanation of the BOSL2 implementation model because once I understand the mechanism, I can easier use a library, the code becomes predicable in my mind.

I think they skimped on these 'implementation' details because a lot of people tune out and look for something they think will be simpler. However, I think it might help some people if the implementation aspects were documented. There are some really interesting data structures like desc and geom that are at the code and people like me would really be helped if they were well documented.

Good luck!

[adrianVmariano]

The internal data structures are not documented because they are internal and you aren't supposed to use them. They may change without warning at any time.

Would it be worth adding to the tutorials your description above (or a version of it) about the internals of attachment and tagged operations? It seems like a lot of users are overwhelmed by the basic concepts of attachment, so implementation details are not what they need. But as you say maybe it's helpful to somebody?

[pkriens]

It is a good idea to keep the data structures internal but it would be nice to have a consistent set of access functions. Maybe this could be a start to use the new object functions?

desc = Desc( parent());
bbox = desc.bbox();
...
conoid = Conoid( d1=10, d2=5, h=10);
angle = conoid.angle();
bot = conoid.slice(0,5);

If you're interested I could propose a scad file that provide such an object oriented API? I know object is experimental but if we make it a new include file it should not be an issue, should it?

Maybe create an 'under the hood' tutorial? I guess my problem was that I have 55 years of software experience and applied this without too much thinking to OpenSCAD/BOSL2. I actually last week had to sit down and figure out what children really means. Even though I create a grammar for OpenSCAD, I did not know if children() was the chain of invocations or just the first. I now know that it is only the first invocation, only a block provides more children. Problem is it looks like a duck, it quacks like a duck but it actually isn;t a duck. I realize that this chained invocation is fundamental to OpenSCAD and not BOSL2 but BOSL2 relies on it so much, it is so core, that I think explaining this is kind of crucial. Without understanding how attachable() does its work makes it kind of magic and almost impossible. Explaining how the chaining works could use some pictures.

There was a Dutch soccer player , Cruyff, who had an expression: "You only see it when you get it." Several times when I saw it I thought I help out and write a section for BOSL2 only to find out that it was already there.

Clearly you can pick any of my texts for whatever purpose. However, I am also willing to help out in making another Attachment tutorial. I do have some ideas.

[adrianVmariano]

I don't think I understand the API you are proposing. What user access do you want to the internal data structures that isn't already available? We prefer to minimize features that rely on experimental OpenSCAD features.

If you write a tutorial on attachment internals or want to improving or expanding the existing tutorials we can include your updates. The tutorials are in markdown with examples inserted in a different way than in the docs, so take a look at one to see how it needs to be done.