Skip to content

API‐Transform

Jump to bottom
ZangoTech edited this page Jun 20, 2026 · 1 revision

Transform

← Back to API Reference · Home

Namespace: acl::transform (CPP) / acl::neon::transform (NEON)

Transform is split into two categories:

  • Matrix computation (compute the transform matrix from point pairs): getRotationMatrix2D / getAffineTransform / getPerspectiveTransform / findHomography
  • Applying the transform (resample the image using the matrix): warpAffine / warpPerspective / remap / yuvRemap

getRotationMatrix2D

Construct a 2×3 affine matrix from rotation around (cx, cy) + scaling.

Tier: Starter+
Channels: N/A (matrix builder)
Inplace: not supported
Types:

Template parameter Allowed types Constraint
T double —

CPP Signature

int getRotationMatrix2D(
    double cx, double cy,
    double angle, double scale,
    double* M);
Parameter Type Meaning Default
cx, cy double Rotation center coordinates —
angle double Rotation angle (degrees, counter-clockwise positive) —
scale double Scaling factor —
M double* Output 2×3 matrix, row-major, 6 doubles non-null

getAffineTransform

Compute a 2×3 affine transform matrix from 3 point pairs.

Tier: Starter+
Channels: N/A (matrix builder)
Inplace: not supported
Types:

Template parameter Allowed types Constraint
T double —

CPP Signature

int getAffineTransform(
    const double* srcImage, const double* dstImage,
    double* M);
Parameter Type Meaning
srcImage const double* 3 source points (x0,y0, x1,y1, x2,y2), 6 doubles total
dstImage const double* 3 destination points (same format as above)
M double* Output 2×3 matrix, row-major

getPerspectiveTransform

Compute a 3×3 perspective transform matrix from 4 point pairs.

Tier: Starter+
Channels: N/A (matrix builder)
Inplace: not supported
Types:

Template parameter Allowed types Constraint
T double —

CPP / NEON Signature (identical)

int getPerspectiveTransform(
    const double* srcImage, const double* dstImage,
    double* M);
Parameter Type Meaning
srcImage const double* 4 source points, 8 doubles total
dstImage const double* 4 destination points
M double* Output 3×3 matrix, row-major, 9 doubles (finally normalized so M[8] = 1)

findHomography

Compute a 3×3 homography from N ≥ 4 point pairs; supports least-squares or RANSAC.

Tier: Pro+
Channels: N/A (point sets)
Inplace: not supported
Types:

Template parameter Allowed types Constraint
T double —

CPP / NEON Signature (identical)

int findHomography(
    const double* srcPts, const double* dstPts,
    int numPts, double* H,
    int method = 0,
    double ransacThreshold = 3.0);
Parameter Type Meaning Default
srcPts const double* N source points (x0,y0, x1,y1, …), 2*N doubles total non-null
dstPts const double* N destination points non-null
numPts int Number of point pairs, must be ≥ 4 —
H double* Output 3×3 homography, row-major, normalized H[8] = 1 non-null
method int 0 = least-squares DLT; 1 = RANSAC 0
ransacThreshold double RANSAC inlier distance threshold 3.0

When numPts == 4, getPerspectiveTransform is used automatically (exact solution).

dltHomography

Low-level / algorithm-customization API. Most users should call findHomography; use this only if you need direct access to the linear DLT solver and will handle outlier rejection yourself.

Solve a 3×3 homography from numPts ≥ 4 point pairs using a single normalized Direct Linear Transform (DLT) least-squares pass — no RANSAC, no robust filtering.

Tier: Pro+
Channels: N/A (point sets)
Inplace: not supported

CPP Signature (acl::transform only)

This helper is not declared under acl::neon::transform; NEON packages expose findHomography, getPerspectiveTransform, warpAffine, and warpPerspective, but not the DLT helper.

int dltHomography(
    const double* srcPts, const double* dstPts,
    int numPts, double* H);
Parameter Type Meaning
srcPts const double* N source points (x0,y0, x1,y1, …), 2*N doubles
dstPts const double* N destination points, same layout
numPts int Number of point pairs, must be ≥ 4
H double* Output 3×3 homography, row-major, normalized H[8] = 1

Returns: 0 on success, non-zero on failure (degenerate point configuration, numPts < 4).

homographyError

Low-level / algorithm-customization API. Mostly useful when implementing custom outlier rejection or scoring loops on top of dltHomography.

Project a single point through a homography and return the squared Euclidean distance to its observed correspondence — i.e. the per-correspondence reprojection error used inside RANSAC scoring.

Tier: Pro+
Channels: N/A (scalar math)
Inplace: N/A

CPP Signature (acl::transform only)

This helper is not declared under acl::neon::transform; call acl::transform::homographyError from paid packages.

double homographyError(
    const double* H,
    double sx, double sy,
    double dx, double dy);
Parameter Type Meaning
H const double* Row-major 3×3 homography
sx, sy double Source point coordinates
dx, dy double Observed destination point coordinates

Returns: Squared Euclidean distance between H · (sx, sy, 1) (normalized to z=1) and (dx, dy).

warpAffine

Apply a 2×3 affine transform to an image. Uses inverse mapping: destination pixel (x', y') looks up source coordinates (x, y) = M * (x', y', 1)^T.

Tier: Starter+
Channels: 1ch / 3ch / 4ch (via runtime cn parameter)
Inplace: not supported
Types:

Template parameter Allowed types Constraint
IMG_T {uint8_t, uint16_t, float} —
MAT_T {float, double} —

CPP / NEON Signature (identical)

template<class IMG_T, class MAT_T = double>
int warpAffine(
    const IMG_T* srcImage, IMG_T* dstImage,
    const MAT_T* M,
    int srcWidth, int srcHeight,
    int dstWidth, int dstHeight,
    int srcStride = 0, int dstStride = 0,
    acl::InterpMode interpMode = acl::InterpMode::LINEAR2D,
    int cn = 1);
Parameter Type Meaning Default
srcImage, dstImage const IMG_T* / IMG_T* input / output non-null
M const MAT_T* 2×3 affine matrix, row-major non-null
srcWidth, srcHeight int Source image size > 0
dstWidth, dstHeight int Destination image size > 0
srcStride, dstStride int Bytes per row 0 = auto
interpMode acl::InterpMode NEAREST / LINEAR2D LINEAR2D
cn int Channel count (1 / 3 / 4) 1

warpPerspective

Apply a 3×3 perspective transform to an image. Inverse mapping; homogeneous coordinates are divided by w.

Tier: Starter+
Channels: 1ch / 3ch / 4ch (via runtime cn parameter)
Inplace: not supported
Types:

Template parameter Allowed types Constraint
IMG_T {uint8_t, uint16_t, float} —
MAT_T {float, double} —

CPP / NEON Signature (identical)

template<class IMG_T, class MAT_T = double>
int warpPerspective(
    const IMG_T* srcImage, IMG_T* dstImage,
    const MAT_T* M,
    int srcWidth, int srcHeight,
    int dstWidth, int dstHeight,
    int srcStride = 0, int dstStride = 0,
    acl::InterpMode interpMode = acl::InterpMode::LINEAR2D,
    int cn = 1);

Runtime parameters are the same as warpAffine; M is a 3×3 matrix (9 MAT_T).

Example (warpAffine + warpPerspective chain)

uint8_t srcImage[1920*1080], dstImage[1920*1080];

// 1) Build a 30° rotation matrix around the image center
double M_affine[6];
acl::transform::getRotationMatrix2D(960.0, 540.0, 30.0, 1.0, M_affine);

// 2) Apply affine (NEON-accelerated, LINEAR2D)
acl::neon::transform::warpAffine<uint8_t, double>(
    srcImage, dstImage, M_affine, 1920, 1080, 1920, 1080,
    0, 0, acl::InterpMode::LINEAR2D, 1);

// 3) 4-point perspective matrix
double srcPts[8] = { 0,0,  1920,0,  1920,1080,  0,1080 };
double dstPts[8] = { 100,50,  1820,0,  1920,1080,  50,1050 };
double H[9];
acl::transform::getPerspectiveTransform(srcPts, dstPts, H);
acl::neon::transform::warpPerspective<uint8_t, double>(
    srcImage, dstImage, H, 1920, 1080, 1920, 1080,
    0, 0, acl::InterpMode::LINEAR2D, 1);

remap

Generic pixel remap: dst(x, y) = src(mapX(x, y), mapY(x, y)). Can be used to implement fisheye correction, arbitrary distortion correction, etc.

Tier: Starter+
Channels: 1ch / 3ch / 4ch (via runtime cn parameter)
Inplace: not supported
Types:

Template parameter Allowed types Constraint
IMG_T {uint8_t, uint16_t, float} —
MAP_T {float, double} —

CPP Signature

template<class IMG_T, class MAP_T>
int remap(
    const IMG_T* srcImage, IMG_T* dstImage,
    const MAP_T* mapX, const MAP_T* mapY,
    int srcWidth, int srcHeight,
    int dstWidth, int dstHeight,
    int srcStride = 0, int dstStride = 0,
    int mapStride = 0,
    acl::InterpMode interpMode = acl::InterpMode::LINEAR2D,
    int cn = 1);
Parameter Type Meaning Default
mapX, mapY const MAP_T* Source coordinate map, size dstWidth × dstHeight (one (x, y) pair per pixel) non-null
mapStride int Map bytes per row (shared by mapX and mapY) 0 = auto
interpMode acl::InterpMode Interpolation mode LINEAR2D
cn int Channel count 1

yuvRemap

Remap an NV21 / NV12 image directly while preserving the Y / UV plane structure (equivalent to remap followed by restoration of the YUV sampling relationship).

Tier: Business
Channels: NV21 / NV12 (Y plane + interleaved UV plane)
Inplace: not supported
Types:

Template parameter Allowed types Constraint
IMG_T uint8_t —
MAP_T {float, double} —

CPP Signature

template<class IMG_T, class MAP_T>
int yuvRemap(
    const IMG_T* srcYImage, const IMG_T* srcUVImage,
    IMG_T* dstYImage, IMG_T* dstUVImage,
    const MAP_T* mapX, const MAP_T* mapY,
    int srcWidth, int srcHeight,
    int dstWidth, int dstHeight,
    int srcStride = 0, int dstStride = 0, int mapStride = 0,
    acl::InterpMode interpMode = acl::InterpMode::LINEAR2D);
Parameter Type Meaning
srcYImage, srcUVImage const IMG_T* Source NV21 / NV12 planes
dstYImage, dstUVImage IMG_T* Destination NV21 / NV12 planes
mapX, mapY const MAP_T* Source coordinate map based on the Y plane size (UV is automatically sampled at half resolution)

Navigation

Clone this wiki locally