OpenSCAD Code Blocks in Org mode

To use OpenSCAD source blocks in Org mode, you must first have the OpenSCAD program itself installed on your system.

Official installers, packages, and detailed instructions are available for all major operating systems on the OpenSCAD downloads page.

• Linux: Available in most distribution repositories (e.g., sudo apt install openscad).
• macOS: Available via Homebrew (brew install openscad) or direct download.
• Windows: Available via WinGet (winget install -e OpenSCAD.OpenSCAD) or direct download.

The scad-mode package, available on MELPA, provides syntax highlighting for .scad files and Org Babel support.

1. Ensure MELPA is in your package archives.
2. Install the package:
   • M-x package-install RET scad-mode RET.
   • Or within your configuration using for instance use-package.

Add OpenSCAD support to your Babel languages:

(org-babel-do-load-languages
 'org-babel-load-languages
 '((scad . t)))

;; Optional: Set OpenSCAD executable path if not in system PATH
(setq org-babel-openscad-command "openscad")

OpenSCAD code blocks support several header arguments that map to OpenSCAD command-line options and rendering parameters:

OpenSCAD does not support persistent sessions in the traditional Babel sense, as each code block execution starts a new OpenSCAD process. However, you can use Org mode variables to maintain parameter consistency across blocks.

OpenSCAD produces model files (STL, OFF, AMF, 3MF, CSG), 2D export files (DXF, SVG), and image files (PNG) via the :file header argument. Debug output formats (AST, TERM, NEF3, NEFDBG) are also supported.

Console output from OpenSCAD's echo() function, warnings, and errors is not directly captured by Babel. To capture this output, use the shell wrapper method described in the console section.

Create a simple cube and export it as a PNG image:

#+NAME: basic-sphere
#+CAPTION: A simple sphere generated with OpenSCAD
#+HEADER: :file ./images/basic-sphere.png
#+HEADER: :colorscheme Cornfield
#+HEADER: :size 300,300
#+begin_src scad :exports results
  diameter = 10;

  color("Cornfield", 0.5) sphere(s=diameter, $fn=36);
#+end_src

When working with 2D geometries in OpenSCAD, using orthographic projection with a top-down camera view provides an accurate, undistorted representation of dimensions. This is particularly important for 2D shapes where precise measurements matter.

#+NAME: square-circle
#+CAPTION: Some 2D primitives
#+HEADER: :file ./images/some-2d-primitives.png
#+HEADER: :colorscheme Cornfield
#+HEADER: :projection ortho
#+HEADER: :camera 0,0,0,0,0,0,0
#+HEADER: :size 300,300
#+begin_src scad :exports both
  side=20; radius=10; offset=12.5;
  module place_in_quadrant(quadrant) {
    x = (quadrant==1 || quadrant==4 ? 1 : -1) * offset;
    y = (quadrant==1 || quadrant==2 ? 1 : -1) * offset;
    translate([x, y]) children(0);
  }
  place_in_quadrant(1) square(side, center=true);
  place_in_quadrant(2) circle(radius, $fn=30);
  place_in_quadrant(3) circle(radius, $fn=5);
  place_in_quadrant(4) circle(radius, $fn=6);
#+end_src

The :camera header supports two different camera modes in OpenSCAD, each with its own parameter format:

• Gimbal Camera uses the format: transx,transy,transz,rotx,roty,rotz,distance, where:
  • transx,transy,transz - Translation (movement) of the object in X, Y, Z directions
  • rotx,roty,rotz - Rotation around X, Y, Z axes in degrees
  • distance - Distance between camera and object center
• Vector Camera uses the format: eyex,eyey,eyez,centerx,centery,centerz, where:
  • eyex,eyey,eyez - Eye (camera) position coordinates
  • centerx,centery,centerz - Center (target) position coordinates

Org mode's noweb syntax allows you to break complex designs into reusable components and share parameters across multiple code blocks.

#+NAME: parametric-box-full-output
#+CAPTION: Complete output including debug messages and render statistics
#+begin_src shell :results output :exports both :noweb yes :wrap results
  output=$(openscad -o /dev/null --export-format asciistl - <<'EOF' 2>&1
  <<parametric-box>>
  EOF
  )

  echo "=== Debug Information ==="
  echo "$output" | grep -i echo

  echo
  echo "=== Render Statistics ==="
  echo "$output" | grep -v -i echo
#+end_src

#+RESULTS: parametric-box-full-output
#+begin_results
=== Debug Information ===
ECHO: "width, length, height, thickness: ", 30, 20, 10, 2
ECHO: version = [2021, 1, 0]

=== Render Statistics ===
Geometries in cache: 3
Geometry cache size in bytes: 2184
CGAL Polyhedrons in cache: 1
CGAL cache size in bytes: 23888
Total rendering time: 0:00:00.018
   Top level object is a 3D object:
   Simple:        yes
   Vertices:       16
   Halfedges:      48
   Edges:          24
   Halffacets:     22
   Facets:         11
   Volumes:         2
#+end_results

• The shell code block uses openscad -o /dev/null to discard the .stl output
• --export-format asciistl ensures OpenSCAD processes the file
• 2>&1 redirects both stdout and stderr to capture all output
• echo() statements in OpenSCAD are captured as "ECHO:" lines
• The exit code shows whether the OpenSCAD code compiled successfully

If you encounter errors like openscad: command not found, ensure OpenSCAD is installed and the path is set correctly in your Emacs Configuration using the org-babel-openscad-command variable.

OpenSCAD is strict about syntax. Use the console output capture method to debug errors (see console section).

Complex models may render slowly. Simplify designs, reduce $fn values, or use smaller :size values (e.g., :size 200,200) for faster previews.