Getting started with pythonocc

Release 0.16.0

Thomas Paviot

November 13, 2014

CONTENTS

Introduction

Build / Install
2.1 Build / install from source . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Download / install precompiled binaries . . . . . . . . . . . . . . . . . . . . .
2.3 Conda packages (OSX only) . . . . . . . . . . . . . . . . . . . . . . . . . . .

5
5
6
7

Thirty minutes with pythonocc

9
3.1 The use-case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2 Import a standard file and display a shape . . . . . . . . . . . . . . . . . . . . 10
3.3 Create the mold print using a boolean cut operation . . . . . . . . . . . . . . . 13

Conclusion

17

Indices and tables

19

ii

Getting started with pythonocc, Release 0.16.0

Contents:

CONTENTS

Getting started with pythonocc, Release 0.16.0

CONTENTS

CHAPTER

ONE

INTRODUCTION

This document explains how to get starting with pythonocc: how to build/install, 30 first minutes experience with the package.
pythonocc will allow you to write python scripts that creates and operates 3D BRep geometry.

Getting started with pythonocc, Release 0.16.0

Chapter 1. Introduction

CHAPTER

TWO

BUILD / INSTALL

The build system uses cmake to configure the project. This is a crossplatform solution: steps
below are the same for Linux, OSX, or Windows platforms.

2.1 Build / install from source

2.1.1 Requirements
pythonOCC needs the following libraries or programs to be installed before you can compile/use it :
the python programming language (http://www.python.org). Python 2.7 and 3.x are officially supported,
OpenCascade Community Edition 0.16 (https://github.com/tpaviot/oce),
SWIG 2.0.10 or higher (http://www.swig.org),
CMake 2.8 or higher (http://www.cmake.org).

2.1.2 pythonocc-core compilation

From the current directory:
$ cd pythonocc-core
$ mkdir cmake-build
$ cd cmake-build

The configuration steps uses cmake:

$ cmake ..

By default, cmake looks for oce include headers in /usr/local/include/oce and libraries
in /usr/local/include/lib. If these paths dont match your installation, you have to set
OCE_INCLUDE_PATH and OCE_LIB_PATH

Getting started with pythonocc, Release 0.16.0

$ cmake -DOCE_INCLUDE_PATH=/your_oce_headers -DOCE_LIB_PATH=/your_lib_dir ..

If you prefer, you can launche the cmake-gui using the following command
$ cmake-gui ..

And launch the build process

$ make

If you have many cpus, you can increase the compilation speed with::
$ make -j$ncpus

According to your machine/os/ncpus, the total compilation time shold be between 5 to 15

minutes.
Then
$ make install

You may require admin privileges to install

$ sudo make install

2.1.3 test
In order to check that everything is ok, run the pythonocc unittest suite:
$ cd ../test
$ python run_tests.py

You can also run the examples avalaible in the pythonocc-core/examples directory.

2.2 Download / install precompiled binaries

Windows
Binary packages for Windows/py2 and py3 are available at our github release page.
Debian
.deb binary packages are available at our github release page.
Ubuntu

Chapter 2. Build / Install

Getting started with pythonocc, Release 0.16.0

$
$
$
$

sudo
sudo
sudo
sudo

add-apt-repository ppa:freecad-maintainers/oce-release -y
add-apt-repository ppa:tpaviot/pythonocc -y
apt-get update -q
apt-get install pythonocc-core

OSX
.dmg binary package is available at our github release page.

2.3 Conda packages (OSX only)

Packaging with conda
pythonocc depends on one of the largest Open Source code bases out there, OpenCasCADE
specifically, the OpenCasCADE Community Edition (oce).
conda is a solution to install pythonOCC and all of its dependencies in about 5 minutes.
How is this done?
First, decide if you prefer the completeanaconda <http://docs.continuum.io/anaconda/index.html#packagesincluded-in-anaconda>_ that comes with many great modules readily installed or a lighter
handed approach (prefered), by installing miniconda. This is accomplished through the
following command on linux:

$ curl 'http://repo.continuum.io/miniconda/Miniconda-3.7.0-Linux-x86_64.sh' > Mi

$ bash Miniconda.sh

and for mac osx through:

$ curl 'http://repo.continuum.io/miniconda/Miniconda-3.7.0-MacOSX-x86_64.sh' > M

$ bash Miniconda.sh

that installs a fresh python interpreter.

As of now, only an osx build is completed, as conda support for pythonocc is a work in progress.
You can install pythonocc-core like so:
#
$
#
$
#
$

add the channel

conda config --add channels http://conda.binstar.org/jf
create a pythonocc environment
conda create -n pythonocc python
grab and install pythonocc
conda install pythonocc-core

Youre encouraged to install a GUI manager PyQt4 or wxPython:

$ conda install pyqt

2.3. Conda packages (OSX only)

Getting started with pythonocc, Release 0.16.0

Environments
Environments are a very important concept, and conda provides more fundamental support
for environments than for instance virtualenv. This is again, related to dependencies. With
conda, mutiple version of pythonocc supporting different version of the OCE library can be
supported. By changing your environment, its easy to upgrade your codebase to a newer version
of PythonOCC while still being able to switch to any older version.
packages at binstar
binstar is a site where you can upload and distribute your own repository of packages (heres
Jelle). Ownership of packages can be shared, which is great for working together on supporting
a package for different platforms. Check out available packages by the [maintainer of conda
and binstar](https://binstar.org/asmeurer/_list-packages)
Contribute pythonocc package for your platform
Using conda, you can also compile and upload binaries with others. First install necessary stuff
to build conda packages:
$ conda install conda-build
$ conda install jinja2

The build the package:

$ cd pkg/conda
$ conda-build .

To go further
If your interested to learn more about conda, check out the documentation. Youre also encouraged you to see this excellent talk by Aaron Meurer.

Chapter 2. Build / Install

CHAPTER

THREE

THIRTY MINUTES WITH PYTHONOCC

In this section, you will discover, in less than 30 minutes, a set of features that covers the
following fields: data import from a STEP AP 203 file, modeling a box, perform a boolean
operation (cut), visualize a shape and render in WebGl.
This tutorial is based upon the ipython console: the qt ipython mode allows an interactive session with pythonocc, without worrying about gui/event management/program freeze comming
along.

3.1 The use-case

The use case suggested comes from a current situation in the industry: youre a manufacturing
engineer, specialized in molding, receiving a 3d model for which you have to design the mold.
Your customer needs your skills to produce a set of 10.000 engines block, as you can see on
figure model_engine .
Your customer uses a famous CAD package to design its products: Autodesk Inventor Professional 15 (see image 2).

Getting started with pythonocc, Release 0.16.0

3.2 Import a standard file and display a shape

3.2.1 Launch the ipython environnement
$ ipython --gui='qt'

You should have a python prompt.

3.2.2 Import the STEP file

The customer sent to you, via an email, a 2.2Mb step file: cylinder_block.stp, generated with Autodesk Inventor (Note: most CAD vendors provide this feature).
A STEPControl_Reader instance is necessary to read/import STEP files::
from OCC.STEPControl import STEPControl_Reader
step_reader = STEPControl_Reader()
step_reader.ReadFile('../_models/cylinder_block.stp')
step_reader.TransferRoot()
block_cylinder_shape = step_reader.Shape()
...
Step File Reading : ../_models/cylinder_block.stp
...
STEP File
Read
...
Elapsed time: 0 Hours 0 Minutes 0.056925 Seconds
CPU user time: 0.04 seconds
CPU system time: 0 seconds
>>>
>>>
>>>
>>>
>>>

10

Chapter 3. Thirty minutes with pythonocc

Getting started with pythonocc, Release 0.16.0

... Step File loaded ...

Elapsed time: 0 Hours 0 Minutes 0.110026 Seconds
CPU user time: 0.09 seconds
CPU system time: 0.01 seconds
54737 records (entities,sub-lists,scopes), 171664 parameters
... Parameters prepared ... Elapsed time: 0 Hours 0 Minutes 0.158572 Se
CPU user time: 0.13 seconds
CPU system time: 0.01 seconds
Report : 4 unknown entities
...
Objets analysed ...
Elapsed time: 0 Hours 0 Minutes 0.239736 Seconds
CPU user time: 0.21 seconds
CPU system time: 0.02 seconds
STEP Loading done : 31486 Entities

STEP file was successfull. Lets now display the shape in the graphic window.

3.2.3 Display the block engine shape

First import the module providing a basic qt based gui
>>> from OCC.Display.SimpleGui import init_display

Then initialize the graphic window

>>> display, start_display, add_menu, add_function_to_menu = init_display()
###### 3D rendering pipe initialisation #####
Display3d class initialization starting ...
Aspect_DisplayConnection created.
Graphic_Driver created.
Cocoa window created.
V3d_Viewer created.
V3d_View created
AIS_InteractiveContext created.
Display3d class successfully initialized.
########################################

You should now see a graphic window, empty, with just a rvb triedron at the lower right corner.
Just pass the blocke_engine_shape to the display, and ask for a refresh
>>> display.DisplayShape(block_cylinder_shape, update=True)

You can see the cylinder block shape, in a light orange color.
Using your mouse you can: * left click and move to rotate * right click and move to pan *
middle click (or mouse wheel) and move to zoom in/out.
3.2. Import a standard file and display a shape

11

Getting started with pythonocc, Release 0.16.0

12

Chapter 3. Thirty minutes with pythonocc

Getting started with pythonocc, Release 0.16.0

You can also : * type a/b: enable/disable antialiasing * type w/s: switch from wireframe
to shaded representation modes
A lot more things can be customized though.

3.3 Create the mold print using a boolean cut operation

3.3.1 Loads the step file
Reproduce the previous steps from scratch, import and display the step file
cylinder_block_mold_model.stp. It is the shape from which the mold will be
created.

3.3.2 Create the mold basis: a box

We need the BRepPrimAPI_MakeBox class to create the box, then a transformation to move
it along the y and z axis

3.3. Create the mold print using a boolean cut operation

13

Getting started with pythonocc, Release 0.16.0

>>>
>>>
>>>
>>>
>>>
>>>
>>>

from OCC.BRepPrimAPI import BRepPrimAPI_MakeBox

from OCC.gp import gp_Vec, gp_Trsf
from OCC.BRepBuilderAPI import BRepBuilderAPI_Transform
box = BRepPrimAPI_MakeBox(30, 90, 90).Shape()
trns = gp_Trsf()
trns.SetTranslation(gp_Vec(0, -35, -35))
mold_basis = BRepBuilderAPI_Transform(box, trns).Shape()

The mold basis is created, lets display it with another material

>>> from OCC.Graphic3d import Graphic3d_NOM_STEEL
>>> display.DisplayShape(mold_basis, update=True, material=Graphic3d_NOM_STEEL)

And here is what we obtain

3.3.3 Compute the mold print

We have to perform a boolean cut operation between the box and the block. This is achieved
using the BRepAlgoAPI_Cut class

14

Chapter 3. Thirty minutes with pythonocc

Getting started with pythonocc, Release 0.16.0

>>> from OCC.BRepAlgoAPI import BRepAlgoAPI_Cut

>>> mold = BRepAlgoAPI_Cut(mold_basis, block_cylinder_shape).Shape()

Display the result, but first erase what is curently displayed

>>> display.EraseAll()
>>> display.DisplayShape(mold, update=True, material=Graphic3d_NOM_STEEL)

Here we are!

3.3.4 At last, display the shape in the browser

Imagine you want to share the shape with someone would dont have any CAD software installed, of no STEP or CAD file viewer. Lets provide him a single html page he will be able to
view in its web browser, without any plugin. For that, we will use the x3dom renderer.
>>> from OCC.Display.WebGl import x3dom_renderer
>>> my_webgl_renderer = x3dom_renderer.X3DomRenderer()
>>> my_webgl_renderer.DisplayShape(mold)

3.3. Create the mold print using a boolean cut operation

15

Getting started with pythonocc, Release 0.16.0

Your default webbrowser will display the generated html page: handle the 3D model the same
way you did it in the qt based window.

16

Chapter 3. Thirty minutes with pythonocc

CHAPTER

FOUR

CONCLUSION

There are many many more features available in pythonocc. To go further, here is what you
can do:
go to the /examples folder and run/study/modify what you see,
read the api documentation,
ask questions to pythonocc@googlegroups.com,
check oce.
Please report to tpaviot@gmail.com any comment or suggestion to improve this document.

17

Getting started with pythonocc, Release 0.16.0

18

Chapter 4. Conclusion

CHAPTER

FIVE

INDICES AND TABLES

genindex
modindex
search

19