Hole Wizard

[pierremtb]

Milestone for issue tracking: https://github.com/KittyCAD/modeling-app/milestone/13
Milestone contributors: @adamchalmers @pierremtb

---

Mechanical engineers work with holes, and ZDS needs first-class support for them. It's possible to design holes yourself right now from KCL primitives (e.g. revolving a profile, then subtracting it from a solid), but we should provide users with higher-level functions that are easier to use.

Requirements

We will add several new KCL functions to easily create holes. A new UI, the hole wizard, will let point-and-click users fill in the parameters for these functions, and when users press OK in the wizard, it'll update their KCL and insert calls to them.

1. A hole wizard UI element that lets users choose what their hole looks like

• Users can fill in parameters from a text input, or
• Users can choose a standard hole from a drop-down list (see 4)
• Users can save their custom holes and reuse them.
• Saving a hole will create a holes.kcl in the top level dir of the project, and the wizard will check for this file and load its holes for users to choose from.
• (debatable?) The wizard should encourage users to choose from their custom holes, or standard holes, before defining their own. This encourages users to use a consistent range of holes in their models. It's better engineering practice to use the same hole multiple times rather than making each hole its own idiosyncratic little unique project.

2. Hole functions in KCL, which the wizard calls into

See below for details

3. Holes can have three parts, which can all be selected independently:

• Its top (countersink, counterbore, or normal)
• Its body (currently we will only support a blind depth e.g. 4cm)
• Its bottom (flat, or drilled)

4. We will provide a library of standard holes

• For example, "USA Toaster Manufacturing Corporation Standard Countersunk Drill Hole Q"
• KCL's standard library won't contain these, they will be available in an external library, maintained by Zoo
• Users will be able to define and use their own external libraries with other collections of standard holes

Out of scope

1. Engine integration (e.g. no virtual preview in the video feed of what your hole will look like which updates as you update the wizard's values)
2. Interactive gizmos in the scene which let you drag them to update the wizard
3. Support for editing the hole's profile in sketch mode
4. Threaded holes
5. Through holes that either go through a particular solid, or end at a particular solid's face. For now, users can just set the depth of the hole to some variable, and use that variable as the extrusion distance of a solid too.

API

The API for this project is just the KCL type signatures. This is what the frontend will need to instantiate, and what the KCL team will implement.

Hole functions

A hole is defined by 3 things:

• Top
• Body
• Bottom

I'm not sure if these are the right terms, so please feel free to suggest alternative names.

A hole is simply a choice for each of these.

• For tops, we will support normal, countersink or counterbore (eventually we will support both countersink and counterbore, but not yet).
• For bodies, we will support blind (eventually we will support through but not yet).
• For bottoms, we will support flat or drilled.

Here's the parameters we will support for countersink and counterbore:

The KCL for these is defined as:

/// ---------
/// Tops
/// ---------

/// Angular area
fn countersink(
    /// E.g. 82 degrees for American inch screws, or 90 for ISO metric screws.
    angle: number(Angle),
    /// The outer diameter, as the inner diameter is defined by the hole body.
    diameter: number(Length),
    /// Chamfer the bottom of the counterbore where it meets the rest of the hole
    chamfer: number(Length),
): HoleTop {}

/// Straight down area
fn counterbore(
    diameter: number(Length),
    depth: number(Length),
): HoleTop {}

/// No top feature, straight into the hole.
fn normalTop(): HoleTop {}

/// ---------
/// Bodies
/// ---------

fn blind(length: number(Length), diameter: number(Length): HoleBody {}

/// ---------
/// Bottoms
/// ---------

fn drilled(tipAngle: number(Angle)): HoleBottom {}
fn flat():    HoleBottom {}

/// ---------
/// Placing holes
/// --------- 

/// Convenient type alias
type HoleProfile = Sketch

/// Defines a hole, but doesn't actually cut it from anything.
/// You can either use it with the functions below, or with `revolve() |> subtract()`
fn holeProfile(top, middle, bottom): HoleProfile {}

/// Using a defined hole, cuts it into a solid.
/// Return the modified solid.
/// Roughly equivalent to taking the hole profile, revolving it 360 degrees, and subtracting from a solid.
fn hole(@solid, face, holeProfile, cutAt: Point2d): Solid {}

/// Like `hole` but takes multiple holes, probably the output of a pattern.
/// Roughly equivalent to taking the patterned array of profiles, revolving each 360 degrees, and subtracting them from the solid.
/// `cutAt` is the first hole in the pattern.
fn holes(@solid, face, holeProfiles: [Profile; 1+], cutAt: Point2d): Solid {}

Here are some examples of using this library.

// Define one hole
myHole = holeProfile(
  bottom = drill(pointAngle = 55deg),
  body = blind(depth = 4, diameter = 0.5),
  holeType = counterbore(diameter = 5, depth = 1)
)

// Cut out one hole
startSketchOn(XY)
  |> rectangle(width = cubeLen, height = cubeLen, center = [0, 0])
  |> extrude(length = cubeLen, symmetric = true)
  |> hole(
    face = END,
    cutAt = [4, 0],
    holeProfile = myHole,
  )

// Cut out many holes
startSketchOn(XY)
  |> rectangle(width = cubeLen, height = cubeLen, center = [0, 0])
  |> extrude(length = cubeLen, symmetric = true)
  |> holes(
    face = END,
    cutAt = [4, 0],
    holeProfiles = patternLinear2d(
      myHole,
      instances = 4,
      distance = 0.6,
      axis = [1, 0],
    ),
  )

We will also publish a KCL library with choices for these. For example, here's how we would define the Q screw from the Acme standard.

export acmeQTop:    HoleTop    = counterbore(diameter = 2in, depth = 4.4in)
export acmeQBody:   HoleBody   = blind(length = 8in, diameter = 2in)
export acmeQBottom: HoleBottom = drilled(tipAngle = 33deg)
export acmeQ:       Hole       = hole(top = acmeQTop, body = acmeQBody, bottom = acmeQBottom)

This KCL library will be published as a second-party library, i.e. maintained by Zoo but not in the standard library. It'll be available for all users, but this way we can change its details later.

Delivery plan:

• Phase 1: the KCL functions for top/bottom/body/hole. The basic wizard which lets users set those values via a text input.
• Phase 2: the KCL library with standard holes. Wizard adds drop-down list to pick from these standards.
• Phase 3: the wizard can save user's custom screws in holes.kcl per-project.

[pierremtb]

Slack context: https://kittycadworkspace.slack.com/archives/C06L2RHP9SL/p1750364920356969?thread_ts=1750363654.828379&channel=C06L2RHP9SL&message_ts=1750364920.356969

As described by @nickmccleery

At some point it basically needs configuration of:

• Diameter (ideally from a catalogue)
• Thread spec
• Bottom type (flat vs. specified drill point angle)
• Chamfer/countersink option.Counterbore option.
  The hole diameter option should probably be driven by thread types (UNF, UNC, BSP, NPT, vanilla metric) and ISO fits tables

Example youtube video from @jamwaffles: https://www.youtube.com/watch?v=ObLRU6Ouyl0

This likely require work from:

• Engine (unless we want KCL to have the library of holes and we can use existing CSG APIs?)
• KCL
• Frontend

[jamwaffles]

Alongside the MasterCAM video above, here are a couple of UI examples for inspiration. First from Fusion (pretty clean):

And FreeCAD (typically obtuse OSS software UI 😁):

The FreeCAD Wiki page has some decent behavioural descriptions but I think whatever we do, we should be involving a MechE (even myself if you want someone who cosplays as one) in the final feature design.

[pierremtb]

Including a 3d preview draggable gizmo

[pierremtb]

Interestingly enough there doesn't seem to be any way to pick standard sizes in Fusion https://forums.autodesk.com/t5/fusion-360-ideastation-archived/standardized-hole-sizes/idi-p/6551056

[pierremtb]

Compared to the MasterCAM one in the video above which I really like too!

[jamwaffles]

Interestingly enough there doesn't seem to be any way to pick standard sizes in Fusion

That thread is pretty old now. IIRC from using Fusion yonks ago you have to select one of the hole and/or tap type options to get a standard sizes dropdown.

[pierremtb]

@jamwaffles Ok thanks I probably missed it!

[adamchalmers]

Redacted: original comment copied from #7633 was moved to the top post as source of truth.

[adamchalmers]

How about this?

/// Defines a hole, but doesn't actually cut it from anything.
fn holeProfile(top, middle, bottom): HoleProfile {}

/// These all cut your hole(s) into the solid. Return the modified solid.
fn hole         (@solid, face, holeProfile): Solid {}
fn holesLinear  (@solid, face, holeProfile, instances, distance, axis): Solid {}
fn holesCircular(@solid, face, holeProfile, center, instances, arcDegrees?, rotateDuplicates?): Solid {}

hole is equivalent to holeProfile |> revolve |> subtract.
holesLinear is basically equivalent to holeProfile |> revolve |> patternLinear |> subtract.

[pierremtb]

Oh thanks I think I like this better yes!

Related: Should we allow users to specify sketch points as input hole locations? (like I was doing in trad cad earlier with a circle from which I was selecting the center)? That might have to wait for sketch regions I guess. Reason I'm saying this is because we could pass an array of those, just like we can pass an array of profiles to all sweeps today which generates patterns in a way too

[adamchalmers]

Oh yeah I forgot about the position. So how about this?

/// Defines a hole, but doesn't actually cut it from anything.
fn holeProfile(top, middle, bottom): HoleProfile {}

/// These all cut your hole(s) into the solid. Return the modified solid.
fn hole         (@solid, face, holeProfile, point): Solid {}
fn holesLinear  (@solid, face, holeProfile, startPoint, instances, distance, axis): Solid {}
fn holesCircular(@solid, face, holeProfile, center, instances, arcDegrees?, rotateDuplicates?): Solid {}

IMO we should probably reuse our pattern syntax, rather than making users do the calculations themselves.

[pierremtb]

Yeah that's good to get started I think. I do think there will be use cases leveraging the sketch constraint system once we have it to position those but that should not a blocker for now

[adamchalmers]

Great. Updated the spec.

[pierremtb]

@adamchalmers Re:

Delivery plan:
Phase 1: the KCL functions for top/bottom/body/hole. The basic wizard which lets users set those values via a text input.
Phase 2: the KCL library with standard holes. Wizard adds drop-down list to pick from these standards.
Phase 3: the wizard can save user's custom screws in holes.kcl per-project.

I think this is a great breakdown. Once we agree on this I'll probably create dedicated discussions for Phase 2 and Phase 3.

[nrc]

Saving a hole will create a holes.kcl in the top level dir of the project, and the wizard will check for this file and load its holes for users to choose from.

This is kind of a new category of things for ZMA - having a distinguished module for things. It's not a very scalable or customisable solution though - it doesn't allow the user to have multiple modules for holes, or holes in a sub-module if we support them in the future, or to have a holes file called something else (perhaps there is a naming convention in their project which doesn't work here). It also doesn't allow easy merging of projects or parts of projects.

I'm not sure what exactly a hole is in KCL yet, but assuming it's a function or type, they could be annotated with an attribute, e.g., @(wizard = hole).

[adamchalmers]

I was thinking that if we kept them in their own module, it'd be easy for the hole wizard UI to find them. There's no real need for it, I just thought it would be convenient for users to read and for the hole wizard to find. We could definitely make it customizable later. There could be a setting to control where holes are saved.

If we create the holes in whatever file the user has open at the time (with an annotation), then we'd need the hole wizard to add an export to the front of it and to build an import statement for it later, and to search the whole project for holes (possibly caching the search to reuse later).

[nrc]

KCL's standard library won't contain these, they will be available in an external library, maintained by Zoo

There is a plan for external libraries, but I'm not sure how it should be prioritised. At the moment, I've got it very much a lower priority than the sketch mode changes, so that's probably a 6-12 month timescale. If we want this done sooner for the holes work or otherwise, please let me know!

[adamchalmers]

Yes, this is the most controversial part of the design I think. As an alternative, we could just provide a .kcl file to download from GitHub without any special library support. We could even have a UI command to fetch this file (similar to how the frontend can create a new KCL project from the KCL samples -- both approaches download some static KCL from Zoo and insert them into the user's filesystem).

[nrc]

Do we ever need the Hole object rather than the hole profile? It seems like an unnecessary extra step to have to call holeProfile when hole could just return a profile. But actually, maybe that is what is intended? The example and API definition seem to have different definitions of the hole function.

[adamchalmers]

One question around "holeProfile is just a sketch" is, what plane should the sketch be on? Sketches are always on a plane. But when you define the hole, you don't really include the surface you intend to cut it out from. You're just defining a hole profile in the abstract. It should be compatible with many different faces/solids, i.e. many different planes.

Jon and I chatted and he suggested we basically define the hole on a "conventional plane", e.g. global XY. Then when the hole is actually cut out, via the hole(@solid, face, ...) function, the hole function finds the plane of the solid's face (call this the target plane), and rotates the hole profile from the conventional plane onto the target plane. Then cuts.

This would be neat, it lets us separate the abstract definition of a hole vs. the cutting of a hole from a particular surface. I'm not really sure of the math necessary to do the rotation though.

[jamwaffles]

Jon's suggestion sounds pretty good! I can see it being easier to manage custom hole profiles if each one in a library/module is just a sketch at the origin. Will the transform work for offset planes and curved surfaces? For example, I just sneezed this shaft collar out in FreeCAD with a custom depth counterbore where the hole top is referenced from the (yellow) reference plane:

[adamchalmers]

My current prototype works just fine with offset planes, but not curved surfaces. Right now it only works with planar surfaces.

When cutting into a curved surface, how do you know which way is "down" into the solid? Would the user just choose the direction?

[jamwaffles]

Now I think about it, I'm not sure curved surfaces are very useful. Personally I'd probably create a plane and sketch the locations on that, although some CAD programs might let you click a point and orient the hole opposite to the surface normal at that point. @nickmccleery and other MEs, thoughts? Right now I reckion just supporting planar surfaces is gonna be fine for 95% of use cases.

Fusion has a little icon to the right of the distance behaviour to swap the hole direction:

FreeCAD has a "reversed" option:

Most of the time they can figure out the right direction but sometimes can't. In our case, that could be a plane with a normal that's pointing the wrong way, for example.

[adamchalmers]

OK great, I was just thinking today, "gosh, my heuristic for telling which way "down into the surface" points is pretty good, but what if it gets something wrong? Should we have a box for "flip direction"? Isn't that pretty janky?"

But if other CAD suites do it too, we should be OK.

[jamwaffles]

This has kind of turned into a future features wishlist so apologies for that, but I thought I'd post this list anyway in case it's useful.

1. Is it possible to pattern holes using the "standard" patterning functionality? It's not clear to me why hole-specific patterning ops are required.

2. Minor name suggestion fn drilled(drillPoint: number(Angle)): HoleBottom {} -> fn drilled(tipAngle: number(Angle)): HoleBottom {}

3. Threads are not supported for now, but have there been any thoughts to how we add them to the API? Would we introduce another parameter to hole e.g. fn holeProfile(top, middle, bottom, thread): HoleProfile {}? I don't know if the intent was to repurpose bottom to add threads but IMO they're certainly two different things if so.

4. More future consideration: most if not all fastener standards include specified thread lengths for a given length of fastener, for example an M12 DIN 4014 bolt under 125mm long has a 30mm thread length at the end of the bolt. Other standards thread the entire bolt length.

5. It's best practice to chamfer the bottom of the counterbore where it meets the rest of the hole, as bolt heads never join the shank with a perfect right angle so need some clearance for that radius. I'd love a way to specify this chamfer separately from the normal chamfer tool (which should be used for hole top/bottom) as it's more part of the hole profile than a "normal" chamfer.

   

[adamchalmers]

Thanks James, these are all helpful.

1. Yes, I chatted with Jon today and we figured out how to make normal patterns work. I'll update the spec shortly.
2. Done
3. Yes, another param sounds good. We'd add another thread: HoleThread param to fn holeProfile, and a new fn holeThread where you can set params, e.g. the thread position, length, thickness, whatever.
4. Sounds good, I'll add a chamfer param to the counterbore function.

[nickmccleery]

Just to add more colour here, mostly on nomenclature:

Drills

ISO 5419 (this too) refers to the drill tip angle specifically as point angle. I think ideally we should refer to the drill tip with this.

Fusion's naming system adopts Tip Angle, though I think this is a little confusing; they use Drill Point to differentiate between bottom types (Flat or Angle), but who says your hole has to be made with a drill? I think that's up to the machinist, and Autodesk are sort of putting words in their mouth there.

Countersinks, Counterbores, and Counterdrills

I don't think it makes sense for a hole to have a 'top'. Existing CAD/CAM tools adopt the following:

• CATIA: Hole Type, options: Counterbored, Countersunk, Counterdrilled.
• Fusion: Hole Type, options: Simple, Counterbore, Countersink.
• Onshape: doesn't give a name for the option: Simple, Counterbore, Countersink.
• FreeCAD: Hole Type, options: countersink, counterbore, straight
• DraftSight: Hole Type, kinda groups a bunch of things together, options: Counterbore, Countersink, Thru Hole, Tap, Slot.

See:

• http://catiadoc.free.fr/online/fm1ug_C2/fm1ugbt0111.htm
• https://help.autodesk.com/view/fusion360/ENU/?guid=GUID-0DFCBD4F-5130-4CC9-B1A7-23C88147752A
• https://forum.onshape.com/discussion/21338/countersunk-holes
• https://wiki.freecad.org/PartDesign_Hole
• https://help.solidworks.com/2019/English/DraftSight/DraftSightSW/HLPID_HOLE_COUNTERSINK.htm

Extension

Hole 'body' also sounds a bit odd to me. I think that should be something like depth, distance, or extension.

Existing tools adopt the following:

• CATIA: Extension
• Onshape: Termination
• FreeCAD: just diameter and depth.

Recommendations

I think we should modify the way holeProfile is called, removing top and body as parameters.

• Countersink, counterbore, and counterdrill options should be driven via a type parameter.
  • For example: type = simple(), type=counterbored(...), type=countersunk(...).
• Diameter and depth can be simple parameters; they're 'first class citizen' properties of the hole itself.
  • For example: diameter=4.2, depth=4mm.
  • Requires some thinking on how we deal with through holes and any scenario where someone wants to specify depth to point tip vs. end of full diameter section.

I have a weak preference for the bottom related parameterisation changing to match the ISO standard, so pointAngle instead of tipAngle, but appreciate that there is precedent for tipAngle via Fusion.

[adamchalmers]

Requires some thinking on how we deal with through holes and any scenario where someone wants to specify depth to point tip vs. end of full diameter section.

This is exactly why I'd like these to be in their own arg, it seems very likely that we'll add support for a different kind of end later, and it should be clear that they're mutually exclusive. Other than that, sure, happy to do all the renames you suggested.

[pierremtb]

@nickmccleery Just to add color as well, MasterCAM uses 'Hole Style' instead of 'Hole Type' which might help us steering out of 'type' to avoid clashes in programming languages?

[nickmccleery]

We chatted this through on Slack, but I like 'Hole Style' a lot, very happy with that.

What are we thinking on the arg front for blind holes vs. thru etc.? Of the things that bubble into my mind, I think exposing utility/helper functions feels kinda cluttered and requires the user to remember more (e.g. depth=blind(4mm) and depth=thru() or whatever), but also think passing in magic strings or similar is in the same boat (e.g. depthType="blind", depth=4mm).

Could we maybe use like mutually exclusive depth and to/upto or something? Depth taking a numeric value makes sense to me, with a 'to' arg taking a reference to a plane or surface?