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

| vigra/iteratortraits.hxx |
--- | --- | ---

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