Direct bindings implementation

Inheritance diagram of anatomist.direct.api.Anatomist

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

centralRef

Referential – Anatomist central referential (talairach acpc ref)

mniTemplateRef

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

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

handlers

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.

Parameters:
doit(event)[source]

This method is called when the event occurs.

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

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)[source]

Base class for representing an object in Anatomist application.

anatomistinstance

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.

internalRep

object – Representation of this object in anatomist application.

ref

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

refType

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.

getInfo()[source]

Gets information about this object.

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

Represents an object in Anatomist application.

Following information can be obtained using ObjectInfo command:

objectType

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

children

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

filename

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

name

str – Name of the object presented in Anatomist window.

copy

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

material

anatomist.cpp.Material – Object material parameters

referential

Anatomist.Referential – Referential assigned to this object.

extractTexture(time=-1)[source]

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)[source]

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()[source]

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

setChanged()[source]

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

toAimsObject()[source]

Converts AObject to aims object.

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

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

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

Represents an anatomist window.

windowType

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

group

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

objects

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

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

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.

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

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

A window containing other windows.

nbCols

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 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 Referential(anatomistinstance, internalRep=None, uuid=None)[source]
refUuid

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

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

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)[source]

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

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.
convertParamsToAItems(params, convertIDs=False, changed=[True])[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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='')[source]

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)[source]

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)[source]

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

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)[source]

Set listening of this event off.

Parameters:event (str) – Name of the event to disable.
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
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.

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

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

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)[source]

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()[source]
Returns:info – Information about the AIMS library.
Return type:str
getCommandsList()[source]
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)[source]

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()[source]
Returns:info – Dict of modules and their description. dict module name -> dict attribute -> value (description)
Return type:dict
getObjects()[source]

Gets all objects referenced in current context.

Returns:objects – List of existing objects
Return type:list of AObject
getPalette(name)[source]
Returns:palette – The named palette
Return type:APalette
getPalettes()[source]
Returns:palettes – List of palettes.
Return type:list of APalette
getReferentials()[source]

Gets all referentials in current context.

Returns:refs – List of referentials
Return type:list of Referential
getSelection(group=None)[source]
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()[source]

Gets all transformations.

Returns:trans – List of transformations
Return type:list of Transformation
getVersion()[source]
Returns:version – Anatomist version
Return type:str
getWindows()[source]

Gets all windows referenced in current context.

Returns:windows – List of opened windows
Return type:list of AWindow
groupObjects(objects)[source]

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)[source]

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()[source]

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

Returns:refs – List of referentials
Return type:list of Referential
importTransformations()[source]

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

Returns:trans – List of transformations
Return type:list of Transformation
importWindows()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

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()[source]

Creates a new item representation.

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

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()[source]

Wait for anatomist finishing current processing.

toAObject(object)[source]

Converts an AIMS object or numpy array to AObject.

Returns:aobject
Return type:AObject
toAimsObject(object)[source]

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)[source]

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

Returns:object
Return type:AObject