[ VIGRA Homepage | Class Index | Function Index | File Index | Main Page ]

details vigra/iteratortraits.hxx VIGRA

00001 /************************************************************************/
00002 /*                                                                      */
00003 /*               Copyright 1998-2002 by Ullrich Koethe                  */
00004 /*       Cognitive Systems Group, University of Hamburg, Germany        */
00005 /*                                                                      */
00006 /*    This file is part of the VIGRA computer vision library.           */
00007 /*    ( Version 1.3.3, Aug 18 2005 )                                    */
00008 /*    You may use, modify, and distribute this software according       */
00009 /*    to the terms stated in the LICENSE file included in               */
00010 /*    the VIGRA distribution.                                           */
00011 /*                                                                      */
00012 /*    The VIGRA Website is                                              */
00013 /*        http://kogs-www.informatik.uni-hamburg.de/~koethe/vigra/      */
00014 /*    Please direct questions, bug reports, and contributions to        */
00015 /*        koethe@informatik.uni-hamburg.de                              */
00016 /*                                                                      */
00017 /*  THIS SOFTWARE IS PROVIDED AS IS AND WITHOUT ANY EXPRESS OR          */
00018 /*  IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED      */
00019 /*  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. */
00020 /*                                                                      */
00021 /************************************************************************/
00022 
00023 
00024 #ifndef VIGRA_ITERATORTRAITS_HXX
00025 #define VIGRA_ITERATORTRAITS_HXX
00026 
00027 #include <vigra/accessor.hxx>
00028 #include <vigra/imageiteratoradapter.hxx>
00029 
00030 namespace vigra {
00031 
00032 /** \addtogroup ImageIterators
00033 */
00034 //@{
00035 /** \brief Export associated information for each image iterator.
00036 
00037     The IteratorTraits class contains the following fields:
00038 
00039     \code
00040     template <class T>
00041     struct IteratorTraits
00042     {
00043         typedef T                                     Iterator;
00044         typedef Iterator                              iterator;
00045         typedef typename iterator::iterator_category  iterator_category;
00046         typedef typename iterator::value_type         value_type;
00047         typedef typename iterator::reference          reference;
00048         typedef typename iterator::index_reference    index_reference;
00049         typedef typename iterator::pointer            pointer;
00050         typedef typename iterator::difference_type    difference_type;
00051         typedef typename iterator::row_iterator       row_iterator;
00052         typedef typename iterator::column_iterator    column_iterator;
00053         typedef StandardAccessor<value_type>          DefaultAccessor;
00054         typedef StandardAccessor<value_type>          default_accessor;
00055 
00056         typedef VigraTrueType/VigraFalseType          hasConstantStrides;
00057     };
00058     \endcode
00059 
00060     By (partially) specializing this template for an iterator class
00061     the defaults given above can be changed as appropriate. For example, iterators
00062     for rgb images are associated with <TT>RGBAccessor<value_type></TT>
00063     instead of <TT>StandardAccessor<value_type></TT>. To get the accessor
00064     associated with a given iterator, use code like this:
00065 
00066     \code
00067     template <class Iterator>
00068     void foo(Iterator i)
00069     {
00070         typedef typename IteratorTraits<Iterator>::DefaultAccessor Accessor;
00071         Accessor a;
00072         ...
00073     }
00074     \endcode
00075 
00076     This technique is, for example, used by the
00077     \ref IteratorBasedArgumentObjectFactories. The possibility to retrieve the default accessor by means of a traits
00078     class is especially important since this information is not
00079     contained in the iterator directly.
00080     
00081     The member <tt>hasConstantStrides</tt> is useful for certain 
00082     optimizations: it helps to decide whether we can replace iterator
00083     operations such as <tt>iter++</tt> ot <tt>iter =+ n</tt> with
00084     corresponding pointer operations (which may be faster), where
00085     the pointer is obtained as the address of iterator's pointee 
00086     (the object the iterator currently  refers to). 
00087     This flag would be tt>VigraFalseType</tt> for a
00088     <tt>std::list&lt;int&gt;::iterator</tt>, but is <tt>VigraTrueType</tt> 
00089     for most VIGRA iterators.
00090 
00091     <b>\#include</b> "<a href="iteratortraits_8hxx-source.html">vigra/iteratortraits.hxx</a>"
00092     Namespace: vigra
00093 */
00094 template <class T>
00095 struct IteratorTraits
00096 {
00097     typedef T                                          Iterator;
00098     typedef Iterator                                   iterator;
00099     typedef typename iterator::iterator_category       iterator_category;
00100     typedef typename iterator::value_type              value_type;
00101     typedef typename iterator::reference               reference;
00102     typedef typename iterator::index_reference         index_reference;
00103     typedef typename iterator::pointer                 pointer;
00104     typedef typename iterator::difference_type         difference_type;
00105     typedef typename iterator::row_iterator            row_iterator;
00106     typedef typename iterator::column_iterator         column_iterator;
00107     typedef typename
00108         AccessorTraits<value_type>::default_accessor   DefaultAccessor;
00109     typedef DefaultAccessor                            default_accessor;
00110 
00111     // default: disable the constant strides optimization
00112     typedef VigraFalseType                             hasConstantStrides;
00113 };
00114 
00115 template <class T>
00116 struct IteratorTraitsBase
00117 {
00118     typedef T                                     Iterator;
00119     typedef Iterator                              iterator;
00120     typedef typename iterator::iterator_category  iterator_category;
00121     typedef typename iterator::value_type         value_type;
00122     typedef typename iterator::reference          reference;
00123     typedef typename iterator::index_reference    index_reference;
00124     typedef typename iterator::pointer            pointer;
00125     typedef typename iterator::difference_type    difference_type;
00126     typedef typename iterator::row_iterator       row_iterator;
00127     typedef typename iterator::column_iterator    column_iterator;
00128 };
00129 
00130 /***********************************************************/
00131 
00132 /** \page ArgumentObjectFactories Argument Object Factories
00133 
00134     Factory functions to create argument objects which simplify long argument lists.
00135 
00136     <DL>
00137     <DT>
00138         <IMG BORDER=0 ALT="-" SRC="documents/bullet.gif">
00139         \ref ImageBasedArgumentObjectFactories
00140         <DD>
00141     <DT>
00142         <IMG BORDER=0 ALT="-" SRC="documents/bullet.gif">
00143         \ref MultiArrayBasedArgumentObjectFactories
00144         <DD>
00145     <DT>
00146         <IMG BORDER=0 ALT="-" SRC="documents/bullet.gif">
00147         \ref IteratorBasedArgumentObjectFactories
00148         <DD>
00149     </DL>
00150 
00151     Long argument lists provide for greater flexibility of functions,
00152     but they are also tedious and error prone, when we don't need
00153     the flexibility. Thus, we define argument objects which
00154     automatically provide reasonable defaults for those arguments that we
00155     didn't specify explicitly.
00156 
00157     The argument objects are created via a number of factory functions.
00158     Since these functions have descriptive names, they also serve
00159     to improve readability: the name of each factory tells te purpose of its
00160     argument object.
00161 
00162     Consider the following example. Without argument objects we had to
00163     write something like this (cf. \ref copyImageIf()):
00164 
00165     \code
00166     vigra::BImage img1, img2, img3;
00167 
00168     // fill img1 and img2 ...
00169 
00170     vigra::copyImageIf(img1.upperLeft(), img1.lowerRight(), img1.accessor(),
00171                 img2.upperLeft(), img2.accessor(),
00172                 img3.upperLeft(), img3.accessor());
00173     \endcode
00174 
00175     Using the argument object factories, this becomes much shorter and
00176     more readable:
00177 
00178     \code
00179     vigra::copyImageIf(srcImageRange(img1),
00180                 maskImage(img2),
00181                 destImage(img3));
00182     \endcode
00183 
00184     The names of the factories clearly tell which image is source, mask,
00185     and destination. In addition, the suffix <TT>Range</TT> must be used
00186     for those argument objects that need to specify the lower right
00187     corner of the region of interest. Typically, this is only the first
00188     source argument, but sometimes the first destiniation argument must
00189     also contain a range.
00190 
00191     The factory functions come in two flavours: Iterator based and
00192     image based factories. Above we have seen the image based variant.
00193     The iterator based variant would look like this:
00194 
00195     \code
00196     vigra::copyImageIf(srcIterRange(img1.upperLeft(), img1.lowerRight()),
00197                 maskIter(img2.upperLeft()),
00198                 destIter(img3.upperLeft()));
00199     \endcode
00200 
00201     These factory functions contain the word <TT>Iter</TT> instead of the word
00202     <TT>Image</TT>,  They would normally be used if we couldn't access the
00203     images (for example, within a function which got passed iterators)
00204     or if we didn't want to operate on the entire image. The default
00205     accessor is obtained via \ref vigra::IteratorTraits.
00206 
00207     All factory functions also allow to specify accessors explicitly. This
00208     is useful if we can't use the default accessor. This variant looks
00209     like this:
00210 
00211     \code
00212     vigra::copyImageIf(srcImageRange(img1),
00213                 maskImage(img2, MaskPredicateAccessor()),
00214                 destImage(img3));
00215     \endcode
00216 
00217     or
00218 
00219     \code
00220     vigra::copyImageIf(srcIterRange(img1.upperLeft(), img1.lowerRight()),
00221                 maskIter(img2.upperLeft(), MaskPredicateAccessor()),
00222                 destIter(img3.upperLeft()));
00223     \endcode
00224 
00225     All versions can be mixed freely within one explession.
00226     Technically, the argument objects are simply defined as
00227     pairs and triples of iterators and accessor so that all algorithms
00228     should declare a call interface version based on pairs and triples
00229     (see for example \ref copyImageIf()).
00230 
00231   \section ImageBasedArgumentObjectFactories Image Based Argument Object Factories
00232 
00233     <b>Include:</b> automatically included with the image classes<br>
00234     Namespace: vigra
00235 
00236     These factories can be used to create argument objects when we
00237     are given instances or subclasses of \ref vigra::BasicImage (see
00238     \ref StandardImageTypes for instances defined per default).
00239     These factory functions access <TT>img.upperLeft()</TT>,
00240     <TT>img.lowerRight()</TT>, and <TT>img.accessor()</TT> to obtain the iterators
00241     and accessor for the given image (unless the accessor is
00242     given explicitly). The following factory functions are provided:
00243 
00244     <table>
00245     <tr><td>
00246         \htmlonly
00247         <th bgcolor="#f0e0c0" colspan=2 align=left>
00248         \endhtmlonly
00249         <TT>\ref vigra::BasicImage "vigra::BasicImage<SomeType>" img;</TT>
00250         \htmlonly
00251         </th>
00252         \endhtmlonly
00253     </td></tr>
00254     <tr><td>
00255 
00256     <TT>srcImageRange(img)</TT>
00257     </td><td>
00258         create argument object containing upper left, lower right, and
00259         default accessor of source image
00260 
00261     </td></tr>
00262     <tr><td>
00263 
00264     <TT>srcImageRange(img, SomeAccessor())</TT>
00265     </td><td>
00266         create argument object containing upper left, lower right
00267         of source image, and given accessor
00268 
00269     </td></tr>
00270     <tr><td>
00271 
00272     <TT>srcImage(img)</TT>
00273     </td><td>
00274         create argument object containing upper left, and
00275         default accessor of source image
00276 
00277     </td></tr>
00278     <tr><td>
00279 
00280     <TT>srcImage(img, SomeAccessor())</TT>
00281     </td><td>
00282         create argument object containing upper left
00283         of source image, and given accessor
00284 
00285     </td></tr>
00286     <tr><td>
00287 
00288     <TT>maskImage(img)</TT>
00289     </td><td>
00290         create argument object containing upper left, and
00291         default accessor of mask image
00292 
00293     </td></tr>
00294     <tr><td>
00295 
00296     <TT>maskImage(img, SomeAccessor())</TT>
00297     </td><td>
00298         create argument object containing upper left
00299         of mask image, and given accessor
00300 
00301     </td></tr>
00302     <tr><td>
00303 
00304     <TT>destImageRange(img)</TT>
00305     </td><td>
00306         create argument object containing upper left, lower right, and
00307         default accessor of destination image
00308 
00309     </td></tr>
00310     <tr><td>
00311 
00312     <TT>destImageRange(img, SomeAccessor())</TT>
00313     </td><td>
00314         create argument object containing upper left, lower right
00315         of destination image, and given accessor
00316 
00317     </td></tr>
00318     <tr><td>
00319 
00320     <TT>destImage(img)</TT>
00321     </td><td>
00322         create argument object containing upper left, and
00323         default accessor of destination image
00324 
00325     </td></tr>
00326     <tr><td>
00327 
00328     <TT>destImage(img, SomeAccessor())</TT>
00329     </td><td>
00330         create argument object containing upper left
00331         of destination image, and given accessor
00332 
00333     </td></tr>
00334     </table>
00335 
00336 
00337   \section MultiArrayBasedArgumentObjectFactories MultiArrayView Based Argument Object Factories
00338 
00339     <b>Include:</b> automatically included with 
00340        "<a href="multi__array_8hxx-source.html">vigra/multi_array.hxx</a>"<br>
00341     Namespace: vigra
00342 
00343     These factories can be used to create argument objects when we
00344     are given instances or subclasses of \ref vigra::MultiArrayView.
00345     These factory functions access <TT>array.traverser_begin()</TT>,
00346     <TT>array.traverser_end()</TT> to obtain the iterators. If no accessor is
00347     given, they use the <tt>AccessorTraits<T></tt> to determine the default 
00348     accessor associated with the array's value type <tt>T</tt>.
00349     The following factory functions are provided:
00350 
00351     <table>
00352     <tr><td>
00353         \htmlonly
00354         <th bgcolor="#f0e0c0" colspan=2 align=left>
00355         \endhtmlonly
00356         <TT>\ref vigra::MultiArrayView "vigra::MultiArrayView<N, SomeType>" array;</TT>
00357         \htmlonly
00358         </th>
00359         \endhtmlonly
00360     </td></tr>
00361     <tr><td>
00362 
00363     <TT>srcMultiArrayRange(img)</TT>
00364     </td><td>
00365         create argument object containing a \ref vigra::MultiIterator 
00366         marking the begin of the array, a shape object giving the desired
00367         shape of the array (possibly a subarray) and the default const accessor for
00368         <tt>SomeType</tt>
00369 
00370     </td></tr>
00371     <tr><td>
00372 
00373     <TT>srcMultiArrayRange(img, SomeAccessor())</TT>
00374     </td><td>
00375         create argument object containing a \ref vigra::MultiIterator 
00376         marking the begin of the array, a shape object giving the desired
00377         shape of the array (possibly a subarray) and the given accessor
00378 
00379     </td></tr>
00380     <tr><td>
00381 
00382     <TT>srcMultiArray(img)</TT>
00383     </td><td>
00384         create argument object containing a \ref vigra::MultiIterator
00385         marking the begin of the array, and the default const accessor for
00386         <tt>SomeType</tt>
00387 
00388     </td></tr>
00389     <tr><td>
00390 
00391     <TT>srcMultiArray(img, SomeAccessor())</TT>
00392     </td><td>
00393         create argument object containing a \ref vigra::MultiIterator 
00394         marking the begin of the array and the given accessor
00395 
00396     </td></tr>
00397     <tr><td>
00398 
00399     <TT>destMultiArrayRange(img)</TT>
00400     </td><td>
00401         create argument object containing a \ref vigra::MultiIterator 
00402         marking the begin of the array, a shape object giving the desired
00403         shape of the array (possibly a subarray) and the default accessor for
00404         <tt>SomeType</tt>
00405 
00406     </td></tr>
00407     <tr><td>
00408 
00409     <TT>destMultiArrayRange(img, SomeAccessor())</TT>
00410     </td><td>
00411         create argument object containing a \ref vigra::MultiIterator's 
00412         marking the begin of the array, a shape object giving the desired
00413         shape of the array (possibly a subarray) and the given accessor
00414 
00415     </td></tr>
00416     <tr><td>
00417 
00418     <TT>destMultiArray(img)</TT>
00419     </td><td>
00420         create argument object containing a \ref vigra::MultiIterator 
00421         marking the begin of the array and the default accessor for
00422         <tt>SomeType</tt>
00423 
00424     </td></tr>
00425     <tr><td>
00426 
00427     <TT>destMultiArray(img, SomeAccessor())</TT>
00428     </td><td>
00429         create argument object containing a \ref vigra::MultiIterator's 
00430         marking the begin of the array and the given accessor
00431 
00432     </td></tr>
00433     </table>
00434 
00435 
00436   \section IteratorBasedArgumentObjectFactories Iterator Based Argument Object Factories
00437 
00438     <b>\#include</b> "<a href="iteratortraits_8hxx-source.html">vigra/iteratortraits.hxx</a>"
00439     Namespace: vigra
00440 
00441     These factories can be used to create argument objects when we
00442     are given \ref ImageIterators.
00443     These factory functions use \ref vigra::IteratorTraits to
00444     get the default accessor for the given iterator unless the
00445     accessor is given explicitly. The following factory functions
00446     are provided:
00447 
00448     <table>
00449     <tr><td>
00450         \htmlonly
00451         <th bgcolor="#f0e0c0" colspan=2 align=left>
00452         \endhtmlonly
00453         <TT>\ref vigra::BasicImage::Iterator "vigra::BasicImage<SomeType>::Iterator" i1, i2;</TT>
00454         \htmlonly
00455         </th>
00456         \endhtmlonly
00457     </td></tr>
00458     <tr><td>
00459 
00460     <TT>srcIterRange(i1, i2)</TT>
00461     </td><td>
00462         create argument object containing the given iterators and
00463         corresponding default accessor (for source image)
00464 
00465     </td></tr>
00466     <tr><td>
00467 
00468     <TT>srcIterRange(i1, i2, SomeAccessor())</TT>
00469     </td><td>
00470         create argument object containing given iterators and
00471         accessor (for source image)
00472 
00473     </td></tr>
00474     <tr><td>
00475 
00476     <TT>srcIter(i1)</TT>
00477     </td><td>
00478         create argument object containing the given iterator and
00479         corresponding default accessor (for source image)
00480 
00481     </td></tr>
00482     <tr><td>
00483 
00484     <TT>srcIter(i1, SomeAccessor())</TT>
00485     </td><td>
00486         create argument object containing given iterator and
00487         accessor (for source image)
00488 
00489     </td></tr>
00490     <tr><td>
00491 
00492     <TT>maskIter(i1)</TT>
00493     </td><td>
00494         create argument object containing the given iterator and
00495         corresponding default accessor (for mask image)
00496 
00497     </td></tr>
00498     <tr><td>
00499 
00500     <TT>maskIter(i1, SomeAccessor())</TT>
00501     </td><td>
00502         create argument object containing given iterator and
00503         accessor (for mask image)
00504 
00505     </td></tr>
00506     <tr><td>
00507 
00508     <TT>destIterRange(i1, i2)</TT>
00509     </td><td>
00510         create argument object containing the given iterators and
00511         corresponding default accessor (for destination image)
00512 
00513     </td></tr>
00514     <tr><td>
00515 
00516     <TT>destIterRange(i1, i2, SomeAccessor())</TT>
00517     </td><td>
00518         create argument object containing given iterators and
00519         accessor (for destination image)
00520 
00521     </td></tr>
00522     <tr><td>
00523 
00524     <TT>destIter(i1)</TT>
00525     </td><td>
00526         create argument object containing the given iterator and
00527         corresponding default accessor (for destination image)
00528 
00529     </td></tr>
00530     <tr><td>
00531 
00532     <TT>destIter(i1, SomeAccessor())</TT>
00533     </td><td>
00534         create argument object containing given iterator and
00535         accessor (for destination image)
00536 
00537     </td></tr>
00538     </table>
00539 */
00540 
00541 template <class Iterator, class Accessor>
00542 inline triple<Iterator, Iterator, Accessor>
00543 srcIterRange(Iterator const & upperleft, Iterator const & lowerright, Accessor a)
00544 {
00545     return triple<Iterator, Iterator, Accessor>(upperleft, lowerright, a);
00546 }
00547 
00548 template <class Iterator, class Accessor>
00549 inline pair<Iterator, Accessor>
00550 srcIter(Iterator const & upperleft, Accessor a)
00551 {
00552     return pair<Iterator, Accessor>(upperleft, a);
00553 }
00554 
00555 template <class Iterator, class Accessor>
00556 inline pair<Iterator, Accessor>
00557 maskIter(Iterator const & upperleft, Accessor a)
00558 {
00559     return pair<Iterator, Accessor>(upperleft, a);
00560 }
00561 
00562 template <class Iterator, class Accessor>
00563 inline pair<Iterator, Accessor>
00564 destIter(Iterator const & upperleft, Accessor a)
00565 {
00566     return pair<Iterator, Accessor>(upperleft, a);
00567 }
00568 
00569 
00570 template <class Iterator, class Accessor>
00571 inline triple<Iterator, Iterator, Accessor>
00572 destIterRange(Iterator const & upperleft, Iterator const & lowerright, Accessor a)
00573 {
00574     return triple<Iterator, Iterator, Accessor>(upperleft, lowerright, a);
00575 }
00576 
00577 template <class Iterator>
00578 inline pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>
00579 srcIter(Iterator const & upperleft)
00580 {
00581     return pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>(
00582                   upperleft,
00583                   typename IteratorTraits<Iterator>::DefaultAccessor());
00584 }
00585 
00586 template <class Iterator>
00587 inline triple<Iterator, Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>
00588 srcIterRange(Iterator const & upperleft, Iterator const & lowerright)
00589 {
00590     return triple<Iterator, Iterator,
00591                   typename IteratorTraits<Iterator>::DefaultAccessor>(
00592                   upperleft, lowerright,
00593                   typename IteratorTraits<Iterator>::DefaultAccessor());
00594 }
00595 
00596 template <class Iterator>
00597 inline pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>
00598 maskIter(Iterator const & upperleft)
00599 {
00600     return pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>(
00601                   upperleft,
00602                   typename IteratorTraits<Iterator>::DefaultAccessor());
00603 }
00604 
00605 template <class Iterator>
00606 inline pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>
00607 destIter(Iterator const & upperleft)
00608 {
00609     return pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>(
00610                   upperleft,
00611                   typename IteratorTraits<Iterator>::DefaultAccessor());
00612 }
00613 
00614 template <class Iterator>
00615 inline triple<Iterator, Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>
00616 destIterRange(Iterator const & upperleft, Iterator const & lowerright)
00617 {
00618     return triple<Iterator, Iterator,
00619                   typename IteratorTraits<Iterator>::DefaultAccessor>(
00620                   upperleft, lowerright,
00621                   typename IteratorTraits<Iterator>::DefaultAccessor());
00622 }
00623 
00624 //@}
00625 
00626 } // namespace vigra
00627 
00628 #endif // VIGRA_ITERATORTRAITS_HXX

© Ullrich Köthe (koethe@informatik.uni-hamburg.de)
Cognitive Systems Group, University of Hamburg, Germany

html generated using doxygen and Python
VIGRA 1.3.3 (18 Aug 2005)