add README article
s-ol
3 years ago
0 | watch-cad | |
1 | ========= | |
2 | ||
3 | this is a testbed/toy implementation of a new way to interact with graphical editors, such as CAD or vector software, | |
4 | combining the speed and ease of use of direct manipulation (using mouse and drawing tablets) with the expressivity, accuracy and reusability of code. | |
5 | ||
6 | With watch-cad, you edit a piece of code at the same time as you work on your document. | |
7 | The code defines the tool you use in the document. | |
8 | It is constantly error-checked, parsed and run. | |
9 | The API that is made available to the code lets you easily define direct manipulation interactions, | |
10 | allowing you to effortlessy string together custom tools as you go along. | |
11 | ||
12 | With this flexibility, creating custom tools and using them blend together into a single workflow that powers `watch-cad`. | |
13 | ||
14 | status | |
15 | ------ | |
16 | ||
17 | Currently this repo contains a [LÖVE](https://love2d.org) implementation of the concept. | |
18 | The engine only supports a few shapes, and documents can't be saved, so you have to start from scratch every time. | |
19 | To run it, you need to install love2d, and then `moonscript` and `luafilesystem`, e.g. using [luarocks](https://luarocks.org/). | |
20 | Then the project can be run from the project folder using `love .`, which should bring up a mostly-black window. | |
21 | ||
22 | To do something, you can create or open a Lua or Moonscript file in `library/`, and tell `watch-cad` about it using `:run <filename>`. | |
23 | For example to run the 'place' example, enter `:run place.moon` (and confirm with enter). | |
24 | Now you can place objects by clicking and dragging the mouse and confirm their creation with the spacebar. | |
25 | ||
26 | When `:run`-ing a script file, the script is reloaded whenever the file is saved on disk. | |
27 | ||
28 | *** | |
29 | ||
30 | Clearly this implementation is lacking many features. | |
31 | This is because this project is more about testing *the principles* (see below), rather than creating a fully featured application. | |
32 | In fact I am currently looking for a suitable 'host' application that the principles could be implemented into. | |
33 | I am considering KiCAD, Inkscape and Blender at the moment, but I am unsure which to go with. | |
34 | If you have any ideas, suggestions or opinions I would be very happy to hear them :) | |
35 | ||
36 | three principles | |
37 | ---------------- | |
38 | ||
39 | ### combine direct manipulation and code | |
40 | There are great arguments for the use of both direct manipulation and code. | |
41 | Code allows to abstract away tedious, repetitive tasks and helps with precision for geometric shapes. | |
42 | ||
43 | But editing code is not always the most natural way to interact with things, especially when a graphical representation already exists. | |
44 | Direct manipulation is much more intuitive for making adjustments to freehand shapes, fine-tuning parameters and many other tasks. | |
45 | ||
46 | That's why `watch-cad` makes it as easy as possible to combine the two, by offering primitives such as draggable points, object-selection etc. to be used in code. | |
47 | ||
48 | ### don't worry, preview | |
49 | Because `watch-cad` shifts a lot of the work into creating ad-hoc programs, it's very important to make this process as fast and reliable as possible. | |
50 | Part of that is making sure that unfinished or buggy code doesn't cause problems. | |
51 | That's why code you write in `watch-cad` never changes anything in the document directly. | |
52 | All changes are instead previewed in the document itself, as code is edited and interacted with. | |
53 | ||
54 | Whenever you are happy with the results, you can apply the changes instantly. | |
55 | This makes sure you can freely experiment with the code without fearing to lose anything, | |
56 | and be sure that what happens when you *do* commit is exactly what you wanted. | |
57 | ||
58 | ### immediate feedback, always | |
59 | A big part of programming is figuring out what's going wrong. | |
60 | As a consequence of it's design, `watch-cad` constantly parses and runs your code (or the last parse-able version of it). | |
61 | This means that it can give constant feedback for errors as you work on the code. | |
62 | ||
63 | It's also easy to spot problems in your logic, since any changes you apply in your code are previewed in realtime on the canvas. | |
64 | The drawing API also makes it easy to add more debug visualisations, right in the graphical context. | |
65 | ||
66 | `watch-cad` versus regular scripting APIs | |
67 | ----------------------------------------- | |
68 | Many applications already ship with a scripting interface, | |
69 | for example KiCAD, Inkscape and Blender all support extensions written in Python. | |
70 | ||
71 | While this is great to have, in an effort to keep the interface more aligned (presumably), | |
72 | however all of these applications are optimized for using such extensions, not for creating them (especially on-the-fly), | |
73 | and even when running them the user-experience is severly limited. | |
74 | ||
75 | For example in Inkscape python plugins can be added only as importers, exporters or 'filters'. | |
76 | Filters are the most general of the cases here, but even they come with a severe limitation: | |
77 | They cannot be controlled by user input other than the state of the document and a popup window that can be optionally defined. | |
78 | This means that extensions are completely cut-off from defining their own (or even re-using existing) direct manipulation operations. | |
79 | ||
80 | The editing experience makes this a lot worse. | |
81 | To add new functionality, a script has to be created in a specific place on the disk and filled with python code. | |
82 | When a new extension is added for the first time, Inkscape has to be restarted. | |
83 | While the code is edited, there is no feedback at all, | |
84 | and to check whether progress has been made while working on a new filter, | |
85 | it has to be run manually every once in a while. | |
86 | Because a work-in-progress extension may corrupt the document it is tested in, | |
87 | either care must be taken to immediately undo anything the extension did between tests, | |
88 | or to work in a copy of the original file or a new test document. | |
89 | ||
90 | All of this constitutes an exeperience that is simply too annoying to routinely use for small improvements in workflow. |