SolidPython Documentation

py_scadparser is a basic OpenSCAD parser written in Python using ply. Its primary purpose is to enable solidpython to import existing OpenSCAD code.

Instead of parsing the entire language for execution, it focuses on extracting top-level global definitions from an OpenSCAD file, which includes:

• use() and include() filenames
• Global variables
• Function definitions
• Module definitions

SolidPython provides syntactic sugar by overriding basic operators to perform OpenSCAD boolean operations:

• + (Union): obj1 + obj2 is equivalent to union()(obj1, obj2).
• - (Difference): obj1 - obj2 is equivalent to difference()(obj1, obj2).
• * (Intersection): obj1 * obj2 is equivalent to intersection()(obj1, obj2).
• In-place subtraction: obj1 -= obj2 performs a difference operation.

c = cylinder(r=10, h=5) + cylinder(r=2, h=30)
c = cylinder(r=10, h=5)
c -= cylinder(r=2, h=30)

To simplify complex boolean subtractions, SolidPython uses hole() and part().

• hole(): Wraps an object to designate it as a void. When added to other objects, the void area is preserved.
• part(): Used to specify that a certain part of a structure is intended to receive or occupy a space defined by a hole.

This prevents the need for complex manual union/difference ordering when creating joints or hollow structures.

outer = cylinder(r=pipe_od, h=seg_length)
inner = cylinder(r=pipe_id, h=seg_length)
pipe_a = outer - hole()(inner)

You can install the latest release of SolidPython via PyPI or install the current master branch directly from GitHub.

To install from PyPI:

pip install solidpython

To install from GitHub:

pip install git+https://github.com/SolidCode/SolidPython.git

To visualize SolidPython or OpenSCAD code directly within a Jupyter notebook, use the ViewSCAD library. You can install it via pip:

pip install viewscad

Note: Additional installation steps may be required depending on your environment; refer to the ViewSCAD repository for specific setup instructions.

SolidPython allows you to generate valid OpenSCAD code using Python syntax.

1. Import the library: Use from solid import * and optionally from solid.utils import *.
2. Define geometry: Use Python functions (like cube(), sphere(), difference()) to build your model. Note that OpenSCAD curly-brace blocks are represented by parentheses with comma-delimited lists in SolidPython.
3. Render the code:
   • Use scad_render(py_scad_obj) to get the OpenSCAD code as a string.
   • Use scad_render_to_file(py_scad_obj, 'filepath.scad') to save the code to a file. If the file is open in the OpenSCAD IDE with 'Automatic Reload and Compile' enabled, the model will update automatically.

from solid import *
from solid.utils import *

d = difference()( 
    cube(10), 
    sphere(15) 
)
print(scad_render(d))

You can import existing OpenSCAD modules or libraries into your SolidPython script using solid.import_scad(path).

• Single file: import_scad('/path/to/scadfile.scad') returns an object where the SCAD modules become methods of that object.
• Directory (Recursive): Passing a directory argument to import_scad() allows for recursive importing of libraries (like MCAD).
• Namespace pollution: While use() and include() are available to mimic OpenSCAD behavior, they pollute the global namespace. import_scad() is generally preferred as it keeps imports contained within an object.

Example of importing a module from a file:

from solid import *

scadfile = import_scad('/path/to/scadfile.scad') 
# If scadfile.scad has a module 'box(w,h,d)'
b = scadfile.box(2,4,6)
scad_render_to_file(b, 'out_file.scad')

The solid.splines module provides functions to generate smooth curves through control points using Catmull-Rom or Bezier algorithms. This is useful for creating organic or curved shapes in OpenSCAD via Python.

Key functions:

• catmull_rom_polygon(points, show_controls=True): Generates a Catmull-Rom curve polygon. Use show_controls=True to visualize the control points.
• bezier_polygon(points, subdivisions=20): Generates a Bezier curve polygon. The subdivisions parameter controls the smoothness of the curve.

from solid import translate
from solid.splines import catmull_rom_polygon, bezier_polygon
from euclid3 import Point2

points = [ Point2(0,0), Point2(1,1), Point2(2,1), Point2(2,-1) ]  
shape = catmull_rom_polygon(points, show_controls=True)

bezier_shape = translate([3,0,0])(bezier_polygon(points, subdivisions=20))