![[Articles/Linux/OpenSCAD in Obsidian/cover.png]] Rendered 3D object using OpenSCAD in Obsidian - Screenshot by 'Mateusz Adamczyk' / blog.amatthew.eu, [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) ## Sections ### Centralising workbooks in a popular sync-enabled text editor Obsidian is a popular text editor, widely used for writing notes, rendering graphs, visualisation of data in the general sense and even standalone web pages (published notes). It is a quite versatile piece of software doing a solid job within its designed scope of operations, so mostly text editing. It has a couple of strong features, that are typically not found in CAD IDEs, such as: - support for a variety of functionally extending plugins - *letting the editor be somewhat hackable* - adjustable interface themes - *making contents easy to read* - backups and synchronisation across different devices - *protecting files with redundancy* - templates, convenient management of folders and support for nested binary data, e.g. images, PDF files - *allowing for snippets with documentation* ### Why not use Visual Studio Code instead? VSC does offer plenty of very creative and helpful extensions, that accelerate different types of workflows. One can easily work with SOCs (3D printer motherboards, "Arduinos", ESPs), compiled text engines like TeX, even CAD software using just VSC. It is a bit of an '*Emacs for Zoomers'*... which is a good thing actually, but it's still closer to Emacs than CAD. As an example - I have tried out an extension called "OpenSCAD" by **"Antyos"**, which is meant to render VSC's file content inside OpenSCAD, then bring back the renderer window for a preview. It works pretty well. However - I needed **simple file management with automatic backups and quick synchronisation**. The idea was to move wildly changing prototypes of simple components off my mind (whenever I actually have the time and energy to 3D prototype), so that they do not get lost in the depths of my cluttered desktop. Additionally, the ability to stash and open parts schematics (2D schematics, 3D STLs) within the same work folder is invaluable - as it leads to a well organised catalogue with all parts needed, especially image previews. VSC builds atop well-tested solutions, e.g. the **GIT** system, which works perfectly for versioning, collaboration, tracking of source code, but is not suitable for 3D prototyping. An SMB may be used instead, or a synced cloud drive (e.g. OneDrive, Dropbox, Mega). However this adds complexity and will not work for certain devices (e.g. smartphones) - so the criteria of synchronisation would not be met. Of course, **technically**, GIT may be used for nearly everything, even storing cooking recipes or books. An example of 'GitFood' - by ['Jondavid Black'](https://github.com/jondavid-black)' / [source](https://github.com/jondavid-black/food), [MIT](https://mit-license.org/) <center><iframe src="https://gitfood.org/" height="400" width="600"></iframe></center> ### Why OpenSCAD? Without delving into the world of opinions - Linux users do not have a good selection of CAD software. There are *some* alternatives to popular proprietary software available on MacOS and Windows, but the quality evaluation of those alternatives is to be carried out individually... What is universally available, even if quite complicated - but also very convenient depending on the project's specifics, is the *programmers'* CAD. There are a couple of such CADs; **CadQuery**, **BRL-CAD** and of course **OpenSCAD**. OpenSCAD is my personal choice, as it is lightweight, cross-platform and relatively simple. And on the side-note, it also has a friendly looking website with good tutorials. In essence - all one needs to work with OpenSCAD is creativity, imagination and the official cheatsheet. ![[Articles/Linux/OpenSCAD in Obsidian/Pasted image 20250103211757.png]] OpenSCAD Cheatsheet - by 'Peter Uithoven' / [source](https://openscad.org/cheatsheet/), [CC-BY license](https://freedomdefined.org/Licenses/CC-BY) ### Integrating OpenSCAD with Obsidian #### Dependencies What will be needed: - OpenSCAD installed as a system package (.RPM, .DEB) or a Flatpak, AppImage - Obsidian installed as a system package or an AppImage (a non-containerised binary) - "Shell commands" plugin by 'Taitava' (Jarkko Linnanvirta) / [obsidian](obsidian://show-plugin?id=obsidian-shellcommands) [github](https://github.com/Taitava/obsidian-shellcommands) - "Buttons" plugin by 'shabegom (Sam)' / [obsidian](obsidian://show-plugin?id=buttons) [github](https://github.com/shabegom/buttons) It is important to note down that Obsidian **must** be installed as a non-containerised binary package. Obsidian may be installed in different ways, yet when using the Flatpak distribution it will be executed inside a restricted (somewhat isolated) environment. You can [discuss](https://github.com/Taitava/obsidian-shellcommands/discussions/225) about a solution with the plugin's author if you know one! ![[Articles/Linux/OpenSCAD in Obsidian/Pasted image 20250106131140.png]] [Flatpak runtimes]([https://docs.flatpak.org/en/latest/available-runtimes.html](https://docs.flatpak.org/en/latest/available-runtimes.html) ) - Screenshot by 'Mateusz Adamczyk' / blog.amatthew.eu, [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) The Flatpak scenario is not limited to this extension. Other extensions dependant on Shell 'calls' and system binaries may also not function properly. I personally attempted adjusting the permissions using **Flatseal** (mainly D-Bus and filesystem settings) without success. #### Configuration - Enable the plugins. - Enter Obsidian settings. - Enter "Shell commands" tab at the bottom. - Create custom shell commands (OS dependant). Suggested commands: - OpenSCAD-Open - OpenSCAD-Render-PNG - OpenSCAD-Render-STL Each command will execute a slightly different type of code. I provide examples only for **Linux** based Operating Systems. The end result will be an Obsidian notebook file with 3 different buttons used for different OpenSCAD commands. The idea behind this integration is based on **Markdown Code Blocks** with special custom tags and Obsidian's pre-defined variables. In this case, some of them come from the "Shell commands" plugin. I highly recommend visiting the plugin's [documentation](https://publish.obsidian.md/shellcommands/Index) page, which is very thorough and informative! ![[Articles/Linux/OpenSCAD in Obsidian/Pasted image 20250106141400.png]] Preview of OpenSCAD in Obsidian - Screenshot by 'Mateusz Adamczyk' / blog.amatthew.eu, [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) ![[Articles/Linux/OpenSCAD in Obsidian/Pasted image 20250108001517.png]] Example of a custom command - Screenshot by 'Mateusz Adamczyk' / blog.amatthew.eu, [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) As seen, each button has a different command appended to it. I settled down with 3 main functions - opening a code snippet in the program, rendering the code snippet as PNG output, rendering the code snippet as STL output. openscad-open ```bash mkdir -p /tmp/openscad && echo -e {{file_content}}} | grep --perl-regexp --null-data --only-matching '```OpenSCAD\n(\X*?)\n```' | tr -d '\000' | sed '1d; $d' | tee /tmp/openscad/{{!file_name}}.scad && openscad --viewall /tmp/openscad/{{!file_name}}.scad ``` openscad-render-png ```bash mkdir -p /tmp/openscad && echo -e {{file_content}}} | grep --perl-regexp --null-data --only-matching '```OpenSCAD\n(\X*?)\n```' | tr -d '\000' | sed '1d; $d' | tee /tmp/openscad/{{!file_name}}.scad && openscad --viewall /tmp/openscad/{{!file_name}}.scad --o /tmp/openscad/{{!file_name}}.png && mv /tmp/openscad/{{!file_name}}.png {{folder_path:absolute}} ``` openscad-render-stl ```bash mkdir -p /tmp/openscad && echo -e {{file_content}}} | grep --perl-regexp --null-data --only-matching '```OpenSCAD\n(\X*?)\n```' | tr -d '\000' | sed '1d; $d' | tee /tmp/openscad/{{!file_name}}.scad && openscad --viewall /tmp/openscad/{{!file_name}}.scad --o /tmp/openscad/{{!file_name}}.stl && mv /tmp/openscad/{{!file_name}}.stl {{folder_path:absolute}} ``` I will now *dissect* the code above into separate pieces to explain what is happening in these code snippets. `mkdir -p /tmp/openscad &&` - this part will generate a new temporary folder inside the /tmp directory. This is used solely for generation of OpenSCAD inputs and outputs, as OpenSCAD is unable to accept CLI input other than a file path. `echo -e {{file_content}}} | grep --perl-regexp --null-data --only-matching '```OpenSCAD\n(\X*?)\n```' | tr -d '\000' | sed '1d; $d' | tee /tmp/openscad/{{!file_name}}.scad && openscad --viewall /tmp/openscad/{{!file_name}}.scad` - this part is much more complicated. - It will copy all lines of content of the opened Obsidian file using **echo**, then pipe it - use a custom regex (PERL flavour) pattern in **grep** to extract only contents of a special custom markdown code block (including the tags). Grep must be used with **--null-data** to treat input as a sequence of lines from a file (which results in an extra character at the end), then pipe it - then remove a tracing *null* character using **tr**, then pipe it - use **sed** to remove the first and last line of the input (they contain the markdown code block tags), then pipe it - use tee to produce an output from the command and save the contents into the temporary file with the notebook's file filename, and - lastly, the file will be opened in OpenSCAD using its path The remaining 2 commands simply extend upon this idea, to either call OpenSCAD in PNG or STL output rendering mode. Additionally, the commands will use the **mv** tool to move the rendered outputs from the temporary folder into the notebook's folder. Thus, one click not only generates an output in an external program, but also appends the results automatically into the same folder. The last step in order to create an OpenSCAD Obsidian notebook is to have a template with buttons and the custom code blocks. This is where the second plugin comes into play, as it offers the capability of nesting Obsidian buttons directly into a note, hence allowing for a simple interface for the first plugin. ```button name OpenSCAD - Open type command customTextColor #D1A151 action Shell commands: Execute: openscad-open ``` ```button name OpenSCAD - Render PNG type command customTextColor #D1A151 action Shell commands: Execute: openscad-render-png ``` ```button name OpenSCAD - Render STL type command customTextColor #D1A151 action Shell commands: Execute: openscad-render-stl ``` For best experience I recommend using the native support of templates in Obsidian, then simply generate 3D project backbone templates with the predefined buttons. Each template may contain only **one** markdown OpenSCAD block. ![[Articles/Linux/OpenSCAD in Obsidian/obsidian-in-openscad.gif]] The animated end result based off 'Wikipedia' / [source](https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/2D_to_3D_Extrusion), [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) - Animation by 'Mateusz Adamczyk' / blog.amatthew.eu, [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) ## References ### Section 1 - Centralising workbooks in a popular sync-enabled text editor - https://obsidian.md ### Section 2 - Why not use Visual Studio Code instead? - https://marketplace.visualstudio.com/items?itemName=Antyos.openscad - https://opencollective.com/openscad ### Section 3 - Why use OpenSCAD? - https://openscad.org/cheatsheet/ ### Section 4 - Integrating OpenSCAD with Obsidian - https://github.com/Taitava/obsidian-shellcommands - https://github.com/shabegom/buttons - https://github.com/Taitava/obsidian-shellcommands/discussions/225 - https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/2D_to_3D_Extrusion ## Metadata Date of creation: 2025.01.06 Date of revision: 2025.07.12