Dali: Geometric Operations on ByteImages -- C API

Header Files

#include <dvmbytegeom.h>

Type Definitions

RectRegion

The RectRegion type defines a rectangular region. It is used as the return value of two functions, ByteAffineRectRegion() and ByteHomoRectRegion(). These functions compute the bounding box of the region in an image that will be affected by the corresponding operation (affine or homogenous transformations).

     typedef struct RectRegion {
         int x;
         int y;
         int w;
         int h;
     } RectRegion;

x

x-coordinate of the upper-left corner

y

y-coordinate of the upper-left corner

w

the width of the rectangle

h

the height of the rectangle

Constants

Return Codes

There return codes indicates if the operation was successful, or what error occured (if any).

DVM_BYTE_OK is returned if an operation is completed successfully.
DVM_BYTE_TOO_SMALL is returned when the destination ByteImage is too small to contain the result of the transformation. Either crop the source image using ByteClip() or allocate a larger destination image.
DVM_BYTE_BAD_MATRIX is returned when the specified operation (e.g., matrix inversion) cannot be performed on the homogenous/affine matrix passed in (e.g., because the matrix has no inverse).

    #define DVM_BYTE_OK 0
    #define DVM_BYTE_TOO_SMALL -1
    #define DVM_BYTE_BAD_MATRIX -2

Operators

Scaling

int ByteShrink1x2 (ByteImage *src, ByteImage *dest, int *newWidth, int *newHeight) int ByteShrink2x1 (ByteImage *src, ByteImage *dest, int *newWidth, int *newHeight) int ByteShrink2x2 (ByteImage *src, ByteImage *dest, int *newWidth, int *newHeight) int ByteShrink4x4 (ByteImage *src, ByteImage *dest, int *newWidth, int *newHeight)

ByteShrinkMxN shrinks src by a factor of M in the horizontal direction and N in the vertical direction. The result is written into dest. Pixels are combined by averaging (i.e., a box filter is used). Upon return, newWidth and newHeight contain the width and height of the resulting image.
For example, to scale a 320x240 image down to 160x120, you would use ByteShrink2x2(). ByteShrink1x2() would scale the same image to 320x120. These functions return DVM_BYTE_TOO_SMALL if dest is not large enough to hold the output -- otherwise, they return DVM_BYTE_OK.

int ByteExpand4x4 (ByteImage *src, ByteImage *dest, int *newWidth, int *newHeight) int ByteExpand2x2 (ByteImage *src, ByteImage *dest, int *newWidth, int *newHeight) int ByteExpand1x2 (ByteImage *src, ByteImage *dest, int *newWidth, int *newHeight) int ByteExpand2x1 (ByteImage *src, ByteImage *dest, int *newWidth, int *newHeight)

ByteExpandMxN enlarges src by a factor of M in the horizontal direction and N in the vertical direction. The result is written into dest. Pixels are combined by duplication (i.e., the effect is one of "fat-bitting" the pixels) Upon return, newWidth and newHeight contain the width and height of the resulting image.
For example, to scale a 80x60 image up to 320x240, you would use ByteExpand4x4(). These functions return DVM_BYTE_TOO_SMALL if dest is not large enough to hold the output --

int ByteScaleBilinear (ByteImage *src, ByteImage *dest, int newWidth, int newHeight)

Scale src to fit into an area newWidth x newHeight pixels in dest using bilinear interpolation. The result is written into starting at the upper left corner of dest.
For best results, the overall scaling factor should be between 1/2 and 2. ByteScaleBilinear will produce reasonable results for other factors, but some aliasing may occur. For scaling up or down by more than a factor of two, you should apply ByteShrinkMxN or ByteExpandMxN until the scaling factor is within between 1/2 and 2. DVM_BYTE_TOO_SMALL is returned if the destination is not large enough to hold the output, otherwise DVM_BYTE_OK if the operations is successful.

Rotation

void ByteRotate90a (ByteImage *src, ByteImage *dest) void ByteRotate90c (ByteImage *srcBuf, ByteImage *destBuf)

ByteRotate90a rotates src anti-clockwise by 90 degrees and stores the result in dest. ByteRotate90c rotates src clockwise by 90 degrees.

void ByteRotateOrig (ByteImage *src, ByteImage *dest, double theta)

This function rotates src counter-clockwise by theta degrees around its origin (i.e., the top-left corner of src). The rotated image is stored in dest.

void ByteRotate (ByteImage *src, ByteImage *dest, double theta, int x, int y)

This function rotates src counter-clockwise by theta degrees around the point (x,y). The rotated image is stored in dest.

Affine Transformations

void ByteAffine (ByteImage *src, ByteImage *dest, double a, double b, double c, double d, double e, double f)

Texture map src using the affine transformation specified by the parameters a..f. The result is written into dest.
The equation of the transform is
x' = ax + by + c
y' = dx + ey + f
where (x,y) are coordinates in src, and (x',y') are coordinates in dest.

RectRegion ByteAffineRectRegion (ByteImage *src, double a, double b, double c, double d, double e, double f)

Return the bounding box that src will map to (in the coordinate system of dest) given the affine coefficients specified.

Homogeneous Transformations

void ByteHomo (ByteImage *src, ByteImage *dest, double a, double b, double c, double d, double e, double f, double m, double n, double p)

Texture map src using the homogeneous transformation specified by the floating point parameters a..p. The result is written into dest.
The equation of the transform is
x' = (ax+by+c) / w
y' = (dx+ey+f) / w
where
w = mx+ny+p
The coordinates (x,y) are in src, and (x',y') are in the dest.
Note: this function assumes that dest is large enough to accomodate the transformed image. It may cause a segmentation fault otherwise.

RectRegion ByteHomoRectRegion (ByteImage *src, double a, double b, double c, double d, double e, double f, double m, double n, double p)

Return the bounding box (in destination image coordinates) where src will be mapped if it is texture mapped using the given homogeneous matrix coefficients. The return value is in the coordinate system of the destination image.

int ByteHomoComputeMatrix (double w, double h, double x1, double y1, double x2, double y2, double x3, double y3, double *a, double *b, double *d, double *e, double *m, double *n)
Find the homogeneous matrix which transforms the rectangle with corners at (0,0), (w,0), (w,h), (0,h) into the the quadrilateral with coordinates (0,0), (x1,y1), (x2,y2) (x3,y3)

The return value is given by the six reference parameters a..n. These are part of the matrix:
        a b 0
        d e 0
        m n 1
      
The value DVM_BYTE_BAD_MATRIX is returned if no projective transform exists given the value specified. Otherwise, DVM_BYTE_OK is returned.
int ByteHomoInvertMatrix (double a, double b, double d, double e, double m, double n, double *aNew, double *bNew, double *dNew, double *eNew, double *mNew, double *nNew)
Compute the inverse of the homogeneous matrix
        a b 0
        d e 0
        m n 1
      
The inverse matrix is returned in the values aNew..nNew, which correspond to a', b', d', e', m', and n' in the matrix
        a' b' 0
        d' e' 0
        m' n' 1
      
The value DVM_BYTE_BAD_MATRIX is returned if no projective transform exists given the value specified. Otherwise, DVM_BYTE_OK is returned.