OpenSCAD in Obsidian
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 - text editing.
As software, 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 the workflow for different types of applications. One can easily work with SOCs (3D printer motherboards, "Arduinos", ESPs), compiled text engines like TeX, even CAD software using just VSC.
As an example - I had 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 sufficiently for an average person' needs.
Why not use Visual Studio Code then?
The answer in my case was simple - I needed just simple file management with cloud backups and quick synchronisation.
I wanted to move wildly changing prototypes of simple components off my mind so that they do not get lost in the depths of my cluttered desktop. Additionally, the ability to stash and open parts schematics (source, STL) within the same work folder is invaluable, as it leads to well organised catalogue with all parts needed.
VSC like similar development software builds atop well-tested solutions provided a long time ago, for a plenty of reasons, e.g. the GIT system, which works perfectly for versioning, collaboration, tracking, but is absolutely needless for prototyping of simple 3D parts, recipes or guides.
One may of course use an SMB, or a synced cloud drive (e.g. OneDrive, Dropbox, Mega). However this adds complexity and will not work for certain devices (e.g. smartphones).
It is an editor mostly meant for Software Development and not strictly 3D prototyping, creative works or editorial work (e.g. in LaTeX).
Why OpenSCAD?
Without delving into the area of opinions, licenses, FOSS and wizardry - 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 evaluation of those alternatives should be delegated to the individual users for an objective review*.
What is universally available, is indeed 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 you need to work with OpenSCAD is creativity, imagination and the official cheatsheet.
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 github
- "Buttons" plugin by 'shabegom (Sam)' / obsidian github
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 about a solution with the plugin's author if you know one!
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 page, which is very thorough and informative!
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.
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-open
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-png
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}}
openscad-render-stl
I will now dissect the code above into separate pieces, based on the example of the first command. The other commands differ only by the CLI arguments of the OpenSCAD program.
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 to create an OpenSCAD Obsidian notebook is to create 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.
name OpenSCAD - Open
type command
customTextColor #D1A151
action Shell commands: Execute: openscad-open
name OpenSCAD - Render PNG
type command
customTextColor #D1A151
action Shell commands: Execute: openscad-render-png
name OpenSCAD - Render STL
type command
customTextColor #D1A151
action Shell commands: Execute: openscad-render-stl
And this is it. 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.
References
Section 1 - Centralising workbooks in a popular sync-enabled text editor
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?
Section 4 - Integrating OpenSCAD with Obsidian
Member discussion