[ 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.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) |
html generated using doxygen and Python
|