[ 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.2.0, Aug 07 2003 )                                    */
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 approiate. 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 StandardAccessor<value_type>          DefaultAccessor;
00096     typedef StandardAccessor<value_type>          default_accessor;
00097 };
00098 
00099 /***********************************************************/
00100 
00101 /** \page ArgumentObjectFactories Argument Object Factories
00102     
00103     Factory functions to create argument objects which simplify long argument lists.
00104 
00105     <DL>
00106     <DT>
00107         <IMG BORDER=0 ALT="-" SRC="documents/bullet.gif"> 
00108         \ref ImageBasedArgumentObjectFactories
00109         <DD>
00110     <DT>
00111         <IMG BORDER=0 ALT="-" SRC="documents/bullet.gif"> 
00112         \ref IteratorBasedArgumentObjectFactories
00113         <DD>
00114     </DL>
00115 
00116     Long argument lists provide for greater flexibility of functions,
00117     but they are also tedious and error prone, when we don't need
00118     the flexibility. Thus, we define argument objects which
00119     automatically provide reasonable defaults for those arguments that we 
00120     didn't specify explicitly. 
00121     
00122     The argument objects are created via a number of factory functions.
00123     Since these functions have descriptive names, they also serve
00124     to improve readability: the name of each factory tells te purpose of its
00125     argument object. 
00126     
00127     Consider the following example. Without argument objects we had to 
00128     write something like this (cf. \ref copyImageIf()):
00129     
00130     \code
00131     vigra::BImage img1, img2, img3;
00132     
00133     // fill img1 and img2 ...
00134     
00135     vigra::copyImageIf(img1.upperLeft(), img1.lowerRight(), img1.accessor(),
00136                 img2.upperLeft(), img2.accessor(),
00137                 img3.upperLeft(), img3.accessor());
00138     \endcode
00139     
00140     Using the argument object factories, this becomes much shorter and
00141     more readable:
00142     
00143     \code
00144     vigra::copyImageIf(srcImageRange(img1),
00145                 maskImage(img2),
00146                 destImage(img3));
00147     \endcode
00148     
00149     The names of the factories clearly tell which image is source, mask, 
00150     and destination. In addition, the suffix <TT>Range</TT> must be used 
00151     for those argument objects that need to specify the lower right
00152     corner of the region of interest. Typically, this is only the first
00153     source argument, but sometimes the first destiniation argument must 
00154     also contain a range.
00155     
00156     The factory functions come in two flavours: Iterator based and 
00157     image based factories. Above we have seen the image based variant.
00158     The iterator based variant would look like this:
00159     
00160     \code
00161     vigra::copyImageIf(srcIterRange(img1.upperLeft(), img1.lowerRight()),
00162                 maskIter(img2.upperLeft()),
00163                 destIter(img3.upperLeft()));
00164     \endcode
00165     
00166     These factory functions contain the word <TT>Iter</TT> instead of the word 
00167     <TT>Image</TT>,  They would normally be used if we couldn't access the 
00168     images (for example, within a function which got passed iterators)
00169     or if we didn't want to operate on the entire image. The default 
00170     accessor is obtained via \ref vigra::IteratorTraits.
00171     
00172     All factory functions also allow to specify accessors explicitly. This
00173     is useful if we can't use the default accessor. This variant looks 
00174     like this:
00175     
00176     \code
00177     vigra::copyImageIf(srcImageRange(img1),
00178                 maskImage(img2, MaskPredicateAccessor()),
00179                 destImage(img3));    
00180     \endcode
00181     
00182     or
00183     
00184     \code
00185     vigra::copyImageIf(srcIterRange(img1.upperLeft(), img1.lowerRight()),
00186                 maskIter(img2.upperLeft(), MaskPredicateAccessor()),
00187                 destIter(img3.upperLeft()));
00188     \endcode
00189     
00190     All versions can be mixed freely within one explession.
00191     Technically, the argument objects are simply defined as 
00192     pairs and triples of iterators and accessor so that all algorithms 
00193     should declare a call interface version based on pairs and triples 
00194     (see for example \ref copyImageIf()).
00195 
00196   \section ImageBasedArgumentObjectFactories Image Based Argument Object Factories
00197         
00198     <b>Include:</b> automatically included with the image classes<br>
00199     Namespace: vigra
00200     
00201     These factories can be used to create argument objects when we 
00202     are given instances or subclasses of \ref vigra::BasicImage (see
00203     \ref StandardImageTypes for instances defined per default).
00204     These factory functions access <TT>img.upperLeft()</TT>, 
00205     <TT>img.lowerRight()</TT>, and <TT>img.accessor()</TT> to obtain the iterators
00206     and accessor for the given image (unless the accessor is 
00207     given explicitly). The following factory functions are provided:
00208     
00209     <table>
00210     <tr><td>
00211         \htmlonly
00212         <th bgcolor="#f0e0c0" colspan=2 align=left>
00213         \endhtmlonly
00214         <TT>\ref vigra::BasicImage "vigra::BasicImage<SomeType>" img;</TT>
00215         \htmlonly
00216         </th>
00217         \endhtmlonly
00218     </td></tr>
00219     <tr><td>
00220         
00221     <TT>srcImageRange(img)</TT>
00222     </td><td>
00223         create argument object containing upper left, lower right, and
00224         default accessor of source image
00225         
00226     </td></tr>
00227     <tr><td>
00228         
00229     <TT>srcImageRange(img, SomeAccessor())</TT>
00230     </td><td>
00231         create argument object containing upper left, lower right
00232         of source image, and given accessor
00233         
00234     </td></tr>
00235     <tr><td>
00236         
00237     <TT>srcImage(img)</TT>
00238     </td><td>
00239         create argument object containing upper left, and
00240         default accessor of source image
00241         
00242     </td></tr>
00243     <tr><td>
00244         
00245     <TT>srcImage(img, SomeAccessor())</TT>
00246     </td><td>
00247         create argument object containing upper left
00248         of source image, and given accessor
00249         
00250     </td></tr>
00251     <tr><td>
00252     
00253     <TT>maskImage(img)</TT>
00254     </td><td>
00255         create argument object containing upper left, and
00256         default accessor of mask image
00257         
00258     </td></tr>
00259     <tr><td>
00260         
00261     <TT>maskImage(img, SomeAccessor())</TT>
00262     </td><td>
00263         create argument object containing upper left
00264         of mask image, and given accessor
00265         
00266     </td></tr>
00267     <tr><td>
00268     
00269     <TT>destImageRange(img)</TT>
00270     </td><td>
00271         create argument object containing upper left, lower right, and
00272         default accessor of destination image
00273         
00274     </td></tr>
00275     <tr><td>
00276         
00277     <TT>destImageRange(img, SomeAccessor())</TT>
00278     </td><td>
00279         create argument object containing upper left, lower right
00280         of destination image, and given accessor
00281         
00282     </td></tr>
00283     <tr><td>
00284         
00285     <TT>destImage(img)</TT>
00286     </td><td>
00287         create argument object containing upper left, and
00288         default accessor of destination image
00289         
00290     </td></tr>
00291     <tr><td>
00292         
00293     <TT>destImage(img, SomeAccessor())</TT>
00294     </td><td>
00295         create argument object containing upper left
00296         of destination image, and given accessor
00297         
00298     </td></tr>
00299     </table>
00300 
00301 
00302   \section IteratorBasedArgumentObjectFactories Iterator Based Argument Object Factories
00303         
00304     <b>\#include</b> "<a href="iteratortraits_8hxx-source.html">vigra/iteratortraits.hxx</a>"
00305     Namespace: vigra
00306     
00307     These factories can be used to create argument objects when we 
00308     are given \ref ImageIterators.
00309     These factory functions use \ref vigra::IteratorTraits to
00310     get the default accessor for the given iterator unless the 
00311     accessor is given explicitly. The following factory functions 
00312     are provided:
00313     
00314     <table>
00315     <tr><td>
00316         \htmlonly
00317         <th bgcolor="#f0e0c0" colspan=2 align=left>
00318         \endhtmlonly
00319         <TT>\ref vigra::BasicImage::Iterator "vigra::BasicImage<SomeType>::Iterator" i1, i2;</TT>
00320         \htmlonly
00321         </th>
00322         \endhtmlonly
00323     </td></tr>
00324     <tr><td>
00325         
00326     <TT>srcIterRange(i1, i2)</TT>
00327     </td><td>
00328         create argument object containing the given iterators and
00329         corresponding default accessor (for source image)
00330         
00331     </td></tr>
00332     <tr><td>
00333         
00334     <TT>srcIterRange(i1, i2, SomeAccessor())</TT>
00335     </td><td>
00336         create argument object containing given iterators and
00337         accessor (for source image)
00338         
00339     </td></tr>
00340     <tr><td>
00341         
00342     <TT>srcIter(i1)</TT>
00343     </td><td>
00344         create argument object containing the given iterator and
00345         corresponding default accessor (for source image)
00346         
00347     </td></tr>
00348     <tr><td>
00349         
00350     <TT>srcIter(i1, SomeAccessor())</TT>
00351     </td><td>
00352         create argument object containing given iterator and
00353         accessor (for source image)
00354         
00355     </td></tr>
00356     <tr><td>
00357     
00358     <TT>maskIter(i1)</TT>
00359     </td><td>
00360         create argument object containing the given iterator and
00361         corresponding default accessor (for mask image)
00362         
00363     </td></tr>
00364     <tr><td>
00365         
00366     <TT>maskIter(i1, SomeAccessor())</TT>
00367     </td><td>
00368         create argument object containing given iterator and
00369         accessor (for mask image)
00370         
00371     </td></tr>
00372     <tr><td>
00373     
00374     <TT>destIterRange(i1, i2)</TT>
00375     </td><td>
00376         create argument object containing the given iterators and
00377         corresponding default accessor (for destination image)
00378         
00379     </td></tr>
00380     <tr><td>
00381         
00382     <TT>destIterRange(i1, i2, SomeAccessor())</TT>
00383     </td><td>
00384         create argument object containing given iterators and
00385         accessor (for destination image)
00386         
00387     </td></tr>
00388     <tr><td>
00389         
00390     <TT>destIter(i1)</TT>
00391     </td><td>
00392         create argument object containing the given iterator and
00393         corresponding default accessor (for destination image)
00394         
00395     </td></tr>
00396     <tr><td>
00397         
00398     <TT>destIter(i1, SomeAccessor())</TT>
00399     </td><td>
00400         create argument object containing given iterator and
00401         accessor (for destination image)
00402         
00403     </td></tr>
00404     </table>
00405 */
00406 
00407 template <class Iterator, class Accessor>
00408 inline triple<Iterator, Iterator, Accessor>
00409 srcIterRange(Iterator const & upperleft, Iterator const & lowerright, Accessor a)
00410 {
00411     return triple<Iterator, Iterator, Accessor>(upperleft, lowerright, a);
00412 }
00413 
00414 template <class Iterator, class Accessor>
00415 inline pair<Iterator, Accessor>
00416 srcIter(Iterator const & upperleft, Accessor a)
00417 {
00418     return pair<Iterator, Accessor>(upperleft, a);
00419 }
00420 
00421 template <class Iterator, class Accessor>
00422 inline pair<Iterator, Accessor>
00423 maskIter(Iterator const & upperleft, Accessor a)
00424 {
00425     return pair<Iterator, Accessor>(upperleft, a);
00426 }
00427 
00428 template <class Iterator, class Accessor>
00429 inline pair<Iterator, Accessor>
00430 destIter(Iterator const & upperleft, Accessor a)
00431 {
00432     return pair<Iterator, Accessor>(upperleft, a);
00433 }
00434 
00435 
00436 template <class Iterator, class Accessor>
00437 inline triple<Iterator, Iterator, Accessor>
00438 destIterRange(Iterator const & upperleft, Iterator const & lowerright, Accessor a)
00439 {
00440     return triple<Iterator, Iterator, Accessor>(upperleft, lowerright, a);
00441 }
00442 
00443 template <class Iterator>
00444 inline pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>
00445 srcIter(Iterator const & upperleft)
00446 {
00447     return pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>(
00448                   upperleft,
00449                   IteratorTraits<Iterator>::DefaultAccessor());
00450 }
00451 
00452 template <class Iterator>
00453 inline triple<Iterator, Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>
00454 srcIterRange(Iterator const & upperleft, Iterator const & lowerright)
00455 {
00456     return triple<Iterator, Iterator, 
00457                   typename IteratorTraits<Iterator>::DefaultAccessor>(
00458                   upperleft, lowerright, 
00459                   IteratorTraits<Iterator>::DefaultAccessor());
00460 }
00461 
00462 template <class Iterator>
00463 inline pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>
00464 maskIter(Iterator const & upperleft)
00465 {
00466     return pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>(
00467                   upperleft,
00468                   IteratorTraits<Iterator>::DefaultAccessor());
00469 }
00470 
00471 template <class Iterator>
00472 inline pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>
00473 destIter(Iterator const & upperleft)
00474 {
00475     return pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>(
00476                   upperleft,
00477                   IteratorTraits<Iterator>::DefaultAccessor());
00478 }
00479 
00480 template <class Iterator>
00481 inline triple<Iterator, Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>
00482 destIterRange(Iterator const & upperleft, Iterator const & lowerright)
00483 {
00484     return triple<Iterator, Iterator, 
00485                   typename IteratorTraits<Iterator>::DefaultAccessor>(
00486                   upperleft, lowerright, 
00487                   IteratorTraits<Iterator>::DefaultAccessor());
00488 }
00489 
00490 //@}
00491 
00492 } // namespace vigra
00493 
00494 #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.2.0 (7 Aug 2003)