PyAims low-level classes and functions

You will look at this part only when needed, dont’t look at it at the beginning. The useful part is accessed via the PyAims high-level functions and classes.

IO system

class soma.aims.Reader(typemap=None, allocmode=None, options=None)[source]

Generic reader that can theorerically load any SIP-mapped AIMS or Cartograph object. A translation table can be provided to correctly map readers and objects. For quick and simple operations, you can also use the gloabl soma.aims.read() and soma.aims.write() functions, which use a Reader object internally.

typemap can be provided to specify which reader may be used to load objects whose type has been read. A default internal map is present but can be replaced.

The map has 2 modes:

  • object_type : object_type (ex: {'Volume' : 'AimsData'} )

  • object_type : dict( data_type : full_type ) (ex: 'Mesh' : { 'VOID' : 'AimsSurfaceTriangle' } )

    A default object_type can be specified if the data_type is not found:

    'Mesh' : { 'VOID' : 'AimsSurfaceTriangle',
            'default_object_type' : 'AimsTimeSurface_3_VOID' }

    (and this example corresponds to the default internal map if none is specified)

Parameters:
mapType(iotype, aimstype)[source]

Get the translated type correspondance between identified data type (from IO system) and the data type that will actually be read. This is generally the identity, but a few IO/types allow some variations.

read(filename, border=0, frame=-1, dtype=None)[source]

Reads the object contained in the file <filename>, whatever the type of the contents of the file. All objects types supported by Aims IO system can be read. A border width and a frame number may be specified and will be only used by formats that support them. If <dtype> is specified, the corresponding object/data type is forced. It may be useful to force reading a volume with float voxels for instance. It is only supported by a few formats. <dtype> may contain a string or a type object, as accepted by soma.aims.typeCode(). The read function may follow other object/data types rules, allocators and options, as specified in the Reader constructor.

class soma.aims.Writer[source]
writtenObjectType()[source]
writtenObjectDataType()[source]
writtenObjectFullType()[source]
write(obj, filename, format=None, options={})[source]

Writes the object <obj> in a file named <filename>, whatever the type of <obj>, as format <format>. All objects types and formats supported by the Aims IO system can be used. <obj> may be a reference-counter to an object type supported by the IO system. Additional specific options may be passed to the underlying IO system in an optional <options> dictionary.

writtenObjectDataType()[source]

Data content type (voxel or texture type…) written (available after writing)

writtenObjectFullType()[source]

Data full type written (available after writing)

writtenObjectType()[source]

Data object type (Volume, Mesh…) written (available after writing)

class soma.aims.Finder

See the Finder C++ class

check(filename)
header()
objectType()
dataType()
format()
soma.aims.typeCode(data)[source]

returns the AIMS type code for the given input data. data may be a string code, a python/numpy numeric type, an AIMS type, or an instance of such a type.

soma.aims.voxelTypeCode(data)[source]

returns the AIMS type code for the given input data voxel type. For instance, for a volume of 16 bit ints, it will be ‘S16’, whereas typeCode() would return ‘Volume_S16’.

Input data may be a type or an instance of a container type.

soma.aims.somaio_typeCode(data)[source]

returns the Soma-IO type code (as in soma.carto.IOObjectTypesDictionary.readTypes() dict keys) for the given input type.

Parameters:data (string or type or instance, or 2-tuple) – If type or instance, get the type code for the given object. If string, try to translate AIMS IO to soma-IO codes. If 2-tuple, translate AIMS object type / data type couple

Neuroimaging data structures

Volumes

class soma.aims.Volume_U8
class soma.aims.Volume_S16
class soma.aims.Volume_U16
class soma.aims.Volume_S32
class soma.aims.Volume_U32
class soma.aims.Volume_RGB
class soma.aims.Volume_RGBA
class soma.aims.Volume_DOUBLE
class soma.aims.Volume_CDOUBLE
class soma.aims.Volume_CFLOAT
class soma.aims.Volume_FLOAT(*args)

Generalities

The various Volume_<type> classes are bindings to the C++ template classes carto::Volume. It represents a 4D volume (1D to 4D, actually) storing a specific type of data: for instance S16 is signed 16 bit short ints, FLOAT is 32 bit floats, etc.

Volumes are read and written using the Reader and Writer classes, which are in turn used by the simple read() and write() functions.

A volume of a given type can be built either using its specialized class constructor, or the general Volume() function which can take a voxel type in its arguments: the following are equivalent:

>>> v = aims.Volume_S16(100, 100, 10)
>>> v = aims.Volume('S16', 100, 100, 10)
>>> v = aims.Volume(100, 100, 10, dtype='S16')
>>> v = aims.Volume([100, 100, 10], dtype='S16')
>>> import numpy
>>> v = aims.Volume(numpy.int16, 100, 100, 10)

Numpy arrays and volumes

A volume is an array of voxels, which can be accessed via the at() method. For standard numeric types, it is also possible to get the voxels array as a numpy array, using the __array__() method, or more conveniently, numpy.asarray(volume) or numpy.array(volume, copy=False). In aims >= 5.0.2, a more concise shortcut is also available: volume.np (this is available on all types providing numpy bindings actually). The array returned is a reference to the actual data block, so any modification to its contents also affects the Volume contents, so it is generally an easy way of manipulating volume voxels because all the power of the numpy module can be used on Volumes. The obsoloete arraydata() method used to return a numpy array just like it is in memory, that is a 4D (or more) array generally indexed by [t][z][y][x] (but it depands how it has been built), which is generally not what you like and is not consistent with AIMS indexing. Contrarily, using volume.np sets strides in the returned numpy array, so that indexing is in the “normal” order [x][y][z][t], while still sharing the same memory block. The Volume object now also wraps the numpy accessors to the volume object itself, so that volume[x, y, z, t] is the same as nupmy.asarray(volume)[x, y, z, t].

new in PyAims 4.7

Since PyAims 4.7 the numpy arrays bindings have notably improved, and are now able to bind arrays to voxels types which are not scalar numeric types. Volumes of RGB, RGBA, HSV, or Point3df now have numpy bindings. The bound object have generally a “numpy struct” binding, that is not the usual C++/python object binding, but instead a structure managed by numpy which also supports indexing. For most objects we are using, they also have an array stucture (a RGB is an array with 3 int8 items), and are bound under a sturcture with a unique field, named “v” (for “vector”):

>>> v = aims.Volume('RGB', 100, 100, 10)
>>> v[0, 0, 0, 0]
([0, 0, 0],)

Such an array may be indexed by the field name, which returns another array with scalar values and additional dimensions:

>>> v['v'].dtype
dtype('uint8')
>>> v['v'].shape
(100, 100, 10, 1, 3)

Both arrays share their memory with the aims volume.

See also

Precisions about aims / numpy bindings

Header

Volumes also store a header which can contain various information (including sizes and voxel sizes). The header is a dictionary-like generic object (Object) which can be accessed by the header() method. This header object also has a read-write access with some restrictions inherent to the Object mechanism. It will be saved with the volume contents when the volume is saved on disk.

Volumes support a number of arithmetic operators like +, - etc. when the operands types and sizes match: for instance:

>>> # V1 and V2 are two volumes
>>> V3 = V1 + V2  # adds two volumes
>>> V2 -= V1
>>> V3 = V1 + 3   # adds 3 to aceh voxel
>>> V3 = V1 * V2  # itemwise multiplication

Some type conversions can be performed on volumes, for istance to convert a Volume_S16 to a Volume_FLOAT. The simplest, to convert to another data type, is to use the astype() method.

To convert a volume into diffent structure types, such as Buckets, use the converter classes Converter_<type1>_<type2> and ShallowConverter_<type1>_<type2> with <type1> and <type2> being volume or other object types: for instance Converter_Volume_S16_Volume_FLOAT. The converter can also be called using type arguments:

>>> vol1 = aims.AimsData('S16', 100, 100, 10)
>>> c = aims.Converter(intype=vol1, outtype='BucketMap_VOID')
>>> vol2 = c(vol1)

Volume from a numpy array

It is also possible to build a Volume from a numpy array:

>>> v = aims.Volume(numpy.zeros((100, 100, 10)))

Note that passing a 1D numpy array of ints will build a volume mapping the array contents, whereas passing a python list or tuple of ints will interpret the list as a shape for the volume:

>>> v = aims.Volume(numpy.array([100, 100, 10]).astype('int32'))
>>> print(v.getSize())
[ 3, 1, 1, 1 ]
>>> print(v.np)
[100 100  10]
>>> v = aims.Volume([100, 100, 10])
>>> print(v.getSize())
[ 100, 100, 10, 1 ]
class Position4Di

4 ints for position or size, used for Volume views.

arraydata()

Note

arraydata() returns a numpy array to the internal memory block, without strides. Given the internal ordering of Aims Volumes, the resulting numpy array is indexed as [t][z][y][x]. This order corresponds to the numpy “fortran” order: order='F' If you need the inverse, more natural, [x][y][z][t] ordering, use the following:

>>> volarray = numpy.array(volume, copy=False)

or:

>>> volarray = numpy.asarray(volume)

Note

The array conversion is currently only supported for scalar volumes, and is not present on volumes of types RGB or RGBA.

astype(dtype, copy=False)

Easy conversion method for volumes. Works in a similar was as numpy arrays astype() methods, except that the “copy” parameter defaults to False.

Parameters:
  • dtype (string or type object) – may be a volume or voxel type, specified either as a type oject (int, aims.Volume_S32, numpy.int16), or as a string (“S16”…).
  • copy (bool) – if False, a ShallowConverter will be used: if dtype matches the current volume type, a shared reference to self will be returned. Otherwise a new copy will be returned.
Returns:
Return type:

A volume of the converted type
at(posx, posy=0, posz=0, post=0)

Returns the volume value for the selected voxel. at(vector_int)

Returns the volume value for the selected voxel.

fill(value)

Fill Volume_FLOAT using the given value.

fillBorder(value)

Fill the surrounding of the volume view in the reference volume (if any) using the given value.

getSize()

Number of voxels in each dimension (list of 4 ints)

getVoxelSize()

Voxel sizes in mm (list of 4 floats)

header()

The header contains all meta-data.

posInRefVolume()

If the volume is a view into another (larger) one, this returns the position in “parent” one.

refVolume()

If the volume is a view into another (larger) one, this returns the “parent” one.

setPosInRefVolume()

Set position in parent volume

setValue(value, x, y=0, z=0, t=0)

Set the voxel value at the given position. setValue(value, [x1, x2, x3, x4, x5, x6…])

Set the voxel value at the given position.

value(posx, posy=0, posz=0, post=0)

value is an alias to at(): returns the volume value for the selected voxel.

class soma.aims.AimsData_U8
class soma.aims.AimsData_S16
class soma.aims.AimsData_U16
class soma.aims.AimsData_S32
class soma.aims.AimsData_U32
class soma.aims.AimsData_RGB
class soma.aims.AimsData_RGBA
class soma.aims.AimsData_DOUBLE
class soma.aims.AimsData_CDOUBLE
class soma.aims.AimsData_CFLOAT
class soma.aims.AimsData_FLOAT(*args)

AimsData_<type> classes correspond to the python bindings of C++ template classes AimsData. They are planned to be obsolete, and replaced with the Volume_<type> classes. Try avoiding using them unless using functions that work on AimsData_<type>.

AimsData actually contains a Volume: you can retreive it using the volume() method.

Inversely, you can also build a Volume from a AimsData by passing it to the Volume constructor.

In all cases the voxels memory block is shared.

clone()
dimT()

equivalent to soma.aims.Volume_FLOAT.getSizeT()

dimX()

equivalent to soma.aims.Volume_FLOAT.getSizeX()

dimY()

equivalent to soma.aims.Volume_FLOAT.getSizeY()

dimZ()

equivalent to soma.aims.Volume_FLOAT.getSizeZ()

fill(value)
fillBorder(value)
header()
maxIndex()
maximum()
minIndex()
minimum()
setSizeT(sizet)

This is the voxel size, not the volume size as in :py:class::soma.aims.Volume_FLOAT.

setSizeX(sizex)
setSizeXYZT(size)
setSizeY(sizey)
setSizeZ(sizez)
setValue(value, posx, posy = 0, posz = 0, post = 0)
sizeT()

This is the voxel size, not the volume size as in :py:class::soma.aims.Volume_FLOAT.

sizeX()
sizeY()
sizeZ()
value(posx, posy = 0, posz = 0, post = 0)
volume()

Returns the underlying :py:class::soma.aims.Volume_FLOAT object.

Graphs and trees

class soma.aims.Graph(*args)

See the Graph C++ documentation

class soma.aims.Tree(*args)

See the Tree C++ documentation

Meshes and textures

class soma.aims.AimsTimeSurface_3_VOID(*args)

See the AimsTimeSurface C++ documentation

Note

Before PyAIMS 4.5, compared to the C++ classes, the texture type template argument had beed dropped from the Python bindings, because textures are handled via separate objects (see soma.aims.TimeTexture()) and the builtin texture was actually never used. However textured meshes have shown useful to be read/written as an exchange format to other software and formats (typically the Wavefront .obj format), so the support for textured meshes has been added in Pyaims 4.5. As a consequence, mesh classes have changed name. To maintain compatibility with older code, the AimsTimeSurface_D_VOID classes (D being 2, 3 or 4) can still be found under their older names: AimsTimeSurface_D.

header()

The header contains all meta-data.

class soma.aims.AimsTimeSurface_2_VOID
class soma.aims.AimsTimeSurface_4_VOID
class soma.aims.AimsTimeSurface_2_FLOAT
class soma.aims.AimsTimeSurface_3_FLOAT
class soma.aims.AimsTimeSurface_4_FLOAT
class soma.aims.AimsTimeSurface_2_POINT2DF
class soma.aims.AimsTimeSurface_3_POINT2DF
class soma.aims.AimsTimeSurface_4_POINT2DF
class soma.aims.TimeTexture_FLOAT(*args)

See the TimeTexture C++ documentation

class soma.aims.Texture_FLOAT

See the Texture C++ documentation

“Buckets”

class soma.aims.BucketMap_VOID(*args)

See the BucketMap C++ documentation

General purpose C++ containers

Generic object

class soma.aims.carto

This class represents the carto C++ namespace. It is rather used like a module, not as a class.

class AllocatorContext

Allocation context specifications. This object is used when memory must be allocated for large objects (volumes, arrays…), especially for data which will be read from disk. It allows to specify how the memory will be used (read-only, read-write, how much…) to allow to decide whether any memory mapping techniques should be used or not.

class AllocatorStrategy

Memory management strategy helper. Contains mainly constants and a memory query function.

class DataAccess

Data access mode

InternalModif:
random access in memory, disk data (memmapped) should not be overwritten.
ReadOnly:
read only in memory. Accessing data in write mode may cause a crash.
ReadWrite:
read/write both in memory and on disk, if memmapped.
NotOwner:
data is unallocated, or its ownership belongs to a proxy object.
class MappingMode

Memory mapping modes

Memory, (MEM):
in-memory allocation
CopyMap, (MAP, MAP_COPY):
data is copied into a memmaped file (accessed read/write)
ReadOnlyMap, (MAP_RO):
read-only memory mapping
ReadWriteMap, (MAP_RW):
read/write memory mapping: modifying the memory also modifies the file on disk.
Unallocated:
not allocated.
allocator()

Create an AllocatorContext object with the required mapping mode

memSizes()

Check the current system memory and return the amount of RAM, free RAM, and swap.

class GenericObject(*args)

Generic dynamic polymorphic object.

GenericObject should not be used directly, but rather through the soma.aims.Object proxy.

See soma.aims.Object for a complete documentation.

class soma.aims.rc_ptr_GenericObject
get(*args, **kwargs)

get() is ambiguous: rc_ptr / Object has the get() method, providing access to the underlying object. GenericObject has the method get(key, default=None) as a dictionary-like object. This proxy calls the right one depending on arguments.

Vectors and points

soma.aims.Point3df

alias of soma.aims.AimsVector_FLOAT_3

class soma.aims.AimsVector_FLOAT_3

This class wraps an aims Point3df aka AimsVector<3, float> use the method items() to get a tuple out of it use setItems(Point3df) to affect new values

See the AimsVector C++ documentation

soma.aims.Point2df

alias of soma.aims.AimsVector_FLOAT_2

soma.aims.Point3d

alias of soma.aims.AimsVector_S16_3

RGB

class soma.aims.AimsRGB
class soma.aims.AimsRGBA

Fibers and Bundles handling

class soma.aims.BundleListener

Serial processing of bundles.

BundleListener listens events from a BundleProducer object, typically emitted when a new bundle starts or ends, a fiber starts or ends etc.

To use it, BundleListener has to be subclassed and some of the following methods overloaded: * bundleStarted * bundleTerminated * fiberStarted * fiberTerminated * newFiberPoint * noMoreBundle

To connect the listener to a producer, use BundleProducer::addBundleListener().

Inherited classes may inherit both BundleListener and BundleProducer, if they are part of a processing chain.

bundleStarted(producer, bundle_info)
bundleTerminated(producer, bundle_info)
fiberStarted(producer, bundle_info, fiber_info)
fiberTerminated(producer, bundle_info, fiber_info)
newFiberPoint(producer, bundle_info, fiber_info, point)
noMoreBundle(producer)
class soma.aims.BundleProducer

Serial processing of bundles.

BundleProducer emits events to a BundleListener object while walking through a bundles set structure (or a bundles file), typically when a new bundle starts or ends, a fiber starts or ends etc.

To connect the listener to a producer, use BundleProducer::addBundleListener().

Inherited classes may inherit both BundleListener and BundleProducer, if they are part of a processing chain.

addBundleListener(listener)

Connects a BundleProducer to a BunsdleListener.

class soma.aims.BundleReader

Reads a bundles file, and emits events while walking through its data.

BundleReader is a BundleProducer, so can be listened by any BundleListener. It may read several bundles/fibers formats, using a lower-level BundleProducer dedicated to a specific format.

Currently .bundles (AIMS/Connectomist) and .trk (Trackvis) formats are supported.

formatExtensions(format='ALL')

return a set of file extensions associated with the given format. If the format is “ALL” (default) then all extensions of all supported formats are returned. If the format does not exist, an empty set is returned, and no error is issued.

read()

read() is the entry point to fibers processing, and triggers the producer machinery.

supportedFormats()

return a set of fiber tracts formats names supported by the BundlesReader.

class soma.aims.BundleWriter

Writes bundles information to a bundles file.

BundleWriter is a BundleListener, thus must be connected to a BundleProducer, and is fed by it.

It will write the .bundles format.

bundleStarted(producer, bundle_info)
bundleTerminated(producer, bundle_info)
fiberStarted(producer, bundle_info, fiber_info)
fiberTerminated(producer, bundle_info, fiber_info)
newFiberPoint(producer, bundle_info, fiber_info, point)
noMoreBundle(producer)
setFileString(filename)

Set the output file name.

class soma.aims.BundleToGraph

Bundles structure building as a Graph

The Graph structure is used to represent bundles and fibers when we need to keep their complete structure in memory. This structure is especially used for 3D rendering in Anatomist.

BundleToGraph is a BundleListener, thus has to be connected to a BundleProducer to work (typically, a BundleReader).

Note that the BundleProducer / BundleListener system work as processing chains, and allows to keep only a small set of data in memory at one time. The Graph structure, on the contrary, keeps all information in memory, so may need a large amount of memory.

bundleStarted(producer, bundle_info)
bundleTerminated(producer, bundle_info)
fiberStarted(producer, bundle_info, fiber_info)
fiberTerminated(producer, bundle_info, fiber_info)
newFiberPoint(producer, bundle_info, fiber_info, point)
noMoreBundle(producer)

Conversion classes and functions

soma.aims.convertersObjectToPython = {'POINT2DF': <built-in function fromObject>, 'POINT3DF': <built-in function fromObject>, 'POINT4DF': <built-in function fromObject>, 'PyObject': <built-in function PyObjectfromObject>, 'S16': <built-in function asInt>, 'S32': <built-in function asInt>, 'U16': <built-in function asInt>, 'U32': <built-in function asInt>, 'boolean': <built-in function asBool>, 'rc_ptr of Mesh of FLOAT': <built-in function fromObject>, 'rc_ptr of Mesh of POINT2DF': <built-in function fromObject>, 'rc_ptr of Mesh of VOID': <built-in function fromObject>, 'rc_ptr of Mesh4 of FLOAT': <built-in function fromObject>, 'rc_ptr of Mesh4 of POINT2DF': <built-in function fromObject>, 'rc_ptr of Mesh4 of VOID': <built-in function fromObject>, 'rc_ptr of Segments of FLOAT': <built-in function fromObject>, 'rc_ptr of Segments of POINT2DF': <built-in function fromObject>, 'rc_ptr of Segments of VOID': <built-in function fromObject>, 'rc_ptr of bucket of DOUBLE': <built-in function fromObject>, 'rc_ptr of bucket of FLOAT': <built-in function fromObject>, 'rc_ptr of bucket of S16': <built-in function fromObject>, 'rc_ptr of bucket of S32': <built-in function fromObject>, 'rc_ptr of bucket of U16': <built-in function fromObject>, 'rc_ptr of bucket of U32': <built-in function fromObject>, 'rc_ptr of bucket of VOID': <built-in function fromObject>, 'rc_ptr of mesh of VOID': <built-in function fromObject>, 'rc_ptr of texture of FLOAT': <built-in function fromObject>, 'rc_ptr of texture of POINT2DF': <built-in function fromObject>, 'rc_ptr of texture of S16': <built-in function fromObject>, 'rc_ptr of texture of S32': <built-in function fromObject>, 'rc_ptr of texture of U32': <built-in function fromObject>, 'string': <function <lambda> at 0x7f7ca3afb6d0>}

Conversion function map. These converters are used to convert between a C++ object inside a generic object to their Python equivalent. They are typically used when accessing a sub-object – >>> from soma import aims >>> v = aims.Object(aims.vector_STRING()) >>> v.append(‘toto’) >>> v.append(‘bubu’) >>> type(v) soma.aims.Object >>> v.type() ‘vector of string’ >>> v[0] ‘toto’ >>> type(v[0]) str

In this example, v contains a C++ object of type std::vector<std::string>. Its elements are accessed via a wrapping which is using a C++ generic object (carto::Object). But in python we obtain a str (pyton string): the string has been taken out of the generic object using this conversion map (and then converted automatically to str by the SIP tool).

class soma.aims.Converter_Volume_S16_Volume_FLOAT

Converter classes can be used using the convert() method, or as a callable object:

result = converter(input_data)

Parameters:input_data (Volume_S16) – data to be converted
Returns:output data – converted data
Return type:Volume_FLOAT
convert(input_data, output_data)

In-place converson inside existing allocated data

Parameters:
  • input_data (Volume_S16) – data to be converted
  • output_data (Volume_FLOAT) – conversion output will be done into this data
Returns:
Return type:

None
class soma.aims.ShallowConverter_Volume_S16_Volume_FLOAT

Soma-IO

In this module, the newer IO system Soma-IO and supporting library is made available in Python, in the module soma.aims.soma.

class soma.aims.soma

This class represents the soma C++ namespace. It is rather used like a module, not as a class.

class DataSource(*args)

Abstraction layer for various data sources (file, buffer, socket…).

It can be seen as a stream, and is inspired by the QIODevice of Qt library.

Abstract class.

allowsMemoryMapping()

returns True if memory mapping is allowed on this kind of stream

at()

offset = at()

returns the current position in the stream bool at(pos)

Sets the current position in the stream (when supported). Returns True if successful.

atEnd()

True if the current position is at the end of the stream

clone()

duplicate the DataSource object

close()

Close the stream

eof()

when the end of stream is reached

flush()

flush the stream for buffered output

getch()

read one char and returns it

isOpen()

tells if the stream is open / ok.

iterateMode()

bitwise combination of possible access: direct (1) or sequential (2) access

mode()

access mode(s) (read/write): bitwise OR of Mode values

none()

An empty ref-counter that is more convenient than calling a constructor of rc_ptr_DataSource (useful when calling functions)

open(mode)

Opens the stream (when supported) in the specified Mode

Parameters:mode (int) – access Mode: Read (1), Write (2) or ReadWrite (3)
Returns:ok – if the operation was successful
Return type:bool
putch(ch)

write one char, and returns it

Parameters:ch (int) – char to write
readBlock(data, maxlen)
Parameters:
  • data (char*) – read buffer (C++)
  • maxlen (unsigned long int) – number of bytes to read
Returns:

num – number of bytes actually read
Return type:

long int
reset()

reset the stream and get to the start

size()

size (or len) of the data inn stream, in bytes

ungetch(ch)

un-read one char: put it back in the read buffer, and rewind one char

url()

URL of filename for the stream, when available

writeBlock(data, len)
Parameters:
  • data (const char * (C++)) – buffer to be written
  • len (unsigned long int) – size of the buffer to be written
Returns:

num – number of bytes actually written
Return type:

long int
class DataSourceInfo

Informative object used by IO system

This object is used by FormatChecker, FormatReader or FormatWriter to describe a DataSource. It contains a DataSourceList which contains at first a single default DataSource, a Object header and a DataSourceCapabilities.

  • The list is built by a FormatChecker and contains all the files involved in the reading/writing process (header, data, …)
  • The header is built by a FormatChecker and contains meta information.
  • The DSC contains properties dependant of the format, the specific file, the reading process (partial reading), etc.

It is possible to fix some or all of these three objects so that they are not recomputed by the FormatChecker.

see DataSourceInfoLoader DataSourceList DataSourceCapabilities

header()

get the header dict of the underlying data

identifiedFormat()

file format name

list()

get the DataSourceList of the underlying data

setIdentifiedFormat(format)

force the identified format name

url()

main filename or URL

class DataSourceInfoLoader

Generic information retreiver / checker for all data sources and file formats

It replaces aims.Finder.

DataSourceInfoLoader provides a plug-in system for new formats and data types. Formats are hidden in the plugins and should never be accessed directly.

Usage: check() the DataSourceInfo and then process according to the object type (“Volume of S16”, “Mesh”, “Texture”, “Bucket”, …).

Use the generic Reader once the data type is known, the right format will be selected automatically.

Avoiding manually switching on objects and data types is possible using the ReaderAlgorithm interface and presumably, template functions.

Here is an example of how to use the DataSourceInfoLoader class:

from soma import aims
from soma.aims import soma

f = soma.DataSourceInfoLoader()
info = f.check("toto.nii")
if not info.header():
    print "could not load", info.url()
else:
  object_type = info.header()["object_type"]
  if object_type == aims.typeCode(aims.Volume_S16):
      vr = soma.Reader_Volume_S16(info)
      try:
          vol = vr.read()
          print "volume read"
      except:
          print "Error loading", info.url()
  elif object_type == aims.typeCode(aims.Object):
      # do your thing
      print "Object"
  else:
      print info.url(), "is of type", object_type, \
          "which is not handled"

see DataSourceInfo, Reader, ReaderAlgorithm

check(dsi, options=aims.carto.none(), passbegin=1, passend=3)

Finds the right format checker

It is possible to specify wich passes to process through passbegin and passend. * pass 1: extension * pass 2: empty extension * pass 3: all writers see DataSourceInfo DataSourceList DataSourceCapabilities

Parameters:
  • dsi (DataSourceInfo containing header, DSlist and .) – capabilities. It allows us to have none, some or all information already computed. It is for the DSIloader to deal with the all case, and for the FormatCheckers to deal with some and none cases.
  • options (A dictionary containing options. They may not be of) – any use to the checker, but soma are (resolution_level).
Returns:

  • A DataSourceInfo object containing a header, a list of
  • DataSource and a list of Capabilities.
errorMessage()

error message from the last check

extensions(format)

Query supported file extensions for a format

Parameters:format (string) – format to query
Returns:exts – set of extensions names
Return type:set_STRING
launchException()

raise the read exception which was most probably the cause of a check() failure

readMinf(ds, base=aims.none(), options=aims.none())

read a .minf file dictionary

Parameters:
  • ds (DataSource) – minf file DataSource
  • base (Object) – base dict to be completed by .minf information
  • options (Object) – options dict
Returns:

minf – the minf file contents as a dictionary
Return type:

Object
state()

state of the DataSourceInfoLoader reading trial

class DataSourceList

This class allows to manipulate “lists” of pointers to DataSource.

It has the design of a dictionary in order to sort sources by content (header, minf, data, …). Since those contents depend on the format, the keywords used are defined by specific checkers and readers.

see FormatChecker FormatReader

The only global keyword is “default” which is used to store the DataSource defining (at construction) a reader.

see Reader

Note

The “default” keyword always contains at least one entry, which may be empty. I haven’t for now found any use to several “default” entries.

Access to a source is done using dataSource(…) methods. Sources are ordered by increasing order of insertion and numbering starts at 0.

addDataSource(key, ds)

Adds an element to the dictionary If new keyword, creates it.

Parameters:
dataSource()

datasource(key=”default”, i=0)

Accessing an element of the list If keyword doesn’t exist, or is empty, or coordinate is undefined, launches exception.

Parameters:
  • key (string (optional)) – keyword
  • i (int (optional)) – number of the element in list. Numbering starts at 0
empty()

Returns true only if no keyword inserted.

Warning

May return false while no DataSource present True if there is no key in the dictionary

exists(key)

True if the key exists in the dictionary

reset()

clear the dictionary: all keys and contents are removed.

size(key)

number of elements with the key key

typecount()

number of keys in the types dictionary

types()

Returns existing keywords.

Warning

There may be existing keywords with no DataSource

class FDDataSource(*args)

DataSource specialization for file descriptor stream

descriptor()

get the file descriptor

isFile()

True if the DataSource is a file

setDescriptor(fd)

Set the file descriptor fd (int)

class FileDataSource(*args)

DataSource specialization for a file.

initialOffset()

initial offset in the input file to start reading

url()

file name or URL of the file

class Reader_Object

Soma-IO Reader class. This is a C++ template class, which can read a specific type of data. All supported formats can be read.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
  • rc_ptr_DataSourceInfo: DataSource with info (more optimal when the data source has been identified and the header loaded)
allocatorContext()

Get the allocation context

attach(ds)

Attach a DataSource to read from (rc_ptr_DataSource) attach(filename, offset=0)

Attach a new filename + offset for reading

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

dataSourceInfo()

Get the dataSourceInfo, providing information on the read data

flush()

Flush the read buffer

options()

Get reading options (Object dictionary)

read()

Read an object from source. Two main modes exist:

  • full: read a full new object and return it
  • in-place: read an existing object, in-place

A multi-pass procedure is used to identify and read the data from the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all readers
Parameters:
  • or header (obj) – in-place mode: carto::Object, object to be read. OR: full mode: header (Object), optional
  • header (Object (optional)) –
  • passbegin (int (optional)) – begin at given step of the multi-pass identification/read procedure
  • passend (int (optional)) – end at given step of the multi-pass identification/read procedure
Returns:

  • in-place mode – True upon success False upon failure (but readers will more likely throw an exception)
  • full mode – the read object
setAllocatorContext(context)

Set allocation context for reading

setOptions(options)

set reading options (Object dictionary)

class Reader_Volume_CDOUBLE

Soma-IO Reader class. This is a C++ template class, which can read a specific type of data. All supported formats can be read.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
  • rc_ptr_DataSourceInfo: DataSource with info (more optimal when the data source has been identified and the header loaded)
allocatorContext()

Get the allocation context

attach(ds)

Attach a DataSource to read from (rc_ptr_DataSource) attach(filename, offset=0)

Attach a new filename + offset for reading

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

dataSourceInfo()

Get the dataSourceInfo, providing information on the read data

flush()

Flush the read buffer

options()

Get reading options (Object dictionary)

read()

Read an object from source. Two main modes exist:

  • full: read a full new object and return it
  • in-place: read an existing object, in-place

A multi-pass procedure is used to identify and read the data from the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all readers
Parameters:
  • or header (obj) – in-place mode: Volume_CDOUBLE, object to be read. OR: full mode: header (Object), optional
  • header (Object (optional)) –
  • passbegin (int (optional)) – begin at given step of the multi-pass identification/read procedure
  • passend (int (optional)) – end at given step of the multi-pass identification/read procedure
Returns:

  • in-place mode – True upon success False upon failure (but readers will more likely throw an exception)
  • full mode – the read object
setAllocatorContext(context)

Set allocation context for reading

setOptions(options)

set reading options (Object dictionary)

class Reader_Volume_CFLOAT

Soma-IO Reader class. This is a C++ template class, which can read a specific type of data. All supported formats can be read.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
  • rc_ptr_DataSourceInfo: DataSource with info (more optimal when the data source has been identified and the header loaded)
allocatorContext()

Get the allocation context

attach(ds)

Attach a DataSource to read from (rc_ptr_DataSource) attach(filename, offset=0)

Attach a new filename + offset for reading

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

dataSourceInfo()

Get the dataSourceInfo, providing information on the read data

flush()

Flush the read buffer

options()

Get reading options (Object dictionary)

read()

Read an object from source. Two main modes exist:

  • full: read a full new object and return it
  • in-place: read an existing object, in-place

A multi-pass procedure is used to identify and read the data from the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all readers
Parameters:
  • or header (obj) – in-place mode: Volume_CFLOAT, object to be read. OR: full mode: header (Object), optional
  • header (Object (optional)) –
  • passbegin (int (optional)) – begin at given step of the multi-pass identification/read procedure
  • passend (int (optional)) – end at given step of the multi-pass identification/read procedure
Returns:

  • in-place mode – True upon success False upon failure (but readers will more likely throw an exception)
  • full mode – the read object
setAllocatorContext(context)

Set allocation context for reading

setOptions(options)

set reading options (Object dictionary)

class Reader_Volume_DOUBLE

Soma-IO Reader class. This is a C++ template class, which can read a specific type of data. All supported formats can be read.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
  • rc_ptr_DataSourceInfo: DataSource with info (more optimal when the data source has been identified and the header loaded)
allocatorContext()

Get the allocation context

attach(ds)

Attach a DataSource to read from (rc_ptr_DataSource) attach(filename, offset=0)

Attach a new filename + offset for reading

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

dataSourceInfo()

Get the dataSourceInfo, providing information on the read data

flush()

Flush the read buffer

options()

Get reading options (Object dictionary)

read()

Read an object from source. Two main modes exist:

  • full: read a full new object and return it
  • in-place: read an existing object, in-place

A multi-pass procedure is used to identify and read the data from the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all readers
Parameters:
  • or header (obj) – in-place mode: Volume_DOUBLE, object to be read. OR: full mode: header (Object), optional
  • header (Object (optional)) –
  • passbegin (int (optional)) – begin at given step of the multi-pass identification/read procedure
  • passend (int (optional)) – end at given step of the multi-pass identification/read procedure
Returns:

  • in-place mode – True upon success False upon failure (but readers will more likely throw an exception)
  • full mode – the read object
setAllocatorContext(context)

Set allocation context for reading

setOptions(options)

set reading options (Object dictionary)

class Reader_Volume_FLOAT

Soma-IO Reader class. This is a C++ template class, which can read a specific type of data. All supported formats can be read.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
  • rc_ptr_DataSourceInfo: DataSource with info (more optimal when the data source has been identified and the header loaded)
allocatorContext()

Get the allocation context

attach(ds)

Attach a DataSource to read from (rc_ptr_DataSource) attach(filename, offset=0)

Attach a new filename + offset for reading

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

dataSourceInfo()

Get the dataSourceInfo, providing information on the read data

flush()

Flush the read buffer

options()

Get reading options (Object dictionary)

read()

Read an object from source. Two main modes exist:

  • full: read a full new object and return it
  • in-place: read an existing object, in-place

A multi-pass procedure is used to identify and read the data from the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all readers
Parameters:
  • or header (obj) – in-place mode: Volume_FLOAT, object to be read. OR: full mode: header (Object), optional
  • header (Object (optional)) –
  • passbegin (int (optional)) – begin at given step of the multi-pass identification/read procedure
  • passend (int (optional)) – end at given step of the multi-pass identification/read procedure
Returns:

  • in-place mode – True upon success False upon failure (but readers will more likely throw an exception)
  • full mode – the read object
setAllocatorContext(context)

Set allocation context for reading

setOptions(options)

set reading options (Object dictionary)

class Reader_Volume_HSV

Soma-IO Reader class. This is a C++ template class, which can read a specific type of data. All supported formats can be read.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
  • rc_ptr_DataSourceInfo: DataSource with info (more optimal when the data source has been identified and the header loaded)
allocatorContext()

Get the allocation context

attach(ds)

Attach a DataSource to read from (rc_ptr_DataSource) attach(filename, offset=0)

Attach a new filename + offset for reading

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

dataSourceInfo()

Get the dataSourceInfo, providing information on the read data

flush()

Flush the read buffer

options()

Get reading options (Object dictionary)

read()

Read an object from source. Two main modes exist:

  • full: read a full new object and return it
  • in-place: read an existing object, in-place

A multi-pass procedure is used to identify and read the data from the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all readers
Parameters:
  • or header (obj) – in-place mode: Volume_HSV, object to be read. OR: full mode: header (Object), optional
  • header (Object (optional)) –
  • passbegin (int (optional)) – begin at given step of the multi-pass identification/read procedure
  • passend (int (optional)) – end at given step of the multi-pass identification/read procedure
Returns:

  • in-place mode – True upon success False upon failure (but readers will more likely throw an exception)
  • full mode – the read object
setAllocatorContext(context)

Set allocation context for reading

setOptions(options)

set reading options (Object dictionary)

class Reader_Volume_POINT3DF

Soma-IO Reader class. This is a C++ template class, which can read a specific type of data. All supported formats can be read.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
  • rc_ptr_DataSourceInfo: DataSource with info (more optimal when the data source has been identified and the header loaded)
allocatorContext()

Get the allocation context

attach(ds)

Attach a DataSource to read from (rc_ptr_DataSource) attach(filename, offset=0)

Attach a new filename + offset for reading

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

dataSourceInfo()

Get the dataSourceInfo, providing information on the read data

flush()

Flush the read buffer

options()

Get reading options (Object dictionary)

read()

Read an object from source. Two main modes exist:

  • full: read a full new object and return it
  • in-place: read an existing object, in-place

A multi-pass procedure is used to identify and read the data from the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all readers
Parameters:
  • or header (obj) – in-place mode: Volume_POINT3DF, object to be read. OR: full mode: header (Object), optional
  • header (Object (optional)) –
  • passbegin (int (optional)) – begin at given step of the multi-pass identification/read procedure
  • passend (int (optional)) – end at given step of the multi-pass identification/read procedure
Returns:

  • in-place mode – True upon success False upon failure (but readers will more likely throw an exception)
  • full mode – the read object
setAllocatorContext(context)

Set allocation context for reading

setOptions(options)

set reading options (Object dictionary)

class Reader_Volume_RGB

Soma-IO Reader class. This is a C++ template class, which can read a specific type of data. All supported formats can be read.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
  • rc_ptr_DataSourceInfo: DataSource with info (more optimal when the data source has been identified and the header loaded)
allocatorContext()

Get the allocation context

attach(ds)

Attach a DataSource to read from (rc_ptr_DataSource) attach(filename, offset=0)

Attach a new filename + offset for reading

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

dataSourceInfo()

Get the dataSourceInfo, providing information on the read data

flush()

Flush the read buffer

options()

Get reading options (Object dictionary)

read()

Read an object from source. Two main modes exist:

  • full: read a full new object and return it
  • in-place: read an existing object, in-place

A multi-pass procedure is used to identify and read the data from the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all readers
Parameters:
  • or header (obj) – in-place mode: Volume_RGB, object to be read. OR: full mode: header (Object), optional
  • header (Object (optional)) –
  • passbegin (int (optional)) – begin at given step of the multi-pass identification/read procedure
  • passend (int (optional)) – end at given step of the multi-pass identification/read procedure
Returns:

  • in-place mode – True upon success False upon failure (but readers will more likely throw an exception)
  • full mode – the read object
setAllocatorContext(context)

Set allocation context for reading

setOptions(options)

set reading options (Object dictionary)

class Reader_Volume_RGBA

Soma-IO Reader class. This is a C++ template class, which can read a specific type of data. All supported formats can be read.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
  • rc_ptr_DataSourceInfo: DataSource with info (more optimal when the data source has been identified and the header loaded)
allocatorContext()

Get the allocation context

attach(ds)

Attach a DataSource to read from (rc_ptr_DataSource) attach(filename, offset=0)

Attach a new filename + offset for reading

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

dataSourceInfo()

Get the dataSourceInfo, providing information on the read data

flush()

Flush the read buffer

options()

Get reading options (Object dictionary)

read()

Read an object from source. Two main modes exist:

  • full: read a full new object and return it
  • in-place: read an existing object, in-place

A multi-pass procedure is used to identify and read the data from the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all readers
Parameters:
  • or header (obj) – in-place mode: Volume_RGBA, object to be read. OR: full mode: header (Object), optional
  • header (Object (optional)) –
  • passbegin (int (optional)) – begin at given step of the multi-pass identification/read procedure
  • passend (int (optional)) – end at given step of the multi-pass identification/read procedure
Returns:

  • in-place mode – True upon success False upon failure (but readers will more likely throw an exception)
  • full mode – the read object
setAllocatorContext(context)

Set allocation context for reading

setOptions(options)

set reading options (Object dictionary)

class Reader_Volume_S16

Soma-IO Reader class. This is a C++ template class, which can read a specific type of data. All supported formats can be read.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
  • rc_ptr_DataSourceInfo: DataSource with info (more optimal when the data source has been identified and the header loaded)
allocatorContext()

Get the allocation context

attach(ds)

Attach a DataSource to read from (rc_ptr_DataSource) attach(filename, offset=0)

Attach a new filename + offset for reading

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

dataSourceInfo()

Get the dataSourceInfo, providing information on the read data

flush()

Flush the read buffer

options()

Get reading options (Object dictionary)

read()

Read an object from source. Two main modes exist:

  • full: read a full new object and return it
  • in-place: read an existing object, in-place

A multi-pass procedure is used to identify and read the data from the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all readers
Parameters:
  • or header (obj) – in-place mode: Volume_S16, object to be read. OR: full mode: header (Object), optional
  • header (Object (optional)) –
  • passbegin (int (optional)) – begin at given step of the multi-pass identification/read procedure
  • passend (int (optional)) – end at given step of the multi-pass identification/read procedure
Returns:

  • in-place mode – True upon success False upon failure (but readers will more likely throw an exception)
  • full mode – the read object
setAllocatorContext(context)

Set allocation context for reading

setOptions(options)

set reading options (Object dictionary)

class Reader_Volume_S32

Soma-IO Reader class. This is a C++ template class, which can read a specific type of data. All supported formats can be read.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
  • rc_ptr_DataSourceInfo: DataSource with info (more optimal when the data source has been identified and the header loaded)
allocatorContext()

Get the allocation context

attach(ds)

Attach a DataSource to read from (rc_ptr_DataSource) attach(filename, offset=0)

Attach a new filename + offset for reading

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

dataSourceInfo()

Get the dataSourceInfo, providing information on the read data

flush()

Flush the read buffer

options()

Get reading options (Object dictionary)

read()

Read an object from source. Two main modes exist:

  • full: read a full new object and return it
  • in-place: read an existing object, in-place

A multi-pass procedure is used to identify and read the data from the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all readers
Parameters:
  • or header (obj) – in-place mode: Volume_S32, object to be read. OR: full mode: header (Object), optional
  • header (Object (optional)) –
  • passbegin (int (optional)) – begin at given step of the multi-pass identification/read procedure
  • passend (int (optional)) – end at given step of the multi-pass identification/read procedure
Returns:

  • in-place mode – True upon success False upon failure (but readers will more likely throw an exception)
  • full mode – the read object
setAllocatorContext(context)

Set allocation context for reading

setOptions(options)

set reading options (Object dictionary)

class Reader_Volume_U16

Soma-IO Reader class. This is a C++ template class, which can read a specific type of data. All supported formats can be read.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
  • rc_ptr_DataSourceInfo: DataSource with info (more optimal when the data source has been identified and the header loaded)
allocatorContext()

Get the allocation context

attach(ds)

Attach a DataSource to read from (rc_ptr_DataSource) attach(filename, offset=0)

Attach a new filename + offset for reading

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

dataSourceInfo()

Get the dataSourceInfo, providing information on the read data

flush()

Flush the read buffer

options()

Get reading options (Object dictionary)

read()

Read an object from source. Two main modes exist:

  • full: read a full new object and return it
  • in-place: read an existing object, in-place

A multi-pass procedure is used to identify and read the data from the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all readers
Parameters:
  • or header (obj) – in-place mode: Volume_U16, object to be read. OR: full mode: header (Object), optional
  • header (Object (optional)) –
  • passbegin (int (optional)) – begin at given step of the multi-pass identification/read procedure
  • passend (int (optional)) – end at given step of the multi-pass identification/read procedure
Returns:

  • in-place mode – True upon success False upon failure (but readers will more likely throw an exception)
  • full mode – the read object
setAllocatorContext(context)

Set allocation context for reading

setOptions(options)

set reading options (Object dictionary)

class Reader_Volume_U32

Soma-IO Reader class. This is a C++ template class, which can read a specific type of data. All supported formats can be read.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
  • rc_ptr_DataSourceInfo: DataSource with info (more optimal when the data source has been identified and the header loaded)
allocatorContext()

Get the allocation context

attach(ds)

Attach a DataSource to read from (rc_ptr_DataSource) attach(filename, offset=0)

Attach a new filename + offset for reading

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

dataSourceInfo()

Get the dataSourceInfo, providing information on the read data

flush()

Flush the read buffer

options()

Get reading options (Object dictionary)

read()

Read an object from source. Two main modes exist:

  • full: read a full new object and return it
  • in-place: read an existing object, in-place

A multi-pass procedure is used to identify and read the data from the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all readers
Parameters:
  • or header (obj) – in-place mode: Volume_U32, object to be read. OR: full mode: header (Object), optional
  • header (Object (optional)) –
  • passbegin (int (optional)) – begin at given step of the multi-pass identification/read procedure
  • passend (int (optional)) – end at given step of the multi-pass identification/read procedure
Returns:

  • in-place mode – True upon success False upon failure (but readers will more likely throw an exception)
  • full mode – the read object
setAllocatorContext(context)

Set allocation context for reading

setOptions(options)

set reading options (Object dictionary)

class Reader_Volume_U8

Soma-IO Reader class. This is a C++ template class, which can read a specific type of data. All supported formats can be read.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
  • rc_ptr_DataSourceInfo: DataSource with info (more optimal when the data source has been identified and the header loaded)
allocatorContext()

Get the allocation context

attach(ds)

Attach a DataSource to read from (rc_ptr_DataSource) attach(filename, offset=0)

Attach a new filename + offset for reading

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

dataSourceInfo()

Get the dataSourceInfo, providing information on the read data

flush()

Flush the read buffer

options()

Get reading options (Object dictionary)

read()

Read an object from source. Two main modes exist:

  • full: read a full new object and return it
  • in-place: read an existing object, in-place

A multi-pass procedure is used to identify and read the data from the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all readers
Parameters:
  • or header (obj) – in-place mode: Volume_U8, object to be read. OR: full mode: header (Object), optional
  • header (Object (optional)) –
  • passbegin (int (optional)) – begin at given step of the multi-pass identification/read procedure
  • passend (int (optional)) – end at given step of the multi-pass identification/read procedure
Returns:

  • in-place mode – True upon success False upon failure (but readers will more likely throw an exception)
  • full mode – the read object
setAllocatorContext(context)

Set allocation context for reading

setOptions(options)

set reading options (Object dictionary)

class Transformation(*args)

Base class for spatial transformations.

isIdentity()

Test if the transformation can safely be omitted

This method must only return true if the transformation behaves exactly like an identity transformation (notably, the transform methods will always return the input coordinates unchanged).

NOTE: Implementors of derived classes may choose to always return false if a test would be difficult to implement or expensive to run.

class Transformation3d(*args)

Base class for spatial transformations in 3D.

class Writer_Object

Soma-IO Writer class. This is a C++ template class, which can write a specific type of data. All supported formats can be written.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
attach(ds)

Attach a new data source (rc_ptr_DataSource) to write into attach(filename)

Attach a new output file name to write into

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

flush()

flush the write buffer

write()

Write the given object to the data source (generally files)

A multi-pass procedure is used to identify and write the data to the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all writes
Parameters:
  • obj (carto::Object) – object to write
  • options (Object (optional)) – Options can be passed to specify some writing parameters. The most important is the format (“format” property): if it is specified, this format is tried first, so you can use it to force the format, otherwise it will be determined from the filename extension (if available). If no extension and no format are given, the first working format will be used.
  • passbegin (int (optional)) –
  • passend (int (optional)) –
Returns:
Return type:

True upon success, False upon failure, but an exception is more likely thrown in such case
writtenObjectType()

After writing, get the object type code (string) of the data

class Writer_Volume_CDOUBLE

Soma-IO Writer class. This is a C++ template class, which can write a specific type of data. All supported formats can be written.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
attach(ds)

Attach a new data source (rc_ptr_DataSource) to write into attach(filename)

Attach a new output file name to write into

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

flush()

flush the write buffer

write()

Write the given object to the data source (generally files)

A multi-pass procedure is used to identify and write the data to the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all writes
Parameters:
  • obj (Volume_CDOUBLE) – object to write
  • options (Object (optional)) – Options can be passed to specify some writing parameters. The most important is the format (“format” property): if it is specified, this format is tried first, so you can use it to force the format, otherwise it will be determined from the filename extension (if available). If no extension and no format are given, the first working format will be used.
  • passbegin (int (optional)) –
  • passend (int (optional)) –
Returns:
Return type:

True upon success, False upon failure, but an exception is more likely thrown in such case
writtenObjectType()

After writing, get the object type code (string) of the data

class Writer_Volume_CFLOAT

Soma-IO Writer class. This is a C++ template class, which can write a specific type of data. All supported formats can be written.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
attach(ds)

Attach a new data source (rc_ptr_DataSource) to write into attach(filename)

Attach a new output file name to write into

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

flush()

flush the write buffer

write()

Write the given object to the data source (generally files)

A multi-pass procedure is used to identify and write the data to the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all writes
Parameters:
  • obj (Volume_CFLOAT) – object to write
  • options (Object (optional)) – Options can be passed to specify some writing parameters. The most important is the format (“format” property): if it is specified, this format is tried first, so you can use it to force the format, otherwise it will be determined from the filename extension (if available). If no extension and no format are given, the first working format will be used.
  • passbegin (int (optional)) –
  • passend (int (optional)) –
Returns:
Return type:

True upon success, False upon failure, but an exception is more likely thrown in such case
writtenObjectType()

After writing, get the object type code (string) of the data

class Writer_Volume_DOUBLE

Soma-IO Writer class. This is a C++ template class, which can write a specific type of data. All supported formats can be written.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
attach(ds)

Attach a new data source (rc_ptr_DataSource) to write into attach(filename)

Attach a new output file name to write into

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

flush()

flush the write buffer

write()

Write the given object to the data source (generally files)

A multi-pass procedure is used to identify and write the data to the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all writes
Parameters:
  • obj (Volume_DOUBLE) – object to write
  • options (Object (optional)) – Options can be passed to specify some writing parameters. The most important is the format (“format” property): if it is specified, this format is tried first, so you can use it to force the format, otherwise it will be determined from the filename extension (if available). If no extension and no format are given, the first working format will be used.
  • passbegin (int (optional)) –
  • passend (int (optional)) –
Returns:
Return type:

True upon success, False upon failure, but an exception is more likely thrown in such case
writtenObjectType()

After writing, get the object type code (string) of the data

class Writer_Volume_FLOAT

Soma-IO Writer class. This is a C++ template class, which can write a specific type of data. All supported formats can be written.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
attach(ds)

Attach a new data source (rc_ptr_DataSource) to write into attach(filename)

Attach a new output file name to write into

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

flush()

flush the write buffer

write()

Write the given object to the data source (generally files)

A multi-pass procedure is used to identify and write the data to the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all writes
Parameters:
  • obj (Volume_FLOAT) – object to write
  • options (Object (optional)) – Options can be passed to specify some writing parameters. The most important is the format (“format” property): if it is specified, this format is tried first, so you can use it to force the format, otherwise it will be determined from the filename extension (if available). If no extension and no format are given, the first working format will be used.
  • passbegin (int (optional)) –
  • passend (int (optional)) –
Returns:
Return type:

True upon success, False upon failure, but an exception is more likely thrown in such case
writtenObjectType()

After writing, get the object type code (string) of the data

class Writer_Volume_HSV

Soma-IO Writer class. This is a C++ template class, which can write a specific type of data. All supported formats can be written.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
attach(ds)

Attach a new data source (rc_ptr_DataSource) to write into attach(filename)

Attach a new output file name to write into

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

flush()

flush the write buffer

write()

Write the given object to the data source (generally files)

A multi-pass procedure is used to identify and write the data to the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all writes
Parameters:
  • obj (Volume_HSV) – object to write
  • options (Object (optional)) – Options can be passed to specify some writing parameters. The most important is the format (“format” property): if it is specified, this format is tried first, so you can use it to force the format, otherwise it will be determined from the filename extension (if available). If no extension and no format are given, the first working format will be used.
  • passbegin (int (optional)) –
  • passend (int (optional)) –
Returns:
Return type:

True upon success, False upon failure, but an exception is more likely thrown in such case
writtenObjectType()

After writing, get the object type code (string) of the data

class Writer_Volume_POINT3DF

Soma-IO Writer class. This is a C++ template class, which can write a specific type of data. All supported formats can be written.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
attach(ds)

Attach a new data source (rc_ptr_DataSource) to write into attach(filename)

Attach a new output file name to write into

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

flush()

flush the write buffer

write()

Write the given object to the data source (generally files)

A multi-pass procedure is used to identify and write the data to the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all writes
Parameters:
  • obj (Volume_POINT3DF) – object to write
  • options (Object (optional)) – Options can be passed to specify some writing parameters. The most important is the format (“format” property): if it is specified, this format is tried first, so you can use it to force the format, otherwise it will be determined from the filename extension (if available). If no extension and no format are given, the first working format will be used.
  • passbegin (int (optional)) –
  • passend (int (optional)) –
Returns:
Return type:

True upon success, False upon failure, but an exception is more likely thrown in such case
writtenObjectType()

After writing, get the object type code (string) of the data

class Writer_Volume_RGB

Soma-IO Writer class. This is a C++ template class, which can write a specific type of data. All supported formats can be written.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
attach(ds)

Attach a new data source (rc_ptr_DataSource) to write into attach(filename)

Attach a new output file name to write into

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

flush()

flush the write buffer

write()

Write the given object to the data source (generally files)

A multi-pass procedure is used to identify and write the data to the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all writes
Parameters:
  • obj (Volume_RGB) – object to write
  • options (Object (optional)) – Options can be passed to specify some writing parameters. The most important is the format (“format” property): if it is specified, this format is tried first, so you can use it to force the format, otherwise it will be determined from the filename extension (if available). If no extension and no format are given, the first working format will be used.
  • passbegin (int (optional)) –
  • passend (int (optional)) –
Returns:
Return type:

True upon success, False upon failure, but an exception is more likely thrown in such case
writtenObjectType()

After writing, get the object type code (string) of the data

class Writer_Volume_RGBA

Soma-IO Writer class. This is a C++ template class, which can write a specific type of data. All supported formats can be written.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
attach(ds)

Attach a new data source (rc_ptr_DataSource) to write into attach(filename)

Attach a new output file name to write into

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

flush()

flush the write buffer

write()

Write the given object to the data source (generally files)

A multi-pass procedure is used to identify and write the data to the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all writes
Parameters:
  • obj (Volume_RGBA) – object to write
  • options (Object (optional)) – Options can be passed to specify some writing parameters. The most important is the format (“format” property): if it is specified, this format is tried first, so you can use it to force the format, otherwise it will be determined from the filename extension (if available). If no extension and no format are given, the first working format will be used.
  • passbegin (int (optional)) –
  • passend (int (optional)) –
Returns:
Return type:

True upon success, False upon failure, but an exception is more likely thrown in such case
writtenObjectType()

After writing, get the object type code (string) of the data

class Writer_Volume_S16

Soma-IO Writer class. This is a C++ template class, which can write a specific type of data. All supported formats can be written.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
attach(ds)

Attach a new data source (rc_ptr_DataSource) to write into attach(filename)

Attach a new output file name to write into

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

flush()

flush the write buffer

write()

Write the given object to the data source (generally files)

A multi-pass procedure is used to identify and write the data to the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all writes
Parameters:
  • obj (Volume_S16) – object to write
  • options (Object (optional)) – Options can be passed to specify some writing parameters. The most important is the format (“format” property): if it is specified, this format is tried first, so you can use it to force the format, otherwise it will be determined from the filename extension (if available). If no extension and no format are given, the first working format will be used.
  • passbegin (int (optional)) –
  • passend (int (optional)) –
Returns:
Return type:

True upon success, False upon failure, but an exception is more likely thrown in such case
writtenObjectType()

After writing, get the object type code (string) of the data

class Writer_Volume_S32

Soma-IO Writer class. This is a C++ template class, which can write a specific type of data. All supported formats can be written.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
attach(ds)

Attach a new data source (rc_ptr_DataSource) to write into attach(filename)

Attach a new output file name to write into

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

flush()

flush the write buffer

write()

Write the given object to the data source (generally files)

A multi-pass procedure is used to identify and write the data to the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all writes
Parameters:
  • obj (Volume_S32) – object to write
  • options (Object (optional)) – Options can be passed to specify some writing parameters. The most important is the format (“format” property): if it is specified, this format is tried first, so you can use it to force the format, otherwise it will be determined from the filename extension (if available). If no extension and no format are given, the first working format will be used.
  • passbegin (int (optional)) –
  • passend (int (optional)) –
Returns:
Return type:

True upon success, False upon failure, but an exception is more likely thrown in such case
writtenObjectType()

After writing, get the object type code (string) of the data

class Writer_Volume_U16

Soma-IO Writer class. This is a C++ template class, which can write a specific type of data. All supported formats can be written.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
attach(ds)

Attach a new data source (rc_ptr_DataSource) to write into attach(filename)

Attach a new output file name to write into

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

flush()

flush the write buffer

write()

Write the given object to the data source (generally files)

A multi-pass procedure is used to identify and write the data to the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all writes
Parameters:
  • obj (Volume_U16) – object to write
  • options (Object (optional)) – Options can be passed to specify some writing parameters. The most important is the format (“format” property): if it is specified, this format is tried first, so you can use it to force the format, otherwise it will be determined from the filename extension (if available). If no extension and no format are given, the first working format will be used.
  • passbegin (int (optional)) –
  • passend (int (optional)) –
Returns:
Return type:

True upon success, False upon failure, but an exception is more likely thrown in such case
writtenObjectType()

After writing, get the object type code (string) of the data

class Writer_Volume_U32

Soma-IO Writer class. This is a C++ template class, which can write a specific type of data. All supported formats can be written.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
attach(ds)

Attach a new data source (rc_ptr_DataSource) to write into attach(filename)

Attach a new output file name to write into

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

flush()

flush the write buffer

write()

Write the given object to the data source (generally files)

A multi-pass procedure is used to identify and write the data to the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all writes
Parameters:
  • obj (Volume_U32) – object to write
  • options (Object (optional)) – Options can be passed to specify some writing parameters. The most important is the format (“format” property): if it is specified, this format is tried first, so you can use it to force the format, otherwise it will be determined from the filename extension (if available). If no extension and no format are given, the first working format will be used.
  • passbegin (int (optional)) –
  • passend (int (optional)) –
Returns:
Return type:

True upon success, False upon failure, but an exception is more likely thrown in such case
writtenObjectType()

After writing, get the object type code (string) of the data

class Writer_Volume_U8

Soma-IO Writer class. This is a C++ template class, which can write a specific type of data. All supported formats can be written.

Constructor parameters may be:

  • string: filename
  • rc_ptr_DataSource: generic DataSource
attach(ds)

Attach a new data source (rc_ptr_DataSource) to write into attach(filename)

Attach a new output file name to write into

close()

Close the data source stream

dataSource()

Get the data source (rc_ptr_DataSource)

flush()

flush the write buffer

write()

Write the given object to the data source (generally files)

A multi-pass procedure is used to identify and write the data to the data source:

  • pass 1: format hint
  • pass 2: extension
  • pass 3: empty extension
  • pass 4: all writes
Parameters:
  • obj (Volume_U8) – object to write
  • options (Object (optional)) – Options can be passed to specify some writing parameters. The most important is the format (“format” property): if it is specified, this format is tried first, so you can use it to force the format, otherwise it will be determined from the filename extension (if available). If no extension and no format are given, the first working format will be used.
  • passbegin (int (optional)) –
  • passend (int (optional)) –
Returns:
Return type:

True upon success, False upon failure, but an exception is more likely thrown in such case
writtenObjectType()

After writing, get the object type code (string) of the data