🚀 Enhancement Proposal: Deferred Anchor Cloning / Named Anchor Aliasing in BOSL2

[aeonik]

🧵 TL;DR

I'm trying to automate anchor aliasing, and want to know:

• Is there a better pattern than manually resolving with _find_anchor()?
• Should BOSL2 allow named_anchor("name", "existing-name")?
• How can I make this more idiomatic?

❓ Problem Statement

I'm building a dynamic module that needs to generate reusable, programmatically named anchors for downstream attach() calls — especially for patterns like inlet1, inlet2, etc.

I’d like to alias or clone an existing anchor (e.g. "start-centroid") to a new name (e.g. "inletN") inside a module, so the caller can easily attach to custom-named positions.

However, BOSL2’s current anchor system doesn’t seem to support deferred anchor aliasing (there is also a strong probability that I have absolutely no idea what I am doing). Specifically:

include <BOSL2/std.scad>
include <BOSL2/rounding.scad>

module inlet_tube() {
    // ❌ Fails: named_anchor requires a numeric vector, not a symbolic anchor name
    a = named_anchor("inlet1", "start-centroid");

    // ❌ Fails: _find_anchor is evaluated immediately — $parent_geom isn't populated yet
    // a2 = _find_anchor("start-centroid", $parent_geom)[1]; 

    path = arc(r=50, angle=90);
    path_sweep(circle(r=5), path)

    // ✅ Works: capture anchors *after* child geometry is created using parent()
    let (
        desc = parent(),                            // [geometry, anchors]
        a = last(desc[1]),                          // Last anchor (should match end-centroid)
        a1 = _find_anchor("start-centroid", $parent_geom)[1],  // Resolve anchor manually
        a2 = [named_anchor("inlet1", "start-centroid")],       // ❌ Fails, symbolic
        a3 = [named_anchor("inlet1", a1)]           // ✅ Works, manually resolved
    )
    echo("Resolved anchor via _find_anchor:", a1)
    echo("Named anchor using symbol:", a2)
    echo("Named anchor using resolved vec:", a3)
    echo(concat(a, a2)) // Just testing output of anchor stack

    children();
}

// ✅ External attach still works fine.
inlet_tube()
    echo("Final Anchors", last($parent_geom));

// Generate programmatic anchor names
inlets = [for (i=[1:10]) str_join(["inlet", i])];
echo(inlets);

⚙️ Desired Behavior

I’d love to be able to do something like this inside a module:

named_anchor("inlet1", "start-centroid");  // alias or clone to an existing anchor name

Or possibly support deferred execution of _find_anchor(...) that only triggers after children() have rendered.

I looked at the source for named_anchor, and it looks like it needs a numeric [pos]

BOSL2/attachments.scad

Lines 3302 to 3319 in 4f0b7e5

	function named_anchor(name, pos, orient, spin, rot, flip, info) =
	assert(num_defined([orient,spin])==0 || num_defined([rot,flip])==0, "Cannot mix orient or spin with rot or flip")
	assert(num_defined([pos,rot])>0, "Must give pos or rot")
	is_undef(rot) ? [name, pos, default(orient,UP), default(spin,0), if (info) info]
	:
	let(
	flip = default(flip,false),
	pos = default(pos,apply(rot,CTR)),
	rotpart = _force_rot(rot),
	dummy = assert(approx(det4(rotpart),1), "Input rotation is not a rotation matrix"),
	dir = flip ? apply(rotpart,DOWN)
	: apply(rotpart,UP),
	rot = flip? affine3d_rot_by_axis(apply(rotpart,BACK),180)*rot
	: rot,
	decode=rot_decode(rot(to=UP,from=dir)*_force_rot(rot)),
	spin = decode[0]*sign(decode[1].z)
	)
	[name, pos, dir, spin, if (info) info];

Is it a bad idea to just check if [pos] is a string, and if so, call _find_anchor(pos)?

🤔 Questions

1. Is there a BOSL2-native way to defer anchor resolution or clone existing anchors under new names without manually using _find_anchor and let() gymnastics?
2. Could named_anchor() be extended to accept an existing anchor name (and internally resolve it) instead of only accepting vectors?
3. Is there a better idiomatic way to generate many named anchors dynamically within a module?

💡 Use Case

I'm building complex parametric components like duct joiners or manifolds with N inlets and 1 outlet. I want each inlet to expose a clearly named anchor like "inlet1", "inlet2", etc. for other modules to attach to. This makes downstream composition and GUI parameterization in tools like the OpenSCAD customizer much cleaner.

Regards,
Aeonik

[aeonik]

Hey again! 👋

Still diving deep into anchor aliasing — no replies yet, so I wanted to post an update with my latest findings in case anyone can point me in the right direction or help clarify whether I'm on the right path.

🧠 TL;DR

I'm trying to create a system where a module can alias or clone an existing anchor (e.g., "start-centroid") to a custom name like "inlet1", so that downstream users can attach("inlet1"), attach("inlet2"), etc... instead of the generic names. Some of my shapes will eventually have conflicting anchor names once unioned, so I need to keep everything unambiguous and explicitly named.

🔍 Latest Observations

After re-reading the Attachments Tutorial about 10 times, I found a few things that seem promising:

• expose_tags=true allows children to propagate tag visibility up through the hierarchy — but I'm unclear if this affects anchors or just visual tag toggling like diff().
• “Delay the decision to display or not display this object to the children…” Source: attachable docs
• override_anchor and tag scoping seem relevant, especially since I’m trying to pass through an attachable while adding/modifying a few anchors.
• I expected the “pass-through attachables” section in the tutorial to mention this, but it doesn't go into anchor rewriting — only tag control.

What I really want is:
🧱 A “wrapper” attachable that simply passes through geometry and adds a few renamed anchors.
🌯 Perhaps a burrito.

expose_tags: If true then delay the decision to display or not display this object to the children, which it possible for tags to respond to operations like diff() used outside the attachable object. Only works correctly if everything in the attachable is also attachable. Default: false
Source: attachable docs

Fundamentally, a "pass-through with just a few additions or modifications to the anchor" is in a nutshell the capability I am trying to perform. I would have expected information like this to appear after this section in the tutorial: pass-through attachables.

At this point I am looking through the source code, and experimenting on how to override the special variables that are used to store geom information, but I am pretty unfamiliar with how this is done. Example of my updated code. I can't seem to get the anchors to propagate up. I think the attachable module is just undeffing everything? Or the let statement is creating locally scoped special variables and they get dropped once out of scope?

include <BOSL2/std.scad>
include <BOSL2/rounding.scad>

// Define a reusable inlet tube with an arc path and a circular cross-section.
module inlet_tube(anchor=CENTER, spin=0, orient=TOP) {
    // ❌ This fails: named_anchor requires a numeric position (vector), not a symbolic reference.
    a = named_anchor("inlet1", "start-centroid"); 

    // ❌ This also fails: _find_anchor is evaluated *immediately*,
    // before the child geometry has populated $parent_geom.
    // We would want this to be deferred until after children() executes.
    // a2 = _find_anchor("start-centroid", $parent_geom)[1]; 

    attachable(anchor, spin, orient, expose_tags=true){
        path = arc(r=50, angle=90);
        path_sweep(circle(r=5), path)

        // Try to capture anchors *after* geometry is created using parent()
        let (
            desc = parent(),
            a = last(desc[1]),
            a1 = _find_anchor("start-centroid", $parent_geom)[1],
            a2 = [named_anchor("inlet1", "start-centroid")],
            a3 = [named_anchor("inlet1", a1)],
            parent_anchors = concat(a, a3),
            $parent_anchors = parent_anchors,
            $anchor_override = parent_anchors,
            $parent_geom = parent_anchors
        )
        echo("Find anchor, parent_geom", a1)
        echo("Named anchor, symbolic", a2)
        echo("Named anchor, symbolic resolved", a3)
        echo("Concatenated, desc+unresolved", concat(a, a2))
        echo("Concatenated, desc+resolved", concat(a, a3));

        children();
    }
}

// Anchors are centered, not working...
inlet_tube()
    echo("Final Anchors", last($parent_geom))
    show_anchors();

// Attempt to generate a list of numbered inlet anchor names
inlets = [for (i=[1:10]) str_join(["inlet", i])];
echo(inlets);

These functions also look like they might be useful:

BOSL2/attachments.scad

Lines 5049 to 5088 in 4f0b7e5

	function parent() =
	let(
	geom = default($parent_geom, attach_geom([0,0,0]))
	)
	[$transform, geom];
	// Module: restore()
	// Synopsis: Restores transformation state and attachment geometry from a description
	// Topics: Transforms, Attachments, Descriptions
	// See Also: parent()
	// Usage:
	// restore([desc]) CHILDREN;
	// Description:
	// Restores the transformation and parent geometry contained in the specified description which you obtained with {{parent()}}.
	// If you don't give a description then restores the global world coordinate system with a zero size cuboid object as the parent.
	// Arguments:
	// desc = saved description to restore. Default: restore to world coordinates
	// Example(3D): The pink cube is a child of the green cube, but {{restore()}} restores the state to the yellow parent cube, so the pink cube attaches to the yellow cube
	// left(5) cuboid(10)
	// let(save_pt = parent())
	// attach(RIGHT,BOT) recolor("green") cuboid(3)
	// restore(save_pt)
	// attach(FWD,BOT) recolor("pink") cuboid(3);
	module restore(desc)
	{
	req_children($children);
	if (is_undef(desc)){
	T = matrix_inverse($transform);
	$parent_geom = attach_geom([0,0,0]);
	multmatrix(T) children();
	}
	else{
	check=assert(is_description(desc), "Invalid description");
	T = linear_solve($transform, desc[0]);
	$parent_geom = desc[1];
	multmatrix(T) children();
	}
	}

🤔 Remaining Questions

• Is there a BOSL2-sanctioned way to pass through an attachable while adding one or more new anchor names (e.g. clone "start-centroid" to "inlet1")?
• Is it safe (or intended) to override $parent_geom, or is that explicitly sanitized by attachable()?
• Should named_anchor() support symbolic references like "start-centroid", internally resolving them with _find_anchor()?
• Could tag scoping or override_anchor help propagate custom anchors upward?

[adrianVmariano]

It may be appropriate to raise this sort of feature question as an Issue. I'm not sure how often Revar looks in here, but I rarely remember that this discussion area exists.

First of all, nothing can ever propagate upwards. The thing you want to do is hard because the named anchors don't exist when you are defining your new named anchors. To make this work we would need to add a new feature that allows named anchors to be defined as aliases of other anchors---and when you use it you wouldn't have access to the names of the pre-existing named anchors, which seems like a serious limitation. I'm not sure how hard this would be to do in a way that is robust. Maybe it would be easier to have a propagate_anchors option that copies the named anchors of the parent. I am again uncertain about the difficulty of implementing that in a robust fashion.

It is not intended that users modify $parent_geom or invoke _find_anchor(). But if you modify $parent_geom in a way that is valid nothing is going to break.

[adrianVmariano]

// Arguments:
//   named = list of named anchors to add
//   alias = list of string pairs of the form [newname,oldname] creating named anchor aliases
//   remove = list of strings giving anchors to remove

module change_anchors(named=[], alias=[], remove=[])
{
  oldanch = last($parent_geom);
  allremove = concat(column(named,0), remove);
  keepanch = [for(anch=oldanch) if (!in_list(anch[0],allremove)) anch];
  aliasanch = [for(name=alias)
                  let(
                      found = search([name[1]], oldanch, num_returns_per_match=1)[0]
                  )
                  assert(found!=[], str("Alias references unknown anchor: ",name[1]))
                  list_set(oldanch[found],0,name[0])
              ];
  newanch = concat(keepanch, aliasanch, named);
  $parent_geom = list_set($parent_geom,-1,newanch);
  children();
}  

Try the above. If this solves the problem we can add it.