Rough lay-out for a quick reference for Replicad

[raydeleu]

As I frequently needed to dive into the source code or API description to determine how I could use Replicad, I started to collect all commands that I found into categories. Based on this I assembled a rough layout for a Quick Reference document. This could also be the start for a more extensive manual. Please feel free to comment if commands are missing or are placed in the wrong category. I have not figured out the behaviour of all functions yet. The commands to find Edges are still missing but will follow the same pattern as the commands to find Faces.

Replicad Quick Reference.pdf

This is the asciidoc source code for the Quick Reference document:

replicad-qrc.txt

I started a new repository to add the file as well.

https://github.com/raydeleu/ReplicadManual/blob/main/replicad-qrc.adoc

[sgenoud]

Thanks! I really like how you structured the flow!

I think we can also split the API into two levels of complexity - the make... functions tend to be lower level, closer to direct opencascade manipulations.

Typically everything having to do with understanding faces and wires should be though of another level of abstraction - actually I think you do not use them directly in the how tos you have done so far (but I might be wrong).

A notion that might be interesting to detail is the notion of plane - but there might be changes to be made on the API before it makes sense!

Would you be interested in adding the quick reference in the documentation? I can help you setup a section and tell you how to create with docusaurus.

[raydeleu]

I would certainly be willing to adapt the document to fit into the documentation. I had a short look at Docusaurus and if I understand it correctly it is based on relatively standard markdown syntax. For my own work I prefer asciidoc, as it allows me to download the files from Github and turn it into a nice pdf document. Things like section numbering, figure numbering and tables are a bit more complicated in Markdown as it is aimed mainly at web formatting instead of document formatting. But the two are quite similar, so it should be doable to translate from asciidoc to markdown and vice versa.

[raydeleu]

I updated the flow structure with your comments @sgenoud and started with some cleanup in the rest of the document. The update is here:

https://github.com/raydeleu/ReplicadManual/blob/main/replicad-qrc.adoc

[sgenoud]

This is great! I really like the image to explain what the different line actions do! Do you use powerpoint to generate them (a vector drawing tool like Inkscape would be able to export something in SVG)?

You probably have not played with it (yet), but the smoothSpline is definitely worth a look. By default it draws a bezier curve that starts tangent to the previous line, and you can define the end tangent as well. It works a bit like the typical curve tool in a visual editor (you add points and adjust the tangents).

[raydeleu]

I indeed use Powerpoint to create the images. The Powerpoint file can be found on the Github site where the quick reference manual is placed. Using Inkscape would probably be better, but I am not that experienced with Inkscape. Therefore I preferred ease and speed. I had a second look at Inkscape, so I could consider redoing the images. I found out that Inkscape has some practical shortcut keys, so perhaps in the end Inkscape is even faster than Powerpoint :-).

For now I have as a goal to check the functions to be able to describe what they do, so I will certainly try out the smoothSpline.

[raydeleu]

Today I found out that Powerpoint can export SVG as well. So in the short term, if a higher resolution output is needed this can be achieved via the route Powerpoint - SVG - Inkscape - PNG.

[sgenoud]

I copied (and played with some converters) to add the quick reference to the documentation, you can have a look here: https://feature-adding-quick-referen.replicad.pages.dev/docs/quick-reference/

I need to automate the adoc - md conversion, as well as fix some small issues, but the spirit is here!

[raydeleu]

Looks great! The fact that the tables are translated correctly is the best, because adapting those would be labour intensive. Yesterday I encountered two questions regarding the quick reference:

• I tried to display more than three shapes in the visualiser, but this did not work. I am not sure if this was caused by an error in my code or whether this is a limitation in the visualiser.
• In your example for the visualiser I saw the "sketchOnPlane" command. Is this how you intended to handle the plane interface? Shall I already include this in a section on planes?

[sgenoud]

I tried to display more than three shapes in the visualiser, but this did not work. I am not sure if this was caused by an error in my code or whether this is a limitation in the visualiser.

Looks like a problem with your code - what did it look like?

In your example for the visualiser I saw the "sketchOnPlane" command. Is this how you intended to handle the plane interface? Shall I already include this in a section on planes?

No this is related to the new draw API. With the Sketcher API you define the plane at the sketcher instanciation (new Sketcher(plane)) - then you draw in a plane in 3D (each point is already set in the 3D space).

The drawing API does this the other way - you draw in 2D only. This allows me to define transformations of drawings (like you have 3D shapes): translations, mirrors, ... as well as boolean operations: cuts and fuses.

Then you can take this 2D drawing and embed it in the 3D space by sketching in a plane (or even in a face, but I have a bit more job to support any kind of face, and offer an intuitive API).

[raydeleu]

I was not able to reproduce the error in displaying multiple shapes. I tried to display one 3D shape and three wires in the scene and it seemed as if the last wire was not shown. I tried it just now and it seems to work.

Am I correct that after performing a loft, the wires are deleted from the scene? The same for shapes that are used in a fuse/common/intersect?

I thought it would be interesting to be able to display all separate components during the construction of a part so that a viewer can visually understand how a model was built. Until now I tried to achieve that by using a clone() (starting from the assumption that the original will be deleted after performing a function on it) but this did not always work. I am sometimes confused whether the result of an operation is a wire or a face. As a result I then get an error when I try to clone() , rotate() or scale(). In that sense I am looking forward to the draw API that you are describing.

Perhaps a related question: did you include a setting to display a part with an alpha color, so partly transparent? And is there a list of colours that can be chosen? Is it https://www.w3.org/wiki/CSS/Properties/color/keywords ?

[sgenoud]

Am I correct that after performing a loft, the wires are deleted from the scene?

As it is now, they tend to be deleted. It was a good thing until I could get a way to manage memory automatically (which is the case now). I should remove the automatic deletion of sketches now.

Perhaps a related question: did you include a setting to display a part with an alpha color, so partly transparent? And is there a list of colours that can be chosen? Is it https://www.w3.org/wiki/CSS/Properties/color/keywords ?

These are the standard threejs colors. From this documentation the named colors are the X11 color names.

Until now it was not possible to manage alpha, but I just added a new parameter to configure it:

    {
      shape,
      color: "DarkGoldenrod",
      opacity: 0.5,
    }

[raydeleu]

This is the experiment I tried earlier: I can indeed display more than 3 shapes now.

[lf94]

For what it's worth I went to replicad.xyz expecting this there already 🥲 Would love to see it merged! ❤️ Since I hop between RepliCAD and Curv it's easy to forget syntax and common classes and functions.