PyAnatomist programming documentation

First, have a look at the PyAnatomist overview slides, which were presented at the Python in Neuroscience 2011 conference on 2011/08/30.


This API enables to drive Anatomist application throught python scripts : running Anatomist, loading volumes, meshes, graphs, viewing them in windows, merging objects, changing colour palette…

  • organization: NeuroSpin and IFR 4
  • license: CeCILL-v2 (GPL-compatible)

From version 4.7.0 and later, PyAnatomist work with both Python 2 (2.7 and later) and Python 3 (3.4 and later) (provided C++/python bindings have been compiled appropriately).

The main entry point is one of the anatomist.base.Anatomist-inhertied classes which must be instantiated before any operation can be performed. It represents Anatomist application. This class contains a number of nested classes: anatomist.base.Anatomist.AObject, anatomist.base.Anatomist.AWindow… that represents handling elements of Anatomist application.

The entry point of this API is the module api, you can import it as below :

>>> import anatomist.api as anatomist

And then create an instance of Anatomist :

>>> a = anatomist.Anatomist()

So you can send commands to Anatomist application, for example creating a window :

>>> window = a.createWindow('3D')


Several means of driving Anatomist in python scripts exist : Python bindings for the C++ library (SIP bindings), or sending commands via a network socket. Behind a general interface, this api provides 2 implementations, one for each method.

Modules organization

  • anatomist.base module contains the general interface : classes and methods that exist in all implementations. This module also provides the general API documentation.
  • anatomist.socket.api module contains an implementation using socket communication with an Anatomist application run in another process in server mode.
  • anatomist.direct.api module contains an implementation using sip bindings of Anatomist C++ api.
  • anatomist.threaded.api module is a thread safe layer for the direct module. Useful if you have to use anatomist api in a multi-threaded environment.
  • anatomist.headless module is an off-screen redirection of Anatomist display.
  • anatomist.cpp module contains sip bindings of Anatomist C++ api. It is a low level module, only for advanced user.
  • Work in progress work in progress module

The direct implementation provides more features as it handles C++ binding objects: all bound features are available. Socket implementation provides features that can be expressed with Anatomist commands system, so a limited set of features. But it runs Anatomist application in a separate process so potential errors in Anatomist don’t crash the application that uses the API.

By default, the implementation used when you import anatomist.api is the direct implementation. If you want to switch to another implementation, use setDefaultImplementation of this module. For example to use the socket implementation :

>>> import anatomist
>>> anatomist.setDefaultImplementation(anatomist.SOCKET)
>>> import anatomist.api as anatomist

Another specific implementation for Brainvisa also exists: brainvisa.anatomist module in brainvisa. It enables to use brainvisa database informations on loaded objects to automatically load associated referentials and transformations. It uses the same api, so it is possible to switch from one implementation to the other.

By default, brainvisa module uses socket implementation. This way, Brainvisa and Anatomist applications run in separated processes. and potential errors in Anatomist do not crash Brainvisa.


str – Use this constant to load anatomist api socket implementation. See anatomist.socket.api module.


str – Use this constant to load anatomist api direct implementation (sip bindings). See anatomist.direct.api module.


str – Use this constant to load anatomist api threaded direct implementation. See anatomist.threaded.api module.

In addition to the Python APIs, the Anatomist.execute method of Anatomist also grants access to the commands system which offers many functionalities, some of which have not been wrapped yet int the more “pythonic” API.


Changes the default implementation of this api. The selected implementation will be loaded on importation of anatomist.api.

Parameters:impl (str) – implementation to set as default. Possible values are SOCKET, DIRECT, THREADED. Default is direct implementation.

How to

PyAnatomist examples

PyAnatomist examples