VIPER REFERENCE MANUAL


NAME
iflMapOrientation, iflMapFlipTrans, iflMapTile, iflMapXY, iflMapXYSign, iflOrientationIsMirror, iflMapSize - orientation utility functions

HEADER FILE
#include <ifl/iflOrientation.h>

SYNOPSIS
iflOrientation iflMapOrientation ( iflOrientation orientation, int flipX, int flipY, int transXY);
void iflMapFlipTrans ( iflOrientation fromOrientation, iflFlip& flip, int& transXY, iflOrientation toOrientation);
void iflMapTile ( iflOrientation fromOrientation, iflTile2D<float>& tile, iflOrientation toOrientation, const iflSize& size);
void iflMapTile ( iflOrientation fromOrientation, iflTile2D<int>& tile, iflFlip& flip, int& transXY, iflOrientation toOrientation, const iflSize& size);
void iflMapTile ( iflOrientation fromOrientation, iflTile2D<int>& tile, iflOrientation toOrientation, const iflSize& size);
void iflMapXY ( iflOrientation fromOrientation, int& x, int& y, iflOrientation toOrientation, const iflSize& size);
void iflMapXY ( iflOrientation fromOrientation, float& x, float& y, iflOrientation toOrientation, const iflSize& size);
void iflMapXYSign ( iflOrientation fromOrientation, float& x, float& y, iflOrientation toOrientation);
int iflOrientationIsMirror ( iflOrientation fromOrientation, iflOrientation toOrientation);
void iflMapSize ( iflOrientation fromOrientation, iflSize& size, iflOrientation toOrientation);
void iflMapSize ( iflOrientation fromOrientation, int& sx, int& sy, iflOrientation toOrientation);

VARIABLE SYNOPSIS
extern char iflOrientationIsLow[];
extern char iflOrientationIsLeft[];
extern char iflOrientationIsTrans[];

DESCRIPTION
These functions allow various operations related to the iflOrientation enumerate type to be performed.

   Notes
A transposed orientation is one in which the X coordinate describes vertical coordinates and the Y coordinate describes horizontal coordinates. Two orientations are "transposed with respect to each other" if one is transposed and the other is not.

An X-flipped orientation is one in which the X coordinates increase from right to left (or top to bottom for transposed orientations). A Y-flipped orientation is one in which the Y coordinates increase from top to bottom (or right to left for transposed orientations). Two orientations are "flipped in X with respect to each other" if one is X-flipped and the other is not. A similar comment holds for Y-flipping.

An "image's orientation" refers to the image's storage format. For all image orientations, X is defined to be the dimension which varies the fastest in storage and Y is the dimension which varies next fastest. Thus, for an image with a non-transposed orientation, the image is mapped into storage in row-major order; for a transposed image, the image is mapped column-major.

When a coordinate tile is mapped from one orientation, fromOrientation, to another orientation, toOrientation, the following actions are performed:

  1. Transpose X and Y if toOrientation is transposed with respect to fromOrientation:
        swap(x, y);
        swap(nx, ny);
    
  2. Flip X and/or Y if toOrientation is flipped with respect to fromOrientation. Flipping is computed relative to a size:
        x = size.x - x - nx;
        y = size.y - y - ny;
    
Note in particular that the size.x and size.y parameters in this process not transposed. Thus, they represent the size of the destination orientation.

FUNCTION DESCRIPTIONS

   iflMapFlipTrans()
void iflMapFlipTrans ( iflOrientation fromOrientation, iflFlip& flip, int& transXY, iflOrientation toOrientation);

This function determines the flips and/or transpositions required to map from fromOrientation to toOrientation. The required flip and transXY values are returned.

   iflMapOrientation()
iflOrientation iflMapOrientation ( iflOrientation orientation, int flipX, int flipY, int transXY);

The function returns the orientation that results from applying some combination of an X flip, followed by a Y flip followed by a transposition, to the supplied orientation. If flipX is TRUE, the x dimension is flipped. If flipY is TRUE, the y dimension is flipped. If transXY is TRUE, the x and y dimensions are swapped.

   iflMapSize()
void iflMapSize ( iflOrientation fromOrientation, iflSize& size, iflOrientation toOrientation);
void iflMapSize ( iflOrientation fromOrientation, int& sx, int& sy, iflOrientation toOrientation);

Transposes the sx and sy size as needed, based on fromOrientation and toOrientation.

   iflMapTile()
void iflMapTile ( iflOrientation fromOrientation, iflTile2D<float>& tile, iflOrientation toOrientation, const iflSize& size);
void iflMapTile ( iflOrientation fromOrientation, iflTile2D<int>& tile, iflFlip& flip, int& transXY, iflOrientation toOrientation, const iflSize& size);
void iflMapTile ( iflOrientation fromOrientation, iflTile2D<int>& tile, iflOrientation toOrientation, const iflSize& size);

The tile referenced by tile is mapped from orientation fromOrientation to the orientation toOrientation. The origin and size members of tile are recomputed to reflect this mapping. The value returned in the iflFlip enumerated type, flip indicates whether the x or the y axis, or both, had to be flipped to effect the mapping.

If no flipping was required, then iflNoFlip is returned. If the x or y axis was flipped, iflXFlip or iflYFlip is returned. If both axes were flipped, (iflXFlip|iflYFlip) is returned. If, to effect the mapping, the x and y axes had to be interchanged (that is, the new x origin and size are the old y origin and size and the converse is true), then TRUE is returned in transXY; otherwise transXY is FALSE.

   iflMapXY...()
void iflMapXY ( iflOrientation fromOrientation, int& x, int& y, iflOrientation toOrientation, const iflSize& size);
void iflMapXY ( iflOrientation fromOrientation, float& x, float& y, iflOrientation toOrientation, const iflSize& size);
void iflMapXYSign ( iflOrientation fromOrientation, float& x, float& y, iflOrientation toOrientation);

The (x,y) pair of values referenced by x and y is mapped from orientation fromOrientation to the orientation toOrientation. In the iflMapXYSign() function, if a flip in the x or y dimensions is required to transform between the two orientations, the x and y values are negated accordingly. If a transpose is required, the x and y values are swapped.

   iflOrientationIsMirror()
int iflOrientationIsMirror ( iflOrientation fromOrientation, iflOrientation toOrientation);

The routine returns TRUE if fromOrientation is a mirror image of toOrientation. This can be useful when implementing operations that have calculations that depend on a particular frame of reference. For example, when implementing an image rotation operator, the angle can need to be negated to produce consistent results on inputs of arbitrary orientation.

VARIABLE DESCRIPTIONS

   iflOrientationIs...
extern char iflOrientationIsLow[];
extern char iflOrientationIsLeft[];
extern char iflOrientationIsTrans[];

Arrays of booleans to be indexed with an iflOrientation value. The array entries indicate whether the indexing iflOrientation has a "Low" origin (vertical coordinates increase from bottom to top), a "Left" origin (horizontal coordinates increase from origin and whether it is a transposed orientation.