{"id":21676963,"url":"https://github.com/uwplse/szalinski","last_synced_at":"2025-03-20T09:41:04.070Z","repository":{"id":77652219,"uuid":"207904567","full_name":"uwplse/szalinski","owner":"uwplse","description":"Szalinski: A Tool for Synthesizing Structured CAD Models with Equality Saturation and Inverse Transformations ","archived":false,"fork":false,"pushed_at":"2023-07-21T07:09:36.000Z","size":128142,"stargazers_count":46,"open_issues_count":12,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-18T05:51:46.467Z","etag":null,"topics":["3d-printing","cad","compiler-optimization","synthesis"],"latest_commit_sha":null,"homepage":"https://dl.acm.org/doi/10.1145/3385412.3386012","language":"OpenSCAD","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uwplse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-11T20:51:34.000Z","updated_at":"2025-01-13T12:41:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"7fbe3efb-cdee-47ed-8330-6eb170f5abf9","html_url":"https://github.com/uwplse/szalinski","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uwplse%2Fszalinski","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uwplse%2Fszalinski/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uwplse%2Fszalinski/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uwplse%2Fszalinski/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uwplse","download_url":"https://codeload.github.com/uwplse/szalinski/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244590231,"owners_count":20477688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-printing","cad","compiler-optimization","synthesis"],"created_at":"2024-11-25T14:17:02.648Z","updated_at":"2025-03-20T09:41:04.063Z","avatar_url":"https://github.com/uwplse.png","language":"OpenSCAD","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PLDI 2020 AEC, Paper\\# 471\n\nNOTE: In the rest of this document, we refer to our tool as `Szalinski`.\nIn our submission, we called it `Albatross` for anonymity.\n\n## Goals of the artifact\n\nIn our paper, we evaluated the following about Szalinski (`Section 7`):\n\n1. End-to-End: we ran Szalinski on the flat CSG outputs of a mesh decompiler\n   (Reincarnate). The results are in `Table 2`.\n\n2. Scalability: we evaluated Szalinski on a large dataset of models scraped\n   from a popular online repository (Thingiverse). The results are in `Figure\n   14` (first three box plots).\n\n3. Sensitivity: we evaluated the usefulness of Szalinski's two main features:\n   CAD rewrites and Inverse Transformations. The results are in `Figure 14`\n   (last two box plots).\n\nIn support of these results, this artifact reproduces `Table 2` and `Figure\n14`. In addition, it also generates the output programs in `Figure 15` that are\nused in the case studies.\n\n\nThis document contains the following parts:\n\n* System requirements\n\n* Getting started\n\n* How to run Szalinski\n  - Reproducing Table 2 (takes \u003c 5 minutes)\n  - Reproducing Figure 14 (takes approx. 1.5 hour)\n  - Reproducing Figure 15 (takes \u003c 5 minutes)\n  - Validation\n\n* Reusability\n  - How to set up Szalinski on a different machine (this is also how\n  we set up the VM)\n  - Description of the code and how to modify it\n\n* Notes and remarks\n\n## System requirements\n\n* We provide the artifact as a virtual machine image. To open it you need\n  virtual box version `6.1.2`, which can be downloaded\n  [here](https://www.virtualbox.org/wiki/Downloads).\n\n* Specs of the machine where we ran the VM:\n  Intel i7-8700K (12 threads @ 4.7GHz), 32GiB RAM\n\n## Getting started\n\n* Please download the `.ova` file [here](https://drive.google.com/drive/folders/1w28mR3hrINCKBkvj1j0GF61mzEsAq7vM)\n  and open it with Virtual Box by\n  going to `File -\u003e import appliance` and giving the path to the `.ova` file\n  and clicking on `continue`. In the next window that pops up, click on\n  `Import`. It should take a few minutes to import.\n\n**NOTE:** When you import the `.ova` file, we recommend that you\nincrease the CPU count as much as you can afford.\nSimilarly, when running `make`, we recommend adding\n`make -jN` where `N` is the number of CPUs you allocated to the VM.\n\n* Next, please open the virtual machine image in virtual box by clicking on the\n  green `Start` button.\n\n* Login is automatic, but in case needed, the password is: `pldi2020`.\n\n* The terminal should be open at startup. The project repository is already\n  cloned.  Navigate to the `szalinski` directory.  All the required packages\n  are already installed and Szalinki is already compiled for you, ready to be\n  run.\n\n* To allow a quick verification of our artifact, we provided pre-generated data and\nresults in the VM. You can therefore skip the `make` commands in the instructions\nand directly view the results (see below on how to do that).\n\n* As a next step, you can verify that the results are indeed\ngenerated from the data we provided. To do so, delete the\nresults (`out/aec-table2/table2.csv`, `out/fig14.pdf`) and run the `make`\ncommands as explained below.\n\n* To run the tool yourself entirely from scratch,\nfirst delete the entire `out` directory and follow the instructions below.\n\n## Running the tools\n\n### Reproducing Table 2\nNavigate to the directory that contains the `Makefile` and\ntype `make out/aec-table2/table2.csv`.\nThis should take about 3 minutes.\nThis will reproduce `Table 2` from the paper.\nTo view the content of the table, type\n`cat out/aec-table2/table2.csv | column -t -s,` and compare the numbers\nwith `Table 2` in the paper.\n\n**NOTE:**\n- We have significantly improved Szalinski since the PLDI deadline.\nAs a result, for several case studies, the numbers in the last three\ncolumns of the table are lower (hence better in this case) than what is\nreported in the paper.\n- We suspect that different versions of OpenSCAD use\ndifferent triangulation algorithms for compiling to mesh.\nThe version supported by Ubuntu 19.10 (the VM) is different from the\nversion we used during the deadline because we ran it on a MacOS.\nDue to this, the numbers in the `#Tri` column may vary in this artifact.\n\n### Reproducing Figure 14\n\nWe have included in the repo the 2,127 examples from Thingiverse that\nwe evaluated on in the paper.\nThe remainder of the 12,939 scraped from Thingiverse were either\nmalformed or used features not supported by Szalinski.\nThe script (`scripts/scrape-thingiverse.sh`) scrapes models under the\n`customizable` category, from the first 500 pages.\n\n*NOTE:* Running this part takes about an hour.\nWe recommend first reproducing `Figure 15` and\n`Table 2`, both of which take much less time.\n\nNavigate to the directory that contains the `Makefile` and type\n`make out/fig14.pdf`. Open the generated file in a pdf viewer and\ncompare with `Figure 14` in the paper.\n\n\n### Reproducing Figure 15 programs\nNavigate to the directory that contains the `Makefile` and\ntype `make aec-fig15`. This should take less than a minute.\nThen look in the `out/aec-fig15` directory. The\noptimized programs generated by Szalinski are in the files with extensions\n`normal.csexp.opt`. There should be 6 such files. Open them and compare the\ncontent with the programs listed in `Figure 15` of the paper.\n\n**NOTE:**\n- The programs in the paper are sugared and represented more\ncompactly for space.\n- `MapI` found in the artifact results corresponds\nto `Tabulate` in the paper.\n- When comparing the results generated by the artifact\nto the programs in `Figure 15` of the paper, it is most important to check\nthat the high-level structure in terms of `Fold` and `MapI`\nsynthesized by the artifact matches that reported in the paper.\n\n### Validation\n\n`Section 6` of our paper describes Szalinski's validation process.\nWe use OpenSCAD to compile CSG programs to meshes and use CGAL to compute\nthe Hausdorff distance between two meshes.\n\nTo validate the programs in `Figure 15`,\nrun `make out/aec-fig15/hausdorff`. This should terminate in less than 3\nminutes. It should show you the names of the 6 examples in `Figure 15` and the\ncorresponding Hausdorff distances which are close to zero.\n\nWe have also validated all our other results reported in the paper.\nHowever, our experience indicates that OpenSCAD's compilation\nstep is often very slow. Therefore, the other commands\nmentioned in the instruction for reproducing the results\ndo not perform validation by default.\n\nYou can validate any example from our evaluation by typing:\n `make out/dir_name/example_name.normal.diff`, where\n`dir_name` can be `aec-table2`, `aec_fig15` or `thingiverse`, and\n`example_name` is the name of whatever example you choose.\nThen open the generated `.diff` file and check\nthat the Hausdorff distance is within some epsilon of 0.\n\n**NOTE:** For many example, CGAL crashes or is slow at computing the Hausdorff distance.\nFor these, we recommend a manual validation if you are interested.\nIn order to validate an example, type the following:\n`make out/dir_name/example_name.diff.scad`. You can open the generated `.scad`\nfile in OpenSCAD (already installed in the VM). In OpenSCAD, click on the\n`Render` button (the second button from the right) in the toolbar.\nYou should either see nothing rendered or some residual thin walls that are\nartifacts of rounding error prevalent in OpenSCAD.\n\n## Reusability\n\nHere we provide instructions on how to start using Szalinski including\ninstallation and changing the rules and features of the Caddy language.\n\n### Setup instructions\n\nFollowing are the steps for setting up Szalinski\nfrom scratch on a different machine that runs Ubuntu 19.10.\n\n* Install rust. Type `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`\n  in the terminal and follow the subsequent instructions. The version we used is `1.41.0`.\n  See`https://www.rust-lang.org/tools/install` for more information.\n\n* Make sure you configure your current shell by typing: `source $HOME/.cargo/env`\n  (the Rust installation will prompt you to do this).\n\n* Install make by typing: `sudo apt-get install make`\n\n* Install g++ by typing: `sudo apt-get install g++`\n\n* Install jq by typing: `sudo apt-get install jq`\n\n* Install [CGAL](https://www.cgal.org/download/linux.html) by typing\n  `sudo apt-get install libcgal-dev`\n\n* Install [OpenSCAD](https://www.openscad.org/) by typing\n  `sudo apt-get install openscad`\n\n* Install git by typing `sudo apt install git`\n\n* Install pip by typing `sudo apt install python3-pip` and then\ninstall `numpy` by typing `pip3 install numpy` and `matplotlib` by typing\n`pip3 install matplotlib`\n\n* We have made a [github release](https://github.com/uwplse/szalinski/tree/pldi2020-aec)\nfor the PLDI AEC from where you can get the source.\n\n* Navigate to the project directory where the `Makefile` is\nand run the tool as described above.\n\n### Changing Caddy and modifying the rules\n\n* The Caddy language is defined in `cad.rs` in the `src` directory.\nA simple feature you can add is support for a new primitive or new\ntransformations. You can also change the costs of various language\nconstructs. The definition of the `cost` function starts at line `267`.\n\n* As we described in the paper, to verify the correctness of Szalinski,\nwe evaluate Caddy programs to flat Core Caddy and pretty print to CSG. This\ncode is in `eval.rs`.\n\n* `solve.rs` and `permute.rs` contains code that solves for first and second\ndegree polynomials in Cartesian and Spherical coordinates, and performs\npartitioning and permutations of lists.\n\n* The rewrites rules are in `rules.rs`. Syntactic rewrites are\nwritten using the `rw!` macro. Each rewrite has a name, a left hand side,\nand a right hand side. You can add / remove rules to see how that affects\nthe final Caddy output of Szalinski. For example, if you comment out the\nrules for inverse transformations, they will not be propagated and\neliminated, and therefore the quality of Szalinski's output will not be\nas good.\n\n## Notes and remarks\n\nSzalinski is implemented in [Rust](https://www.rust-lang.org/).\nAs mentioned in `Section 6` of the paper,\nit uses [OpenSCAD](https://www.openscad.org/)\nto compile CSG programs to triangular meshes, and\n[CGAL](https://www.cgal.org/) to compute the\nHausdorff distance between two meshes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuwplse%2Fszalinski","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuwplse%2Fszalinski","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuwplse%2Fszalinski/lists"}