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> and AimsData_<type>: volumes (the cartodata newer Volume and the older aimsdata version). An important feature of Volumes is the link with the numpy_ 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 functions Volume() and AimsData().
  • 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