Cutting and etching

This example demonstrates the qtcad.builder.Builder.cut and qtcad.builder.Builder.etch operations, as well as how to save and restore the z-coordinate.

Initialization

from qtcad.builder import Builder, Polygon, Mask

Initializing the Builder

Below, we initialize a new instance of qtcad.builder.Builder and define a couple of simple shapes we are going to use in the following.

footprint = Polygon.box(10, 10, name="base").centered()
circle = Polygon.regular(10, 1.8, name="circ").centered()
thin = Polygon.box(10, 0.4, name="thin").centered()

box_mask = Mask("footprint")
box_mask.add_shape(footprint)
box_mask.add_shape(circle)
box_mask.add_shape(thin)

builder = Builder().add_mask(box_mask)
builder.print_mask_tree()

Layout
└── Mask 0 "footprint"
    ├── 0  Polygon  "base"
    ├── 1  Polygon  "circ"
    └── 2  Polygon  "thin"

<qtcad.builder.builder.Builder object at 0x75dd41c3c7d0>

Base geometry

Next, select the generate a geometry with an uneven surface. We use qtcad.builder.Builder.set_group_name to tell the Builder to assign all subsequently created entities to the physical group "model_base". We also use qtcad.builder.Builder.copy_shape to create two translated versions of the circle shape. Using qtcad.builder.Builder.save_z and qtcad.builder.Builder.set_z we can save and restore the z-coordinate of the top of the "base" volume.

builder = (
    builder.set_group_name("model_base")
    .set_mesh_size(10)
    .use_mask("footprint")
    .use_shape("base")
    .extrude(2)
    .save_z("box_top")
    .use_shape("circ")
    .copy_shape(translate=(0, 2))
    .extrude(1)
    .set_z("box_top")
    .copy_shape(translate=(0, -4))
    .extrude(1)
)

[15:24:22] INFO     Using mask 'footprint' (implicitly selecting     builder.py:801
                    shapes [Polygon 0 'base', Polygon 1 'circ',
                    Polygon 2 'thin'])
           INFO     Selected shapes: [Polygon 0 'base']              builder.py:854
           INFO     Extruding shape 0 from mask 'footprint' with    builder.py:2794
                    name 'base' by 2 at z=0
           INFO     Creating new physical group with name           builder.py:2580
                    'model_base_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'model_base_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'model_base_top'
           INFO     Creating new physical group with name           builder.py:2580
                    'model_base_hull'
           INFO     Creating new physical group with name           builder.py:2580
                    'model_base'
           INFO     Setting z-coordinate to 2                        builder.py:903
           INFO     Selected shapes: [Polygon 1 'circ']              builder.py:854
           INFO     Extruding shape 3 from mask 'footprint' with    builder.py:2794
                    name 'circ' by 1 at z=2
           INFO     Fragmenting...                                fragmenter.py:218
           INFO     Setting z-coordinate to 3                        builder.py:903
           INFO     Setting z-coordinate to 2                        builder.py:903
           INFO     Extruding shape 4 from mask 'footprint' with    builder.py:2794
                    name 'circ' by 1 at z=2
           INFO     Fragmenting...                                fragmenter.py:218
           INFO     Setting z-coordinate to 3                        builder.py:903

As promised, all volumes share the same physical group:

builder.view(
    surfaces=False,
    volume_labels=True,
    angles=(-45, 0, 45),
    save="figs/cut_base.svg",
    font_size=15,
    zoom=0.8,
)

           INFO     Saving figure                                   builder.py:1926

<qtcad.builder.builder.Builder object at 0x75dd41c3c7d0>

Cutting

Builder.cut(depth: float, noclip: bool = False) → Self

[🏗️ Operation] Cut the currently selected shape(s) into the model up from the current z coordinate down by depth length units. If noclip=True, the cutting is performed on the whole model rather than clipped by the selected shapes.

See also etch which follows the contours of the top surface.

Parameters:

• depth – The distance by which to etch the selected shapes down into the model.

• noclip – Whether to cut the shape without horizontally clipping to the current shapes.

Next we will make a cut of depth 1 through the first tube shape.

builder.group_from_shape().use_shape("thin").copy_shape(
    name="cut", translate=(0, 2)
).cut(1)

[15:24:23] INFO     Selected shapes: [Polygon 2 'thin']              builder.py:854
           INFO     Cutting shape 5 with name 'cut' by 1 at z=3      builder.py:516
           INFO     Extruding shape 5 from mask 'footprint' with    builder.py:2794
                    name 'cut' by -1 at z=3
           INFO     Creating new physical group with name           builder.py:2580
                    'cut_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'cut_side'
           INFO     Creating new physical group with name 'cut_top' builder.py:2580
           INFO     Creating new physical group with name           builder.py:2580
                    'cut_hull'
           INFO     Fragmenting...                                fragmenter.py:218
           INFO     Creating new physical group with name 'cut'     builder.py:2580
           INFO     Setting z-coordinate to 2                        builder.py:903

<qtcad.builder.builder.Builder object at 0x75dd41c3c7d0>

The cut operation effectively extrudes the currently selected shape(s) downwards and then removes the intersection with existing geometry.

builder.view(
    surfaces=True,
    volume_labels=True,
    surface_labels=False,
    angles=(-45, 0, 45),
    save="figs/cut_result.svg",
    font_size=15,
    zoom=0.8,
)

           INFO     Saving figure                                   builder.py:1926

<qtcad.builder.builder.Builder object at 0x75dd41c3c7d0>

The created surfaces are labeled base on the current naming mode (see Selection of shapes and naming modes).

builder.view(
    surfaces=False,
    volume_labels=False,
    surface_labels=True,
    angles=(-45, 0, 45),
    save="figs/cut_surfs.svg",
    font_size=15,
    zoom=0.8,
    groups=["cut_bottom", "cut_side"],
)

[15:24:25] INFO     Saving figure                                   builder.py:1926

<qtcad.builder.builder.Builder object at 0x75dd41c3c7d0>

Etching

Builder.etch(depth: float, noclip: bool = False) → Self

[🏗️ Operation] Etch the currently selected shape(s) into the model up from the current z coordinate down by depth length units. This is done by cutting into each top surface. If noclip is True, then the surface is not clipped to the currently selected shapes.

See also cut, deposit and grow.

Parameters:

depth – The distance by which to etch the selected shapes down into the model. Must be positive.

In contrast to cutting, etching follows the contour of the top surface.

builder.use_shape("thin").copy_shape(name="etch", translate=(0, -2)).etch(1)

builder.view(
    surfaces=False,
    volume_labels=True,
    surface_labels=False,
    angles=(-45, 0, 45),
    save="figs/etch_result.svg",
    font_size=15,
    zoom=0.8,
)

           INFO     Selected shapes: [Polygon 2 'thin']              builder.py:854
           INFO     Etching shape 6 with name 'etch' by 1            builder.py:548
           INFO     Creating new physical group with name           builder.py:2580
                    'etch_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'etch_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'etch_top'
           INFO     Creating new physical group with name           builder.py:2580
                    'etch_hull'
           INFO     Fragmenting...                                fragmenter.py:218
[15:24:26] INFO     Creating new physical group with name 'etch'    builder.py:2580
           INFO     Saving figure                                   builder.py:1926

<qtcad.builder.builder.Builder object at 0x75dd41c3c7d0>

Again the resulting surfaces are named accordingly.

builder.view(
    surfaces=False,
    volume_labels=False,
    surface_labels=True,
    angles=(-45, 0, 45),
    save="figs/etch_surfs.svg",
    font_size=15,
    zoom=0.8,
    groups=["etch_bottom", "etch_side"],
)

           INFO     Saving figure                                   builder.py:1926

<qtcad.builder.builder.Builder object at 0x75dd41c3c7d0>