Direct bindings implementation

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 anatomist.direct.api.Anatomist(*args, **kwargs)

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).

centralRef

Anatomist central referential (talairach acpc ref)

Type

Referential

mniTemplateRef

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

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

Type

Referential

handlers

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

Type

dict

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

class AEventHandler(notifier, anatomistinstance)

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

Parameters

• notifier (soma.notification.Notifier) – The notifier to activate when the event occurs.

• anatomistinstance (Anatomist) –

doit(event)

This method is called when the event occurs.

class AGraph(anatomistinstance, internalRep=None, *args, **kwargs)

Represents a graph.

If internal rep is given as parameter, the corresponding anatomist object already exists: take a reference on it (to prevent its deletion).

createNode(name=None, syntax=None, with_bucket=None, duplicate=True)

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

Parameters

• 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.

Returns

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

Return type

(AObject, AObject)

class AItem(*args, **kwargs)

Base class for representing an object in Anatomist application.

anatomistinstance

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.

Type

Anatomist

internalRep

Representation of this object in anatomist application.

Type

object

ref

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

Type

bool

refType

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.

Type

str

getInfo()

Gets information about this object.

Returns

info – information about the object (property -> value)

Return type

dict

getInternalRep()

Returns internal representation of the object (implementation dependant).

class AObject(*args, **kwargs)

Represents an object in Anatomist application.

Following information can be obtained using ObjectInfo command:

objectType

object type. For example : volume, bucket, graph, texture…

Type

str

children

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

Type

list of Anatomist.AObject

filename

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

Type

str

name

Name of the object presented in Anatomist window.

Type

str

copy

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

Type

bool

material

Object material parameters

Type

anatomist.cpp.Material

referential

Referential assigned to this object.

Type

Anatomist.Referential

If internal rep is given as parameter, the corresponding anatomist object already exists: take a reference on it (to prevent its deletion).

extractTexture(time=- 1)

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

generateTexture(dimension=1)

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

notifyObservers()

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

releaseAppRef()

Release anatomist application reference on this object: so object life is controled by references on it. If there is no more references on the object, it is deleted. Used when an object is created by python api. It is not owned by anatomist application.

releaseRef()

Release a reference on this object.

setChanged()

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

takeAppRef()

Take anatomist application reference on this object : so object life is controled the normal way by Anatomist. Inverse of releaseAppRef(). The object is now owned by anatomist application.

takeRef()

Take a reference on this object.

toAimsObject()

Converts AObject to aims object.

class APalette(name, anatomistinstance, internalRep=None, *args, **kwargs)

name

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

Type

str

class AWindow(*args, **kwargs)

Represents an anatomist window.

windowType

Windows type ('axial', 'sagittal', …)

Type

str

group

The group which this window belongs to.

Type

Anatomist.AWindowsGroup

objects

The window contains these objects.

Type

list of Anatomist.AObject

If internal rep is given in parameter, the corresponding anatomist window already exists : take a reference on it (to prevent its deletion).

getReferential()

Get the referential attached to the window (the coordinates system used for 3D positions in this window)

imshow(width=0, height=0, figure=None, show=False)

Display the 3D view rendering into a Matplotlib figure using pylab.imshow(). This is useful to display static figures in a widget, or use them to export in a document, or to use the sphinx_gallery module for documentation.

releaseAppRef()

Release anatomist application reference on this object: so object life is controled by references on it. If there is no more references on the object, it is deleted. Used when an object is created by python api. It is not owned by anatomist application.

releaseRef()

Release a reference on this object.

sphinx_gallery_snapshot(width=0, height=0, restore_backend=False)

Render the view in a matplotlib AGG graph to be used by the sphinx_gallery module, when building documentation examples. If sphinx_gallery is not already loaded, then nothing is done

Parameters

• width (int) –

• height (int) –

• restore_backend (bool) – the rendering needs to set matplotlib backend to “agg” temporarily. If restore_backend is True, then the former backend is restored. Otherwise (the default) it is left to agg. sphinx_gallery generally needs to leave it to agg when building docs for multiple Anatomist examples.

Returns

result oy pyplot.imshow(), or None if sphinx_gallery is not loaded

Return type

plot

takeAppRef()

Take anatomist application reference on this object : so object life is controled the normal way by Anatomist. Inverse of releaseAppRef(). The object is now owned by anatomist application.

takeRef()

Take a reference on this object.

class AWindowsBlock(anatomistinstance=None, nbCols=2, nbRows=0, widgetproxy=None)

A window containing other windows.

nbCols

Number of columns of the windows block

Type

int

class WidgetProxy(anatomistinstance, internalRep, widget)

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

class AWindowsGroup(anatomistinstance, groupid=None)

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

class Referential(anatomistinstance, internalRep=None, uuid=None)

refUuid

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

Type

str

class Transformation(anatomistinstance, internalRep=None, *args, **kwargs)

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

addObjects(objects, windows, add_children=False, add_graph_nodes=True, add_graph_relations=False, temporary=False, position=- 1)

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

Parameters

• 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

assignReferential(referential, elements)

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.

Parameters

• 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.

close()

Exits Anatomist application. if anatomist is closed, the singleton instance is deleted. So next time the constructor is called, a new instance will be created.

convertParamsToAItems(params, convertIDs=False, changed=[])

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

Parameters

• 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

Returns

elements – converted elements

Return type

list

convertParamsToObjects(params)

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

convertSingleObjectParamsToIDs(v)

Converts current api object to corresponding anatomist object representation.

Parameters

v (AItem instance) – Element to convert

Returns

Converted elements

Return type

*dictionary* or list

convertSingleObjectParamsToObjects(v)

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

createGraph(object, name=None, syntax=None, filename=None)

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

Parameters

• 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.

Returns

graph – The new graph object

Return type

AGraph

createPalette(name)

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

createReferential(filename='')

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

createTransformation(matrix, origin, destination)

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

Parameters

• 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

Returns

trans – New transformation

Return type

Transformation

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

Creates a new window and opens it.

Parameters

• 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.

Returns

window – The newly created window

Return type

AWindow

createWindowsBlock(nbCols=2, nbRows=0, widget=None)

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.

Parameters

• 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

Returns

block – A window which can contain several AWindow

Return type

AWindowsBlock

disableListening(event)

Set listening of this event off.

Parameters

event (str) – Name of the event to disable.

duplicateObject(source, shallowCopy=True)

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

enableListening(event, notifier)

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.

Parameters

• event (str) – Name of the event to listen

• notifier (soma.notification.Notifier) – The notifier whose notify method must be called when this event occurs

execute(command, **kwargs)

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.

Parameters

• command (str) – Name of the command to execute.

• kwargs (dict) – Parameters for the command

fusionObjects(objects, method='', ask_order=False)

Creates a fusionned multi object that contains all given objects.

Parameters

• 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.

Returns

object – The newly created fusion object.

Return type

AObject

getAItem(idorcpp, convertIDs=True, allowother=True)

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

Parameters

• 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

Returns

aitem – Converted element

Return type

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

getAimsInfo()

Returns

info – Information about the AIMS library.

Return type

str

getCommandsList()

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

getFusionInfo(objects=None)

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

getModulesInfo()

Returns

info – Dict of modules and their description. dict module name -> dict attribute -> value (description)

Return type

dict

getObjects()

Gets all objects referenced in current context.

Returns

objects – List of existing objects

Return type

list of AObject

getPalette(name)

Returns

palette – The named palette

Return type

APalette

getPalettes()

Returns

palettes – List of palettes.

Return type

list of APalette

getReferentials()

Gets all referentials in current context.

Returns

refs – List of referentials

Return type

list of Referential

getSelection(group=None)

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

getTransformations()

Gets all transformations.

Returns

trans – List of transformations

Return type

list of Transformation

getVersion()

Returns

version – Anatomist version

Return type

str

getWindows()

Gets all windows referenced in current context.

Returns

windows – List of opened windows

Return type

list of AWindow

groupObjects(objects)

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

importObjects(top_level_only=False)

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

importReferentials()

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

Returns

refs – List of referentials

Return type

list of Referential

importTransformations()

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

Returns

trans – List of transformations

Return type

list of Transformation

importWindows()

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

Returns

windows – List of opened windows

Return type

list of AWindow

linkCursorLastClickedPosition(ref=None)

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

loadCursor(filename)

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

loadObject(filename, objectName='', restrict_object_types=None, forceReload=True, duplicate=False, hidden=False, asyncCallback=None)

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

Parameters

• 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.

Returns

object – The loaded object

Return type

AObject

loadTransformation(filename, origin, destination)

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

Parameters

• filename (str) – File containing transformation information

• origin (Referential) – Origin of the transformation

• destination (Referential) – Referential after applying transformation

Returns

trans – Transformation to apply to convert coordinates from one referent

Return type

Transformation

newId()

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

newItemRep()

Creates a new item representation.

removeObjects(objects, windows, remove_children=False)

Removes objects from windows.

Parameters

• objects (list of AObject) – List of objects to remove

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

sync()

Wait for anatomist finishing current processing.

toAObject(object)

Converts an AIMS object or numpy array to AObject.

Returns

aobject

Return type

AObject

toAimsObject(object)

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

typedObject(obj)

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

Returns

object

Return type

AObject