Selecting faces of a cube #1798

winksaville · 2025-04-02T22:14:36Z

winksaville
Apr 2, 2025

I want to do something fairly simple, I want to create a cube and select a face and then select the corresponding back face and add some text so that I can easily label multiple cubes with different information. I'm going to be 3D printing these cubes and later more sophisticated things.

Suggestions on how I might go about that?

lorenzncode · 2025-04-04T00:47:11Z

lorenzncode
Apr 4, 2025
Maintainer

I ended up creating a cube with labels as an example - hope it might be useful.

from cadquery.func import *
from cadquery.vis import show

d = 30
dcut = 0.8
htext = 6


def make_text(s):
    return extrude(text(s, htext, "RobotoMono Nerd Font"), (0, 0, dcut)).move(
        z=d / 2.0 - dcut
    )


res = box(d, d, d).move(z=-d / 2.0)  # move to center box in z

res = res - make_text("TOP")
res = res - make_text("BOTTOM").move(rx=180)
res = res - make_text("RIGHT").move(ry=90).move(rx=90)
res = res - make_text("FRONT").move(rx=90)
res = res - make_text("LEFT").move(ry=-90).move(rx=90)
res = res - make_text("BACK").move(rx=-90).move(ry=180)

res.export("cube.stl")

show(res, width=500, height=500, xpos=0.3)

4 replies

winksaville Apr 4, 2025
Author

That is fantastic, thank you very much!

lorenzncode Apr 4, 2025
Maintainer

Here is a Workplane version with same end result.

import cadquery as cq
from cadquery.vis import show

d = 30
dcut = 0.8
htext = 6


def make_text(s):
    def callback(wp):
        wp = wp.workplane(centerOption="CenterOfMass").text(
            s, htext, -dcut, font="RobotoMono Nerd Font"
        )
        return wp

    return callback


res = cq.Workplane().box(d, d, d)

res = res.faces(">Z").invoke(make_text("TOP"))
res = res.faces("<Z").invoke(make_text("BOTTOM"))
res = res.faces(">X").invoke(make_text("RIGHT"))
res = res.faces("<Y").invoke(make_text("FRONT"))
res = res.faces("<X").invoke(make_text("LEFT"))
res = res.faces(">Y").invoke(make_text("BACK"))

res.export("cube.stl")

show(res)

winksaville Apr 5, 2025
Author

I like this workplane example better, is there any reason to choose one over the other?

adam-urbanczyk Apr 5, 2025
Maintainer

Func API is more explicit and flexible. That is both good and bad, so pick your poison.

winksaville · 2025-04-20T22:20:13Z

winksaville
Apr 20, 2025
Author

@lorenzncode, txs for the help on this!

Now I have a related question, rather than recessed text I wanted to see how protruding text would work and look. With the help of ChatGPT I found away, basically creating the text on the default XY plane and then translate it to >Z manually. It works but I wanted to do the work using a workplane on the >Z face, which seems more natural and the purpose of a workplane.

Here is the code with the two versions controlled by the if statement and you can see the error.
If you could show me the right way to do this I'd appreciate it.

$ cat protruding-text 
#!/usr/bin/env python3
import cadquery as cq
from cadquery.vis import show

d = 30         # cube size
htext = 6      # text height
hextrude = 0.3 # extrusion height

# Create base cube
box = cq.Workplane("XY").box(d, d, d)
show(box)  # Show the cube

if False: # Fails if True
    # Here I'm trying to create 2D text directly on the >Z face of the cube
    # and then extrude it upward from the >Z face, but it fails as shown below.

    # Create a workplane on the face I want to have the text appear
    wp = box.faces(">Z").workplane()
    show(wp)  # Show the empty workplane

    # Try creating the 2D text fails we, don't get to show(text_2d) below
    text_2d = wp.text("TOP", htext, 0, font="RobotoMono Nerd Font")
    # The error message is:
    #   ./protruding-text 
    #   Traceback (most recent call last):
    #     File "/home/wink/data/prgs/3dprinting/cq-cube/./protruding-text", line 22, in <module>
    #       text_2d = wp.text("TOP", htext, 0, font="RobotoMono Nerd Font")
    #                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    #     File "/home/wink/miniforge/envs/cq/lib/python3.12/site-packages/cadquery/utils.py", line 71, in wrapped
    #       return f(*args, **kwargs)
    #              ^^^^^^^^^^^^^^^^^^
    #     File "/home/wink/miniforge/envs/cq/lib/python3.12/site-packages/cadquery/cq.py", line 4367, in text
    #       return self._combineWithBase(r, combine, clean)
    #              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    #     File "/home/wink/miniforge/envs/cq/lib/python3.12/site-packages/cadquery/cq.py", line 3287, in _combineWithBase
    #       newS = self._cutFromBase(obj)
    #              ^^^^^^^^^^^^^^^^^^^^^^
    #     File "/home/wink/miniforge/envs/cq/lib/python3.12/site-packages/cadquery/cq.py", line 3331, in _cutFromBase
    #       r = baseSolid.cut(obj)
    #           ^^^^^^^^^^^^^^^^^^
    #     File "/home/wink/miniforge/envs/cq/lib/python3.12/site-packages/cadquery/occ_impl/shapes.py", line 4271, in cut
    #       return tcast(Compound, self._bool_op(self, toCut, cut_op))
    #                              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    #     File "/home/wink/miniforge/envs/cq/lib/python3.12/site-packages/cadquery/occ_impl/shapes.py", line 1241, in _bool_op
    #       return Shape.cast(op.Shape())
    #              ^^^^^^^^^^^^^^^^^^^^^^
    #     File "/home/wink/miniforge/envs/cq/lib/python3.12/site-packages/cadquery/occ_impl/shapes.py", line 442, in cast
    #       t = shapetype(obj)
    #           ^^^^^^^^^^^^^^
    #     File "/home/wink/miniforge/envs/cq/lib/python3.12/site-packages/cadquery/occ_impl/shapes.py", line 364, in shapetype
    #       raise ValueError("Null TopoDS_Shape object")
    #   ValueError: Null TopoDS_Shape object
    show(text_2d)  # Show the 2D text
    
    # Now extrude the 2D text to create 3D text
    text_3d = text_2d.extrude(hextrude)  # Extrude upward from >Z face
    show(text_3d)  # 

    # Union the cube and the text
    res = box.union(text_3d)  # Combine the cube and text
    show(res)  # Show the result
else:
    # This works, but I have to translate the text to the top of the cube

    # Create a workplane on the XY plane
    wp = cq.Workplane("XY")
    show(wp)  # Show the empty workplane

    # Create text_2d on the XY plane
    text_2d = wp.text("TOP", htext, 0, font="RobotoMono Nerd Font")
    show(text_2d)  # Show the 2D text

    # Extrude the 2D text to create 3D text
    text_3d = text_2d.extrude(hextrude)
    show(text_3d)  # Show the 3D text

    # Translate text to top center of cube
    text_3d_translated = text_3d.translate((0, 0, d / 2))  # center on >Z face
    show(text_3d_translated)  # Show the translated text

    # Union the cube and the text
    res = box.union(text_3d_translated)  # Combine the cube and text
    show(res)  # Show the result

0 replies

lorenzncode · 2025-04-21T00:20:48Z

lorenzncode
Apr 21, 2025
Maintainer

Hi @winksaville, See the following.

#!/usr/bin/env python3
import cadquery as cq
from cadquery.vis import show

d = 30  # cube size
htext = 6  # text height
hextrude = 0.3  # extrusion height

# Create base cube
box = cq.Workplane("XY").box(d, d, d)
# show(box)  # Show the cube

# Create a workplane on the face I want to have the text appear
wp = box.faces(">Z").workplane()
# show(wp)  # Show the empty workplane

# Note cut=True by default, setting cut to False here
# Create 3D text, combine with cube: "a" for additive or True for same result
res = wp.text("TOP", htext, hextrude, False, "a", font="RobotoMono Nerd Font")
show(res)

# or create 3D text without combine; combine=False by default
text_3d = wp.text("TOP", htext, hextrude, False, font="RobotoMono Nerd Font")
show(text_3d)
res2 = box.union(text_3d)  # Combine the cube and text
show(res2)

0 replies

winksaville · 2025-04-21T16:13:34Z

winksaville
Apr 21, 2025
Author

@lorenzncode , thank you I now have a better understanding.

Personally, this is seems more complicated than is necessary, my feeling there should be a
Workplane.text2 with the following, changes:

Remove cut parameter and use sign of the distance parameter to define cut or extrude
Change default of combine to True like it is for extrude
Based on warning I see on expore-wp-text 2 is seems some changes are coming

$ ./explore-wp-text 2
/home/wink/miniforge/envs/cq/lib/python3.12/site-packages/cadquery/utils.py:66: FutureWarning: Kwarg <cut> will be removed. Please use <combine='cut'>
  warn(

With those changes recessed is:

    res = wp.text("TOP", htext, -distance, font="RobotoMono Nerd Font")j

protruding is:

    res = wp.text("TOP", htext, distance, font="RobotoMono Nerd Font")j

There is the code I used to educate myself from this cq-cube repo:

#!/usr/bin/env python3
import argparse
import cadquery as cq
import sys
from cadquery.vis import show

alogorithms = ['1', '2', '3', '4']
parser = argparse.ArgumentParser(description="Generate 3D cubes with text inscriptions.")
parser.add_argument("algorithm", choices=alogorithms, type=str, help="Algorithm to use")
if len(sys.argv) == 1:
    parser.print_help()
    parser.exit(1)

args = parser.parse_args()

d = 30         # cube size
htext = 6      # text height
distance = 0.3 # cut/extrusion distance

# Create base cube
box = cq.Workplane("XY").box(d, d, d)
#show(box, title="box")

if args.algorithm == '1':

    # Create a workplane on the face I want to have the text appear
    wp = box.faces(">Z").workplane()
    #show(wp, title="1: wp")

    # Create recessed 3D text on the >Z face of the cube
    # By default cut=True and combine is irrelevant, all these produce the same result
    #res = wp.text("TOP", htext, -distance, cut=True, combine=True, font="RobotoMono Nerd Font")
    #res = wp.text("TOP", htext, -distance, cut=True, combine=False, font="RobotoMono Nerd Font")
    #res = wp.text("TOP", htext, -distance, cut=True, font="RobotoMono Nerd Font")
    res = wp.text("TOP", htext, -distance, font="RobotoMono Nerd Font")
    show(res, title="1: res recessed text")

elif args.algorithm == '2':

    # Create a workplane on the face I want to have the text appear
    wp = box.faces(">Z").workplane()
    #show(wp, title="2: wp") # Show the empty workplane

    # Create protuding 3D text on the >Z face in one step, must have cut=False and combine=True
    res = wp.text("TOP", htext, distance, cut=False, combine=True, font="RobotoMono Nerd Font")
    show(res, title="2: res protuding text")

elif args.algorithm == '3':
    # Similar algorithm 4, step by step but using a workplane on the top face of the cube

    # Create a workplane on the face I want to have the text appear
    wp = box.faces(">Z").workplane()
    #show(wp, title="3: wp")  # Show the empty workplane

    # Creating 2D text oriented at >Z face of the cube, combine defaults to False and is unnecessary
    # so both below produce the same text_2d
    #text_2d = wp.text("TOP", htext, 0, cut=False, combine=False, font="RobotoMono Nerd Font")
    text_2d = wp.text("TOP", htext, 0, cut=False, font="RobotoMono Nerd Font")
    show(text_2d, title="3: text_2d")
    
    # Now extrude the 2D text to create 3D text, extrude combine defaults to True so combine=False is necessary
    # to do step by step and see just the text_3d.
    text_3d = text_2d.extrude(distance, combine=False)
    show(text_3d, title="3: text_3d")

    # Union the cube and the text
    res = box.union(text_3d)  # Combine the cube and text
    show(res, title="3: res")

elif args.algorithm == '4':
    # Create on the XY plane then translate to the top of the cube

    # Create a workplane on the XY plane
    wp = cq.Workplane("XY")
    #show(wp, title="4: wp")  # Show the empty workplane

    # Create text_2d on the XY plane
    text_2d = wp.text("TOP", htext, 0, font="RobotoMono Nerd Font")
    show(text_2d, "4: text_2d")

    # Extrude the 2D text to create 3D text
    text_3d = text_2d.extrude(distance)
    show(text_3d, title="4: text_3d")

    # Translate text to top center of cube
    text_3d_translated = text_3d.translate((0, 0, d / 2))  # center on >Z face
    show(text_3d_translated, title="4: text_3d_translated looks same as text_3d")

    # Union the cube and the text
    res = box.union(text_3d_translated)  # Combine the cube and text
    show(res, title="4: res")

4 replies

lorenzncode Apr 21, 2025
Maintainer

Yes, #1509 is related to this Workplane.text issue.

Until Workplane.text is updated, another way to do this might be with Sketch.

With Sketch we can create the 2d part separately (with goal of being less complicated since it doesn't try to do everything in one method like Workplane.text).

To cut, call extrude with negative value and "s" for subtractive mode.
For protruding text/shape, call extrude with positive value.

Here is a example with a polygon instead of text.

import cadquery as cq
from cadquery.vis import show

d = 30  # cube size
htext = 6  # text height
hextrude = 1  # extrusion height

box1 = cq.Workplane().box(d, d, d)
box1 = box1.faces(">X").workplane()

# 2D Sketch
sk1 = cq.Sketch().regularPolygon(d / 4, 3)

res_cut = box1.placeSketch(sk1).extrude(-hextrude, "s")
res_extrude = box1.placeSketch(sk1).extrude(hextrude)

show(res_cut, res_extrude.val().moved(z=d * 1.1))

Sketch does not provide a text method but I think since PR #1633 we can do something like the following (seems to work but usage isn't found in the Sketch tutorial and might be wrong).

import cadquery as cq
from cadquery.vis import show
from cadquery.func import text

d = 30  # cube size
htext = 6  # text height
hextrude = 1  # extrusion height

box1 = cq.Workplane().box(d, d, d)
box1 = box1.faces(">X").workplane()

# 2D Sketch with text from free func API
skX = cq.Sketch(obj=text("X", htext))

res_cut = box1.placeSketch(skX).extrude(-hextrude, "s")
res_extrude = box1.placeSketch(skX).extrude(hextrude)

show(res_cut, res_extrude.val().moved(z=d * 1.1))

adam-urbanczyk Apr 22, 2025
Maintainer

@winksaville #1509 needs to be fixed. We can discuss about the defaults, but e.g. my typical use case is using cut. I hope that by now you realized that there is a pattern in the API and thickness and combine are two orthogonal concerns. Adding random methods that mix them is a no-go for me.

As mentioned above, if you don't like the fluent API, you can always mix and match with sketch or free function:

from cadquery import Workplane
from cadquery.func import text

res = Workplane().box(5,5,5).faces('>Z').eachpoint(text('CQ', 2)).extrude(1)

adam-urbanczyk Apr 22, 2025
Maintainer

I do admit that I dislike somewhat the name eachpoint, maybe we should add an alias called e.g. place. Any suggestions?

lorenzncode Apr 25, 2025
Maintainer

I do admit that I dislike somewhat the name eachpoint, maybe we should add an alias called e.g. place. Any suggestions?

@adam-urbanczyk I like the alias idea. I overlooked eachpoint here. The place alias would help.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Selecting faces of a cube #1798

{{title}}

Replies: 4 comments 8 replies

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

Select a reply

Selecting faces of a cube #1798

winksaville Apr 2, 2025

Replies: 4 comments · 8 replies

lorenzncode Apr 4, 2025 Maintainer

winksaville Apr 4, 2025 Author

lorenzncode Apr 4, 2025 Maintainer

winksaville Apr 5, 2025 Author

adam-urbanczyk Apr 5, 2025 Maintainer

winksaville Apr 20, 2025 Author

lorenzncode Apr 21, 2025 Maintainer

winksaville Apr 21, 2025 Author

lorenzncode Apr 21, 2025 Maintainer

adam-urbanczyk Apr 22, 2025 Maintainer

adam-urbanczyk Apr 22, 2025 Maintainer

lorenzncode Apr 25, 2025 Maintainer

winksaville
Apr 2, 2025

Replies: 4 comments 8 replies

lorenzncode
Apr 4, 2025
Maintainer

winksaville Apr 4, 2025
Author

lorenzncode Apr 4, 2025
Maintainer

winksaville Apr 5, 2025
Author

adam-urbanczyk Apr 5, 2025
Maintainer

winksaville
Apr 20, 2025
Author

lorenzncode
Apr 21, 2025
Maintainer

winksaville
Apr 21, 2025
Author

lorenzncode Apr 21, 2025
Maintainer

adam-urbanczyk Apr 22, 2025
Maintainer

adam-urbanczyk Apr 22, 2025
Maintainer

lorenzncode Apr 25, 2025
Maintainer