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)[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: - notifier (
soma.notification.Notifier
) – The notifier to activate when the event occurs. - anatomistinstance (
Anatomist
) –
- notifier (
-
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: - name (str) – node name. default is
-
-
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) orStrong
(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.
-
-
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
¶ bool – True 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)
-
-
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.
-
sphinx_gallery_snapshot
(width=0, height=0, restore_backend=False)[source]¶ 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
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
- objects (list of
-
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.
- referential (
-
convertParamsToAItems
(params, convertIDs=False, changed=[True])[source]¶ Recursively converts C++ API objects or context IDs to generic API objects.
Parameters: 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 convertReturns: 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 convertReturns: 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: Returns: graph – The new graph object
Return type:
-
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 uuidReturns: 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:
-
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: - wintype (str) – Type of window to open (
-
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: Returns: block – A window which can contain several
AWindow
Return type:
-
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:
-
fusionObjects
(objects, method='', ask_order=False)[source]¶ Creates a fusionned multi object that contains all given objects.
Parameters: Returns: object – The newly created fusion object.
Return type:
-
getAItem
(idorcpp, convertIDs=True, allowother=True)[source]¶ Converts a C++ API objects or context IDs to a generic API object.
Parameters: Returns: aitem – Converted element
Return type: AItem
instance, or None (or the unchanged input if allowother is True)
-
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
-
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
-
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 groupReturns: 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:
-
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:
-
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
-
removeObjects
(objects, windows, remove_children=False)[source]¶ Removes objects from windows.
Parameters:
-
toAObject
(object)[source]¶ Converts an AIMS object or numpy array to AObject.
Returns: aobject Return type: AObject
-