Click or drag to resize

IMcOMGlobalMcTranspose Method

Transposes the "rows" and "columns" of a matrix or other data object.

Namespace:  MediaCy.IQL.ObjectManager
Assembly:  MediaCy.IQL.ObjectManager (in MediaCy.IQL.ObjectManager.dll) Version: 10.0.6912.0
Syntax
VB
Copy
Function McTranspose ( 
	NDimArray As Object,
	<OptionalAttribute> DimensionOrdering As Object
) As McObject

Parameters

NDimArray
Type: SystemObject
An object of "standard" shape (no VARying size inner dimensions) from which dimensions are to be transposed.
DimensionOrdering (Optional)
Type: SystemObject
If given, a vector of length equal to the number of dimensions in NDimArray; each element gives the destination dimension number to be transposed from that position. For example, if NDimArray is a 4-D object, an Array(3,2,1,0) would specify the default reordering (all dimensions switched). The first element in this array refers to the slowest moving (0th) source dimension (the leftmost C/C++ dimension but the rightmost VB dimension), and dimension number zero refers to the slowest moving destination dimension. If a reordering array is given, it must contain each of the source dimension numbers once and only once. It is legal to call for a transposition that leaves the order of dimensions unchanged, but in this case, the returned object is just a copy of the NDimArray argument.

Return Value

Type: McObject
A McObject of the same type and overall VectorLength as the NDimArray argument and with the same number of dimensions. However, data values and dimensions are switched about (transposed) from those of NDimArray, according to the DimensionOrdering argument. The returned object will have a "standard" shape (leftmost dimension VAR, all others FIX'ed size).
Remarks
For a two dimensional matrix, mA (declared mA[N,M] in C/C++ or mA(0 to M-1,0 to N-1) in VB), the transposed return matrix mB (rows and columns switched, mB[M,N] in C/C++ or mA(0 to N-1,0 to M-1) in VB) is created so that: mB[m,n] = mA[n,m] for m, 0 to M-1, and n, 0 to N-1. (C/C++ syntax) mB(n,m) = mB(m,n) for m, 0 to M-1, and n, 0 to N-1. (VB syntax) Note that for arrays of 2 or more dimensions, for the same layout in memory, the ordering of dimensions is different in VB from that used in C/C++. In VB, the fastest moving dimension (the "row" dimension, whose elements are adjacent in memory) is the leftmost. In C/C++, the fastest moving dimension is the rightmost. For objects with more than two dimensions, the transpose function can perform a general transposition of any or all dimensions. By default, the transposed order of all dimensions is reversed. That is, a 4-D object declared vA[N,M,L,K] (C/C++ ordering) would, by default, be transposed into a 4-D object effectively declared vB[K,L,M,N] (C/C++ ordering), where each element vB[k,l,m,n] is set from the corresponding element vA[n,m,l,k]. A transposition ordering other than the default can be specified by giving an array of dimension numbers in the destination object in the order they are to be taken from the source object. The operation of the McTranspose method is sometimes difficult to visualize, especially for objects with more than two dimensions. However, the method is worth some investment in learning, because it can allow vector operations to replace what would otherwise be possible only by writing an explicit loop for stepping through the elements of some dimension. Example 2 is an illustrations of this sort of use for the Transpose function. The key concept here is to remember that the association rules for binary operations (such as the McOpAdd operation in the example) operate as if both operands were un-wound into simple 1-D arrays. A transposition operation may be necessary to move the dimension you want to operate along into the fastest-moving position; a second transposition can be used to put it back in its original place (as in the example).
Examples
VB
Copy
'Example 1: transpose a 2-D non-square matrix
Dim oA As McObject, oB As McObject
Set oA = McArrayTemp(mcobjTypeINTEGER, Array(2, 3))
oA.OpSelfAssign McOpConcatConcat(Array(0, 1, 2), Array(10, 11, 12))
Set oB = McTranspose(oA)  'swap rows and columns
Results.Text = McCStr("Example 1: oA =\n" & McToText(oA) & _
"\noB (oA transposed) =\n" & McToText(oB) & _
"\nShape oA: " & McToText(oA.Shape(mcobjSIC_SizeAllDims)) & _
"\nShape oB: " & McToText(oB.Shape(mcobjSIC_SizeAllDims)))
' Example 2: to elements of each row, add column number times 10
Dim oC As McObject
Set oC = McArrayTemp(mcobjTypeINTEGER, Array(3, 4))
oC.OpSelfAssign McOpFillIn(0, 4) 'fill 3 rows by 4 cols with 0 to 3
Results.Text = Results.Text + _
McCStr("\n\nExample 2. oC (3 rows of 0,1,2,3) =\n" & McToText(oC))
Set oC = McTranspose(McOpAdd(McTranspose(oC), Array(0, 10, 20)))
Results.Text = Results.Text + _
McCStr("\noC with col index times 10 added to each row =\n" & McToText(oC))
'Example 3: Flip a 3-D array
If ThisApplication.ActiveImage Is Nothing Then Exit Sub
If ThisApplication.ActiveImage.Type.Interpretation <> mciRGB Then
MsgBox "This test needs a RGB image."
Exit Sub
End If
With ThisApplication.ActiveImage.Aoi
.SetBox 0, 0, 0, 100, 200 '101 Wide by 201 High AOI
ThisApplication.ActiveImage.UndoStack.Push ActiveImage, , , , "McTranspose Test."
Dim raAOI As McRegionAccess
Set raAOI = .AccessMaskedImageData
Dim varAOIcolors As Variant
raAOI.GetArea varAOIcolors
'The varAOIcolors is a 3-D array Dim(3,100,200) using VB ordering
Results.Text = Results.Text + _
McCStr("\n\nExample 3. GetArea shape (C/C++ ordering) is :" & _
McToText(McObjectTemp(varAOIcolors).Shape(mcobjSIC_SizeAllDims)))
varAOIcolors = McTranspose(varAOIcolors, Array(1, 0, 2)) 'transpose only slowest 2 dimensions
Results.Text = Results.Text + _
McCStr("\nShape after McTranspose (C/C++ ordering) is :" & _
McToText(McObjectTemp(varAOIcolors).Shape(mcobjSIC_SizeAllDims)))
.SetBox 0, 0, 0, 200, 100 'flip the AOI, too
Set raAOI = .AccessMaskedImageData 'get a RA to the flipped AOI
raAOI.PutArea varAOIcolors 'put the flipped colors into the image
MsgBox "Look at the flipped AOI.  Press OK to put it back."
ThisApplication.ActiveImage.UndoStack.Undo 'restore the image
.Reset 'and clear the AOI
End With 'ActiveImage
See Also