1. Introduction

1.1 Purpose

This document contains a beginner's guide for users of the Replicad (https://replicad.xyz/) libary and tools. Its purpose is mainly to demonstrate how models can be build using the tools, the so-called "studio", that are offered alongside the library. If you want to use this document to generate a separate manual, use one of the tools available to generate a simple document out of a github wiki repository.

At the Replicad website some documentation is offered as well as links to the detailed documentation of the API (Application Progamming Interface) of the library (see https://replicad.xyz/docs/api/). Nevertheless it can be quite daunting to collect all information for people that are just interested in modelling and are less experienced in reading computer code or building applications.

Using the Replicad tools it is possible to build complicated mechanical parts and even free form geometry. Two examples are shown below. Throughout the guide some examples will be given how the commands discussed in each chapter can be applied to real modelling examples. The folder https://github.com/raydeleu/ReplicadManual/tree/main/models contains some examples on how the functions of Replicad can be applied to create models.

For additional help you can visit https://github.com/sgenoud/replicad and in particular the discussions area. There are sections labelled "Q&A" and "modelling help" where you can post your question. The programmer of Replicad is active in responding questions from users and you can also expect some help from fellow users.

To understand how the library can be included in new applications please consult the replicad website at https://replicad.xyz/. A very nice example how the library can be used can be visited at https://blingmything.sgenoud.com/. The code to this application is also available on github at https://github.com/sgenoud/blingmything.

1.2 What is Replicad?

Replicad is a software library that allows the user to enter a kind of script to create a 3D model. This model can then be exported in several formats, allowing the user to create nice images (renders) or to send the shape to a 3D printer.

The approach to model a 3D shape with code (or script) has become popular through the availability of a software package called OpenSCAD (Open Scripted-Computer-Aided-Design). OpenSCAD has been used initially to model simple shapes for 3D modelling. It uses a technique called Constructive Solid Geometry (CSG), which indicates that 3D shapes are created by combining simple geometric shapes such as boxes, spheres, cylinders into more complex shapes. The operations used to combine these shapes are called boolean operations.

This shape is created by entering the following script:

.Code to create a car in OpenSCAD, using two boxes and 6 cylinders (4 wheels and two axles)

cube([60,20,10],center=true);
translate([5,0,10 - 0.001])
    cube([30,20,10],center=true);
translate([-20,-15,0])
    rotate([90,0,0])
    cylinder(h=3,r=8,center=true);
translate([-20,15,0])
    rotate([90,0,0])
    cylinder(h=3,r=8,center=true);
translate([20,-15,0])
    rotate([90,0,0])
    cylinder(h=3,r=8,center=true);
translate([20,15,0])
    rotate([90,0,0])
    cylinder(h=3,r=8,center=true);
translate([-20,0,0])
    rotate([90,0,0])
    cylinder(h=30,r=2,center=true);
translate([20,0,0])
    rotate([90,0,0])
    cylinder(h=30,r=2,center=true);

Replicad takes this approach a step further. It still retains the approach that shapes are created with a simple script, but it uses a more advanced 3D kernel that allows BRep (Boundary Representation) modelling. In this type of 3D kernel a solid is represented as a collection of surface elements - described using a mathematical equation - that define the boundary between interior and exterior points.

The advantage of a BRep kernel is that in addition to the simple boolean operations it is possible to define how the surfaces are linked to each other. This allows a more easy creation of angled edges (chamfers) or rounded edges (fillets).

1.3 Tools to work with Replicad

A model in Replicad is built using a javascript input file (see section 1.4 File Template). The best way for a beginner is to use the studio tools which come in two flavours namely the workbench and a visualizer.

1.3.1 Workbench

The workbench, available at https://studio.replicad.xyz/workbench , is a complete design environment that includes a code editor with a pane to visualize the result of the input file. The result can be exported to STL and STEP formats to allow further processing, for example 3D printing. The code in the editor can be downloaded as a javascript file. Use the icon with a circle and arrow going down that can be found directly on top of the editor window. Of course you can also select the code in the editor and paste it into any other editor.

Note that the Workbench starts to interpret the code as soon as you type it in the editor window. In most cases this will result in an error message and the 3D window will show an animated cloud or "amoebe". The error found by Replicad is shown in a pane that appears directly below the editor. In some cases this is a straightforward error, for example if a function was mistyped or you forgot a closing bracket. In other cases the pane reports a "Kernel Error" followed by a number. Just continue completing the code until you see the progress indicator turning again. If the "Kernel Error" persists, try to remove instructions, for example by adding // at the beginning of this line to indicate that this is only a comment, until you get either an understandable error message or a shape again.

An interesting feature of the workbench that is offered at the link shown above is that you can create a link to your model that includes the code. In that way you can share your model through an internet link that opens the workbench with your code in it. Others can then take your code and make modifications for their own purpose. Use the icon above the editor window that resembles a rectangle with an arrow going up.

1.3.2 Visualizer

For people that prefer to edit the input files on their own computer using their preferred code editor, a visualizer is offered at https://studio.replicad.xyz/visualiser that can be used to show the results of processing an input file. Just like the workbench the visualizer supports the export of the shapes.

If the input file contains an error, the error message is shown in a pop-up window in the 3D view.

1.4 File template

The template to create and display a 3D part in Replicad looks like this.

const r = replicad

const defaultParams = {                // setting the value of the parameters
  height:       100,
  baseWidth:     20,
  ...}

// next lines allow intellisense help in VS Code 
/** @typedef { typeof import("replicad") } replicadLib */
/** @type {function(replicadLib, typeof defaultParams): any} */

function main( 
 { Sketcher, sketchRectangle, ... },   // functions used within the main program
 { height, basewidth, ....        } )  // parameters to adjust the model
{
    // add code to describe the shape
return  shape   |  
return  {shape: [shape], highlight: [foundFeature]}
}

Note that the line

const r = replicad

can be used to circumvent the need to list all functions that are used in the code. Prepending each function with r. directly points the compiler to the complete Replicad source code. So for example, instead of listing the function sketchRectangle at the beginning of the declaration of main you can use r.sketchRectangle. Yet another approach is to list all the functions but add this add the beginning of your code using the notation:

const { draw, ... other functions ... } = replicad;

function main() 
{
    // code to describe the shape
return shape 
} 

Using this notation there is no need to remember which of the arguments in the brackets of function main({functions},{designparams}) contains what. You can simply use main().

Alternatively to the file listing shown above, you can use the arrow notation for the javascript function. This notation can be combined with the notations shown above to shortcut the definition of functions from the Replicad library.

const defaultParams = {                // setting the value of the parameters
  height:       100,
  baseWidth:     20,
  ...}

const main = (
  { Sketcher, sketchRectangle, ... },   // functions used within the main program
  { height, basewidth, ....        }    // parameters to adjust the model
) => {
    // add code to describe the shape
return  shape   |  
return  {shape: [shape], highlight: [foundFeature]}
}

If you want to display multiple shapes, the returned variable should be an array of all shapes. In this array it is possible to define

• the variable name of the shape,
• the name of the shape as a "string",
• the color of the shape in the Visualiser, using the X11 "color name", see https://en.wikipedia.org/wiki/X11_color_names#Color_name_chart

Example colors are black, grey, dimgrey, slategrey, lightslategrey, steelblue, lightsteelblue, red, green, blue, violet, silver, skyblue, magenta, mediumpurple.

• the opacity, where opacity 1 is the default (visible) and 0 is fully transparant.

An example of an array is:

let shapeArray = [
{shape: plunge, name: "plunge", color:"steelblue", opacity: 0.5}, 
{shape: body, color: "orange",opacity:0.5},
{shape: filler, color: "red"}]