vigra - vigra/iteratortraits.hxx Source File

[ VIGRA Homepage | Function Index | Class Index | Namespaces | File List | Main Page ]

iteratortraits.hxx |

1 /************************************************************************/
2 /* */
3 /* Copyright 1998-2002 by Ullrich Koethe */
4 /* */
5 /* This file is part of the VIGRA computer vision library. */
6 /* The VIGRA Website is */
7 /* http://hci.iwr.uni-heidelberg.de/vigra/ */
8 /* Please direct questions, bug reports, and contributions to */
9 /* ullrich.koethe@iwr.uni-heidelberg.de or */
10 /* vigra@informatik.uni-hamburg.de */
11 /* */
12 /* Permission is hereby granted, free of charge, to any person */
13 /* obtaining a copy of this software and associated documentation */
14 /* files (the "Software"), to deal in the Software without */
15 /* restriction, including without limitation the rights to use, */
16 /* copy, modify, merge, publish, distribute, sublicense, and/or */
17 /* sell copies of the Software, and to permit persons to whom the */
18 /* Software is furnished to do so, subject to the following */
19 /* conditions: */
20 /* */
21 /* The above copyright notice and this permission notice shall be */
22 /* included in all copies or substantial portions of the */
23 /* Software. */
24 /* */
25 /* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND */
26 /* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES */
27 /* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND */
28 /* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT */
29 /* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, */
30 /* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING */
31 /* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR */
32 /* OTHER DEALINGS IN THE SOFTWARE. */
33 /* */
34 /************************************************************************/
35
36
37 #ifndef VIGRA_ITERATORTRAITS_HXX
38 #define VIGRA_ITERATORTRAITS_HXX
39
40 #include "accessor.hxx"
41 #include "imageiteratoradapter.hxx"
42
43 namespace vigra {
44
45 /** \addtogroup ImageIterators
46 */
47 //@{
48 /** \brief Export associated information for each image iterator.
49
50 The IteratorTraits class contains the following fields:
51
52 \code
53 template <class T>
54 struct IteratorTraits
55 {
56 typedef T Iterator;
57 typedef Iterator iterator;
58 typedef typename iterator::iterator_category iterator_category;
59 typedef typename iterator::value_type value_type;
60 typedef typename iterator::reference reference;
61 typedef typename iterator::index_reference index_reference;
62 typedef typename iterator::pointer pointer;
63 typedef typename iterator::difference_type difference_type;
64 typedef typename iterator::row_iterator row_iterator;
65 typedef typename iterator::column_iterator column_iterator;
66 typedef typename
67 AccessorTraits<value_type>::default_accessor DefaultAccessor;
68 typedef DefaultAccessor default_accessor;
69
70 typedef VigraTrueType/VigraFalseType hasConstantStrides;
71 };
72 \endcode
73
74 By (partially) specializing this template for an iterator class
75 the defaults given above can be changed as appropriate. For example, iterators
76 for rgb images are associated with <TT>RGBAccessor<value_type></TT>
77 instead of <TT>StandardAccessor<value_type></TT>. To get the accessor
78 associated with a given iterator, use code like this:
79
80 \code
81 template <class Iterator>
82 void foo(Iterator i)
83 {
84 typedef typename IteratorTraits<Iterator>::DefaultAccessor Accessor;
85 Accessor a;
86 ...
87 }
88 \endcode
89
90 This technique is, for example, used by the
91 \ref IteratorBasedArgumentObjectFactories. The possibility to retrieve the default accessor by means of a traits
92 class is especially important since this information is not
93 contained in the iterator directly.
94
95 The member <tt>hasConstantStrides</tt> is useful for certain
96 optimizations: it helps to decide whether we can replace iterator
97 operations such as <tt>iter++</tt> or <tt>iter += n</tt> with
98 corresponding pointer operations (which may be faster), where
99 the pointer is obtained as the address of iterator's pointee
100 (the object the iterator currently refers to).
101 This flag would be <tt>VigraFalseType</tt> for a
102 <tt>std::list<int>::iterator</tt>, but is <tt>VigraTrueType</tt>
103 for most VIGRA iterators.
104
105 <b>\#include</b> <vigra/iteratortraits.hxx>
106 Namespace: vigra
107 */
108 template <class T>
109 struct IteratorTraits
110 {
111 typedef T Iterator;
112 typedef Iterator iterator;
113 typedef typename iterator::iterator_category iterator_category;
114 typedef typename iterator::value_type value_type;
115 typedef typename iterator::reference reference;
116 typedef typename iterator::index_reference index_reference;
117 typedef typename iterator::pointer pointer;
118 typedef typename iterator::difference_type difference_type;
119 typedef typename iterator::row_iterator row_iterator;
120 typedef typename iterator::column_iterator column_iterator;
121 typedef typename
122 AccessorTraits<value_type>::default_accessor DefaultAccessor;
123 typedef DefaultAccessor default_accessor;
124
125 // default: disable the constant strides optimization
126 typedef VigraFalseType hasConstantStrides;
127 };
128
129 template <class T>
130 struct IteratorTraitsBase
131 {
132 typedef T Iterator;
133 typedef Iterator iterator;
134 typedef typename iterator::iterator_category iterator_category;
135 typedef typename iterator::value_type value_type;
136 typedef typename iterator::reference reference;
137 typedef typename iterator::index_reference index_reference;
138 typedef typename iterator::pointer pointer;
139 typedef typename iterator::difference_type difference_type;
140 typedef typename iterator::row_iterator row_iterator;
141 typedef typename iterator::column_iterator column_iterator;
142 };
143
144
145 //@}
146
147
148 /***********************************************************/
149
150 /** \page ArgumentObjectFactories Argument Object Factories
151
152 Factory functions to create argument objects which simplify long argument lists.
153
154 <UL style="list-style-image:url(documents/bullet.gif)">
155 <LI> \ref ImageBasedArgumentObjectFactories
156 <LI> \ref MultiArrayBasedArgumentObjectFactories
157 <LI> \ref IteratorBasedArgumentObjectFactories
158 </UL>
159
160 Long argument lists provide for greater flexibility of functions,
161 but they are also tedious and error prone, when we don't need
162 the flexibility. Thus, we define argument objects which
163 automatically provide reasonable defaults for those arguments that we
164 didn't specify explicitly.
165
166 The argument objects are created via a number of factory functions.
167 Since these functions have descriptive names, they also serve
168 to improve readability: the name of each factory tells te purpose of its
169 argument object.
170
171 Consider the following example. Without argument objects we had to
172 write something like this (cf. \ref copyImageIf()):
173
174 \code
175 vigra::BImage img1, img2, img3;
176
177 // fill img1 and img2 ...
178
179 vigra::copyImageIf(img1.upperLeft(), img1.lowerRight(), img1.accessor(),
180 img2.upperLeft(), img2.accessor(),
181 img3.upperLeft(), img3.accessor());
182 \endcode
183
184 Using the argument object factories, this becomes much shorter and
185 more readable:
186
187 \code
188 vigra::copyImageIf(srcImageRange(img1),
189 maskImage(img2),
190 destImage(img3));
191 \endcode
192
193 The names of the factories clearly tell which image is source, mask,
194 and destination. In addition, the suffix <TT>Range</TT> must be used
195 for those argument objects that need to specify the lower right
196 corner of the region of interest. Typically, this is only the first
197 source argument, but sometimes the first destiniation argument must
198 also contain a range.
199
200 The factory functions come in two flavours: Iterator based and
201 image based factories. Above we have seen the image based variant.
202 The iterator based variant would look like this:
203
204 \code
205 vigra::copyImageIf(srcIterRange(img1.upperLeft(), img1.lowerRight()),
206 maskIter(img2.upperLeft()),
207 destIter(img3.upperLeft()));
208 \endcode
209
210 These factory functions contain the word <TT>Iter</TT> instead of the word
211 <TT>Image</TT>, They would normally be used if we couldn't access the
212 images (for example, within a function which got passed iterators)
213 or if we didn't want to operate on the entire image. The default
214 accessor is obtained via \ref vigra::IteratorTraits.
215
216 All factory functions also allow to specify accessors explicitly. This
217 is useful if we can't use the default accessor. This variant looks
218 like this:
219
220 \code
221 vigra::copyImageIf(srcImageRange(img1),
222 maskImage(img2, MaskPredicateAccessor()),
223 destImage(img3));
224 \endcode
225
226 or
227
228 \code
229 vigra::copyImageIf(srcIterRange(img1.upperLeft(), img1.lowerRight()),
230 maskIter(img2.upperLeft(), MaskPredicateAccessor()),
231 destIter(img3.upperLeft()));
232 \endcode
233
234 All versions can be mixed freely within one expression.
235 Technically, the argument objects are simply defined as
236 pairs and triples of iterators and accessor so that all algorithms
237 should declare a call interface version based on pairs and triples
238 (see for example \ref copyImageIf()).
239
240 \section ImageBasedArgumentObjectFactories Image Based Argument Object Factories
241
242 <b>Include:</b> automatically included with the image classes<br>
243 Namespace: vigra
244
245 These factories can be used to create argument objects when we
246 are given instances or subclasses of \ref vigra::BasicImage (see
247 \ref StandardImageTypes for instances defined per default).
248 These factory functions access <TT>img.upperLeft()</TT>,
249 <TT>img.lowerRight()</TT>, and <TT>img.accessor()</TT> to obtain the iterators
250 and accessor for the given image (unless the accessor is
251 given explicitly). The following factory functions are provided:
252
253 <table>
254 <tr><th bgcolor="#f0e0c0" colspan=2 align=left>
255 <TT>\ref vigra::BasicImage "vigra::BasicImage<SomeType>" img;</TT> or <br>
256 <TT>\ref vigra::BasicImageView "vigra::BasicImageView<SomeType>" img;</TT>
257 </th>
258 </tr>
259 <tr><td>
260
261 <TT>srcImageRange(img)</TT>
262 </td><td>
263 create argument object containing upper left, lower right, and
264 default accessor of source image
265
266 </td></tr>
267 <tr><td>
268
269 <TT>srcImageRange(img, Rect2D(...))</TT>
270 </td><td>
271 create argument object containing the ROI specified by <tt>\ref vigra::Rect2D</tt> and
272 default accessor of source image
273
274 </td></tr>
275 <tr><td>
276
277 <TT>srcImageRange(img, SomeAccessor())</TT>
278 </td><td>
279 create argument object containing upper left, lower right
280 of source image, and given accessor
281
282 </td></tr>
283 <tr><td>
284
285 <TT>srcImageRange(img, Rect2D(...), SomeAccessor())</TT>
286 </td><td>
287 create argument object containing the ROI specified by <tt>\ref vigra::Rect2D</tt> and
288 of source image, and given accessor
289
290 </td></tr>
291 <tr><td>
292
293 <TT>srcImage(img)</TT>
294 </td><td>
295 create argument object containing upper left, and
296 default accessor of source image
297
298 </td></tr>
299 <tr><td>
300
301 <TT>srcImage(img, Point2D(...))</TT>
302 </td><td>
303 create argument object with upper left at point given by <tt>\ref vigra::Point2D</tt>, and
304 default accessor of source image
305
306 </td></tr>
307 <tr><td>
308
309 <TT>srcImage(img, SomeAccessor())</TT>
310 </td><td>
311 create argument object containing upper left
312 of source image, and given accessor
313
314 </td></tr>
315 <tr><td>
316
317 <TT>srcImage(img, Point2D(...), SomeAccessor())</TT>
318 </td><td>
319 create argument object with upper left at point given by <tt>\ref vigra::Point2D</tt> of source image,
320 and given accessor
321
322 </td></tr>
323 <tr><td>
324
325 <TT>maskImage(img)</TT>
326 </td><td>
327 create argument object containing upper left, and
328 default accessor of mask image
329
330 </td></tr>
331 <tr><td>
332
333 <TT>maskImage(img, Point2D(...))</TT>
334 </td><td>
335 create argument object with upper left at point given by <tt>\ref vigra::Point2D</tt>, and
336 default accessor of mask image
337
338 </td></tr>
339 <tr><td>
340
341 <TT>maskImage(img, SomeAccessor())</TT>
342 </td><td>
343 create argument object containing upper left
344 of mask image, and given accessor
345
346 </td></tr>
347 <tr><td>
348
349 <TT>maskImage(img, Point2D(...), SomeAccessor())</TT>
350 </td><td>
351 create argument object with upper left at point given by <tt>\ref vigra::Point2D</tt> of mask image,
352 and given accessor
353
354 </td></tr>
355 <tr><td>
356
357 <TT>destImageRange(img)</TT>
358 </td><td>
359 create argument object containing upper left, lower right, and
360 default accessor of destination image
361
362 </td></tr>
363 <tr><td>
364
365 <TT>destImageRange(img, Rect2D(...))</TT>
366 </td><td>
367 create argument object containing the ROI specified by <tt>\ref vigra::Rect2D</tt> and
368 default accessor of destination image
369
370 </td></tr>
371 <tr><td>
372
373 <TT>destImageRange(img, SomeAccessor())</TT>
374 </td><td>
375 create argument object containing upper left, lower right
376 of destination image, and given accessor
377
378 </td></tr>
379 <tr><td>
380
381 <TT>destImageRange(img, Rect2D(...), SomeAccessor())</TT>
382 </td><td>
383 create argument object containing the ROI specified by <tt>\ref vigra::Rect2D</tt>
384 of destination image, and given accessor
385
386 </td></tr>
387 <tr><td>
388
389 <TT>destImage(img)</TT>
390 </td><td>
391 create argument object containing upper left, and
392 default accessor of destination image
393
394 </td></tr>
395 <tr><td>
396
397 <TT>destImage(img, Point2D(...))</TT>
398 </td><td>
399 create argument object with upper left at point given by <tt>\ref vigra::Point2D</tt>, and
400 default accessor of destination image
401
402 </td></tr>
403 <tr><td>
404
405 <TT>destImage(img, SomeAccessor())</TT>
406 </td><td>
407 create argument object containing upper left
408 of destination image, and given accessor
409
410 </td></tr>
411 <tr><td>
412
413 <TT>destImage(img, Point2D(...), SomeAccessor())</TT>
414 </td><td>
415 create argument object with upper left at point given by <tt>\ref vigra::Point2D</tt> of destination image,
416 and given accessor
417
418 </td></tr>
419 </table>
420
421
422 \section MultiArrayBasedArgumentObjectFactories MultiArrayView Based Argument Object Factories
423
424 <b>Include:</b> automatically included with
425 <vigra/multi_array.hxx><br>
426 Namespace: vigra
427
428 These factories can be used to create argument objects when we
429 are given instances or subclasses of \ref vigra::MultiArrayView.
430 These factory functions access <TT>array.traverser_begin()</TT>,
431 <TT>array.traverser_end()</TT> to obtain the iterators. If no accessor is
432 given, they use the <tt>AccessorTraits<T></tt> to determine the default
433 accessor associated with the array's value type <tt>T</tt>.
434 The following factory functions are provided:
435
436 <table>
437 <tr><th bgcolor="#f0e0c0" colspan=2 align=left>
438 <TT>\ref vigra::MultiArrayView "vigra::MultiArrayView<N, SomeType>" img;</TT>
439 </th>
440 </tr>
441 <tr><td>
442
443 <TT>srcMultiArrayRange(img)</TT>
444 </td><td>
445 create argument object containing a \ref vigra::MultiIterator
446 marking the begin of the array, a shape object giving the desired
447 shape of the array (possibly a subarray) and the default const accessor for
448 <tt>SomeType</tt>
449
450 </td></tr>
451 <tr><td>
452
453 <TT>srcMultiArrayRange(img, SomeAccessor())</TT>
454 </td><td>
455 create argument object containing a \ref vigra::MultiIterator
456 marking the begin of the array, a shape object giving the desired
457 shape of the array (possibly a subarray) and the given accessor
458
459 </td></tr>
460 <tr><td>
461
462 <TT>srcMultiArray(img)</TT>
463 </td><td>
464 create argument object containing a \ref vigra::MultiIterator
465 marking the begin of the array, and the default const accessor for
466 <tt>SomeType</tt>
467
468 </td></tr>
469 <tr><td>
470
471 <TT>srcMultiArray(img, SomeAccessor())</TT>
472 </td><td>
473 create argument object containing a \ref vigra::MultiIterator
474 marking the begin of the array and the given accessor
475
476 </td></tr>
477 <tr><td>
478
479 <TT>destMultiArrayRange(img)</TT>
480 </td><td>
481 create argument object containing a \ref vigra::MultiIterator
482 marking the begin of the array, a shape object giving the desired
483 shape of the array (possibly a subarray) and the default accessor for
484 <tt>SomeType</tt>
485
486 </td></tr>
487 <tr><td>
488
489 <TT>destMultiArrayRange(img, SomeAccessor())</TT>
490 </td><td>
491 create argument object containing a \ref vigra::MultiIterator's
492 marking the begin of the array, a shape object giving the desired
493 shape of the array (possibly a subarray) and the given accessor
494
495 </td></tr>
496 <tr><td>
497
498 <TT>destMultiArray(img)</TT>
499 </td><td>
500 create argument object containing a \ref vigra::MultiIterator
501 marking the begin of the array and the default accessor for
502 <tt>SomeType</tt>
503
504 </td></tr>
505 <tr><td>
506
507 <TT>destMultiArray(img, SomeAccessor())</TT>
508 </td><td>
509 create argument object containing a \ref vigra::MultiIterator's
510 marking the begin of the array and the given accessor
511
512 </td></tr>
513 </table>
514
515
516 \section IteratorBasedArgumentObjectFactories Iterator Based Argument Object Factories
517
518 <b>\#include</b> <vigra/iteratortraits.hxx>
519 Namespace: vigra
520
521 These factories can be used to create argument objects when we
522 are given \ref ImageIterators.
523 These factory functions use \ref vigra::IteratorTraits to
524 get the default accessor for the given iterator unless the
525 accessor is given explicitly. The following factory functions
526 are provided:
527
528 <table>
529 <tr><th bgcolor="#f0e0c0" colspan=2 align=left>
530 <TT>\ref vigra::BasicImage::Iterator "vigra::BasicImage<SomeType>::Iterator" i1, i2;</TT>
531 </th>
532 </tr>
533 <tr><td>
534
535 <TT>srcIterRange(i1, i2)</TT>
536 </td><td>
537 create argument object containing the given iterators and
538 corresponding default accessor (for source image)
539
540 </td></tr>
541 <tr><td>
542
543 <TT>srcIterRange(i1, i2, SomeAccessor())</TT>
544 </td><td>
545 create argument object containing given iterators and
546 accessor (for source image)
547
548 </td></tr>
549 <tr><td>
550
551 <TT>srcIter(i1)</TT>
552 </td><td>
553 create argument object containing the given iterator and
554 corresponding default accessor (for source image)
555
556 </td></tr>
557 <tr><td>
558
559 <TT>srcIter(i1, SomeAccessor())</TT>
560 </td><td>
561 create argument object containing given iterator and
562 accessor (for source image)
563
564 </td></tr>
565 <tr><td>
566
567 <TT>maskIter(i1)</TT>
568 </td><td>
569 create argument object containing the given iterator and
570 corresponding default accessor (for mask image)
571
572 </td></tr>
573 <tr><td>
574
575 <TT>maskIter(i1, SomeAccessor())</TT>
576 </td><td>
577 create argument object containing given iterator and
578 accessor (for mask image)
579
580 </td></tr>
581 <tr><td>
582
583 <TT>destIterRange(i1, i2)</TT>
584 </td><td>
585 create argument object containing the given iterators and
586 corresponding default accessor (for destination image)
587
588 </td></tr>
589 <tr><td>
590
591 <TT>destIterRange(i1, i2, SomeAccessor())</TT>
592 </td><td>
593 create argument object containing given iterators and
594 accessor (for destination image)
595
596 </td></tr>
597 <tr><td>
598
599 <TT>destIter(i1)</TT>
600 </td><td>
601 create argument object containing the given iterator and
602 corresponding default accessor (for destination image)
603
604 </td></tr>
605 <tr><td>
606
607 <TT>destIter(i1, SomeAccessor())</TT>
608 </td><td>
609 create argument object containing given iterator and
610 accessor (for destination image)
611
612 </td></tr>
613 </table>
614 */
615
616 template <class Iterator, class Accessor>
617 inline triple<Iterator, Iterator, Accessor>
618 srcIterRange(Iterator const & upperleft, Iterator const & lowerright, Accessor a)
619 {
620 return triple<Iterator, Iterator, Accessor>(upperleft, lowerright, a);
621 }
622
623 template <class Iterator, class Accessor>
624 inline pair<Iterator, Accessor>
625 srcIter(Iterator const & upperleft, Accessor a)
626 {
627 return pair<Iterator, Accessor>(upperleft, a);
628 }
629
630 template <class Iterator, class Accessor>
631 inline pair<Iterator, Accessor>
632 maskIter(Iterator const & upperleft, Accessor a)
633 {
634 return pair<Iterator, Accessor>(upperleft, a);
635 }
636
637 template <class Iterator, class Accessor>
638 inline pair<Iterator, Accessor>
639 destIter(Iterator const & upperleft, Accessor a)
640 {
641 return pair<Iterator, Accessor>(upperleft, a);
642 }
643
644
645 template <class Iterator, class Accessor>
646 inline triple<Iterator, Iterator, Accessor>
647 destIterRange(Iterator const & upperleft, Iterator const & lowerright, Accessor a)
648 {
649 return triple<Iterator, Iterator, Accessor>(upperleft, lowerright, a);
650 }
651
652 template <class Iterator>
653 inline pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>
654 srcIter(Iterator const & upperleft)
655 {
656 return pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>(
657 upperleft,
658 typename IteratorTraits<Iterator>::DefaultAccessor());
659 }
660
661 template <class Iterator>
662 inline triple<Iterator, Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>
663 srcIterRange(Iterator const & upperleft, Iterator const & lowerright)
664 {
665 return triple<Iterator, Iterator,
666 typename IteratorTraits<Iterator>::DefaultAccessor>(
667 upperleft, lowerright,
668 typename IteratorTraits<Iterator>::DefaultAccessor());
669 }
670
671 template <class Iterator>
672 inline pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>
673 maskIter(Iterator const & upperleft)
674 {
675 return pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>(
676 upperleft,
677 typename IteratorTraits<Iterator>::DefaultAccessor());
678 }
679
680 template <class Iterator>
681 inline pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>
682 destIter(Iterator const & upperleft)
683 {
684 return pair<Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>(
685 upperleft,
686 typename IteratorTraits<Iterator>::DefaultAccessor());
687 }
688
689 template <class Iterator>
690 inline triple<Iterator, Iterator, typename IteratorTraits<Iterator>::DefaultAccessor>
691 destIterRange(Iterator const & upperleft, Iterator const & lowerright)
692 {
693 return triple<Iterator, Iterator,
694 typename IteratorTraits<Iterator>::DefaultAccessor>(
695 upperleft, lowerright,
696 typename IteratorTraits<Iterator>::DefaultAccessor());
697 }
698
699 } // namespace vigra
700
701 #endif // VIGRA_ITERATORTRAITS_HXX

© Ullrich Köthe (ullrich.koethe@iwr.uni-heidelberg.de) Heidelberg Collaboratory for Image Processing, University of Heidelberg, Germany | html generated using doxygen and Python vigra 1.10.0 (Mon Nov 18 2013)