|
MultiArrayView< N, T, StrideTag > Class Template Reference |  |
Base class for, and view to, vigra::MultiArray. More...
#include <vigra/multi_array.hxx>
Public Types | |
| enum | ActualDimension |
| typedef StridedScanOrderIterator < actual_dimension, T, T const &, T const * > | const_iterator |
| typedef const value_type * | const_pointer |
| typedef const value_type & | const_reference |
| typedef vigra::detail::MultiIteratorChooser < StrideTag >::template Traverser< actual_dimension, T, T const &, T const * >::type | const_traverser |
| typedef MultiArrayShape < actual_dimension >::type | difference_type |
| typedef MultiArrayIndex | difference_type_1 |
| typedef StridedScanOrderIterator < actual_dimension, T, T &, T * > | iterator |
| typedef difference_type | key_type |
| typedef MultiArray< N, T > | matrix_type |
| typedef value_type * | pointer |
| typedef value_type & | reference |
| typedef difference_type | size_type |
| typedef vigra::detail::MultiIteratorChooser < StrideTag >::template Traverser< actual_dimension, T, T &, T * >::type | traverser |
| typedef T | value_type |
| typedef MultiArrayView< N, T, StrideTag > | view_type |
Static Public Member Functions | |
| static difference_type | strideOrdering (difference_type strides) |
Protected Attributes | |
| pointer | m_ptr |
| difference_type | m_shape |
| difference_type | m_stride |
Detailed Description
template<unsigned int N, class T, class StrideTag>
class vigra::MultiArrayView< N, T, StrideTag >
Base class for, and view to, vigra::MultiArray.
This class implements the interface of both MultiArray and MultiArrayView. By default, MultiArrayViews are tagged as strided (using StridedArrayTag as third template parameter). This means that the array elements need not be consecutive in memory, making the view flexible to represent all kinds of subarrays and slices. In certain cases (which have become rare due to improvements of optimizer and processor technology), an array may be tagged with UnstridedArrayTag which indicates that the first array dimension is guaranteed to be unstrided, i.e. has consecutive elements in memory.
In addition to the member functions described here, MultiArrayView and its subclasses support arithmetic and algebraic functions via the module vigra::multi_math.
If you want to apply an algorithm requiring an image to a MultiArrayView of appropriate (2-dimensional) shape, you can create a vigra::BasicImageView that acts as a wrapper with the necessary interface – see Create BasicImageView from MultiArrayViews.
The template parameter are as follows
#include <vigra/multi_array.hxx>
Namespace: vigra
- Examples:
- composite.cxx, smooth_explicitly.cxx, subimage.cxx, subimage_tutorial.cxx, and transpose.cxx.
Member Typedef Documentation
| typedef T value_type |
the array's value type
| typedef value_type& reference |
reference type (result of operator[])
| typedef const value_type& const_reference |
const reference type (result of operator[] const)
| typedef value_type* pointer |
pointer type
| typedef const value_type* const_pointer |
const pointer type
| typedef MultiArrayShape<actual_dimension>::type difference_type |
difference type (used for multi-dimensional offsets and indices)
| typedef difference_type key_type |
key type (argument of index operator array[i] – same as difference_type)
| typedef difference_type size_type |
size type
| typedef MultiArrayIndex difference_type_1 |
difference and index type for a single dimension
| typedef StridedScanOrderIterator<actual_dimension, T, T &, T *> iterator |
scan-order iterator (StridedScanOrderIterator) type
| typedef StridedScanOrderIterator<actual_dimension, T, T const &, T const *> const_iterator |
const scan-order iterator (StridedScanOrderIterator) type
| typedef vigra::detail::MultiIteratorChooser< StrideTag>::template Traverser<actual_dimension, T, T &, T *>::type traverser |
traverser (MultiIterator) type
| typedef vigra::detail::MultiIteratorChooser< StrideTag>::template Traverser<actual_dimension, T, T const &, T const *>::type const_traverser |
const traverser (MultiIterator) type
| typedef MultiArrayView<N, T, StrideTag> view_type |
the view type associated with this array.
| typedef MultiArray<N, T> matrix_type |
the matrix type associated with this array.
Member Enumeration Documentation
| enum ActualDimension |
the array's actual dimensionality. This ensures that MultiArrayView can also be used for scalars (that is, when N == 0). Calculated as:
Constructor & Destructor Documentation
| MultiArrayView | ( | ) |
| MultiArrayView | ( | const MultiArrayView< N, T, Stride > & | other | ) |
construct from another array view. Throws a precondition error if this array has UnstridedArrayTag, but the innermost dimension of other is strided.
| MultiArrayView | ( | const difference_type & | shape, |
| const_pointer | ptr | ||
| ) |
construct from shape and pointer
| MultiArrayView | ( | const difference_type & | shape, |
| const difference_type & | stride, | ||
| const_pointer | ptr | ||
| ) |
Construct from shape, strides (offset of a sample to the next) for every dimension, and pointer. (Note that strides are not given in bytes, but in offset steps of the respective pointer type.)
| MultiArrayView | ( | BasicImage< T, ALLOC > const & | image | ) |
Construct from an old-style BasicImage.
Member Function Documentation
| operator MultiArrayView< N, T, StridedArrayTag > | ( | ) | const |
Conversion to a strided view.
| void reset | ( | ) |
Reset this MultiArrayView to an invalid state (as after default construction). Can e.g. be used prior to assignment to make a view object point to new data.
| MultiArrayView& operator= | ( | MultiArrayView< N, T, StrideTag > const & | rhs | ) |
Assignment. There are 3 cases:
-
When this
MultiArrayViewdoes not point to valid data (e.g. after default construction), it becomes a new view of rhs. - Otherwise, when the shapes of the two arrays match, the contents (i.e. the elements) of rhs are copied.
-
Otherwise, a
PreconditionViolationexception is thrown.
| MultiArrayView& operator= | ( | MultiArrayView< N, U, C1 > const & | rhs | ) |
Assignment of a differently typed MultiArrayView. It copies the elements ofrhs or fails with PreconditionViolation exception when the shapes do not match.
| MultiArrayView& operator= | ( | value_type const & | v | ) |
Assignment of a scalar. Equivalent to MultiArrayView::init(v).
| MultiArrayView& operator+= | ( | MultiArrayView< N, U, C1 > const & | rhs | ) |
Add-assignment of a compatible MultiArrayView. Fails with PreconditionViolation exception when the shapes do not match.
| MultiArrayView& operator-= | ( | MultiArrayView< N, U, C1 > const & | rhs | ) |
Subtract-assignment of a compatible MultiArrayView. Fails with PreconditionViolation exception when the shapes do not match.
| MultiArrayView& operator*= | ( | MultiArrayView< N, U, C1 > const & | rhs | ) |
Multiply-assignment of a compatible MultiArrayView. Fails with PreconditionViolation exception when the shapes do not match.
| MultiArrayView& operator/= | ( | MultiArrayView< N, U, C1 > const & | rhs | ) |
Divide-assignment of a compatible MultiArrayView. Fails with PreconditionViolation exception when the shapes do not match.
| MultiArrayView& operator+= | ( | T const & | rhs | ) |
Add-assignment of a scalar.
| MultiArrayView& operator-= | ( | T const & | rhs | ) |
Subtract-assignment of a scalar.
| MultiArrayView& operator*= | ( | T const & | rhs | ) |
Multiply-assignment of a scalar.
| MultiArrayView& operator/= | ( | T const & | rhs | ) |
Divide-assignment of a scalar.
| MultiArrayView& operator= | ( | multi_math::MultiMathOperand< Expression > const & | rhs | ) |
Assignment of an array expression. Fails with PreconditionViolation exception when the shapes do not match.
| MultiArrayView& operator+= | ( | multi_math::MultiMathOperand< Expression > const & | rhs | ) |
Add-assignment of an array expression. Fails with PreconditionViolation exception when the shapes do not match.
| MultiArrayView& operator-= | ( | multi_math::MultiMathOperand< Expression > const & | rhs | ) |
Subtract-assignment of an array expression. Fails with PreconditionViolation exception when the shapes do not match.
| MultiArrayView& operator*= | ( | multi_math::MultiMathOperand< Expression > const & | rhs | ) |
Multiply-assignment of an array expression. Fails with PreconditionViolation exception when the shapes do not match.
| MultiArrayView& operator/= | ( | multi_math::MultiMathOperand< Expression > const & | rhs | ) |
Divide-assignment of an array expression. Fails with PreconditionViolation exception when the shapes do not match.
| reference operator[] | ( | const difference_type & | d | ) |
array access.
| const_reference operator[] | ( | const difference_type & | d | ) | const |
array access.
| MultiArrayView<N-M, T, StridedArrayTag> operator[] | ( | const TinyVector< MultiArrayIndex, M > & | d | ) | const |
equivalent to bindInner(), when M < N.
| reference operator[] | ( | difference_type_1 | d | ) |
Array access in scan-order sense. Mostly useful to support standard indexing for 1-dimensional multi-arrays, but works for any N. Use scanOrderIndexToCoordinate() and coordinateToScanOrderIndex() for conversion between indices and coordinates.
Note: This function should not be used in the inner loop, because the conversion of the scan order index into a memory address is expensive (it must take into account that memory may not be consecutive for subarrays and/or strided arrays). Always prefer operator() if possible.
| const_reference operator[] | ( | difference_type_1 | d | ) | const |
Array access in scan-order sense. Mostly useful to support standard indexing for 1-dimensional multi-arrays, but works for any N. Use scanOrderIndexToCoordinate() and coordinateToScanOrderIndex() for conversion between indices and coordinates.
Note: This function should not be used in the inner loop, because the conversion of the scan order index into a memory address is expensive (it must take into account that memory may not be consecutive for subarrays and/or strided arrays). Always prefer operator() if possible.
| difference_type scanOrderIndexToCoordinate | ( | difference_type_1 | d | ) | const |
convert scan-order index to coordinate.
| difference_type_1 coordinateToScanOrderIndex | ( | const difference_type & | d | ) | const |
convert coordinate to scan-order index.
| reference operator() | ( | difference_type_1 | x | ) |
1D array access. Use only if N == 1.
| reference operator() | ( | difference_type_1 | x, |
| difference_type_1 | y | ||
| ) |
2D array access. Use only if N == 2.
| reference operator() | ( | difference_type_1 | x, |
| difference_type_1 | y, | ||
| difference_type_1 | z | ||
| ) |
3D array access. Use only if N == 3.
| reference operator() | ( | difference_type_1 | x, |
| difference_type_1 | y, | ||
| difference_type_1 | z, | ||
| difference_type_1 | u | ||
| ) |
4D array access. Use only if N == 4.
| reference operator() | ( | difference_type_1 | x, |
| difference_type_1 | y, | ||
| difference_type_1 | z, | ||
| difference_type_1 | u, | ||
| difference_type_1 | v | ||
| ) |
5D array access. Use only if N == 5.
| const_reference operator() | ( | difference_type_1 | x | ) | const |
1D const array access. Use only if N == 1.
| const_reference operator() | ( | difference_type_1 | x, |
| difference_type_1 | y | ||
| ) | const |
2D const array access. Use only if N == 2.
| const_reference operator() | ( | difference_type_1 | x, |
| difference_type_1 | y, | ||
| difference_type_1 | z | ||
| ) | const |
3D const array access. Use only if N == 3.
| const_reference operator() | ( | difference_type_1 | x, |
| difference_type_1 | y, | ||
| difference_type_1 | z, | ||
| difference_type_1 | u | ||
| ) | const |
4D const array access. Use only if N == 4.
| const_reference operator() | ( | difference_type_1 | x, |
| difference_type_1 | y, | ||
| difference_type_1 | z, | ||
| difference_type_1 | u, | ||
| difference_type_1 | v | ||
| ) | const |
5D const array access. Use only if N == 5.
| MultiArrayView& init | ( | const U & | init | ) |
Init with a constant.
| void copy | ( | const MultiArrayView< N, T, StrideTag > & | rhs | ) |
Copy the data of the right-hand array (array shapes must match).
| void copy | ( | const MultiArrayView< N, U, CN > & | rhs | ) |
Copy the data of the right-hand array (array shapes must match).
| void swap | ( | MultiArrayView< N, T, StrideTag > & | other | ) |
Swap the pointers, shaes and strides between two array views.
This function must be used with care. Never swap a MultiArray (which owns data) with a MultiArrayView:
Now, a and b refer to the same memory. This may lead to a crash in their destructor, and in any case leaks b's original memory. Only use swap() on copied MultiArrayViews:
| void swapData | ( | MultiArrayView< N, T, StrideTag > | rhs | ) |
swap the data between two MultiArrayView objects.
The shapes of the two array must match.
| void swapData | ( | MultiArrayView< N, T2, C2 > | rhs | ) |
swap the data between two MultiArrayView objects.
The shapes of the two array must match.
| bool isUnstrided | ( | unsigned int | dimension = N-1 | ) | const |
check whether the array is unstrided (i.e. has consecutive memory) up to the given dimension.
dimension can range from 0 ... N-1. If a certain dimension is unstrided, all lower dimensions are also unstrided.
| MultiArrayView< N-M, T, StrideTag > bindOuter | ( | const TinyVector< Index, M > & | d | ) | const |
bind the M outmost dimensions to certain indices. this reduces the dimensionality of the image to max { 1, N-M }.
Usage:
| MultiArrayView< N-M, T, StridedArrayTag > bindInner | ( | const TinyVector< Index, M > & | d | ) | const |
bind the M innermost dimensions to certain indices. this reduces the dimensionality of the image to max { 1, N-M }.
Usage:
| MultiArrayView<N-1, T, typename vigra::detail::MaybeStrided<StrideTag, M>::type > bind | ( | difference_type_1 | d | ) | const |
bind dimension M to index d. this reduces the dimensionality of the image to max { 1, N-1 }.
Usage:
| MultiArrayView< N-1, T, StrideTag > bindOuter | ( | difference_type_1 | d | ) | const |
bind the outmost dimension to a certain index. this reduces the dimensionality of the image to max { 1, N-1 }.
Usage:
| MultiArrayView< N-1, T, StridedArrayTag > bindInner | ( | difference_type_1 | d | ) | const |
bind the innermost dimension to a certain index. this reduces the dimensionality of the image to max { 1, N-1 }.
Usage:
| MultiArrayView< N-1, T, StridedArrayTag > bindAt | ( | difference_type_1 | m, |
| difference_type_1 | d | ||
| ) | const |
bind dimension m to index d. this reduces the dimensionality of the image to max { 1, N-1 }.
Usage:
| MultiArrayView<N, typename ExpandElementResult<T>::type, StridedArrayTag> bindElementChannel | ( | difference_type_1 | i | ) | const |
Create a view to channel 'i' of a vector-like value type. Possible value types (of the original array) are: TinyVector, RGBValue, FFTWComplex, and std::complex. The list can be extended to any type whose memory layout is equivalent to a fixed-size C array, by specializing ExpandElementResult.
Usage:
| MultiArrayView< N+1, typename ExpandElementResult< T >::type, StridedArrayTag > expandElements | ( | difference_type_1 | d | ) | const |
Create a view where a vector-like element type is expanded into a new array dimension. The new dimension is inserted at index position 'd', which must be between 0 and N inclusive.
Possible value types of the original array are: TinyVector, RGBValue, FFTWComplex, std::complex, and the built-in number types (in this case, expandElements is equivalent to insertSingletonDimension). The list of supported types can be extended to any type whose memory layout is equivalent to a fixed-size C array, by specializing ExpandElementResult.
Usage:
| MultiArrayView< N+1, T, StrideTag > insertSingletonDimension | ( | difference_type_1 | i | ) | const |
Add a singleton dimension (dimension of length 1).
Singleton dimensions don't change the size of the data, but introduce a new index that can only take the value 0. This is mainly useful for the 'reduce mode' of transformMultiArray() and combineTwoMultiArrays(), because these functions require the source and destination arrays to have the same number of dimensions.
The range of i must be 0 <= i <= N. The new dimension will become the i'th index, and the old indices from i upwards will shift one place to the right.
Usage:
Suppose we want have a 2D array and want to create a 1D array that contains the row average of the first array.
| MultiArrayView<N, Multiband<value_type>, StrideTag> multiband | ( | ) | const |
create a multiband view for this array.
The type MultiArrayView<N, Multiband<T> > tells VIGRA algorithms which recognize the Multiband modifier to interpret the outermost (last) dimension as a channel dimension. In effect, these algorithms will treat the data as a set of (N-1)-dimensional arrays instead of a single N-dimensional array.
| MultiArrayView<1, T, StridedArrayTag> diagonal | ( | ) | const |
Create a view to the diagonal elements of the array.
This produces a 1D array view whose size equals the size of the shortest dimension of the original array.
Usage:
| MultiArrayView subarray | ( | difference_type | p, |
| difference_type | q | ||
| ) | const |
create a rectangular subarray that spans between the points p and q, where p is in the subarray, q not. If an element of p or q is negative, it is subtracted from the correspongng shape.
Usage:
- Examples:
- composite.cxx, smooth_explicitly.cxx, and subimage.cxx.
| MultiArrayView<N, T, StridedArrayTag> stridearray | ( | const difference_type & | s | ) | const |
apply an additional striding to the image, thereby reducing the shape of the array. for example, multiplying the stride of dimension one by three turns an appropriately laid out (interleaved) rgb image into a single band image.
| MultiArrayView<N, T, StridedArrayTag> transpose | ( | ) | const |
Transpose an array. If N==2, this implements the usual matrix transposition. For N > 2, it reverses the order of the indices.
Usage:
- Examples:
- transpose.cxx.
| MultiArrayView<N, T, StridedArrayTag> transpose | ( | const difference_type & | permutation | ) | const |
Permute the dimensions of the array. The function exchanges the orer of the array's axes without copying the data. Argumentpermutation specifies the desired order such that permutation[k] = j means that axis j in the original array becomes axis k in the transposed array.
Usage:
| MultiArrayView< N, T, StridedArrayTag > permuteStridesAscending | ( | ) | const |
Permute the dimensions of the array so that the strides are in ascending order. Determines the appropriate permutation and then calls permuteDimensions().
| MultiArrayView< N, T, StridedArrayTag > permuteStridesDescending | ( | ) | const |
Permute the dimensions of the array so that the strides are in descending order. Determines the appropriate permutation and then calls permuteDimensions().
| difference_type strideOrdering | ( | ) | const |
Compute the ordering of the strides in this array. The result is describes the current permutation of the axes relative to the standard ascending stride order.
|
static |
Compute the ordering of the given strides. The result is describes the current permutation of the axes relative to the standard ascending stride order.
| difference_type_1 elementCount | ( | ) | const |
number of the elements in the array.
| difference_type_1 size | ( | ) | const |
number of the elements in the array. Same as elementCount(). Mostly useful to support the std::vector interface.
| const difference_type& shape | ( | ) | const |
return the array's shape.
| difference_type_1 size | ( | difference_type_1 | n | ) | const |
return the array's size at a certain dimension.
| difference_type_1 shape | ( | difference_type_1 | n | ) | const |
return the array's shape at a certain dimension (same as size(n)).
| difference_type_1 width | ( | ) | const |
return the array's width (same as shape(0)).
| difference_type_1 height | ( | ) | const |
return the array's height (same as shape(1)).
| const difference_type& stride | ( | ) | const |
return the array's stride for every dimension.
| difference_type_1 stride | ( | int | n | ) | const |
return the array's stride at a certain dimension.
| bool operator== | ( | MultiArrayView< N, U, C1 > const & | rhs | ) | const |
check whether two arrays are elementwise equal.
| bool operator!= | ( | MultiArrayView< N, U, C1 > const & | rhs | ) | const |
check whether two arrays are not elementwise equal. Also true when the two arrays have different shapes.
| bool isInside | ( | difference_type const & | p | ) | const |
check whether the given point is in the array range.
| bool isOutside | ( | difference_type const & | p | ) | const |
check whether the given point is not in the array range.
| bool all | ( | ) | const |
Check if the array contains only non-zero elements (or if all elements are 'true' if the value type is 'bool').
| bool any | ( | ) | const |
Check if the array contains a non-zero element (or an element that is 'true' if the value type is 'bool').
| void minmax | ( | T * | minimum, |
| T * | maximum | ||
| ) | const |
Find the minimum and maximum element in this array. See Feature Accumulators for a general feature extraction framework.
| void meanVariance | ( | U * | mean, |
| U * | variance | ||
| ) | const |
Compute the mean and variance of the values in this array. See Feature Accumulators for a general feature extraction framework.
| U sum | ( | ) | const |
Compute the sum of the array elements.
You must provide the type of the result by an explicit template parameter:
- Examples:
- smooth_explicitly.cxx.
| void sum | ( | MultiArrayView< N, U, S > | sums | ) | const |
Compute the sum of the array elements over selected axes.
- sums must have the same shape as this array, except for the axes along which the sum is to be accumulated. These axes must be singletons. Note that you must include
multi_pointoperators.hxxfor this function to work.
Usage:
| U product | ( | ) | const |
Compute the product of the array elements.
You must provide the type of the result by an explicit template parameter:
| NormTraits<MultiArrayView>::SquaredNormType squaredNorm | ( | ) | const |
Compute the squared Euclidean norm of the array (sum of squares of the array elements).
| NormTraits< MultiArrayView< N, T, StrideTag > >::NormType norm | ( | int | type = 2, |
| bool | useSquaredNorm = true |
||
| ) | const |
Compute various norms of the array. The norm is determined by parameter type:
- type == 0: maximum norm (L-infinity): maximum of absolute values of the array elements
- type == 1: Manhattan norm (L1): sum of absolute values of the array elements
-
type == 2: Euclidean norm (L2): square root of
squaredNorm()when useSquaredNorm istrue,
or direct algorithm that avoids underflow/overflow otherwise.
Parameter useSquaredNorm has no effect when type != 2. Defaults: compute L2 norm as square root of squaredNorm().
| pointer data | ( | ) | const |
return the pointer to the image data
| bool hasData | ( | ) | const |
returns true iff this view refers to valid data, i.e. data() is not a NULL pointer. (this is false after default construction.)
| iterator begin | ( | ) |
returns a scan-order iterator pointing to the first array element.
| const_iterator begin | ( | ) | const |
returns a const scan-order iterator pointing to the first array element.
| iterator end | ( | ) |
returns a scan-order iterator pointing beyond the last array element.
| const_iterator end | ( | ) | const |
returns a const scan-order iterator pointing beyond the last array element.
| traverser traverser_begin | ( | ) |
returns the N-dimensional MultiIterator pointing to the first element in every dimension.
| const_traverser traverser_begin | ( | ) | const |
returns the N-dimensional MultiIterator pointing to the const first element in every dimension.
| traverser traverser_end | ( | ) |
returns the N-dimensional MultiIterator pointing beyond the last element in dimension N, and to the first element in every other dimension.
| const_traverser traverser_end | ( | ) | const |
returns the N-dimensional const MultiIterator pointing beyond the last element in dimension N, and to the first element in every other dimension.
Member Data Documentation
|
protected |
the shape of the image pointed to is stored here.
|
protected |
the strides (offset of a sample to the next) for every dimension are stored here.
|
protected |
pointer to the image.
The documentation for this class was generated from the following file:
- vigra/multi_array.hxx