/usr/share/doc/libblitz-doc/html/Array-multi.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.0, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Blitz++: Array multi</title>

<meta name="description" content="Blitz++: Array multi">
<meta name="keywords" content="Blitz++: Array multi">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Keyword-Index.html#Keyword-Index" rel="index" title="Keyword Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Customized-Arrays.html#Customized-Arrays" rel="up" title="Customized Arrays">
<link href="Array-usertype.html#Array-usertype" rel="next" title="Array usertype">
<link href="Customized-Arrays.html#Customized-Arrays" rel="prev" title="Customized Arrays">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space: nowrap}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: serif; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<a name="Array-multi"></a>
<div class="header">
<p>
Next: <a href="Array-usertype.html#Array-usertype" accesskey="n" rel="next">Array usertype</a>, Up: <a href="Customized-Arrays.html#Customized-Arrays" accesskey="u" rel="up">Customized Arrays</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Keyword-Index.html#Keyword-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Multicomponent-and-complex-arrays"></a>
<h3 class="section">5.1 Multicomponent and complex arrays</h3>
<a name="index-Array-multicomponent"></a>
<a name="index-multicomponent-arrays"></a>

<p>Multicomponent arrays have elements which are vectors.  Examples of such
arrays are vector fields, colour images (which contain, say, RGB tuples),
and multispectral images.  Complex-valued arrays can also be regarded as
multicomponent arrays, since each element is a 2-tuple of real values.
</p>
<p>Here are some examples of multicomponent arrays:
</p>
<a name="index-RGB24-example"></a>

<div class="example">
<pre class="example">// A 3-dimensional array; each element is a length 3 vector of float
Array&lt;TinyVector&lt;float,3&gt;,3&gt; A;  

// A complex 2-dimensional array
Array&lt;complex&lt;double&gt;,2&gt; B;

// A 2-dimensional image containing RGB tuples
struct RGB24 {
  unsigned char r, g, b;
};

Array&lt;RGB24,2&gt; C;
</pre></div>

<a name="Extracting-components"></a>
<h4 class="subsection">5.1.1 Extracting components</h4>

<a name="index-extracting-components"></a>
<a name="index-Array-extracting-components-1"></a>

<p>Blitz++ provides some special support for such arrays.  The most important
is the ability to extract a single component.  For example:
</p>
<div class="example">
<pre class="example">Array&lt;TinyVector&lt;float,3&gt;,2&gt; A(128,128);
Array&lt;float,2&gt; B = A.extractComponent(float(), 1, 3);
B = 0;
</pre></div>

<p>The call to <code>extractComponent</code> returns an array of floats; this array
is a view of the second component of each element of A.  The arguments of
<code>extractComponent</code> are: (1) the type of the component (in this example,
float); (2) the component number to extract (numbered 0, 1, ... N-1); and
(3) the number of components in the array.
</p>
<p>This is a little bit messy, so Blitz++ provides a handy shortcut using
<code>operator[]</code>:
</p>
<div class="example">
<pre class="example">Array&lt;TinyVector&lt;float,3&gt;,2&gt; A(128,128);
A[1] = 0;
</pre></div>

<p>The number inside the square brackets is the component number.  However, for
this operation to work, Blitz++ has to already know how many components
there are, and what type they are.  It knows this already for
<code>TinyVector</code> and <code>complex&lt;T&gt;</code>.  If you use your own type, though,
you will have to tell Blitz++ this information using the macro
<code>BZ_DECLARE_MULTICOMPONENT_TYPE()</code>.  This macro has three arguments:
</p>
<a name="index-BZ_005fDECLARE_005fMULTICOMPONENT_005fTYPE"></a>

<div class="example">
<pre class="example">BZ_DECLARE_MULTICOMPONENT_TYPE(T_element, T_componentType, numComponents)
</pre></div>

<p><code>T_element</code> is the element type of the array.  <code>T_componentType</code>
is the type of the components of that element.  <code>numComponents</code> is the
number of components in each element.
</p>
<p>An example will clarify this.  Suppose we wanted to make a colour image,
stored in 24-bit HSV (hue-saturation-value) format.  We can make a class
<code>HSV24</code> which represents a single pixel:
</p>
<a name="index-HSV24-example"></a>

<div class="example">
<pre class="example">#include &lt;blitz/array.h&gt;

using namespace blitz;

class HSV24 {
public:
    // These constants will makes the code below cleaner; we can
    // refer to the components by name, rather than number.

    static const int hue=0, saturation=1, value=2;

    HSV24() { }
    HSV24(int hue, int saturation, int value)
      : h_(hue), s_(saturation), v_(value)
    { }

    // Some other stuff here, obviously

private:
    unsigned char h_, s_, v_;
};
</pre></div>

<p>Right after the class declaration, we will invoke the macro
<code>BZ_DECLARE_MULTICOMPONENT_TYPE</code> to tell Blitz++ about HSV24:
</p>
<div class="example">
<pre class="example">// HSV24 has 3 components of type unsigned char
BZ_DECLARE_MULTICOMPONENT_TYPE(HSV24, unsigned char, 3);
</pre></div>

<p>Now we can create HSV images and modify the individual components:
</p>
<div class="example">
<pre class="example">int main()
{
    Array&lt;HSV24,2&gt; A(128,128);   // A 128x128 HSV image
    ...

    // Extract a greyscale version of the image
    Array&lt;unsigned char,2&gt; A_greyscale = A[HSV24::value];

    // Bump up the saturation component to get a
    // pastel effect
    A[HSV24::saturation] *= 1.3; 

    // Brighten up the middle of the image
    Range middle(32,96);
    A[HSV24::value](middle,middle) *= 1.2;
}
</pre></div>

<a name="Special-support-for-complex-arrays"></a>
<h4 class="subsection">5.1.2 Special support for complex arrays</h4>

<a name="index-Array-complex"></a>
<a name="index-complex-arrays-1"></a>

<p>Since complex arrays are used frequently, Blitz++ provides two special
methods for getting the real and imaginary components:
</p>
<div class="example">
<pre class="example">Array&lt;complex&lt;float&gt;,2&gt; A(32,32);

real(A) = 1.0;
imag(A) = 0.0;
</pre></div>

<p>The function <code>real(A)</code> returns an array view of the real component;
<code>imag(A)</code> returns a view of the imaginary component.
</p>
<p>Note: Blitz++ provides numerous math functions defined over complex-valued
arrays, such as <code>conj</code>, <code>polar</code>, <code>arg</code>, <code>abs</code>,
<code>cos</code>, <code>pow</code>, etc.  See the section on math functions
(<a href="Math-functions-1.html#Math-functions-1">Math functions 1</a>) for details.
</p>
<a name="Zipping-together-expressions"></a>
<h4 class="subsection">5.1.3 Zipping together expressions</h4>
<a name="index-zipping-expressions"></a>
<a name="index-Array-zipping-expressions"></a>

<p>Blitz++ provides a function <code>zip()</code> which lets you combine two or more
expressions into a single component.  For example, you can combine two real
expressions into a complex expression, or three integer expressions into an
HSV24 expression.  The function has this syntax:
</p>
<div class="example">
<pre class="example">resultexpr zip(expr1, expr2, T_element)
resultexpr zip(expr1, expr2, expr3, T_element)         ** not available yet
resultexpr zip(expr1, expr2, expr3, expr4, T_element)  ** not available yet
</pre></div>

<p>The types <code>resultexpr</code>, <code>expr1</code> and <code>expr2</code> are array
expressions.  The third argument is the type you want to create.  For
example:
</p>
<div class="example">
<pre class="example">int N = 16;
Array&lt;complex&lt;float&gt;,1&gt; A(N);
Array&lt;float,1&gt; theta(N);

 ...

A = zip(cos(theta), sin(theta), complex&lt;float&gt;());
</pre></div>

<p>The above line is equivalent to:
</p>
<div class="example">
<pre class="example">for (int i=0; i &lt; N; ++i)
   A[i] = complex&lt;float&gt;(cos(theta[i]), sin(theta[i]));
</pre></div>


<hr>
<div class="header">
<p>
Next: <a href="Array-usertype.html#Array-usertype" accesskey="n" rel="next">Array usertype</a>, Up: <a href="Customized-Arrays.html#Customized-Arrays" accesskey="u" rel="up">Customized Arrays</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Keyword-Index.html#Keyword-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
libblitz-doc 1:0.10-3.3 / usr / share / doc / libblitz-doc / html / Array-multi.html
