PyAims programming documentation


The aims module allows access to the AIMS library in python.

  • organization: NeuroSpin and former IFR 49

  • license: CeCILL-B (a free licence comparable to BSD)

Comptibility and requirements

Since version 4.5.1 both Python 2 (2.7 and higher) and Python 3 (3.4 and higher) are supported. However as the module contains compiled code (python / C++ bindings) using specific python C interfaces (APIs/ABIs), PyAIMS has to be compiled separately for a given version of python.

PyAIMS also has bindings to the numpy library, allowing easy array manipulations. This also involves constraints on the Numpy ABI version: once PyAims is compiled, it is not possible to swith numpy to a different version featuring a different ABI (which pip often does without warning, unfortunately).

Most of it is a set of direct bindings to the AIMS C++ library API. But a few classes have been customized or specially written to make easy links to the python world. See also the small AIMS C++ developer doc.

aims contains mainly the AIMS and carto data structures and IO system. It covers several C++ libraries: cartobase, cartodata, graph, aimsdata, plus some C++ classes from the standard library (like std::vector)

Main classes

  • Reader and Writer for the generic IO system, which allows to read and write everything, and which can be, in most cases, replaced with the more convenient global read() and write() functions. Finder is also part of the IO system to identify files and get information about them.

  • Volume_<type>: volumes. An important feature of Volumes is the link with the numpy.ndarray arrays, so all the power of numpy can be used to work on volumes. See for instance Volume_FLOAT. Volumes of various types can be build using the convenience factory function Volume(). Note that the older classes AimsData are deprecated in the C++ library and have been removed from the python bindings in Aims 5.1.

  • carto.GenericObject: the dynamic C++ generic object which behaves much like a python object, and its proxy Object which should always be used to access a GenericObject

  • AimsVector_<type>_<size> for fixed-size vectors, and their aliases for points: Point3df, Point2df, Point3d

  • vector_<type>, set_<type>, list_<type>, map_<type1>_<type2> provide bindings to the C++ std::vector, std::list, std::set, std::map template classes and easy conversions from / to python lists

  • rc_ptr_<type>: bridge with C++ reference counters, which should interact quite well, and most of the time transparently, with python reference counting

  • BucketMap_VOID: list of voxels. Created using the factory function BucketMap()

  • AimsTimeSurface_<polygons_size>_<texture_type=VOID>: meshes, and the factory function AimsTimeSurface(). See for instance AimsTimeSurface_3_VOID.

  • TimeTexture_<type>: textures to map on meshes, and the factory function TimeTexture().

  • Graph

  • Tree

  • AffineTransformation3d: the transformation class that allows referential conversions

  • Converter_<type1>_<type2> and ShallowConverter_<type1>_<type2>: conversions between data types (mainly volume types). See the factory functions Converter() and ShallowConverter()

  • a few algorithms will be added


There is a PyAims tutorial available as a Jupyter/Ipython notebook: