[ 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.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)