dyna3

Abstract

Constraint-based three-dimensional dynamic geometry

Description

From a thorough web search, there does not seem to be a dynamic geometry software package which (a) began its life handling three dimensions, rather than just two, and (b) allows you to express the desired geometric configuration in terms of constraints on the entities (e.g. l and k are parallel, a, b, and c a collinear, etc.) rather than as a construction (e.g. l is the perpendicular bisector of a and b). The goal of the dyna3 project is to close this gap.

Note that currently this is just the barest beginnings of the project, more of a framework for developing dyna3 rather than anything useful.

Implementation goals

• Provide a comfortable, intuitive UI

• Allow execution in browser (so implemented in WASM-compatible language)

• Produce scalable graphics of 3D diagrams, and maybe STL files (or other fabricatable file format) as well

Prototype

The latest prototype is in the folder app-proto. It includes both a user interface and a numerical constraint-solving engine.

Install the prerequisites

1. Install rustup: the officially recommended Rust toolchain manager.
   • It's available on Ubuntu as a Snap.
2. Call rustup default stable to "download the latest stable release of Rust and set it as your default toolchain".
   • If you forget, the rustup help system will remind you.
3. Call rustup target add wasm32-unknown-unknown to add the most generic 32-bit WebAssembly target.
4. Call cargo install wasm-pack to install the WebAssembly toolchain.
5. Call cargo install trunk to install the Trunk web-build tool.
   • In the future, trunk can be updated with the same command. (You may need the --locked flag if your ambient version of rustc does not match that required by trunk.)
6. Add the .cargo/bin folder in your home directory to your executable search path
   • This lets you call Trunk, and other tools installed by Cargo, without specifying their paths.
   • On POSIX systems, the search path is stored in the PATH environment variable.
   • Alternatively, if you don't want to adjust your PATH, you can install trunk in another directory DIR via cargo install --root DIR trunk.

Play with the prototype

1. From the app-proto folder, call trunk serve --release to build and serve the prototype.
   • The crates the prototype depends on will be downloaded and served automatically.
   • For a faster build, at the expense of a much slower prototype, you can call trunk serve without the --release flag.
   • If you want to stay in the top-level folder, you can call trunk serve --config app-proto [--release] from there instead.
2. In a web browser, visit one of the URLs listed under the message INFO 📡 server listening at:.
   • Touching any file in the app-proto folder will make Trunk rebuild and live-reload the prototype.
3. Press ctrl+C in the shell where Trunk is running to stop serving the prototype.

Run the engine on some example problems

1. Use sh to run the script tools/run-examples.sh.

   • The script is location-independent, so you can do this from anywhere in the dyna3 repository.

   • The call from the top level of the repository is:

     sh tools/run-examples.sh
     

   • For each example problem, the engine will print the value of the loss function at each optimization step.

   • The first example that prints is the same as the Irisawa hexlet example from the Julia version of the engine prototype. If you go into engine-proto/gram-test, launch Julia, and then execute

     include("irisawa-hexlet.jl")
     for (step, scaled_loss) in enumerate(history_alt.scaled_loss)
       println(rpad(step-1, 4), " | ", scaled_loss)
     end
     

     you should see that it prints basically the same loss history until the last few steps, when the lower default precision of the Rust engine really starts to show.

Run the automated tests

1. Go into the app-proto folder.
2. Call cargo test.

Deploy the prototype

1. From the app-proto folder, call trunk build --release.
   • Building in release mode produces an executable which is smaller and often much faster, but harder to debug and more time-consuming to build.
   • If you want to stay in the top-level folder, you can call trunk build --config app-proto --release from there instead.
2. Use sh to run the packaging script tools/package-for-deployment.sh.
   • The script is location-independent, so you can do this from anywhere in the dyna3 repository.
   • The call from the top level of the repository is:

     sh tools/package-for-deployment.sh
     

   • This will overwrite or replace the files in deploy/dyna3.
3. Put the contents of deploy/dyna3 in the folder on your server that the prototype will be served from.
   • To simplify uploading, you might want to combine these files into an archive called deploy/dyna3.zip. Git has been set to ignore this path.