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