Cadmium – Solid modelling library #python #opensource

This post turned out to be very lengthy. You can skip through the first half, if you only want to learn about the library itself.

One of the goals of 3DTin is simple interface. But that shouldn’t make 3DTin unsuitable for advanced modelling. Therefore I invested lot of time during past few months, learning how advanced modeling works and I also tried to observe the traditional CAD tools to learn why they are so difficult to master.

One of the observations I’ve had is: a 3D CAD software that runs on a traditional computer has some fundamental limitations imposed by the hardware. The 3D environment that a software can create on a computer with a two dimensional display, keyboard and mouse, is only suitable to render 3D output, but is awkward to take 3D input from the user.

The computer industry has worked hard to optimize the way a software can create 3D environment on a computer. They have developed dedicated hardware to do that and it is now possible to render nearly life like 3D environments on the two dimensional monitor. This progress has mostly been driven by huge popularity of Computer Games. Games demanded 3D environments that have rich and detailed geometry. Therefore 3D output was optimized to great lengths. On the other hand, these games did not require sophisticated 3D input. A first person shooter game can easily be played with simple movement of mouse or W-A-S-D key sequence on keyboard. But when it comes to CAD software, the requirements are different.

A 3D CAD software has to render a 3D environment and also has to give user the ability to modify every aspect of it. Here, 3D input is as important as 3D output, if not more. The ideal hardware for this job is a holographic display, with a sensor that can sense position of your fingers in 3D space. Sadly, we are not there yet (except few brave souls).

Therefore a CAD software running on a traditional computer, can provide an intuitive interface only to a certain point. It can let the user navigate the 3D space and may be do some simple operations like addition/removal of geometry; but any advanced operations beyond that require an interface that involves elaborate menu systems, operating modes, context menus and lengthy toolbars. Traditional CAD tools have done very good job in providing advanced functionality through this interface. Especially tools like Google Sketchup have made the most of what a desktop computer has to offer. This scheme however has a drawback. It requires a lot of effort and patience to learn. It doesn’t help that different CAD packages have their own abstractions and conventions, there is no consistency in the modeling interface across two different CAD tools.

As a result, typically when you are learning to use one of these software you end up googling “How to do X in Y”, where X is some modeling task and Y is the CAD software you are using. You end up with blog posts or youtube videos that tell you how to do it. They explain which buttons to press, which menus and submenus to open in which sequence. Eventually you get the job done and feel a sense of achivement, only until you have to return back to Google for different value of X.

This workflow is essentially an exchange of information about how to perform certain modeling task. Because the functionality to do it, is provided as non-standard menus and buttons, there is no other way to communicate it but to describe it using words, pictures and videos. But it makes the information exchange very inefficient.

What if we perform our modeling tasks through a scripting language, instead of menus and buttons? Instead of providing the modelling features through a series of menus and buttons, we provide them through a scripting language. A script that performs modeling operations one after the other and generates solid models as a result. With the modeling operations encoded in a formal language, we can easily exchange each other’s recepies. In fact, this method will be so transparent that you won’t have to understand the scripts yourself. One person can create a script for a particular model and share it with others. Others then just have to import it into their project and instantiate it. One can even customize the properties of final solid by accepting them as parameter values.

As some of you know, this is not a new idea. In fact, IIRC I started thinking along these lines after learning about the OpenSCAD project.

OpenSCAD developers have created a scripting environment that lets you compose advanced solid models by writing a program in a special language they have designed for the purpose. I loved their approach (except for the language syntax). Since then, I have studied and hacked the open source solid modeling libraries to understand how this is done. And after months of effort I’ve come up with a solution that I would like to share with you. It’s not entirely clear yet, how this project will become part of 3DTin that you use today, but I want to get it out for you to play with. And unlike the client side 3DTin code, this new work is open source. You will be able to use it even without 3DTin.


Cadmium is a Python library for solid modeling. It lets you write a Python script to create solid models. You can define some primitive objects like Box, Cylinder, Sphere, Cone, and then perform standard CSG operations on them by using standard arithmetic operators – Union (+), Subtraction (-), Intersection (*). You can export the final solid into STL file by calling toSTL().

Here is an example of how simple that is.


Here is a screenshot of the generated model.


You can see screenshots of more advanced solids, alongside the cadmium scripts that generated them on the project page. You can get the source on github.

I fetched some OpenSCAD scripts from Thingiverse over weekend and ported them to Cadmium. You can see the results on the page linked above.

The Cadmium library is a thin layer on top of PythonOCC. Most of the modeling algorithms are implemented in OpenCASCADE, for which PythonOCC are a set of python bindings. Cadmium merely creates a set of abstractions that are easy to understand and use.

Cadmium is inspired by OpenSCAD, but it is a completely independent implementation. It has certain advantages over OpenSCAD.

  • No need to learn a new language. It’s all Python code.
  • Cadmium has no GUI, which makes it very light weight and portable. Cadmium let you export the output in STL file, which can be viewed in an STL viewer software of your choice.
  • Cadmium itself is written in pure python and you can run it on any platform where you can install PythonOCC (Windows/Linux/OSX)
  • Because it runs in standard python interpreter you can use advanced features of Python for free – the math module, complex number support, recursion – to name a few.

I announced this project on OpenSCAD and PythonOCC mailing lists last week and have received very positive response so far.

The library is usable today, but it is still in early stages. It will require more work in coming days.

I would like to collect your feedback on it. Feel free to file feature requests, bug reports and send patches.

This entry was posted in Uncategorized. Bookmark the permalink.

4 Responses to Cadmium – Solid modelling library #python #opensource

  1. It’s a shame you don’t have a donate button! I’d most certainly donate to this excellent blog! I suppose for now i’ll settle for book-marking and adding your RSS feed to my Google account. I look forward to fresh updates and will share this website with my Facebook group. Chat soon!

  2. Pingback: Geometry Builder (featuring CSG Subtraction) | 3DTin

  3. George says:

    What a good job you have done,I am looking for it long time. No need to learn a new language,just use python I can write CAD script,really save me a lot of time.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s