Creating Complex 3D Model Graphs with AnchorSCAD

by Gianni Mariani 11-Feb-2024

AnchorSCAD provides an entire workflow for building 3D models. By using Python you get to leverage powerful IDEs including AI tools like github copilot to complement your model building journey. By employing the “class is a shape” paradigm, adding special features to your models becomes simpler, like special anchor functions or other specialised shape specific functionality.

AnchorSCAD empowers you with a complete software development ecosystem. This means you can leverage code reusability, maintain version control, and enjoy the ease of testing and debugging your designs. Imagine building modular components that seamlessly integrate into your grand vision, all within a framework that promotes clean code and efficient development.

There are a number of key components that make the AnchorSCAD ecosystem unique that all work together to minimise code duplication and help you concentrate on building models.

• Anchors - AnchorSCAD’s anchors are static specifiers and evaluated at model build time and can reference any part of the model graph and is easily extensible by just adding an annotated function.
• Parametric complexity simplification - AnchorSCAD uses an extension to Python’s dataclasses (see datatrees) that allows you to inject and bind parameters. This not only simplifies code but also makes it more resilient to parameter changes from shapes that your code depends on.
• Every AnchorSCAD module is a library and a model generator. The anchorscad_main() function used in every AnchorSCAD module will render all the @shape class objects in a module and it will generate all the requested resources which include path, datatree field binding documentation and a visual representation of the model graph.
• AnchorSCAD also has a batch tool that will recursively traverse a directory and generate all the example models and associated STL and 3MF files.
• AnchorSCAD has multi-material support. Working around OpenSCAD’s lack of support for multi-material models, AnchorSCAD is able to utilise OpenSCAD’s “lazy union” feature in its most recent builds that allows multi-model 3MF files to contain separate models for each material.

Building a Model Graph

Anchors: Navigating Your AnchorSCAD Model

Anatomy of an Anchor

Core Shape Anchor Functions

Customising Anchors with the @anchor Annotation

Building Model Graphs

Class Relationship Diagram

Table 1: Class Inheritance for Core Classes

Table 2: Instance Functions and Relations

Shape Operator Functions

Table 3: NamedShape Attributes

Step-by-Step Guide

Step 1: Creating a Basic Shape

Step 2: Naming and Modifying Attributes

Step 3: Defining the Frame of Reference Generates a Maker

Step 4: Adding Shapes to the Maker

Understanding Anchors

Creating Complex Model Hierarchies

Datatrees

Introducing datatrees

Field injection and Field binding

Datatree Wraps Dataclass

Help for Class A

Datatree Inject and Bind

Injected Fields

Example of field binding,

Example of overriding the field binding.

Binding Parameters In self default Fields

Injecting Computed Defaults

Injecting Function Parameters

Inheritance with Datatrees

Mapping Injected Names with a Prefix or Suffix

Override

Hole Gauge Example

From: hole_guage

Building a Model Graph

This section introduces shapes, makers, and composite shapes - the fundamental building blocks that form the foundation of your 3D creations within AnchorSCAD.

Foundation Elements:

• Shape: The basic building block representing a single 3D geometric entity.
• NamedShape: A container assigning a name to a Shape, enabling easy referencing within the model.
• Maker: The central class used to construct and manipulate shapes.
• CompositeShape: A powerful tool allowing you to group multiple shapes and assign transformations, creating complex structures.

Shape Modifiers:

• solid(): Defines the main body of a solid shape.
• hole(): Creates a cutout within a solid, defining internal cavities.
• cage(): Generates a wireframe representation of a shape.
• composite(): Groups multiple shapes under the CompositeShape class, enabling transformations and hierarchical organization.
• hull(): Creates a convex hull encompassing all input shapes.
• minkowski(): Performs a set difference between two shapes.
• intersect(): Creates the intersection volume between two shapes.

Key Points:

• Each Shape class can define custom anchor functions using the @anchor annotation, tailoring reference points to your specific needs.
• Anchors play a crucial role in building organized and well-defined models, especially when dealing with complex hierarchies.

Creating a model hierarchy in AnchorSCAD is based on the concepts behind the Shape, NamedShape, Maker and CompositeShape classes and the various shape modifiers, solid(), hole(), cage(), composite(), hull(), minkowski() and intersect(). The positioning of shapes within a Maker uses “anchors”. Each Shape class can define @anchor functions that can be used to define shape specific functions to locate points on the shape.

The AnchorSCAD API is designed to minimise the possibility of producing illegal model graphs. The API also uses chaining where appropriate to help maintain backwards compatibility as more features are added. The example below shows the construction of “Maker”, a node in the model graph using the Cone shape, applying the “solid” operator, setting the colour and material attributes. Finally, the “at()” function provides the transformation that is used to align the graph node with the graph it is being added to.

The following code demonstrates the creation of  Maker objects (which are graph nodes). It constructs a 3D model consisting of a cone with a sphere placed on its top. The sphere has 6 cylindrical holes evenly distributed around its circumference. The colour and material calls are optional and shown to illustrate how node attributes are applied.

While you can render the OpenSCAD code using print(ad.render(maker).rendered_shape), it’s much easier to use a CompositeShape, see the examples below.

Anchors: Navigating Your AnchorSCAD Model

As the name suggests, AnchorSCAD has a versatile mechanism for defining placement of shapes relative to each other. Quite simply, an anchor resolves to a 4x4 transformation matrix. It is a frame of reference. When adding two shapes, the nominated anchors are aligned and the resulting transformation to perform that alignment is used as the graph.

Perhaps the most important feature of anchors is that they are statically specified and can be supplied as a parameter. This allows for separation of the model building code from the design constraints. Additionally anchors

Below is an example of an anchor. The 'shell' component nominates the name of the shape being selected, this happens to be a Box shape. 'face_edge' is the anchor function on the Box shape and it takes 3 parameters, face, edge, and relative position on the edge which corresponds to 'front', 1, 0.15 finally, an arbitrary post multiplied transformation is applied that translates the anchor up the Z axis by epsilon.

 'shell', 'face_edge', 'front', 1, 0.15, post=tranZ(epsilon)

Anatomy of an Anchor

An anchor consists of several key components:

• <path>: A sequence of names that represents the path through the model hierarchy, leading to the desired location. Each name in the path refers to a shape or group within your model.
• <function>: The name of the shape function at the end of the path. This function defines the type of shape you're referencing.
• <parameters>: Parameters specific to the chosen shape function, further pinpointing the exact reference point within the shape.
• pre: Optional parameters specifying a pre-multiply transformation.
• post: Optional parameters specifying a post-multiply transformation.

Core Shape Anchor Functions

Each shape will define anchor functions that are semantically appropriate, for example Box has ‘face_corner’, ‘face_edge’, ‘face_centre’ and ‘centre’ while Cylinder has anchors ‘top’, ‘base’, ‘surface’ and ‘centre’. Each Core shape has examples rendered with anchors displayed. Here is Cone example render showing the ‘top’ and ‘surface’ anchors with various parameters:

By convention, anchors should have the Z axis pointing away from the shape and normal to the surface unless otherwise specified. Note the ‘surface’ parameter ‘tangent’ is used to determine the orientation of the anchor, either it is normal to the cone surface or if ‘tangent’ is false, it aligns the Y axis with the cone’s central axis.

Customising Anchors with the @anchor Annotation

While core shapes offer predefined functions, you can create custom anchor functions for shape classes (including CompositeShape) using the @anchor annotation. This allows you to define specific reference points relevant to your custom shapes.

Below is an example of an anchor defined in the Pipe class. The inner cylinder of a pipe is a hole and by definition, the normal direction is different. Hence we create an “inner_surface” anchor function that flips the direction by rotating the resultant 4x4 matrix by a rotation around the X axis of 180 degrees.

This is an “EXAMPLE_ANCHORS” render for the “inner_surface” anchor specified in the basic/pipe.py model.

• Building Model Graphs

• AnchorSCAD employs method chaining to specify nodes in the model graph. This reduces the chance of making errors but also makes for a flexible API. However, this requires more classes to implement the API. AnchorSCAD also uses the builder pattern, called “Maker” and are only generated as a result of a sequence of calls to “shape operator”, optional attributes and given a default frame of reference. This section describes these concepts.

• Class Relationship Diagram

• The essential AnchorSCAD core class relationships are shown in the diagram below. Central to AnchorSCAD is the Shape class. The shape class is the parent class to many AnchorSCAD types, concrete types like Box, Cylinder etc as well as model hierarchy like CompositeShape and Maker.
• 

• Table 1: Class Inheritance for Core Classes

• Table 2: Instance Functions and Relations

• Shape Operator Functions

• The shape operator functions in AnchorSCAD require a name parameter that can be any representable (repr-izable), hashable object. This flexibility allows for a wide range of identifiers, commonly strings or tuples of strings and integers. These identifiers serve as unique references to shapes within a node of a model, facilitating their manipulation and interaction.
• Shape modifier functions return a NamedShape. NamedShape allows application of attributes to the model graph node and is used to build a Maker object, a model graph node builder. The shape used to build the Maker is the primary shape for the node. When processing anchors, the primary node’s anchors do not need to be qualified with the name provided to the shape operator.

• These functions not only modify the shapes but also define their roles and interactions within the model, enabling the creation of complex 3D models through intuitive operations.

• Table 3: NamedShape Attributes

• Creating Basic Shapes: Begin by defining basic geometric shapes, such as Box, Cone, Cylinder, etc.
• Naming and Modifying Attributes: After creating a shape, you name it and optionally modify its attributes, such as colour or material.
• Defining the Frame of Reference with at(): Specify the shape's frame of reference using the at() function, which is crucial for positioning within the model hierarchy.
• Creating a Maker: A Maker serves as a node in the model hierarchy, capable of holding and manipulating shapes.
• Adding Shapes to the Maker: Use the Maker's functions to add new shapes to the model, defining their relationships and positions through anchors.

Step-by-Step Guide

Step 1: Creating a Basic Shape

Start by creating a basic shape. This is the foundation of your model.

Step 2: Naming and Modifying Attributes

After creating a shape, you can name it and modify its attributes. Naming is crucial for identifying the shape within the model hierarchy.

Step 3: Defining the Frame of Reference Generates a Maker

The at() function specifies the frame of reference for the shape, determining its position within the model hierarchy.

Step 4: Adding Shapes to the Maker

Use the Maker's functions to add other Maker’s to the model. It’s notable that a Maker can only accept a Maker to be added. All Shape objects must have a shape operator applied and given a frame of reference for it to be added as a node in a Maker.
The add_at() call aligns the anchor specified in the other_maker and the anchor provided as the second parameter in the add_at() call. This anchor can reference any node currently in the maker’s model graph.

Understanding Anchors

Anchors define specific points or specifically frames of reference on shapes that serve as a reference for positioning other shapes. Each shape type, like Box or Cylinder, has predefined anchors (e.g., "centre", "face_centre", "top", "base").

When you specify an anchor in the at() or add_at() function, AnchorSCAD resolves the path component of the anchor and calls the corresponding anchor function on the shape, which returns a transformation matrix defining the frame of reference for that anchor.

The above code prints the GMatrix, note they’re identical.

Creating Complex Model Hierarchies

By nesting Maker instances and utilising anchors, you can create complex model hierarchies. Each Maker can be thought of as a container for shapes and other Makers, allowing for detailed and structured model construction.

Remember, once a Maker is used within another Maker, it is copied, ensuring that mutations to the Maker after its use are not reflected in nodes that have already been constructed. This behaviour facilitates immutable design patterns, making your model hierarchy more predictable and easier to manage.

Datatrees

Building complex hierarchical data objects using dataclasses reduces much of the otherwise needed boilerplate code. This obviously being the point of dataclasses. While using dataclasses to develop AnchorSCAD I found it to be still a very verbose and repetitive and subsequently fragile when building complex 3D models.

Introducing datatrees

datatrees extends (as a wrapper over datatlasses.dataclass) to include:

• Field injection
• Field binding
• self factory default

datatrees can dramatically reduce the overall boilerplate code, however, one still needs to be careful that the datatrees bindings produce the desired outcomes particularly when a multiple classes being injected may cause undesriable name collission.

Field injection and Field binding

Often one desires building dataclass objects containing other dataclass objects from within the __post_init__ function potentially with many instances of the same dataclass type. When creating AnchorSCAD models in particular it may be necessary to build many instances of a dataclass type. For example a 3D model of hole gauge, a plate with multiple holes with different sizes. The height (z) parameter may be shared with all the contained holes while the radius of each individual hole would be specific to that hole. Such a model can be found here (hole_guage).

Datatree Wraps Dataclass

Construct with v1 provided..

Comparison of two different instances with the same value.

Help for Class A

Datatree Inject and Bind

Injected Fields

Datatree uses the a_node field in class Anode above to inject class A constructor parameters as fields in the containing class (class Anode). Node allows specification of name mappings with mapping dictionaries, prefixes, suffixes or specific exclusion of specific parameters.

In the class Anode example above, the field v1 is specified so the field v1 from class A will not be injected and the default parameters specified in class Anode will remain. However the remaining parameters (v2, v3 and v4) will be injected with the default values specified in class A.

Constructing a default class Anode will demonstrate the injected values, see parameters v2, v3 and v4 below:

Note how the a_node field is transformed into a BoundNode. This is a factory for A objects that will pull all constructor parameters from the Anode object that created it. The example below shows how the a_node constructs a  class A object pulling all parameters from the instance containing it.

Example of field binding,

The BoundNode factory also allows all the parameters provided in the associated class (or function) from the corresponding Node. In this case, the v3 parameter is overridden with the value 33.

Example of overriding the field binding.

Binding Parameters In self default Fields

dataclasses.field provides field attributes default and factory_default parameters, the latter being evaluated at object initialization. datatree.dtfield wraps dataclasses.field providing a self_default parameter that takes a function object with a single parameter. At class initialization, these functions are evaluated with the object instance as its value.

The order of evaluation is the order in which they are declared in the class additionally they are evaluated after all the Node fields have been bound (transformed into BoundNode factories). This allows fields specified with a self_default attribute to use any field specified with Node as long as invoking BoundNodes factories (bindings) do not attempt to access self_default fields that are not yet evaluated.

Injecting Computed Defaults

In the example below, class Bind defines the field v1 as a computed sum v2 + v3.

The default value of class Bind is Bind(v1=5, v2=2, v4=4, v3=3). Note the value of v1 being the specified sum.

This demonstrates the value of v1 is evaluated with the values of v2 and v2 that are provided in the constructor.

Injecting Function Parameters

The example below shows that any function (or lambda) can be used as a datatrees.Node. In the example below, the fields lamba_node and func_node use different declaration of essentially the same function but the parameter names from func_a are also injected.

The lambda_node will bind the values a and b and pass it to the lambda in the in the class declaration.

This demonstrates the default value for x being overridden and the default value for y being used in the call to func_a.

Inheritance with Datatrees

Mapping Injected Names with a Prefix or Suffix

It is often important to inject the same or similar class with identical field names. datatree.Node provides for prefix= and suffix= specifiers that can be used to map injected parameter names.

Note the call below to make_stuff() that returns a tuple of the result of invoking a_node() and b_node() from a default class C instance. The fields a_v1 and b_v1 are injected into calls for a_node() and b_node() respectively and hence the difference in the instances of the instances of class A being created.

Override

As mentioned earlier, the override parameter should only be used for debugging purposes. This uses the datatrees.override function to generate a datatrees.Override instance. The parameters to datatrees.override are simply parameters to override that will replace any provided value including explicit values. Since the override parameter is passed down, it also is able to hierarchically provide override values for contained bound nodes.

Note that class O has only one injected parameter, a_v1. The default constructor demonstrates the only provided parameter. The default of a_v1 is from class C’s default value for a_v1,

This demonstrates the node generating an instance of class C.

This demonstrates using the override parameter with an Override specifier that overrides multiple layers within the class O datatree class. Node how the b_node override specifier for v2=909090 is reflected in the resulting value of A() while b_node is called with a value for v2 that is ignored.

Overriding values in this way can cause code to be fragile as disregarding parameter values with those provided by some unrelated function will inevitably cause unexpected and silent issues to appear which are difficult to diagnose. This is why the override parameter should only be used for debugging purposes and not otherwise used.

Hole Gauge Example

The hole_guage.py code below (found in hole_guage) demonstrates how two anchorscad.CompositeShape 3D models can be used where one shape class instance consists of multiple instances of another 3D model and the parameters can be shared. It also demonstrates how self_default bindings can be used in conjunction with BoundNode factories.

To demonstrate the doc field attribute, the following is the pydoc generated for HoleGuage. Note the fields fn, fa and fs are used in AnchorSCAD and it’s desirable to pass these attributes to constructors of contained classes as these are used by the rendering engine to determine the complexity of the polyhedrons approximations of curved surfaces. This is a feature of the anchorscad.ShapeNode subclass of datatrees.Node.

From: hole_guage

The code below is a 3D model using AnchorSCAD that generates a plate of holes. The SingleHoleGauge class generates a single row of holes with radii specified by the hole_rs parameter and the thickness of the plate specified by the h parameter. The HoleGauge class is similar but generates a grid of holes specified by a tuple of tuples of hole radii via parameter hole_rss.

HoleGauge generates a number of SingleHoleGauge shapes and stitches them together but also creates an overall plate sized to contain all the SingleHoleGauge shapes in a single ‘assembly’ plate.