User Guide¶

This section includes information for using the pure Python API of bob.blitz.array. It is mainly intended as a test layer for the C and C++ API.

You can build a new bob.blitz.array using one of two possible ways:

Use the array constructor:

>>> bob.blitz.array((2,3), float)
bob.blitz.array((2,3),'float64')

You should pass the array shape and a dtype convertible object that would identify the type of elements the array will contain. Arrays built this way are uninitialized:
>>> a = bob.blitz.array((2,), 'uint8')
>>> a[0] 
145

Use the bob.blitz.as_blitz() generic converter. This function takes any object that is convertible to a numpy.ndarray, convert it to a behaved (C-order, memory aligned and contiguous) numpy.ndarray and then shallow copy it as a new bob.blitz.array:
```
>>> import bob.blitz
>>> a = bob.blitz.as_blitz(range(5))
>>> print(a)
[0 1 2 3 4]
>>> a.dtype
dtype('int...')
```
The shallow copied ndarray remains visible through the returned object’s base attribute:
```
>>> a.base
array([0, 1, 2, 3, 4])
>>> type(a.base)
<... 'numpy.ndarray'>
```
Because this is a shallow copy, any modifications done in any of the two arrays will be reflected in the other:
```
>>> a.base[3] = 67
>>> print(a)
[ 0  1  2 67  4]
```

You can get and set the individual values on bob.blitz.array objects, using the normal python indexing operatiors []:

>>> a = bob.blitz.array(2, 'float64')
>>> a[0] = 3.2
>>> a[1] = 6.14
>>> print(a)
[ 3.2   6.14]
>>> t = a[1]
>>> print(t)
6.14

You can convert bob.blitz.array objects into either (shallow) numpy.ndarray copies using bob.blitz.array.as_ndarray().

>>> a = bob.blitz.array(2, complex)
>>> a[0] = complex(3,4)
>>> a[1] = complex(2,2)
>>> npy = a.as_ndarray()
>>> print(npy)
[ 3.+4.j  2.+2.j]
>>> id(npy.base) == id(a)
True
>>> print(npy.flags.owndata)
False

You can detach the numpy.ndarray from the bob.blitz.array, by issuing a standard numpy copy:

>>> npy_copy = npy.copy()
>>> npy_copy.base is None
True
>>> print(npy_copy.flags.owndata)
True

You can use bob.blitz.array anywhere a numpy.ndarray is expected. In this case, numpy checks for the existence of an __array__ method on the passed object and if that is available, calls it to get an array representation for the object. For bob.blitz.array, the bob.blitz.array.__array__() method chooses the fastest possible conversion path to generate a numpy.ndarray.

>>> a = bob.blitz.array(2, float)
>>> a[0] = 3
>>> a[1] = 4
>>> print(numpy.mean(a))
3.5