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