Direct bindings implementation

Inheritance diagram of

This module is an implementation of the general interface anatomist.base. It uses Sip bindings of C++ Anatomist api to execute and drive Anatomist application.

This is the default implementation. So, to use it you just have to import anatomist.api, it is automatically linked to this module.

>>> import anatomist.api as anatomist
>>> a = anatomist.Anatomist()

Objects created via this module encapsulate sip bindings of C++ Anatomist api objects (Sip binding classes are in module anatomist.cpp). This implementation provides additional features to those in the general interface because it gives access to the bound C++ objects, and potentially the whole Anatomist library is available, includind direct manipulation and modification of objects in memory using low-level operations. But Anatomist program is loaded in current process so if it fails, the current process also fails and possibly crashes, so it is more dangerous.

This implementation needs to run qt application. In an interactive python shell, this can be done using ipython --gui=qt for example. If the Anatomist object is created outside the main thread, you must get a thread safe version (See anatomist.threaded.api). So you have to change the default implementation before importing anatomist api :

>>> import anatomist
>>> anatomist.setDefaultImplementation(anatomist.THREADED)
>>> import anatomist.api as anatomist
class*args, **kwargs)[source]

Interface to communicate with an Anatomist Application using direct bindings to the C++ api. It inherits from Anatomist class of anatomist.cpp module (Sip bindings module).


Referential – Anatomist central referential (talairach acpc ref)


Referential – Referential of the MNI template (used by spm and other software)

These two referentials and transformation between them are always loaded in anatomist.


dict – Registered handlers for events. name of the event (string) -> event handler (Anatomist.AEventHandler). Handlers must be stored to enable unregistration.

The __init__ method of Singleton derived class should do nothing. Derived classes must define __singleton_init__() instead of __init__.

class AEventHandler(notifier, anatomistinstance)[source]

Anatomist event handler class. When an event is received, the corresponding notifier triggered and a message is logged.


This method is called when the event occurs.

class Anatomist.AGraph(anatomistinstance, internalRep=None, *args, **kwargs)[source]

Represents a graph.

createNode(name=None, syntax=None, with_bucket=None, duplicate=True)[source]

Creates a new node with optionally an empty bucket inside and adds it in the graph.

  • name (str) – node name. default is RoiArg.
  • syntax (str) – node syntax attribute. default is roi.
  • with_bucket (bool) – if True, creates an empty bucket in the node and returns it with the node. default is None, so the bucket is created but not returned
  • duplicate (bool) – enables duplication of nodes with the same name attribute.

node_def – (the created node, the created bucket) or only the created node if with_bucket is False

Return type:

(AObject, AObject)

class Anatomist.AItem(*args, **kwargs)[source]

Base class for representing an object in Anatomist application.


Anatomist – Reference to Anatomist object which created this object. Useful because some methods defined in AItem objects will need to send a command to the Anatomist application.


object – Representation of this object in anatomist application.


bool – Indicates if a reference has been taken on the corresponding anatomist object. If True, the reference is released on deleting this item.


str – Type of reference taken on the object : Weak (reference counter not incremented), WeakShared (reference counter incrementerd but the object can be deleted even if it remains references) or Strong (reference counter is incremented, the object cannot be deleted since there is references on it). If it is not specified, anatomist.base.Anatomist.defaultRefType is used.


Gets information about this object.

Returns:info – information about the object (property -> value)
Return type:dict
class Anatomist.AObject(*args, **kwargs)[source]

Represents an object in Anatomist application.

Following information can be obtained using ObjectInfo command:


str – object type. For example : volume, bucket, graph, texture...


list of Anatomist.AObject – List of objects which are children of current object (for example: nodes in a graph). Can be empty.


str – Name of the file from which the object has been loaded. May be None.


str – Name of the object presented in Anatomist window.


boolTrue indicates that this object is a copy of another object, otherwise it is the original object.


anatomist.cpp.Material – Object material parameters


Anatomist.Referential – Referential assigned to this object.


Extract the object texture to create a new texture object.

Parameters:time (float) – For temporal objects, if this parameter is mentionned the texture will be extracted at this time. if not mentionned, All times will be extracted and the texture will be a temporal object. In socket implementation, it is necessary to get a new id for the texture object and to pass it to the command.
Returns:texture – The newly created texture object
Return type:AObject

Generates an empty texture (value 0 everywhere) for a mesh object.

Parameters:dimension (int) – Texture dimension (1 or 2)
Returns:texture – The newly created texture object
Return type:AObject

Update the observers views on the object (windows, or fusion objects etc will be re-calculated as needed)


Mark the current object as changed, so that a view update will take it into account.


Converts AObject to aims object.

class Anatomist.APalette(name, anatomistinstance, internalRep=None, *args, **kwargs)[source]

str – Palette name. Must be unique, it is the palette identifier.

class Anatomist.AWindow(*args, **kwargs)[source]

Represents an anatomist window.


str – Windows type ('axial', 'sagittal', ...)


Anatomist.AWindowsGroup – The group which this window belongs to.


list of Anatomist.AObject – The window contains these objects.

class Anatomist.AWindowsBlock(anatomistinstance=None, nbCols=2, nbRows=0, widgetproxy=None)[source]

A window containing other windows.


int – Number of columns of the windows block

class WidgetProxy(anatomistinstance, internalRep, widget)[source]

Contains a QWidget. This proxy class is only here to activate reference counting on the widget

class Anatomist.AWindowsGroup(anatomistinstance, groupid=None)[source]

A group containing several windows which are linked. Moving cursor in one window moves it in all linked windows.

class Anatomist.Referential(anatomistinstance, internalRep=None, uuid=None)[source]

str – A unique id representing this referential. Two referential are equal if they have the same uuid.

class Anatomist.Transformation(anatomistinstance, internalRep=None, *args, **kwargs)[source]

This objects contains informations to convert coordinates from one referential to another: rotation_matrix, translation

Anatomist.addObjects(objects, windows, add_children=False, add_graph_nodes=True, add_graph_relations=False, temporary=False, position=-1)[source]

Adds objects in windows. The objects and windows must already exist.

  • objects (list of AObject) – List of objects to add
  • windows (list of AWindow) – List of windows in which the objects must be added
  • add_children (bool (optional)) – if children objects should also be added individually after their parent
  • add_graph_relations (bool (optional)) – if graph relations should be also be added
  • temporary (bool (optional)) – temporary object do not affect the view boundaries and camera settings
  • position (int (optional)) – insert objects as this order number
Anatomist.assignReferential(referential, elements)[source]

Assign a referential to objects and/or windows. The referential must exist. To create a new Referential, execute createReferential, to assign the central referential, first get it with Anatomist.centralRef attribute.

  • referential (Referential) – The referential to assign to objects and/or windows
  • elements (list of AObject / AWindow) – Objects or windows which referential must be changed. The corresponding command tree contains an attribute central_ref to indicate if the referential to assign is anatomist central ref, because this referential isn’t referenced by an id. In the socket implementation, Referential object must have an attribute central_ref, in order to create the command message. In direct impl, it is possible to access directly to the central ref object.
Anatomist.convertParamsToAItems(params, convertIDs=False, changed=[])[source]

Recursively converts C++ API objects or context IDs to generic API objects.

  • params (dict or list or anything else) –
  • convertIDs (bool) – If True, int numbers are treated as item IDs and converted accordingly when possible.
  • changed (list) – If anything has been changed from the input params, then changed will be added a True value. It’s actually an output parameter

elements – converted elements

Return type:



Converts current api objects to corresponding anatomist object representation. This method must be called before sending a command to anatomist application on command parameters.

Parameters:params (dict or list) – Elements to convert
Returns:objects – Converted elements
Return type:dict or list

Converts current api object to corresponding anatomist object representation.

Parameters:v (AItem instance) – Element to convert
Returns:Converted elements
Return type:*dictionary* or list

Converts current api object to corresponding anatomist C++ object representation.

Parameters:v (AItem) – Element to convert
Returns:objects – Converted elements
Return type:dict or list
Anatomist.createGraph(object, name=None, syntax=None, filename=None)[source]

Creates a graph associated to an object (volume for example). This object initializes the graph dimensions (voxel size, extrema).

  • object (AObject) – The new graph is based on this object
  • name (str) – Graph name. default is 'RoiArg'.
  • syntax (str) – Graph syntactic attribute. default is 'RoiArg'.
  • filename (str) – Filename used for saving. Default is None.

graph – The new graph object

Return type:



Creates an empty palette and adds it in the palettes list.

Parameters:name (str) – Name of the new palette
Returns:palette – The newly created palette
Return type:APalette

This command does not exist in Anatomist because the command AssignReferential can create a new referential if needed. But the way of creating a new referential depends on the connection with Anatomist, so it seems to be better to encapsulate this step on another command. So referentials are treated the same as other objects. (LoadObject -> addAobject | createReferential -> assignReferential)

Parameters:filename (str) – Name of a file (minf file, extension .referential) containing information about the referential: its name and uuid
Returns:ref – The newly created referential
Return type:Referential
Anatomist.createTransformation(matrix, origin, destination)[source]

Creates a transformation from a referential to another. The transformation informations are given in a matrix.

  • matrix (float vector, size 12) – Transformation matrix (4 lines, 3 colons ; 1st line: translation, others: rotation)
  • origin (Referential) – Origin of the transformation
  • destination (Referential) – Referential after applying transformation

trans – New transformation

Return type:


Anatomist.createWindow(wintype, geometry=[], block=None, no_decoration=None, options=None)[source]

Creates a new window and opens it.

  • wintype (str) – Type of window to open ("Axial", "Sagittal", "Coronal", "3D", "Browser", "Profile", ...)
  • geometry (int vector) – Position on screen and size of the new window (x, y, w, h)
  • block (AWindowsBlock or QWidget) – A parent block in which the new window must be added. In Anatomist 4.6.2 and later, the block may be a regular QWidget (this is only OK in direct implementation mode)
  • no_decoration (bool) – Indicates if decorations (menus, buttons) can be painted around the view.
  • options (dict) – Internal advanced options.

window – The newly created window

Return type:


Anatomist.createWindowsBlock(nbCols=2, nbRows=0, widget=None)[source]

Creates a window containing other windows.

An id is reserved for that block but the bound object isn’t created. It will be created first time a window is added to the block with createWindow method.

  • nbCols (int) – Number of columns of the windows block
  • nbRows (int) – Number of rows of the windows block (exclusive with nbCols)
  • widget (QWidget (optional)) – New in Anatomist 4.6.2, only applies to the direct implementation. Existing parent widget to be used as a block

block – A window which can contain several AWindow

Return type:



Set listening of this event off.

Parameters:event (str) – Name of the event to disable.
Anatomist.duplicateObject(source, shallowCopy=True)[source]

Creates a copy of source object.

Parameters:source (AObject) – The object to copy.
Returns:object – The copy. it has a reference to its source object, so original object will not be deleted as long as the copy exists.
Return type:AObject
Anatomist.enableListening(event, notifier)[source]

Set listening of this event on. So when the event occurs, the notifier’s notify method is called. This method is automatically called when the first listener is added to a notifier. That is to say that notifiers are activated only if they have registered listeners.

  • event (str) – Name of the event to listen
  • notifier (soma.notification.Notifier) – The notifier whose notify method must be called when this event occurs
Anatomist.execute(command, **kwargs)[source]

Executes a command in anatomist application. It should be a command that can be processed by Anatomist command processor. The list of available commands is in the commands system. Parameters are converted before sending the request to anatomist application.

  • command (str) – Name of the command to execute.
  • kwargs (dict) – Parameters for the command
Anatomist.fusionObjects(objects, method='', ask_order=False)[source]

Creates a fusionned multi object that contains all given objects.

  • objects (list of AObject) – List of objects that must be fusionned
  • method (str) – Method to apply for the fusion ('Fusion2DMethod'...)
  • ask_order (bool) – If True, asks user in which order the fusion must be processed.

object – The newly created fusion object.

Return type:


Anatomist.getAItem(idorcpp, convertIDs=True, allowother=True)[source]

Converts a C++ API objects or context IDs to a generic API object.

  • idorcpp (ID or C++ instance to be converted) – If idorcpp is already an AItem, it is returned as is
  • convertIDs (bool) – If True, int numbers are treated as item IDs and converted accordingly when possible.
  • allowother (bool) – If True, idorcpp is returned unchanged if not recognized

aitem – Converted element

Return type:

AItem instance, or None (or the unchanged input if allowother is True)

Returns:info – Information about the AIMS library.
Return type:str
Returns:commands – Dict of commands available in Anatomist with their parameters. dict command name -> dict parameter name -> dict attribute -> value (needed, type)
Return type:dict

Gets information about fusion methods. If objects is not specified, the global list of all fusion methods is returned. Otherwise the allowed fusions for those specific objects is returned.

Returns:methods – Fusion methods
Return type:dict
Returns:info – Dict of modules and their description. dict module name -> dict attribute -> value (description)
Return type:dict

Gets all objects referenced in current context.

Returns:objects – List of existing objects
Return type:list of AObject
Returns:palette – The named palette
Return type:APalette
Returns:palettes – List of palettes.
Return type:list of APalette

Gets all referentials in current context.

Returns:refs – List of referentials
Return type:list of Referential
Parameters:group (AWindowsGroup) – Get the selection in this group. If None, returns the selection in the default group.
Returns:objects – The list of selected objects in the group of windows
Return type:list of AObject

Gets all transformations.

Returns:trans – List of transformations
Return type:list of Transformation
Returns:version – Anatomist version
Return type:str

Gets all windows referenced in current context.

Returns:windows – List of opened windows
Return type:list of AWindow

Creates a multi object containing objects in parameters.

Parameters:objects (list of AObject) – Objects to put in a group
Returns:group – The newly created multi object
Return type:AObject

Gets objects importing those that are not referenced in the current context.

Parameters:top_level_only (bool) – If True, imports only top-level objects (that have no parents), else all objects are imported.
Returns:objects – List of existing objects
Return type:list of AObject

Gets all referentials importing those that are not referenced in the current context.

Returns:refs – List of referentials
Return type:list of Referential

Gets all transformations importing those that are not referenced in the current context.

Returns:trans – List of transformations
Return type:list of Transformation

Gets all windows importing those that are not referenced in the current context.

Returns:windows – List of opened windows
Return type:list of AWindow

Gives the last clicked position of the cursor.

Parameters:ref (Referential) – If given, cursor position value will be in this referential. Else, anatomist central referential is used.
Returns:position – Last position of the cursor
Return type:float vector, size 3

Loads a cursor for 3D windows from a file.

Parameters:filename (str) – The file containing object data
Returns:cursor – The loaded object
Return type:AObject
Anatomist.loadObject(filename, objectName='', restrict_object_types=None, forceReload=True, duplicate=False, hidden=False, asyncCallback=None)[source]

Loads an object from a file (volume, mesh, graph, texture...)

  • filename (str) – The file containing object data
  • objectName (str) – Object name
  • restrict_object_types (dict) – object -> accpepted types list. Ex: {'Volume' : ['S16', 'FLOAT']}
  • forceReload (bool) – If True, the object will be loaded even if it is already loaded in Anatomist. Otherwise, the already loaded one is returned.
  • duplicate (bool) – If the object already exists, duplicate it. The original and the copy will share the same data but not display parameters as palette. If the object is not loaded yet, load it hidden and duplicate it (unable to keep the original object with default display parameters).
  • hidden (bool) – A hidden object does not appear in Anatomist main control window.

object – The loaded object

Return type:


Anatomist.loadTransformation(filename, origin, destination)[source]

Loads a transformation from a referential to another. The transformation informations are given in a file.

  • filename (str) – File containing transformation information
  • origin (Referential) – Origin of the transformation
  • destination (Referential) – Referential after applying transformation

trans – Transformation to apply to convert coordinates from one referent

Return type:



In this implementation, anatomist objects are accessibles but some commands need an id associated to the object : CreateWindowCommand blockid attribute, linkWindows group attribute... This method generates a unique id in current context.

Returns:id – A new unused ID.
Return type:int

Creates a new item representation.

Anatomist.removeObjects(objects, windows, remove_children=False)[source]

Removes objects from windows.

  • objects (list of AObject) – List of objects to remove
  • windows (list of AWindow) – List of windows from which the objects must be removed

Wait for anatomist finishing current processing.


Converts an AIMS object or numpy array to AObject.

Return type:AObject

Converts an AObject to an AIMS object.

Parameters:object (AObject) – The object to convert
Returns:aims – The underlying converted AIMS object
Return type:various types

Get AObject or a subclass from a sip object when it is possible.

Return type:AObject