Engineering Drawings

[pierremtb]

Important

This is currently in planning, see discussion below.

Milestone(s) for issue tracking: to be created in the relevant repos
Milestone lead: @alteous

---

Slack context: https://kittycadworkspace.slack.com/archives/C04KFV6NKL0/p1752609350744289
Internal discussion: https://kittycadworkspace.slack.com/archives/C09687PREKF

Initial meeting invite sent by @alteous for 2025-07-15

Requirements

1. Ability to switch between 'drawing mode' and 'non-drawing' mode

• The exact method for doing this is left to the team to decide.
• Drawing mode is comparable to sketch mode but operates on drawing entities rather than sketch entities.
• Actions performed by the user update KCL specific to the drawing entities.

2. Drawing toolbar

• When in drawing mode, the user needs to be able to perform from the toolbar:
  • Add view
  • Add line
  • Add circle/arc
  • Add text
  • Add dimension
  • Update drawing

3. KCL generation and regeneration

• The design studio will receive events when drawing entities are updated by the engine and will either generate or amend generated KCL accordingly.

4. Export functionality

• When in drawing mode, the export feature should list 2D formats (e.g., DXF) rather than 3D formats.

Out of scope

1. Multiple page drawings. The implementation may reasonably anticipate this as a future requirement.
2. Sectional views.
3. Constraints on sketch elements.
4. Image import.
5. Foreign drawing file import.

API

The drawing API will include a subset of the sketch API, notably:

• angled*
• arc
• circle
• circleThreePoint
• line
• rectangle
• segAng
• segEnd*
• segStart*
• tangentToEnd
• tangentialArc
• xLine
• yLine

New functions will be needed to represent drawing-specific functionality.

/// Drawing definition and container.
fn drawing(
    /// The physical page size, e.g., A3.
    pageSize: ?,
    /// The document title.
    title: string,
): Drawing {}

/// Add a view to a drawing container.
fn add(
    /// Container.
    @drawing: Drawing,
    /// Item to be added to the drawing.
    item: *,
    /// Placement of the item.
    at: Placement,
): Drawing {}

/// View definition and container. The drawing elements associated with a view are intended to be generated and therefore not to be edited by the user. Nevertheless, the prevent the user from editing generated code for a view. We should anticipate users customising the names of generated tags, for example.
fn view(
    /// The part to be drawn.
    part: Part,
    /// Optional: real-world drawing scale. It is the user's responsibility to ensure this matches any directions on the drawing.
    scale: number,

    /// One of the following optional parameters must be set to define the viewpoint for the view:

    /// Sets the viewpoint will be set to a named view.
    name: string,
    /// Sets the viewpoint will be normal to a face.
    face: ?,
): View {}

/// Group definition and container. A group serves a similar purpose to a view but contains entirely user-defined drawing elements.
fn group(): Group {}

/// Drawing dimension.
fn dimension(
    /// The drawing element to be dimensioned. Expect this to be a tagged item.
    @item: ?,
    /// Placement of the dimension.
    at: Placement,
): Dimension

Views are generated by the engine. The app will request updates as required and amend any generated KCL code. The generated code for a view might look something like this:

view001 = view(part, name = "front")
    // Generated code. Edit with caution.
    |> line(start = [0.0, 1.0], end = [0.0, 0.0], tag = $line001)
    ...

The user will be able to dimension these generated drawing elements using the tags:

dimension(line001, at = ...)

A more complete example might look like this:

import part from "main.kcl"

// User code (the following line only):
view001 = view(part,  face = $face001)
    // Generated code. Edit with caution.
    |> line([1.0, 0.0], tag = $line001)
    |> line([0.0, 1.0], tag = $line002)
    |> line([-1.0, 0.0], tag = $line003)
    |> line([0.0, -1.0], tag = $line004)
    |> moveTo([0.5, 0.5])
    |> circle(radius = 0.5, tag = $circle001)

view002 = view(name = "front", scale = 2.0)
	// (similarly generated code)
	...

/// User code follows:
dimension(line001)
dimension(line002)

group001 = group() |> text("Hello world!")

drawing(pageSize = A4, title = "Example") |> add(view001)

[jamwaffles]

1. Why does the user need to be able to add arbitrary shapes? This isn't something I've seen in other drawing tools but my experience is limited. If this is to allow the user to add arbitrary annotations, I reckon that could be left out for now.

2. Can you give some examples of what the dimension placement parameters would look like in the code? I can't quite envisage what this looks like in a non-Point n Click environment. I'm interested to know how both linear and angle dimensions are placed.

   For angles, how do I place the arc? In other tools, I'd be able to click and drag it closer/further away from the centre. In KCL, is it defined as a distance relative to the centre point? How would I configure it to be an internal/external angle in KCL?

   

   Likewise, how would I move this dimension horizontally, i.e. closer to/farther away from the source line it's dimensioning?

   

3. We need to be careful about dimension() as this is going to conflict with the functionality of the same name in the sketch constraints work. This might be a wider discussion around namespacing/workbenches/modes/whatever you want to call them. CAM is gonna need its own workbench too.

4. I've often seen the lines of the actual part in the drawing be slightly thicker than everything else. Doesn't have to be for MVP but is this easy enough to do with some appearance fiddling?

5. Having the KCL for the base drawing be straight up editable with a warning that it's machine generated code doesn't sit well with me. Could it be hidden somehow? Made un-editable? Put into a module? Code folded in the UI by default? I can see a lot of less code-minded CAD users ignoring/not seeing the warning and either breaking the drawing or becoming very unhappy when some manual tweaks are blastoed by an automatic recompute from the model. My ideal usage for ZDS is to treat KCL as the implementation details of our file format I don't have to care about and PnC everything so this is quite a biased, narrow viewpoint.

6. In PnC, will the added dimension automatically figure out if the user meant a linear or angular distance based on the selection? MVP could be individual buttons in the UI as that's a lot easier to code for.