PythonOpenScad (POSC)

Introduction

PythonOpenScad is a Python library for generating 3D models, primarily targeting OpenSCAD scripts but now also supporting direct mesh generation via the manifold3d library.

The primary client for PythonOpenScad is anchorSCAD, which is a library for generating models from Python code with much easier metaphors for building complex models (holes vs difference, composite shapes, multi-material and multi-part models, path builders, and a whole lot more). PythonOpenScad aims to provide a robust API for both script generation and direct mesh manipulation.

Installation

You can install PythonOpenScad using pip:

pip install pythonopenscad

Note: PythonOpenScad requires Python 3.10 or later.

Getting Started

1. Install OpenSCAD from openscad.org (Optional, if only using the pythonopenscad Manifold3D backend)
2. Install PythonOpenScad using pip: pip install pythonopenscad
3. Create your first model:

from pythonopenscad.posc_main import posc_main, PoscModel
from pythonopenscad import PoscBase, Cube, translate, Sphere, Color
from pythonopenscad.m3dapi import M3dRenderer

# Create a simple model
def make_model() -> PoscBase:
	  return Sphere(r=10) - Color("red")(
            Cube([10, 10, 10]).translate([0, 2, 0])
        ) - Color("cyan")(Cube([2, 2, 20]))

model = make_model()
# Save to OpenSCAD file
model.write('my_model.scad')

# Render to STL
rc = model.renderObj(M3dRenderer())
rc.write_solid_stl("mystl.stl")

# Or, view the result in a 3D viewer.
posc_main([make_model])

Note posc_main() takes a list of model generator functions with the expectation that your source code has functions for various models allowing for easier selection.

Examples

The Python code below generates a 3D solid model of text saying 'Hello world!'. This demonstrates the OpenPyScad style API. In fact, apart from the import line and conversion to string in print, this code should execute as expected using OpenPyScad.

from pythonopenscad import Text 

print(
	Text('Hello world!', size=15).linear_extrude(height=2)
		.translate([-60, 0, 0]))

However, as an alternative, SolidPython style is also supported, like this.

from pythonopenscad import text, linear_extrude, translate

print(
	translate(v=[-60, 0, 0]) (
		linear_extrude(height=2) (
			text(text='Hello world!', size=15)
		),
	)
)

The generated OpenScad code in both cases above looks like the SolidPython style code with some interesting differences, note the braces ({}) which encapsulates the list of objects that the transforms apply to.

// Generated OpenScad code
translate(v=[-60.0, 0.0, 0.0]) {
	linear_extrude(height=2.0) {
	text(text="Hello world!", size=15.0);
	}
}

Note that the OpenScad script above is all using floating point numbers. This is because PythonOpenScad converts all parameters to their corresponding expected type.

If you paste this code into OpenScad you get this:

Modules (OpenSCAD functions) and Lazy Unions

Lazy union is the implicit union for the top level node. This is an experimental feature in OpenSCAD to render multi-component models to a 3mf file. PythonOpenScad supports this feature with LazyUnion but it needs to be the top level node. Also, in order to reduce duplication of code, the Module class will replace a tree with a module call and place the module code at a lower level in the script.

from pythonopenscad import LazyUnion, Module, Text, Translate

thing1 = Text("Hello world!", size=15).linear_extrude(height=2).translate([-60, 20, 0])
thing2 = Text("Hello world 2!", size=15).linear_extrude(height=2).translate([-60, 0, 0])
print(
    LazyUnion()(
        Module("my_module")(thing1),
		Module("my_module")(thing2),
        Translate(v=[0, -40, 0])(Module("my_module")(thing1)),
    )
)

Module names are generated by comparing the node (deep compare) so even if the module names are the same, a different module name will be generated for each distinct graph.

This below is the generated OpenSCAD code. Notice that the module name for thing2 is my_module_1 and the module name for thing1 is my_module even though they are created in the same name. Name collisions are resolved by appending an underscore and a number to the module name. :

// Start: lazy_union
my_module();
my_module_1();
translate(v=[0.0, -40.0, 0.0]) {
  my_module();
}
// End: lazy_union

// Modules.

module my_module() {
  translate(v=[-60.0, 20.0, 0.0]) {
    linear_extrude(height=2.0) {
      text(text="Hello world!", size=15.0);
    }
  }
} // end module my_module

module my_module_1() {
  translate(v=[-60.0, 0.0, 0.0]) {
    linear_extrude(height=2.0) {
      text(text="Hello world 2!", size=15.0);
    }
  }
} // end module my_module_1

Notably, the module functionality is used by AnchorScad for managing multi material and multi part models. Each part/material pair will result in a module. When assembling a model, AnchorScad will combine these modules to respect the material and part priorities which can result in significant code reduction by removing duplicate code, not to mention the readability improvements.

Features

The best things come for free. You're free to use your favorite Python IDE and get all the goodness of a full IDE experience. What doesn't come for free but is very useful is listed below:

• All POSC constructors are type-checked. No generated scripts with junk inside them that's hard to trace, and full debugger support comes for free.

• Supports both OpenPyScad and SolidPython APIs for generating OpenScad code. Some differences exist between them in how the final model looks.

• New: Direct mesh generation using the manifold3d backend, allowing export to formats like STL without requiring OpenSCAD.

  • Note: The manifold3d backend currently does not implement minkowski(), import(), or surface().

• New: Includes a simple viewer and a posc_main helper function to quickly view models from your scripts (see pythonopenscad/posc_main.py and pythonopenscad/examples/primitive_viewer_example.py).

• Flexible code dump API to make it easy to add new functionality if desired.

• POSC PyDoc strings have URLs to all the implemented primitives.

• Global OpenSCAD Parameters: Set global $fn, $fa, and $fs parameters using POSC_GLOBALS that will be automatically included in generated script headers.

• Best of all, it does nothing else. Consider it a communication layer to OpenScad. Other functionality should be built as separate libraries.

Global Parameters

PythonOpenScad supports setting global OpenSCAD parameters ($fn, $fa, $fs) that control mesh resolution and fragment generation. These can be set using the POSC_GLOBALS object:

from pythonopenscad import POSC_GLOBALS, Sphere

# Set global parameters
POSC_GLOBALS._fn = 50  # Use 50 fragments for all circular shapes
POSC_GLOBALS._fa = 6   # Minimum angle of 6 degrees
POSC_GLOBALS._fs = 0.5 # Minimum segment length of 0.5

# These will be included in the generated script header
sphere = Sphere(r=10)
print(sphere)  # Will include "$fn = 50;" etc. at the top

You can also override these per-object or per-operation:

# Override global settings for specific objects
sphere_high_res = Sphere(r=10, _fn=100)  # This sphere uses 100 fragments

# Override when writing/dumping
sphere.write('output.scad', _fn=200)  # Override global _fn when writing

POSC Compatibility with the OpenPyScad and SolidPython APIs

Each POSC object contains member functions for all the OpenScad transformations. (Note: these functions are simply wrapper functions over the transformation class constructors.) This API style is more traditional for solid modeling APIs. However, the POSC implementation gives no preference between either style, and objects created with one API can be mixed and matched with objects created using the other API. All the OpenPyScad equivalent classes have capitalized names, while the SolidPython classes have lowercase names (the classes are different but they can be compared for equality). For example:

	>>> from pythonopenscad import Text, text
	>>> Text() == text()
	True
	>>> Text('a') == text()
	False

OpenPyScad's modifier interface is not implemented but a different PythonOpenScad specific API accomplishes the same function. Modifiers are flags. In PythonOpenScad There are 4 flags, DISABLE, SHOW_ONLY, DEBUG and TRANSPARENT. They can be added and removed with the add_modifier, remove_modifier and has_modifiers functions.

License

PythonOpenSCAD is available under the terms of the GNU LESSER GENERAL PUBLIC LICENSE.

Copyright (C) 2025 Gianni Mariani

PythonOpenScad is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser Gene