Reincarnate Artifact for ICFP 2018
In our paper, we made the following contributions (Section 1
, last paragraph):
-
A purely functional programming language model for 3D CAD along with denotational semantics for both CAD and triangular mesh.
-
A meaning preserving compilation algorithm from 3D CAD to mesh along with a proof sketch for compiler correctness.
-
A synthesis algorithm that can reverse engineer 3D CAD programs from meshes.
In support of these contributions, this artifact will demonstrate:
-
An early prototype of the compiler (
Section 4
) from the core 3D CAD language (Figure 8
in the paper) to mesh. The goal is to show that our compiler is capable of generating valid triangular meshes as we described in the paper. To that end we provide 5 CAD programs which cover all the core CAD language features we described inFigure 8
of the paper: 3D primitives, affine transformations, binary operations, and their combinations. -
An early prototype of the synthesis tool or reverse compiler (
Section 5
) from 3D mesh to CAD. The goal is to show that the synthesis tool is capable of synthesizing CAD programs from meshes for the case studies we described inSection 6
of the paper. Later in this document, we provide instructions on how to view the 3D renderings of the CAD programs our tool synthesizes. You can compare them with the figures we show in the paper, namely inFigures 3, 20, 21
and verify that the renderings look the same.
This document contains the following parts:
-
System requirements
-
Getting started.
-
How to run the compiler and synthesis tool.
-
Some notes and remarks
-
How to set up ReIncarnate on a different machine (this is also how we set up the VM).
-
We provide the artifact as a virtual machine image. To open it you need virtual box version
5.2.12
, which can be downloaded here. -
In the machine where we tested the VM, we have 16 GB RAM and 500 GB hard disk.
-
Please download the
.ova
file from the link and open it with Virtual Box by going toFile -> import appliance
and giving the path to the.ova
file and clicking oncontinue
. In the next window that pops up, click onImport
. It should take a few minutes to import. -
Next, please open the virtual machine image in virtual box by clicking on the green
Start
button. -
Login is automatic, but in case needed, the password is:
icfp2018
. -
The terminal should be open at startup. The project repository is already cloned. Navigate to the
reincarnate
directory. All the required packages are already installed. -
Type
cd src
from thereincarnate
directory and then typemake
. This will build all the tools.
We provide 5 CAD programs and a script that compiles them using our CAD compiler to generate 3D meshes. These CAD programs are in the directory: aec/cads-to-compile/cad3
. We compile the CAD programs to our mesh format (.mesh3 files) and also the industry standard format, STL (.stl files). The .mesh3
files will be saved in the aec/compiled-meshes/mesh3
directory. The .stl
files will be saved in the aec/compiled-meshes/stl
directory.
Note: Before running any scripts, feel free to check that the directories aec/compiled-meshes/mesh3
and aec/compiled-meshes/stl
are empty since that is where the meshes will be saved.
-
To run the compiler, run the following from the
src
directory:./scripts/compile.sh
. This should take 2-3 minutes to finish. -
In order for you to verify that the mesh our compiler generated corresponds to the same CAD program it started with, we recommend viewing the renderings before and after compilation.
- To facilitate viewing the rendering before compilation, we provide the directory
aec/cads-to-compile/scad
that contains the CAD programs from our CAD language (.cad3
files) pretty printed to OpenSCAD's language (.scad
files). OpenSCAD is another programmatic CAD language which has a 3D renderer. We have already installed OpenSCAD in the VM. Simply click on thescad
files in the directoryaec/cads-to-compile/scad
and click theRender
button above the Editor (the icon looks like a small cube with an hourglass at the bottom corner). - To view the rendering after compilation, we again recommend using OpenSCAD: click on the OpenSCAD icon on the vertical panel on the left and then click on
New
. To render anstl
file, type:import("/home/reincarnate/reincarnate/src/aec/compiled-meshes/stl/example-name.stl");
Then click on theRender
button on top and compare with the rendering of the corresponding.scad
file. They should look the same.
- To facilitate viewing the rendering before compilation, we provide the directory
In order to show the working synthesis tool, we provide the case studies we showed in the paper (Section 6
).
Note: Before running any scripts, feel free to check that the directories aec/synthed-cads/cad3
and aec/synthed-cads/scad
are both empty.
-
We recommend first running the script
./scripts/basic-synth.sh
to run the synthesis tool on the 5 meshes our compiler generated. This is just a sanity check. It should finish in ~ 7 minutes and a successful run indicates that it is possible to write CAD programs in our CAD language, compile them to mesh using our compiler, and then synthesize CAD programs back from the meshes. -
To run the case studies in the paper (
Section 6
), run./scripts/paper-synth.sh
. Please let this script run for two hours. Note: for the hexholder, we run a smaller version of it from this script which has fewer holes than the one inFigure 21
of the paper. This is because the one in the paper is very big and it takes about 9 hours to complete. We provide the mesh for the very big one in the directory:aec/paper-synth/bighexholder.mesh3
. In case you are interested to let it run for 9 hours, the command you need to run is:./Main.native --src aec/paper-synth/bighexholder.mesh3 --tgt aec/synthed-cads/cad3/bighexholder.cad3 --glue os-mesh --no-invariants --fuel x
fuel
is a parameter used by the synthesis algorithm shown inFigure 18
inSection 5.1
of the paper. It is used to ensure termination of the algorithm. You can set it to--fuel 1000
. We explain the flags--glue os-mesh
and--no-invariants
in the next section.You can further experiment to generate the corresponding
scad
file. The command for that is:./Main.native --src aec/synthed-cads/cad3/bighexholder.cad3 --tgt aec/synthed-cads/scad/bighexholder.scad
If you just want to look at the code our tool synthesized for this big example, we have included them in the directories: aec/pre-run-big-hexholder/cad3/bighexholder.cad3
and aec/pre-run-big-hexholder/scad/bighexholder.scad
(to open in OpenSCAD and view).
-
All the synthesized CAD programs will be in the directory
aec/synthed-cads
. Our script will generate both.cad3
files and.scad
files in dedicated sub directories withinaec/synthed-cads
. The.cad3
files correspond to the CAD programs synthesized in our CAD language. The.scad
files correspond to equivalent CAD programs in the OpenSCAD language. We do this so that you can use the OpenSCAD GUI to view the rendered CAD programs. Clicking on the files will open them in OpenSCAD from where you can click theRender
button to view the rendering. -
There are some other small examples we provide for synthesis that you can try to run yourself if you are interested. The meshes for these are in the
aec/extra-synth
directory. One is a cylinder primitive, another is a cube with one hole, and the third one is a another small hexholder with 3 holes.
As we have explained in Section 4.2.2
of the paper, the design of our tool is fully functorial. This has been extremely helpful in managing complexity as the codebase has grown beyond 20000 lines. Some advantages of this design decision is being able to parametrize our compiler and synthesis tool over different number systems, and swapping our compiler with other CAD compilers for synthesis (see Section 4.2.2
). There are several implementations of number systems (see NumSys.ml
, MPFRNumSys.ml
, ExactArith.ml
) which are instantiated in Main.ml
. Glue.ml
contains several configurations (called glues) for using our compiler or an external compiler (e.g. OpenSCAD) for synthesis. It is possible to choose the configuration from the command line. Type ./Main.native -h
to see all the options.
For the compiler experiments, we of course use the compiler that we have built. We also check all the invariants (see Section 3.2.1
of the paper) to ensure that the meshes our compiler produces are valid.
Currently for the synthesis experiments, we use the OpenSCAD compiler (indicated by the flag --glue os-mesh
), and also disable our invariant (indicated by the flag --no-invariants
) checks in order to avoid rounding errors. As we explained in Section 8.1
of the paper, rounding errors creep in very frequently in CAD compilation and as part of our future work, we have already started to work on ways to fix it (e.g. exact arithmetic). Since these numerical issues are still work in progress and not a contribution of this paper, for the purpose of demonstrating our synthesis tool, we leverage the fully functorial design of our tools and plug in the OpenSCAD compiler.
- Install system dependencies. On macOS with Homebrew:
$ brew install coreutils autoconf gnu-time gawk parallel git git-lfs graphviz gnuplot
$ brew cask install openscad
$ brew install ocaml opam
The version of Ocaml we use is 4.05
.
On Linux (Ubuntu 18.04) without root, you need to install OpenSCAD and build gnuplot from source. Then using Linuxbrew:
$ brew install autoconf parallel git git-lfs graphviz
$ brew install ocaml opam
On Linux (Ubuntu 18.04) with root and apt
:
$ apt-get install autoconf parallel git git-lfs graphviz gnuplot openscad
$ apt-get install ocaml opam
- Install opam packages:
$ opam init
$ eval `opam config env`
$ opam install mlgmpidl zarith hashcons menhir js_of_ocaml
- Run GNU parallel once interactively and acknowledge that you will cite the authors:
$ parallel --citation
- Build the compiler and synthesis tool:
$ cd reincarnate/src
$ make