Introducing the drawing API

[sgenoud]

I have been iterating a bit on issues with the sketch API, there are things that would be nice to be able to do that would be difficult to implement with sketches

• You cannot translate, rotate or scale them
• It is not possible to do boolean operations on them (let's fuse this circle with this rounded rectangle)
• We cannot export them directly (a sketch is a wire plus some infomation on how it was created.
• It is difficult to sketch on anything else than a plane

As you can guess, "Drawings" and the draw solve all these issues.

For instance:

const main = ({ draw, drawRoundedRectangle }) => {
  const shape1 = draw()
    .halfEllipse(0, 20, 5)
    .smoothSpline(25, -3)
    .smoothSpline(20, 8)
    .smoothSpline(-20, -30, -90)
    .smoothSplineTo([0, 0])
    .close()
    .translate(-15, -10);

  const shape2 = drawRoundedRectangle(20, 30);

  return shape1.fuse(shape2);
};

Note that the drawing API is 2D only (and lives in a 2D plane). If you want to do something in 3D, you will need to sketch your drawing, for instance in a plane:

const main = ({ draw, drawRoundedRectangle }) => {
  const shape1 = draw()
    .halfEllipse(0, 20, 5)
    .smoothSpline(25, -3)
    .smoothSpline(20, 8)
    .smoothSpline(-20, -30, -90)
    .smoothSplineTo([0, 0])
    .close()
    .translate(-15, -10);

  const shape2 = drawRoundedRectangle(20, 30, 5);

  return shape1.fuse(shape2).sketchOnPlane("XY").extrude(5);
};

I have implemented the "canned" or pre-baked sketches as drawings as well, so that one can do stuff more quickly.

This is an experiment - tell me if you prefer to stick with the Sketcher instead of creating a drawing!

There is a little bit of (autogenerated, so not so great) documentation on:

• how to create a drawing
• the methods on the drawing pen (which is the equivalent of the sketcher)
• what you can do with a drawing

[Irev-Dev]

Nice to see iteration on the 2D aspects.

I always thought that 2D is a really important primitive for code cad and thought it's lacking in most of the alternatives. Keep it up.

[raydeleu]

The idea of this concept to draw is very helpful, especially for persons that are used to rotate, scale, translate parts of their 2D drawing and to combine shapes. It could support a more ad-hoc way of defining the drawing compared to figuring out the position of each point in advance.

I have some hesitation towards the need for a plane to place the 2D drawing into the 3D space. If there is a plane that can be deduced from an existing part this is totally fine. But if you want to place a number of cross sections into space to create a loft, for example to create a shape like an aircraft fuselage I would think that it is a faster approach to choose a drawing plane (as in the current approach for the Sketch) and allow a translate/rotate/scale for the 2D shape directly. You could then for example take a cross section, scale it and move it to the next "station line".

source: https://ftforumx2.s3.amazonaws.com/2020/10/328260_1c4a5e63c68d39c95eae195a539e917d.jpg

Creating a plane for each station and then placing a sketch will probably result in more code.

[raydeleu]

In the code below I compared several approaches to draw sketches along the length of a strange shape. For me the first method is the most intuitive, as all rotations and translations are done in the same way as for any shape. Strangely enough this does seem to work only for the sketchCircle, so I guess in my earlier experiments I was just lucky that I chose this shape.

I was confused that the translation in 3D requires a point [x,y,z], whereas the translation in 2D requires the values x,y (without the square brackets). I also found it confusing that the indication "XZ",80 moves the plane in the negative Y direction. Finally I have not yet found a simpler approach to tilt the plane than using the verbose approach shown as "Method 2" in de example code.

const main = ({ draw, 
                drawRoundedRectangle,
                sketchRoundedRectangle,
                sketchFaceOffset,
                sketchCircle, 
                Plane,
                Vector  }) => 
{
    // METHOD 1: using the workaround with sketchFaceOffset 
    //          note that this does not work with sketchRectangle or sketchRoundedRectangle
    let shape0 = sketchCircle(2).face().rotate(60,[0,0,0],[1,0,0]).translate([0,40,-8])
    shape0 = sketchFaceOffset(shape0 , 0 );     
        
    // METHOD 2: Current procedure to draw a sketch of a circle on a tilted plane 
    const planeAxis = new Vector([0, 1, 0]).rotate(-20, [0, 0, 0], [1, 0, 0]);
    const planeCenter = new Vector([0, 20, 5]).rotate(
      -20,
      [0, 0, 0],
      [1, 0, 0]
    );
    const sectionPlane = new Plane(planeCenter, null, planeAxis);
  
    let shape1 = sketchRoundedRectangle(15,15,7,{ plane: sectionPlane });
  
    // METHOD 3: using the draw API 
    const shape2 = drawRoundedRectangle(20, 30, 5).sketchOnPlane("XZ");
    const shape3 = drawRoundedRectangle(25, 30, 5).translate(0,-3).sketchOnPlane("XZ", 30);
    const shape4 = drawRoundedRectangle(20, 20, 8)
        .rotate(45)
        .sketchOnPlane("XZ", 50);
    const shape5 = drawRoundedRectangle(10, 10, 4).rotate(45).translate(0,2).sketchOnPlane("XZ",80);

    
    let fuselage = shape0.loftWith([shape1,shape2, shape3, shape4,shape5], { ruled: true });

    return [{shape:fuselage}]
};

[sgenoud]

I am currently working on the plane modification API. What would you think of something like:

const main = ({ drawRoundedRectangle, makePlane }) => {
  const rect = drawRoundedRectangle(60, 20, 5);

  return [
    {
      shape: rect.sketchOnPlane(makePlane("XZ").translateTo([-10, -60, 30])),
      color: "orange",
    },
    {
      shape: rect.sketchOnPlane(
        makePlane("XZ").translateTo([-10, -60, 30]).pivot(-30, "X")
      ),
      color: "purple",
    },
    {
      shape: rect.sketchOnPlane(
        makePlane("XZ")
          .translateTo([-10, -60, 29])
          .pivot(-30, "X")
          .rotate2DAxes(45)
      ),
      color: "steelblue",
    },
  ];
};

This is in progress work (so not yet working on the visualiser). Is it intuitive for your?

[raydeleu]

Looking at your code I assume that .pivot(-30,"X") rotates the wire/drawing around the local x-axis, making it independent of the translation that you applied before. I think that is really intuitive. The local axes of the shape would then have the origin on the [0,0] position used during the creation of the drawing?

Rotating around the normal vector with .rotate2Daxes(45) is also intuitive, although you might question the need when you can also rotate the drawing itself with a simple .rotate(45). Still, bringing all placement parameters to the same location of the code is practical, so the designer does not need to jump around in the code to adjust the placement of a wire. During the building process for the Plunge watering can I had exactly that issue, where I had a rough idea how I could model the shape and used trial and error to find the correct location of the wires.

[sgenoud]

rotates the wire/drawing around the local x-axis, making it independent of the translation that you applied before. I think that is really intuitive.

It rotates the direction of the plan (according to the global axes), but around its origin. So it is independant of the translation.

Anyway, I have updated the library and the visualiser so you can play with it. For instance with something like that

const main = ({ drawRoundedRectangle, makePlane }) => {
  const rect = drawRoundedRectangle(60, 20, 5);

  const p1 = makePlane("XZ").translateTo([-10, -60, 30]);
  const p2 = p1.pivot(-30, "X");
  const p3 = p2.translateZ(-1).rotate2DAxes(45);

  return [
    {
      shape: rect.sketchOnPlane(p1),
      color: "DarkGoldenrod",
    },
    {
      shape: rect.sketchOnPlane(p2),
      color: "purple",
      opacity: 0.5,
    },
    {
      shape: rect.sketchOnPlane(p3),
      color: "steelblue",
    },
  ];
};

[raydeleu]

Thank you for adding the option for changing the opacity in the Visualiser. I immediately tested it on my "Plunge" project, see #35 (comment).

[raydeleu]

I added some explanation for the drawing API to the Quick Reference. I noticed that for a drawing it is sufficient to call the function draw() without the keyword new. I assume that the creation of a new object for which the drawing methods are defined is embedded in the draw() function. Wouldn't it make sense to use a consistent approach for both objects, i.e. either have

• functions draw() and sketch() or
• use constructors new Sketcher() and new Drawing()?

I can imagine that the second approach is more logical for programmers as it indicates that you can apply methods to this object.

[lf94]

Yep, my vote is on the latter. A drawing is being created. draw() implies some sort of modification. So creating data makes more sense than computation (new X())

[sgenoud]

I do not like the object creation API - it exposes too much of what is going on and is a bit unnecessary. You can use an object for drawing, it is new DrawingPen() - which is what draw() does behind the scene.

I never did it for sketch() - because the verb and the noun are the same and could be confusing. What about sketchOnPlane (for consistency with the drawing method?

[raydeleu]

I would not be confused by sketch() and draw() as long as the Sketcher and DrawingPen are hidden somewhere in the code.

I have added an explanation of the difference between the two in the quick reference, but still wonder if it is clear. I would think that a drawing is always preferable as it is more versatile. What is your argumentation for keeping both? Sometimes less is more?

[sgenoud]

My idea would be to phase out the Sketcher (behind the scene sketches are still there though). I was thinking of different ways I could have sketching be more than drawing:

• support for moving the plane between segment of curve (not sure how that would be useful, but it sounds cool)
• you mentionned the fact that you like to have the exact point you are going to sketch to (to reference for later fillet). This is not possible to do with drawing.

My plan was to introduce drawing, see if there is no big flaw I did not anticipate, rewrite the doc and examplesi to mention drawing instead of sketching and then mark the Sketcher as deprecated.

Part of the reason I am a bit afraid of going full Drawing is that the sketcher is a (partial) copy of what is done in cad query - it is a well known quantity. Drawing is my own thing which may have dragons hiding in the shadows.

[raydeleu]

"you mentionned the fact that you like to have the exact point you are going to sketch to (to reference for later fillet). This is not possible to do with drawing."

You have a good memory! This was a remark I made related to the advantage of using absolute coordinates instead of relative coordinates. In the following handmade sketch I have illustrated my thinking:

If I would have started the sketch or drawing by moving to [3,2] and then create each next segment using relative movement only, it would be difficult to reference point p3 at a later stage. Using my self-made functions to use relative coordinates to calculate the absolute position of p1 to p5, I would be able to access this position later.

The difficulty is that when you place the drawing or sketch on a plane, you have to transform the 2D coordinate into a 3D coordinate. In my example this is very simple as the drawing plane is placed on the XY-plane, so the 2D drawing coordinate [x,y] is transformed in the 3D coordinate [x,y,0]. When I now extrude the drawing or sketch is it easy to identify the edge that is aligned with the Z-axis and contains p3. If I would choose a position halfway of the extrusion with height h a single point [x,y,h/2] could uniquely identify the edge.

I would think that this approach is equally valid for sketches and drawings. Of course things become much more difficult if you want to have a plane that is angled relative to the carthesian orientations. But also here I struggle to see the difference between a sketch and a drawing.

[paulftw]

I've been using the new API and ran into a small inconsistency: lineTo takes one vector argument, but translate takes x and y as two arguments.
A case can be made that translate is part of an entirely different API, however Solid.translate also accepts a vector.

I understand that in simpler use cases two separate values are fewer characters to type, but in my experience these shortcuts always start causing problems at a later stage, as a codebase grows.

Middle ground would be detecting argument type at runtime, but that can sometimes mask bugs in the user's code.

[raydeleu]

See also issue #41
The initial idea is that an absolute point, i.e. with reference to the origin [0,0] is written as a vector [x,y], whereas a relative movement is written as dx,dy. As a drawing is "free floating" until it is placed on a plane with a certain reference point, the argumentation could be that a translate of a drawing is always a relative movement.

[paulftw]

Thanks, your explanation makes a lot of sense - it’s an effort to make difference in behavior (absolute vs relative) more explicit.
Maybe I’m just stubbornly defending my habits, but I still see a few problems:

• Solid.translate still takes a vector - that suggests that 2d and 3D translate are different. I’ve used both and it’s hard for me to come up with a strong enough explanation, other new users may struggle too.
• most other frameworks don’t make this distinction, even if this is a world changing improvement, users with prior experience will need time to adjust
• vector in math is a relative thing, if there’s a function in the API that calculates sum of vectors or combines two transformations, which convention should it use? Which convention similar functions in other frameworks use? (I’m on the phone, so too lazy to check if vectors or points have .sum/.add sorry, if they don’t one day something in replicas most likely will).
• There’s at least one other person who was frustrated enough to raise an issue ;)
• Argument that is most significant to me personally is unfortunately hard to explain, but I’ll try: when a user types: foo.translate(dx, dy) what code do dx and dy come from? For a first draft of a model, or for a CS beginner it’ll be hard coded constants, but as the sketch gets more complex, parts of it get refactored into subroutines, dx and dy will get computed. And in complex programs computing both as a vector leads to a cleaner code.

tldr I see this as a choice between two beginner-friendly mental models vs one harder but more “formal” mental model. I think less is more and unless threejs or webgl make the same distinction it’ll feel gimmicky to every new user and every attempt to integrate replicad with another library.
(Again, I haven’t checked, if threejs does something like that - point me I. The right direction and I’ll shut up).

Anyway, I really appreciate and value all the work that you, @sgenoud has put into replicad, and most importantly I don’t want to be that guy who goes on and on about a tiny nuance.
I realize that it may be hard to change, it may imply breaking changes in the api, etc
Maybe you just like it this way and that’s fine too.
So I won’t argue further :)

[sgenoud]

Solid.translate still takes a vector - that suggests that 2d and 3D translate are different. I’ve used both and it’s hard for me to come up with a strong enough explanation, other new users may struggle too.

Yes, I want to make it behave like in 2D - this is a leftover from my first pass.

Note that there is some work with the mirror API as well (as it mixes plane and point mirrors) and is configured differently in 2D and 3D.

vector in math is a relative thing, if there’s a function in the API that calculates sum of vectors or combines two transformations, which convention should it use? Which convention similar functions in other frameworks use?

There is some of these functions (but the original API was not deeply thought out).

With the sketching/drawing APIs my aim has been to do what UIs do, let user think about the structure of the model and not not geometry (math) behind it.

I have a conviction that math notations and conventions are awful to learn. Every term and notation is overloaded. After the heavy math during my degree in physics, learning to code and the culture of making APIs that are easy to understand instead of beautiful to prove was a breath of fresh air.

There’s at least one other person who was frustrated enough to raise an issue ;)

There is two now, so it feels like I might need to add support for translation vector (even if I will consider it a bad practice).

I realize that it may be hard to change, it may imply breaking changes in the api, etc

What would you think of a translateTo method (by symmetry with the lineTo method)

[paulftw]

Thanks for explaining your broader opinion about math conventions. I'm in the "beautiful to prove" camp but I know many others who struggled with those abstractions.

What would you think of a translateTo method (by symmetry with the lineTo method)

translateTo is ok, but its name implies wiping out previous transformation and replacing it with absolute values. I'm not sure that will be used much.

Let's consider I'm not very thoughtful coder and I'm generating a brick wall in Replicad.
I have a starting point, direction vector, and in a loop I call a brick()function and translate its return into place.
Then I decide to add random gaps between the bricks as a metaphor for imperfection of this world.
I change my brick() function to sometimes build shorter bricks with a random translation. I imagine that when a brick is shorter it'll have random small windows on both sides.
With translate it just works and the story ends here. But with translateTo that random shift will get lost when parent does translateTo.
It's an artificial example, but I think it illustrates how most code is written.

Speaking of vectors vs multiple arguments, since we've decided to stick with the latter I think most important thing is to hold user's hand when we know they may make a mistake:

• two number arguments - it just works
• two arguments and either one is not a number - invalid input exception
• one argument and it's a vector - either process it as a tuple, making sure it has exactly 2 (or 3) numbers, or stay true to our beliefs and throw an exception

That way users won't run into most frustrating engineer's adventure (and my story) of "I just assumed it should be a vector, and spent half hour looking for a bug elsewhere".

[raydeleu]

Or just look at my Replicad Quick Reference 😃 (search github for ReplicadManual)

[sgenoud]

https://replicad.xyz/docs/api/classes/Drawing/#translate