![[Content/SysAdmin/OpenSCAD in Obsidian/cover.png#center | Rendered 3D object using OpenSCAD in Obsidian - Screenshot by 'Mateusz Adamczyk' / blog.amatthew.eu, CC BY-SA 4.0]]
## Sections
### Sync-enabled text editor
Obsidian is a popular text editor, widely used for writing *Markdown* notes. It is quite versatile, yet does a solid job in its primary domain of operations - text editing and storage.
It offers support, to a far less extent, of rendering graphs, visualising data for note-keeping purposes and even publishing (web) notes (this blog included). However due to its primary design, it holds a slight edge over average CAD software.
Obsidian offers:
- support for a variety of community plugins
- *letting the editor be somewhat hackable*
- adjustable interface themes
- *making contents easy to read*
- backups and synchronisation across different devices
- *protecting files through redundancy*
- file templates, convenient management of folders and support for attached binary data, e.g. images, PDF files
- *allowing for custom code snippets and even whole documentation files*
### Why not Visual Studio Code
VSC also support very creative and helpful extensions, that accelerate different types of workflows. The user may easily begin working with programmable 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?
<sup>guilty as charged...</sup>
To paint a picture - I have tried out an extension called "OpenSCAD" by **"Antyos"**, which is meant to render VSC's file context inside OpenSCAD, then bring back the renderer's window for a preview. It works pretty well.
However - I also needed **just** simple file management with automatic backups and quick synchronisation. The last part is not supported in pure VSC, an additional backup software would be required.
The concept was to unload changing prototypes of simple components from my mind so that they do not get lost in the depths of my cluttered desktop (~~or my head~~).
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.
<center><img src="https://media.tenor.com/G-YJxIC925EAAAAM/spongebob-collector.gif"></center>
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 and binary files.
An SMB or cloud drives may be used instead (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)', MIT [[#^2|(2)]].
<center><iframe src="https://gitfood.org/" height="400" width="600"></iframe></center>
### Why OpenSCAD?
Without delving too much - Linux users have limited support from major CAD software developers. There are *some* alternatives to popular proprietary software available on MacOS and Windows, but the evaluation of those alternatives is to be carried out individually...
<center><img src="https://media1.tenor.com/m/IsFEFtj5-Q0AAAAd/the-office-i-dont-like-it.gif"></center>
What software remains universally available, even if quite complicated, yet more conveniently in different aspects - 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 compatible and relatively simple. 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.
OpenSCAD cheatsheet [[#^4|(4)]]
![[Content/SysAdmin/OpenSCAD in Obsidian/Pasted image 20250103211757.png#center | OpenSCAD Cheatsheet - by 'Peter Uithoven' / openscad.org, CC-BY]]
### Integrating OpenSCAD with Obsidian
#### Dependencies
What is 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)
>[!Warning]
>It is important to understand that Obsidian **must** be installed as a non-isolated binary package.
Obsidian may be installed in different ways, yet when using the Flatpak distribution it will be executed inside a 'sandboxed' (so restricted) environment.
You can [discuss](https://github.com/Taitava/obsidian-shellcommands/discussions/225) about a solution with the plugin's author if you know one.
![[Content/SysAdmin/OpenSCAD in Obsidian/Pasted image 20250106131140.png#center | Flatpak runtimes - Screenshot by 'Mateusz Adamczyk' / blog.amatthew.eu, CC BY-SA 4.0]]
The Flatpak use-case 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.
#### Steps
- 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!
![[Content/SysAdmin/OpenSCAD in Obsidian/Pasted image 20250106141400.png#center | Preview of OpenSCAD in Obsidian - Screenshot by 'Mateusz Adamczyk' / blog.amatthew.eu, CC BY-SA 4.0]]
![[Content/SysAdmin/OpenSCAD in Obsidian/Pasted image 20250108001517.png#center | Example of a custom command - Screenshot by 'Mateusz Adamczyk' / blog.amatthew.eu, CC 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 break down the code above into separate parts to explain what each part does.
`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 build 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.
>[!Success]
>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.
The animated end result using modified a CC BY-SA 4.0 'Wikipedia' example [[#^9|(9)]].
![[Content/SysAdmin/OpenSCAD in Obsidian/obsidian-in-openscad.gif#center | Example 3D figure - Animation by 'Mateusz Adamczyk' / blog.amatthew.eu, CC BY-SA 4.0]]
## References
### Section 1 - Sync-enabled text editor
- https://obsidian.md ^1
- https://github.com/jondavid-black ^2
### Section 2 - Why not Visual Studio Code
- https://marketplace.visualstudio.com/items?itemName=Antyos.openscad
- https://opencollective.com/openscad ^3
### Section 3 - Why OpenSCAD?
- https://openscad.org/cheatsheet/ ^4
### Section 4 - Integrating OpenSCAD with Obsidian
- https://github.com/Taitava/obsidian-shellcommands ^5
- https://github.com/shabegom/buttons ^6
- https://github.com/Taitava/obsidian-shellcommands/discussions/225 ^7
- https://docs.flatpak.org/en/latest/available-runtimes.html ^8
- https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/2D_to_3D_Extrusion ^9
## Metadata
Date of creation: 2025.01.06
Date of revision: 2026.01.27