Tags for entities

[Irev-Dev]

There's a need to tag entities in the language to refer to them later, currently, that's done with strings so

const part001 = startSketchAt([-1.2, 4.83])
|> line([2.8, 0], %)
|> angledLine([45, 3.09], %)

might become

const part001 = startSketchAt([-1.2, 4.83])
|> line({ to: [2.8, 0], tag: 'seg01' }, %)
|> angledLine([45, segLen('seg01', %)], %)

There are a number of problems with this

• It's just an arbitrary sequence of characters, it can't really be part of static analysis, miss-spelling would cause segLen('sEg01', %) to fail.
• Someone could put the string in a variable, but it would be outside the pipe and so very ugly with multiple tags and still nothing stopping two tags from conflicting (same string without the user realising)
• Maybe we make some easy way of accessing the tag off the pipe object segLen(%$seg01, %). $ is arbitrary but also a bit weird, maybe .. might be a better convention? %..seg01, maybe also weird that seg01 starts its life as what looks like a string and then changes to something that behaves more like a key.
• Also with the transformation from line([2.8, 0], %) -> line({ to: [2.8, 0], tag: 'seg01' }, %) you can see that I'm trying to keep the line function to always taking two params, and adding in more optional params by changing the first param to a key-value pair, which in itself is kind of ugly.

With all of that said maybe attributes could work as a way of adding tags that's still compatible with pipeExpressions or not

const part001 = startSketchAt([-1.2, 4.83])
#[tag=seg01]
|> line([2.8, 0], %)
|> angledLine([45, segLen(%..seg01, %)], %)

And maybe there's a possibility of this having this part of the typing system i.e.

const part001 = startSketchAt([-1.2, 4.83])
|> line([2.8, 0], %)
|> angledLine([45, segLen(%..seg01, %)], %) // <- error trying to access a non-existant tag

It would know that the tag seg01 doesn't exist ahead of execution/calls to the engine?

This goes against something I said in #2, that attributes can be used for metadata not associated with modelling, but I think I can live with that.

[adamchalmers]

Yeah, I really like this idea!

One way to make it more ergonomic would be this convention: any constant implicitly has a default tag, which is the name of that constant. So if you left off the #[tag=seg01] from your example, it would use part001 as the tag.

BTW in all the API code I call the tag the "ID", so we should standardize so we don't go back and forth between tag and ID.

[adamchalmers]

Based on the discussion in #2 I think we're going to avoid attributes for now. But you can easily specify a part's tag via a keyword (or required positional) argument. I still like the idea that named constants would have default tags from their binding label.

[Irev-Dev]

The intention I had with the example the tag was for the line was for the line call, so part001 wouldn't make sense in this case. Taging the line would be used to fillet that edge after it was extruded or similar.

The default tag could still work but would be for the (sketch in this case) entity as a whole instead of something within.
But yeah if we're not going with attributes that's cool.

I'll close this one.

[adamchalmers]

Let's leave this open and discuss tags more generally. Thanks for explaining, and also for your blog post sketching out these ideas a few years ago.

I think tag should be an optional keyword argument in many kinds of function. At least, as you suggest, the lineTo functions.

Type

Current KCL docs don't have an arbitrary String type, rather, a Text type which is specifically for putting text into your designs. I suggest we have a new type which is Tag, which works kinda like Ruby symbols. Symbols are:

• No difference between name and contents. With strings, you can have different names and content e.g. user = "me"), but a symbol is just its name, there is no extra content. It's just user or just me, there's no difference between the name of the binding and the value being bound to the name.
• Unique (every symbol can be defined only once)
• Immutable (because there's no value being bound, there's no value to change)

Seems like a good fit for tags. When the AST runs semantic analysis, it can track every tag declaration and make sure every tag reference refers to a valid tag. This means we'll need a consistent way to recognize when tags are being set.

What can be tagged?

We want lines to be tagged, as in your sketch example. What about particular faces? E.g. if you want to sketch on top of a cylinder, do you tag the top face of the cylinder, and then reference that tag in your sketch? Josh explained to me yesterday that generally CAD either sketches on a plane or on a face of a solid. Maybe our sketches will start by taking a "what to sketch on" parameter, which is something like

enum WhatToSketchOn = X | Y | Z | Face(Tag)

i.e. you can sketch on any plane, or on some tagged face of a Solid3D.

Syntax proposal

WIP idea, so please criticize it.

To tag an entity, you pass a tag keyword argument into its constructor, e.g. |> lineTo(point(28, 0), %, tag = seg01). All keyword arguments are optional, so it doesn't change the type signature or force you to tag everything.

Functions which can refer to tags explicitly have a parameter of type tag somewhere, e.g.

// Function is declared like this
const angledLine = (angle: Angle, length: Literal(Distance) | LengthOf(Tag), start: Point) =>
    todo!()

Note that here I've declared an anonymous enum for the length parameter. You could change this to a properly declared enum type, but it seems convenient to have inline enum declaration for cases like this. Typescript has them, they seem useful, and if you ever need to reuse them elsewhere you can always factor them out into a proper, named type.

Here's how you'd actually invoke the function:

// Used like this
myLine1 = angledLine(Angle::d(45), Literal(Distance::cm(4)), (0,0))
// Or like this
myLine2 = angledLine(Angle::d(45), LengthOf(seg01), (0,0))

[franknoirot]

length: Literal(Distance) | LengthOf(Tag)

This might be nice for generated code, but I imagine it would be hard to remember as a learning designer/programmer that you have to include this kind of inline enum in the function declaration if you want to be able to refer to tagged values in your custom functions (sidenote: I do think we will likely see end-users refer to things like that as "custom" even though it's all kinda custom, just arbitrary code).

Might be a silly question, but does that inline enum need to be there? LengthOf(seg01) as it's being passed into angledLine() should resolve to a valid Literal(Distance) anyway if the compiler resolves that inner function call first, right?

[adamchalmers]

Oh yeah, your point is compelling and noble, I prefer your design!

…

On Tue, 18 July 2023, 11:14 am Frank Noirot, ***@***.***> wrote: length: Literal(Distance) | LengthOf(Tag) This might be nice for generated code, but I imagine it would be hard to remember as a learning designer/programmer that you have to include this kind of inline enum in the function declaration if you want to be able to refer to tagged values in your custom functions (sidenote: I do think we will likely see end-users refer to things like that as "custom" even though it's all kinda custom, just arbitrary code). Might be a silly question, but does that inline enum need to be there? LengthOf(seg01) as it's being passed into angledLine() should resolve to a valid Literal(Distance) anyway if the compiler resolves that inner function call first, right? — Reply to this email directly, view it on GitHub <#3 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABJIFYJMIC36MZH7JCJFD5LXQ2Y6LANCNFSM6AAAAAA2JYQC6I> . You are receiving this because you modified the open/close state.Message ID: ***@***.***>

[franknoirot]

Regarding the question of what can be tagged, I think any geometry can be:

• Point
• Line
• Plane / Face

To that end, I think it's worth thinking about the signature for functions like lengthOf(). My initial thought is this:

/// Find the length of Line given its Tag
const lengthOf = (Tag::Line -> Literal(Distance)) => 
    todo!()

So you couldn't pass in the Tag for a Point, because getting the length of a Point is nonsensical as far as I know. But I don't know if that Tag::Line syntax is right.

However I'm not sure how to enumerate which kinds of entity tags can be passed into a function; like are there functions that make sense for Points, Lines, Planes, and any other geometric entities I'm missing?

[adamchalmers]

The current language design has a few built-in traits e.g. number, comparable. We could add a new trait dimensional which is implemented by Solid2D, Solid3D, Path, PathSegment. Then you'd have functions like

const lengthOf = (shape: dimensional -> Distance) => todo!()
const heightOf = (shape: dimensional -> Distance) => todo!()

etc.

I don't know if "height" and "length" are meaningful concepts here because they kinda presuppose a view or frame of reference. How do users say that the 2x4 rectangle has length 2 depth 4 vs. depth 2, length 4?

[franknoirot]

I like the dimensional trait idea, but yeah that's a good point: I agree that length as it relates to height isn't meaningful for this, as they're both "lengths" just along different named axes.

I don't think there would be a heightOf() function, and lengthOf() would only refer to Lines, where there is no ambiguity about which dimension.

I'm beginning to think that we won't need a way to represent a function type signature that accepts more than one type of Tag.

[franknoirot]

Been giving this a think today. I don't love the idea of having to pass in an argument for tags for two reasons:

1. it's unclear to me if it's a universally-available named parameter or only available on certain kinds of functions
2. it provides no way for us to tag geometry that isn't directly created by the operation, but implicitly as a side-effect

I've written up my thoughts on tagging these implicitly-created pieces of geometry here:

Summary

We will need an affordance to tag pieces of geometry (Points, Lines, and Planes/Faces) that were implicitly created by an operation for reference to use later in KCL programs.

Problem Statement

In all CAD programs, it is possible to create a new sketch on a face created from an extrusion command. Here is a very basic example recorded in Onshape:
https://github.com/KittyCAD/kcl/assets/23481541/5d1b0fd0-f8c1-4312-9327-b37619b29d35

Extrusions implicitly create a number of new Faces and Lines within the model, as do other operations such as a Boolean Subtraction, Intersection, or Exclusion. Currently we have no way in KCL to represent these implicitly-created pieces of geometry.

Proposed Solution

Since there could be any number of new faces or lines created in such operations, I propose that we create a deterministic rule set for how they are indexed, something like:

Objects created implicitly by operations are indexed starting at 0 with the first index representing the element with the high maximum Z value, increasing to n. For any sets of implicitly-created elements with equal maximum Z bounds, they are indexed in ascending order according to the angle their first point makes with the positive X-axis about the Z-axis. For any further ties, they are ordered in ascending order by the distance of their first point from the origin...

...and so on until it is impossible to create a non-deterministic arrangement of implicit geometry. I believe my example above has some problems because if the object is rotated or translated, so I'd like people smarter than me to help find a deterministic way to index.

We index implicitly-created Faces and Lines using a rubric like the one above into separate lists. And we allow all geometry-creating functions to tag any of its sub-elements using a tagFace and tagEdge function that takes an index.

Code example

width = 10.cm
length = 5.cm
height = 12.cm

// Also showing a JS feature of matched named parameters  not needing "width = width"
box = startSketch(0, 0)
  |> rectangle(center = [0, 0], width, height = length) 
  |> extrude(height)

sketchingFace = box.tagFace(2)
roundedEdge = box.tagEdge(3)

knob = let (
    center = [length / 2, height / 2]
    radius = 3.mm
  ) in startSketch(sketchingFace)
  |> circle(center, radius)

fullPart = union(box, knob)

Conclusion

We should give every returned value from a geometry-creating function access to .tagFace(index) and .tagLine(index) methods, so that geometry both implicit and explicit can be represented and tagged for later use.

If we have more ergonomic or robust ways of indexing into the faces and lines I would love that, but as a product of codegen I don't see a huge usability issue with having it just be an index integer. Our compiler could give index out-of-bound error messages and so on if things change further up the dependency graph.

[Irev-Dev]

This is kind of why I think the base primitive should always be a segment,
Sorry I really don't like indexes sketchingFace = box.tagFace(2) strikes me as something we should avoid if we can.
It's going to make things harder to read, more arbitrary conventions that you will have to painfully learn slowly.

and not anything more abstract like a rectangle or a box because of this problem. By keeping segments, as the base, it means we can always come back to tagging them when a user wants to build on a face.

And btw, I don't think this then limits our UI/UX, as there's no reason why clicking a rectangle tool and dragging it on a sketch plane can't produce,

startLoop()
|> xLine(5, tag:'seg01', %)
|> yLine(4, tag:'seg01', %)
|> xLine(-segLen(%..seg01), %)
|> yLine(-segLen(%..seg02), %)