Skip to main content

An interpreter for OpenSCAD that renders to build123d objects

Project description

buildSCAD

An interpreter for OpenSCAD that emits OCC objects, wrapped with build123d.

Rationale

Today's 3D programs can import STEP models, thus can deal with "real" curves and solids instead of mesh approximations.

Unfortunately, the CGAL 3D package used by OpenSCAD is mesh-based. Owch.

On the other hand, OpenSCAD is somewhat widely used for creating parameterized models algorithmically. Sites like Thingiverse or Printables contain quite a few models built with it.

This package translates OpenSCAD to "real" 3D models.

Approach

The OpenSCAD code is parsed into a syntax tree and interpreted on the fly when a "module" (in OpenSCAD terms) is called.

The result is an OCC Solid (or sketch if 2D), wrapped with build123d, and can be used just like any other object.

Functional replacements

If a module cannot be implemented in build123d/OCC, most likely because it uses hull or minkowsky, often the most expedient fix is to write a replacement in Python.

To use this feature, simply add a function with the desired name to the environment you pass to process, or pre-load a Python file.

In order to read global variables, functions may access the current environment via the contextvar buildscad.env.

Limitations

This tool started off as a proof of concept. A lot of methods and some support functions are not implemented yet, though the grammar itself should be complete.

Variables whose name start with a '$' are usable. However, they cannot be passed to functions as keywords. Instead, $-prefixed keywords get passed to called functions in the environment so that functions implemented in Python don't have to deal with them.

Corollary: Don't even think of creating a six-sided polygon by using circle(r=2, $fn=6) with this code.

Speed could probably be improved; on the other hand, let's face it, OpenSCAD's mesh rendering can be slow as molasses too.

The minkowski and hull operators don't exist in build123d. Implementing them is way out of scope for this project.

undef is evaluated as None.

Differences to OpenSCAD

Evaluation Order

Our parser delays evaluation of variables until they're needed.

In other words, this …

:: bar = foo(123); function foo(x) = x;

… works just fine.

Variable handling

Unknown variables (i.e. those that are never assigned to) cause an error. As in OpenSCAD, unfilled parameters are "undef", i.e.

function xx(a,b) = b;
echo(xx(1));

does emit "ECHO: undef".

Value redefinition

Updating a variable will emit a warning but not change the value.

Included Files

Variables declared in include files can be overridden in the main code, as in OpenSCAD. However, values from included files don't filter back to the main code.

Invalid Values

OpenSCAD tends to return undef whenever it doesn't understand something, which typically results in any numer of follow-up warnings.

We don't do that. Errors raise exceptions.

Testing

The subdirectory tests/models includes various OpenSCAD files, with accompanying Python code.

The models in these files are built in three ways:

  • directly by OpenSCAD
  • by emulating OpenSCAD
  • by Python code

The test builder calls the work function (Python) / module (OpenSCAD). If that doesn't exist, top-level objects (OpenSCAD) / variables (Python) are used.

The following special constants are recognized:

  • tolerance

    The maximum difference (volume) between the various models. The default is 0.001 but anything that depends on OpenSCAD's $fn probably requires looser constraints.

  • volume

    The volume (in mm³) that the model is supposed to have.

  • skip

    Skip this test when auto-running.

  • no_add

    When set to True, do not add the various volumes. This is a workaround for an OCC bug which causes an endless loop.

    Setting this flag causes this testcase to only compare volumes and bounding boxes, which is not as accurate.

  • trace

    Log (some) calls to build123.

If the Python part only contains constants, it must declare work=None. Otherwise the test code assumes that you wrote e.g. Sphere(42) without assigning the result to anything, and thus refuses to accept the testcase.

If you want to test a functional result against OpenSCAD, the best way is to create a Box(result,1,1) object.

Viewing tests

examples/test_viewer.py can be opened with CQ-Editor to compare models visually.

Test Traces

If the testcase sets tracing=True, the actual build123d calls will be logged and the STL file from OpenSCAD will not be deleted.

This is mainly useful for generating a test case for bug reports that doesn't depend on this code.

Trace support is still somewhat incomplete.

TODO

To fix:

  • linear_extrude with scaling
  • linear_extrude with scaling and twist
  • polyhedrons
  • use/include from a library (via envvar OPENSCADPATH)

Implement a lot of functions.

Improve error reporting.

Test working with 2D.

An option to generate a build123d script instead of the actual objects would be nice.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

buildscad-0.4.1.tar.gz (31.0 kB view details)

Uploaded Source

Built Distribution

buildscad-0.4.1-py3-none-any.whl (26.3 kB view details)

Uploaded Python 3

File details

Details for the file buildscad-0.4.1.tar.gz.

File metadata

  • Download URL: buildscad-0.4.1.tar.gz
  • Upload date:
  • Size: 31.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.6

File hashes

Hashes for buildscad-0.4.1.tar.gz
Algorithm Hash digest
SHA256 36101fc36fafcd76df725fb811f7591db2836fb8e034424bd761160e7736ac57
MD5 a3ad6cb4ef7626fb1cc07e95a454d7ee
BLAKE2b-256 7762fbc4d8f8ef8953cd267182ec726dd31977831c145eadab9c7e77e1023742

See more details on using hashes here.

File details

Details for the file buildscad-0.4.1-py3-none-any.whl.

File metadata

  • Download URL: buildscad-0.4.1-py3-none-any.whl
  • Upload date:
  • Size: 26.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.6

File hashes

Hashes for buildscad-0.4.1-py3-none-any.whl
Algorithm Hash digest
SHA256 9d887c535bb07e729c91341943c35bfb477d49ce3bd6f5a8b3a4bfa0c0238fd7
MD5 233f780ca1e170a834ceb0107b2daefa
BLAKE2b-256 abec67d394b4960854587c9785c1b6ee8605c509a4ea08b3dcb28aeec93f3763

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page