nodes::utils::array_handler Namespace Reference

Classes
class	ArrayCache
Functions
def	array2vtk
def	array2vtkCellArray
def	array2vtkIdList
def	array2vtkPoints
def	convert_array
def	create_vtk_array
def	deref_array
def	deref_vtk
def	get_correct_sig
def	get_numeric_array_type
def	get_sizeof_vtk_array
def	get_vtk_array_type
def	get_vtk_to_numeric_typemap
def	is_array
def	is_array_or_vtkarray
def	is_array_sig
def	vtk2array
Variables
	_array_cache = _dummy
	_dummy = None
	ID_TYPE_CODE = numpy.int32
	LONG_TYPE_CODE = numpy.int32
list	mod = sys.modules[name]
	numpy_support = None
	ULONG_TYPE_CODE = numpy.uint32
tuple	VTK_ID_TYPE_SIZE = vtk.vtkIdTypeArray()
tuple	VTK_LONG_TYPE_SIZE = vtk.vtkLongArray()

Detailed Description

This module contains all the array handling code for TVTK.

The most important functions provided by this module involve the
conversion of numpy arrays/Python lists to different VTK data arrays
and vice-versa.

Warning: Numpy Character arrays will not work properly since there
seems no unique one-to-one VTK data array type to map it to.

Function Documentation

def nodes::utils::array_handler::array2vtk	(	num_array,
		vtk_array = `None`
	)

Converts a real numpy Array (or a Python list) to a VTK array
object.

This function only works for real arrays.  Complex arrays are NOT
handled.  It also works for multi-component arrays.  However, only
1, and 2 dimensional arrays are supported.  This function is very
efficient, so large arrays should not be a problem.

Even in cases when no copy of the numpy array data is performed,
a reference to the array is cached.  The passed array can
therefore be deleted safely in all circumstances.

Parameters
----------

- num_array : numpy array or Python list/tuple

  The input array must be 1 or 2D.  A copy of the numeric array
  data passed is made in the following circumstances:

   1. A Python list/tuple was passed.
   2. A non-contiguous numpy array was passed.
   3. A `vtkBitArray` instance was passed as the second argument.
   4. The types of the `vtk_array` and the `num_array` are not
      equivalent to each other.  For example if one is an integer
      array and the other a float.


- vtk_array : `vtkDataArray` (default: `None`)

  If an optional `vtkDataArray` instance, is passed as an argument
  then a new array is not created and returned.  The passed array
  is itself returned.

Definition at line 231 of file array_handler.py.

def nodes::utils::array_handler::array2vtkCellArray	(	num_array,
		vtk_array = `None`
	)

Given a nested Python list or a numpy array, this method
creates a vtkCellArray instance and returns it.

A variety of input arguments are supported as described in the
Parameter documentation.  If numpy arrays are given, this method
is highly efficient.  This function is most efficient if the
passed numpy arrays have a typecode `ID_TYPE_CODE`.  Otherwise a
typecast is necessary and this involves an extra copy.  This
method *always copies* the input data.

An alternative and more efficient way to build the connectivity
list is to create a vtkIdTypeArray having data of the form
(npts,p0,p1,...p(npts-1), repeated for each cell) and then call
<vtkCellArray_instance>.SetCells(n_cell, id_list).

Parameters
----------

- num_array : numpy array or Python list/tuple

  Valid values are:

    1. A Python list of 1D lists.  Each 1D list can contain one
       cell connectivity list.  This is very slow and is to be
       used only when efficiency is of no consequence.

    2. A 2D numpy array with the cell connectivity list.

    3. A Python list of 2D numpy arrays.  Each numeric array can
       have a different shape.  This makes it easy to generate a
       cell array having cells of different kinds.

- vtk_array : `vtkCellArray` (default: `None`)

  If an optional `vtkCellArray` instance, is passed as an argument
  then a new array is not created and returned.  The passed array
  is itself modified and returned.

Example
-------

   >>> a = [[0], [1, 2], [3, 4, 5], [6, 7, 8, 9]]
   >>> cells = array_handler.array2vtkCellArray(a)
   >>> a = numpy.array([[0,1,2], [3,4,5], [6,7,8]], 'l')
   >>> cells = array_handler.array2vtkCellArray(a)
   >>> l_a = [a[:,:1], a[:2,:2], a]
   >>> cells = array_handler.array2vtkCellArray(l_a)

Definition at line 417 of file array_handler.py.

def nodes::utils::array_handler::array2vtkIdList	(	num_array,
		vtk_idlist = `None`
	)

Converts a numpy array/Python list to a vtkIdList object.

Parameters
----------

- num_array : numpy array or Python list/tuple

  The input array must be 2D with `shape[1] == 3`.

- vtk_idlist : `vtkIdList` (default: `None`)

  If an optional `vtkIdList` instance, is passed as an argument
  then a new array is not created and returned.  The passed array
  is itself modified and returned.

Definition at line 579 of file array_handler.py.

def nodes::utils::array_handler::array2vtkPoints	(	num_array,
		vtk_points = `None`
	)

Converts a numpy array/Python list to a vtkPoints object.

Unless a Python list/tuple or a non-contiguous array is given, no
copy of the data is made.  Thus the function is very efficient.

Parameters
----------

- num_array : numpy array or Python list/tuple

  The input array must be 2D with `shape[1] == 3`.

- vtk_points : `vtkPoints` (default: `None`)

  If an optional `vtkPoints` instance, is passed as an argument
  then a new array is not created and returned.  The passed array
  is itself modified and returned.

Definition at line 546 of file array_handler.py.

def nodes::utils::array_handler::convert_array	(	arr,
		vtk_typ = `None`
	)

Convert the given array to the optional type specified by
`vtk_typ`.

Parameters
----------

- arr : numpy array/list.
- vtk_typ : `string` or `None`
  represents the type the array is to be converted to.

Definition at line 620 of file array_handler.py.

def nodes::utils::array_handler::create_vtk_array ( vtk_arr_type )

Internal function used to create a VTK data array from another
VTK array given the VTK array type.

Definition at line 220 of file array_handler.py.

def nodes::utils::array_handler::deref_array	(	args,
		sigs = `None`
	)

Given a bunch of arguments and optional signature information,
this converts the arguments suitably.  If the argument is either a
Python list or a numpy array it is converted to a suitable type
based on the signature information.  If it is not an array, but a
TVTK object the VTK object is dereferenced.  Otherwise nothing is
done.  If no signature information is provided the arrays are
automatically converted (this can sometimes go wrong).  The
signature information is provided in the form of a list of lists.

Definition at line 741 of file array_handler.py.

def nodes::utils::array_handler::deref_vtk ( obj )

Dereferences the VTK object from the object if possible.  This
is duplicated from `tvtk_base.py` because I'd like to keep this
module independent of `tvtk_base.py`.

Definition at line 730 of file array_handler.py.

def nodes::utils::array_handler::get_correct_sig	(	args,
		sigs
	)

Given a list of args and a collection of possible signatures,
this function returns the most appropriate signature.  This
function is only called by deref_array.  This implies that one of
the signatures has an array type.

Definition at line 676 of file array_handler.py.

def nodes::utils::array_handler::get_numeric_array_type ( vtk_array_type )

Returns a numpy array typecode given a VTK array type.

Definition at line 198 of file array_handler.py.

def nodes::utils::array_handler::get_sizeof_vtk_array ( vtk_array_type )

Returns the size of a VTK array type.

Definition at line 203 of file array_handler.py.

def nodes::utils::array_handler::get_vtk_array_type ( numeric_array_type )

Returns a VTK typecode given a numpy array.

Definition at line 158 of file array_handler.py.

def nodes::utils::array_handler::get_vtk_to_numeric_typemap ( )

Returns the VTK array type to numpy array type mapping.

Definition at line 181 of file array_handler.py.

def nodes::utils::array_handler::is_array ( arr )

Returns True if the passed `arr` is a numpy array or a List.

Definition at line 613 of file array_handler.py.

def nodes::utils::array_handler::is_array_or_vtkarray ( arg )

Returns True if the argument is an array/Python list or if it
is a vtk array.

Definition at line 663 of file array_handler.py.

def nodes::utils::array_handler::is_array_sig ( s )

Given a signature, return if the signature has an array.

Definition at line 652 of file array_handler.py.

def nodes::utils::array_handler::vtk2array ( vtk_array )

Converts a VTK data array to a numpy array.

Given a subclass of vtkDataArray, this function returns an
appropriate numpy array containing the same data.  The function
is very efficient since it uses the VTK imaging pipeline to
convert the data.  If a sufficiently new version of VTK (5.2) is
installed then it actually uses the buffer interface to return a
view of the VTK array in the returned numpy array.

Parameters
----------

- vtk_array : `vtkDataArray`

  The VTK data array to be converted.

Definition at line 331 of file array_handler.py.