pIceImarisConnector

class pIceImarisConnector.pIceImarisConnector(imarisApplication=None)

pIceImarisConnector is a simple Python class that eases communication between Bitplane Imaris and Python using the Imaris XT interface.

Copyright Aaron Ponti, 2013 - 2015.

Parameters:imarisApplication – (optional) if omitted, a pIceImarisConnector object is created that is not connected to any Imaris instance.

Imaris can then be started (and connected) using the startImaris() method:

>>> conn.startImaris()

Alternatively, imarisApplication can be:

  • an Imaris Application ID as provided by Imaris,
  • a pIceImarisConnector reference,
  • an Imaris Application ICE object.

In all these cases, the instantiated pIceImarisConnector object is connected to and ready to interface with Imaris.

REMARK

The Imaris Application ICE object is stored in the property mImarisApplication. The mImarisApplication property gives access to the entire Imaris ICE API.

Example:

>>> conn.mImarisApplication.GetSurpassSelection()

returns the currently selected object in the Imaris surpass scene.

autocast(dataItem)

Casts IDataItems to their derived types.

Parameters:dataItem (Imaris::IDataItem) – object to be cast.
Returns:object cast to the appropriate Imaris::IDataItem subclass.
Return type:One of:
  • Imaris::IClippingPlane
  • Imaris::IDataContainer
  • Imaris::IFilaments
  • Imaris::IFrame
  • Imaris::IDataSet
  • Imaris::IICells
  • Imaris::ILightSource
  • Imaris::IMeasurementPoints
  • Imaris::ISpots
  • Imaris::ISurfaces
  • Imaris::IVolume
  • Imaris::ISurpassCamera
  • Imaris::IImageProcessing
  • Imaris::IFactory
closeImaris(quiet=False)

Closes the Imaris instance associated to the pIceImarisConnector object and resets the mImarisApplication property.

Parameters:quiet (Boolean) – (optional, default False) If True, Imaris won’t pop-up a save dialog and close silently.
Returns:True if Imaris could be closed successfully, False otherwise.
Return type:Boolean
createAndSetSpots(coords, timeIndices, radii, name, color, container=None)

Creates Spots and adds them to the Surpass Scene.

Parameters:
  • coords (list) – (nx3) [x, y, z]n coordinate matrix in dataset units.
  • timeIndices (list) – spots time indices.
  • radii (list) – spots radii.
  • name (string) – name of the Spots object.
  • color (list, tuple or float32 Numpy Array) – (1x4), (0..1) vector of [R, G, B, A] values. Example: [0.5, 1.0, 1.0, 1.0].
  • container (an Imaris::IDataContainer object) – (optional) if not set, the Spots object is added at the root of the Surpass Scene. Please note that it is the user’s responsibility to attach the container to the surpass scene!
Returns:

the generated Spots object.
Return type:

Imaris::ISpots
createDataset(datatype, sizeX, sizeY, sizeZ, sizeC, sizeT, voxelSizeX=1, voxelSizeY=1, voxelSizeZ=1, deltaTime=1)

Creates an Imaris dataset and replaces current one.

Parameters:
  • datatype (one of ‘uint8’, ‘uint16’, ‘single’, Imaris.tType.eTypeUInt8, Imaris.tType.eTypeUInt16, Imaris.tType.eTypeFloat) – datype for the dataset to be created
  • sizeX (int) – dataset width.
  • sizeY (int) – dataset height.
  • sizeZ (int) – number of planes.
  • sizeC (int) – number of channels.
  • sizeT (int) – number of timepoints.
  • voxelSizeX (float) – (optional, default = 1) voxel size in X direction.
  • voxelSizeY (float) – (optional, default = 1) voxel size in Y direction.
  • voxelSizeZ (float) – (optional, default = 1) voxel size in Z direction.
  • deltaTime (float) – (optional, default = 1) time difference between consecutive time points.
Returns:

created DataSet
Return type:

Imaris::IDataSet

EXAMPLE

>>> conn.createDataset('uint8', 100, 200, 50, 3, 10, 0.20, 0.25, 0.5, 0.1)

REMARKS

The function takes care of adding the created dataset to Imaris.

display()

Displays the string representation of the pIceImarisConnector object.

getAllSurpassChildren(recursive, typeFilter=None)

Returns all children of the surpass scene recursively. Folders (i.e. IDataContainer objects) may be scanned (recursively) but are not returned. Optionally, the returned objects may be filtered by type.

Parameters:
  • recursive (Boolean) – If True, folders will be scanned recursively; if False, only objects at root level will be inspected.
  • typeFilter (string) – (optional) Filters the children by type. Only the surpass children of the specified type are returned. One of:
  • ‘Cells’
  • ‘ClippingPlane’
  • ‘Dataset’
  • ‘Filaments’
  • ‘Frame’
  • ‘LightSource’
  • ‘MeasurementPoints’
  • ‘Spots’
  • ‘Surfaces’
  • ‘SurpassCamera’
  • ‘Volume’
Returns:child objects.
Return type:list
getDataSubVolume(x0, y0, z0, channel, timepoint, dX, dY, dZ, iDataSet=None)

Returns a data subvolume from Imaris.

Parameters:
  • x0 (int) – x coordinate of the top-left vertex of the subvolume to be returned.
  • y0 (int) – y coordinate of the top-left vertex of the subvolume to be returned.
  • z0 (int) – z coordinate of the top-left vertex of the subvolume to be returned.
  • channel (int) – channel index.
  • timepoint (int) – timepoint index.
  • dX (int) – extension in x direction of the subvolume to be returned.
  • dY (int) – extension in y direction of the subvolume to be returned.
  • dZ (int) – extension in z direction of the subvolume to be returned.
  • iDataSet (Imaris::IDataSet) – (optional) get the data volume from the passed IDataSet object instead of current one; if omitted, current dataset (i.e. conn.mImarisApplication.GetDataSet()) will be used. This is useful for instance when masking channels.
Returns:

data subvolume.
Return type:

Numpy array with dtype being one of numpy.uint8, numpy.uint16, numpy.float32.

EXAMPLE

The following holds:

>>> stack = conn.getDataVolume(0, 0)
>>> subVolume = conn.getDataSubVolume(x0, y0, z0, 0, 0, dX, dY, dZ)
>>> subStack = stack[z0 : z0 + dZ, y0 : y0 + dY, x0 : x0 + dX]

subVolume is identical to subStack

REMARKS

  • Implementation detail: this function gets the subvolume as a 1D array and reshapes it in place.
  • Coordinates and extensions are in voxels (integers) and not in units!
getDataVolume(channel, timepoint, iDataSet=None)

Returns the data volume from Imaris.

Parameters:
  • channel (int) – channel index.
  • timepoint (int) – timepoint index.
  • iDataSet (Imaris::IDataSet) – (optional) get the data volume from the passed IDataSet object instead of current one; if omitted, current dataset (i.e. conn.mImarisApplication.GetDataSet()) will be used. This is useful for instance when masking channels.
Returns:

data volume (3D Numpy array).
Return type:

Numpy array with dtype being one of np.uint8, np.uint16, np.float32.

REMARKS

Implementation detail: this function gets the volume as a 1D array and reshapes it in place.

getExtends()

Returns the dataset extends.

Returns:DataSet extends.
Return type:tuple

The extends tuple is: (minX, minY, minZ, maxX, maxY, maxZ), where:

  • minX : min extend along X dimension,
  • minY : min extend along Y dimension,
  • minZ : min extend along Z dimension,
  • maxX : max extend along X dimension,
  • maxY : max extend along Y dimension,
  • maxZ : max extend along Z dimension.
getImarisVersionAsInteger()

Returns the Imaris version as an integer.

The conversion is performed as follows: v = 100000 * Major + 10000 * Minor + 100 * Patch.

Returns:Imaris version as integer.
Return type:int
getNumpyDatatype()

Returns the datatype of the dataset as a python Numpy type (or None).

Returns:datatype of the dataset as a Numpy type.
Return type:one of np.uint8, np.uint16, np.float32, or None if the type is unknown in Imaris.
getSizes()

Returns the dataset sizes.

Returns:DataSet sizes.
Return type:tuple

The sizes tuple is: (sizeX, sizeY, sizeZ, sizeC, sizeT), where:

  • sizeX : dataset size X,
  • sizeY : dataset size Y,
  • sizeZ : number of planes,
  • sizeC : number of channels,
  • sizeT : number of time points.
getSurpassCameraRotationMatrix()

Calculates the rotation matrix that corresponds to current view in the Surpass Scene (from the Camera Quaternion) for the axes with “Origin Bottom Left”.

Returns:tuple with (4 x 4) rotation matrix (R) and a Boolean (isI) that indicates whether or not the rotation matrix is the Identity matrix (i.e. the camera is perpendicular to the dataset).
Return type:tuple (R, isI)

REMARKS

TODO: Verify the correctness for the other axes orientations.

getSurpassSelection(typeFilter=None)

Returns the auto-cast current surpass selection. If the ‘typeFilter’ parameter is specified, the object class is checked against it and None is returned instead of the object if the type does not match.

Parameters:typeFilter (String) – (optional, default None) Specifies the expected object class. If the selected object is not of the specified type, the function will return None instead. Type is one of:
  • ‘Cells’
  • ‘ClippingPlane’
  • ‘Dataset’
  • ‘Filaments’
  • ‘Frame’
  • ‘LightSource’
  • ‘MeasurementPoints’
  • ‘Spots’
  • ‘Surfaces’
  • ‘SurpassCamera’
  • ‘Volume’
Returns:autocast, currently selected surpass object; if nothing is selected, or if the object class does not match the passed type, selection will be None instead.
Return type:One of:
  • Imaris::IClippingPlane
  • Imaris::IDataContainer
  • Imaris::IFilaments
  • Imaris::IFrame
  • Imaris::IDataSet
  • Imaris::IICells
  • Imaris::ILightSource
  • Imaris::IMeasurementPoints
  • Imaris::ISpots
  • Imaris::ISurfaces
  • Imaris::IVolume
  • Imaris::ISurpassCamera
  • Imaris::IImageProcessing
  • Imaris::IFactory
getTracks(iObject=None)

This method returns the tracks associated to an ISpots or an ISurfaces object. If no object is passed as argument, the function will try with the currently selected object in the Surpass Scene. If this is not an ISpots nor an ISurfaces object, an empty result set will be returned.

:param iSpots (optional, default None) (optional) either an ISpots or an ISurfaces object. If not passed, the function will try with the currently selected object in the Surpass Scene. :type Imaris::IDataItem

Returns:tuple containing an array of tracks and and array of starting time indices for each track.
Return type:tuple

The tracks array will be empty if no tracks exist for the object or if the argument is not an ISpots or an ISurfaces object. Each track is in the form [x y z]n, were n is the length of the track.

getVoxelSizes()

Returns the X, Y, and Z voxel sizes of the dataset.

Returns:dataset voxel sizes.
Return type:tuple

The voxelsize tuple is: (voxelSizeX, voxelSizeY, voxelSizeZ), where:

  • voxelSizeX: voxel Size in X direction,
  • voxelSizeY: voxel Size in Y direction,
  • voxelSizeZ: voxel Size in Z direction.
info()

Prints to console the full paths to the Imaris and ImarisServerIce executables and the ImarisLib module.

isAlive()

Checks whether the (stored) connection to Imaris is still alive.

Returns:True if the connection is still alive, False otherwise.
Return type:Boolean
mapPositionsUnitsToVoxels(uPos)

Maps voxel coordinates in dataset units to voxel indices.

Parameters:uPos (list or float32 Numpy array.) – (N x 3) matrix containing the X, Y, Z coordinates in dataset units.
Returns:(N x 3) matrix containing the X, Y, Z voxel indices.
Return type:list
mapPositionsVoxelsToUnits(vPos)

Maps voxel indices in dataset units to unit coordinates.

Parameters:vPos (list or float32 Numpy array.) – (N x 3) matrix containing the X, Y, Z unit coordinates mapped onto a voxel grid.
Returns:(N x 3) matrix containing the X, Y, Z coordinates in dataset units.
Return type:list
mapRgbaScalarToVector(rgbaScalar)

Maps an int32 RGBA scalar to an 1-by-4, (0..1) float vector.

Parameters:rgbaScalar (int32) – scalar coding for RGBA (as returned from Imaris via the GetColorRGBA() method of IDataItem objects).
Returns:1-by-4 array with [R, G, B, A] indicating (R)ed, (G)reen, (B)lue, and (A)lpha (=transparency; 0 is opaque) in the 0..1 range.
Return type:float Numpy array

IMPORTANT REMARKS

Imaris stores the color components of objects internally as an uint32 scalar. When this scalar is returned by ImarisXT via the GetColorRGBA() method, it reaches python as signed int32 instead.

By the way the R, G, B and A components are packed into the scalar, a forced typecast from uint32 to int32 corrupts the value of the transparency component (the actual colors are not affected). In case the transparency is zero, the uint32 and int32 rendition of the number is the same, and there is no problem; but if it is not, the returned value WILL BE NEGATIVE and will need to be casted before it can be processed.

The mapRgbaScalarToVector() method will transparently work around this problem for you.

EXAMPLE

In this example, current color of a Spots object is obtained from Imaris and pushed back.

>>> spots = conn.getSurpassSelection('Spots')
>>> current = conn.mapRgbaScalarToVector(spots.GetColorRGBA())
>>> spots.SetColorRGBA(conn.mapRgbaVectorToScalar(current))
mapRgbaVectorToScalar(rgbaVector)

Maps an 1-by-4, (0..1) RGBA vector to an int32 scalar.

Parameters:rgbaVector (float32 Numpy array) – 1-by-4 array with [R, G, B, A] indicating (R)ed, (G)reen, (B)lue, and (A)lpha (=transparency; 0 is opaque). All values are between 0 and 1.
Returns:scalar coding for RGBA (to be used with the SetColorRGBA() method of IDataItem objects).
Return type:int32

IMPORTANT REMARKS

The way one calculates the RGBA value from an [R, G, B, A] vector (with the values of R, G, B, and A all between 0 and 1) is simply:

uint32([R G B A] * [1 256 256^2 256^3])

(where * is the matrix product). This gives a number between 0 and 2^32 - 1.

To pass this number to Imaris through ImarisXT via the SetColorRGBA() method, we need to type cast it to signed int32. If we do not do this, Imaris will misinterpret the value for the transparency.

The mapRgbaVectorToScalar() method will transparently work around this problem for you.

setDataVolume(stack, channel, timepoint)

Sets the data volume to Imaris.

Parameters:
  • stack (np.uint8, np.uint16 or np.float32) – 3D array.
  • channel (int) – channel index.
  • timepoint (int) – timepoint index.

REMARKS

If a dataset exists, the X, Y, and Z dimensions must match the ones of the stack being copied in. If no dataset exists, one will be created to fit it with default other values.

startImaris(userControl=False)

Starts an Imaris instance and stores the ImarisApplication ICE object.

Parameters:userControl (Boolean) – (optional, default False) The optional parameter userControl sets the fate of Imaris when the client is closed: if userControl is True, Imaris terminates when the pIceImarisConnector object is deleted. If is it set to False, Imaris stays open after the pIceImarisConnector object is deleted.
Returns:True if starting Imaris was successful, False otherwise.
Return type:Boolean