API‐Reference

ACL Pack API Reference

Version: 1.0.3
Platform: Android arm64-v8a · Linux aarch64
Language: C++17
Delivery: Static library (libacl.a) + Headers

← Back to Home

Table of Contents

1. Operator Catalog
2. Getting Started
3. Error Codes
4. Type Definitions
5. Analysis
6. Arithmetic
7. Color Conversion
8. Filter
9. Geometric
10. Feature Detection
11. Transform
12. Math
13. Drawing
14. Contour Analysis
15. Utilities

---

Operator Catalog

One-page panorama of every operator ACL Pack ships, grouped by category. Tier suffix tells you which license unlocks the call:

• No suffix — Starter tier
• [Pro] — requires Pro or Business license
• [Business] — requires Business license

Per-operator signatures and supported types live in the category sections below.

Category	Operators
Filter	GaussianBlur, BoxFilter, Filter2D, SepFilter2D, Sobel, Scharr, Laplacian, Canny, MedianFilter, BilateralFilter [Pro], NLMeansDenoising [Pro], GuidedFilter [Pro], UnsharpMask [Pro], StackBlur, GaborFilter [Pro], Erode / Dilate, EdgePreservingFilter [Business], MergeMertens [Business], Tonemap [Business]
Color	RGB2Gray, BGR↔RGB / BGRA / RGBA (10 channel-swap variants), RGB↔HSV [Pro], RGB↔Lab [Pro], RGB↔YUV (NV21 / YV12 / YUV444, BT601 / 709 / 2020), Bayer demosaic, GammaTransform
Geometric	Resize (NEAREST / LINEAR2D / AREA_AVG / CUBIC4x4), Rotate (0 / 180 / CW90 / CCW90 / FLIP_V / FLIP_H / XPOSE), PyrDown / PyrUp / buildPyramid, NEON resizeYUV / rotateYUV
Arithmetic	AddImg, AbsDiff, AddWeighted, AlphaImgFusion, Multiply, Threshold, AdaptiveThreshold [Pro], Bitwise AND / NOT / XOR, LUT, ConvertScaleAbs, InRange, Normalize, Phase [Pro], Magnitude [Pro], LinearTransform2x2 [Business]
Analysis	Integral, Histogram, BlockAverage, EqualizeHist, CopyMakeBorder, CLAHE [Pro], HistMatch [Pro], MinMaxLoc, Mean, Count, MatchTemplate [Pro], Moments [Pro], FindContours [Pro], ExtractBlockPixels [Business], DistanceTransform [Business], ConnectedComponentLabeling / connectedComponent_8n_dfs [Business]
Feature	FAST, Harris, Shi-Tomasi (+ Detect variant), ORB (detect + detectAndCompute), HOG, HoughLines / HoughLinesP / HoughCircles, OpticalFlowLK, bfMatch / bfMatchBinary / bfKnnMatch / bfKnnMatchBinary — all [Pro]; SIFT, SURF [Business]
Transform	WarpAffine, WarpPerspective, Remap (CPP only), GetAffineTransform, GetPerspectiveTransform, GetRotationMatrix2D, FindHomography [Pro], yuvRemap [Business]
Math (NEON)	DFT (dft1d / dft2d / dftReal1d / idftReal1d), mulSpectrums, getOptimalDFTSize — all [Pro]
Draw (CPP)	drawLine, drawRect, drawCircle, putText (u8 only)
Contour (CPP)	contourArea, arcLength, boundingRect, convexHull, approxPolyDP, minAreaRect, fitEllipse — all [Pro]

Commercial Tier And Type Policy

The customer-facing tier names are Starter, Pro, and Business. Older labels such as Core, Advanced, and Full are not used by the commercial headers or package metadata.

Tier	Operator availability	Image pixel types admitted by the commercial header
Starter	Starter operators	uint8_t
Pro	Starter + Pro operators	uint8_t, uint16_t
Business	Starter + Pro + Business operators	uint8_t, uint16_t, float

Each operator's Types table describes the implementation-level template support. In commercial packages, the actually callable type set is the intersection of that table and the tier type policy above. Unsupported combinations are rejected by the delivered <acl/api.h> at compile time, often through explicitly deleted template specializations. For example, blockAverage<uint16_t> and blockAverage<float> are deleted in Starter; blockAverage<float> is deleted in Pro; Business exposes all three listed pixel types.

The Trial package is separate from the generic acl::* / acl::neon::* API surface. It exposes only two fixed-parameter wrappers under acl::trial: resizeBilinear2xDown_cpp and resizeBilinear2xDown_neon. Trial users should not call the generic namespaces documented for paid tiers.

namespace acl::trial {
int resizeBilinear2xDown_cpp(const uint8_t* srcImage, uint8_t* dstImage);
int resizeBilinear2xDown_neon(const uint8_t* srcImage, uint8_t* dstImage);
}

These Trial wrappers use the fixed Trial input size 1920x1280; the 2x downscale wrapper writes 960x640.

Getting Started

Initialization

#include <acl/acl.h>

// Initialize with license file
int result = acl::init("/path/to/license.dat");

// Check the result
if (result == 0) {
    // Success — all operators available
} else {
    // Failure — see error codes below
}

// Get library version
const char* ver = acl::version();  // "1.0.3"

License Initialization

namespace acl {
    int init(const char* licensePath, JNIEnv* env = nullptr, jobject context = nullptr);
    const char* version();   // returns "1.0.3"
}

Parameter	Type	Description
licensePath	const char*	Absolute path to license.dat on the device
env	JNIEnv*	JNI environment, optional. Reserved in the ABI for future use; the current implementation does not read it. Pass nullptr for pure native calls
context	jobject	Android Context, same as env

init() reads the license file and verifies its integrity and tier. Within the scope of your purchase agreement, the version you received continues to work. Call it once at process start before invoking any operator; calling it again later in the same process returns the same status without re-reading the file.

Return values:

• 0 — success
• -1001 — License invalid (file missing, signature corrupted, tampered with, or init() not called)
• -1005 — Tier mismatch: license.tier does not match the compiled library tier (at init stage), or the operator is not in the current tier (at runtime)
• -1006 — Resolution does not match the Trial fixed size (1920×1280)

Architecture

ACL Pack provides two parallel implementations:

• acl::{module}::* — Portable C++ scalar implementation. Many operators are templated for the standard image pixel types (uint8_t / uint16_t / float; see each operator's description for exact combinations). All scalar operators sit directly under acl::{module}:: (no cpp segment). All declarations ship in a single header — <acl/api.h>.
• acl::neon::{module}::* — ARM NEON hand-vectorized implementation. Most operators target uint8_t first; uint16_t and float support is operator-dependent and may use scalar fallback. Typical speedup is 2-25× over the scalar layer, peaking at 50×+.

The two API signatures are almost identical. On Android arm64-v8a the neon:: version is recommended; if a given entry point is only provided in scalar (the docs will note this explicitly), use the corresponding acl::{module}:: entry point.

short / int16_t, int, int64_t, and double are supported in specific auxiliary roles such as gradient outputs, labels, integral accumulators, transform matrices, moments, and parameters. They are not general image pixel input types. <acl/typeDef.h> defines shared public structs/enums; it is not a guarantee that every enum value or datatype is implemented by every operator.

Conventions

• Image data is passed as raw pointers (const T* input, T* output)
• stride is in bytes (not pixels). When 0 is passed it is auto-computed as width × channels × sizeof(T) (requires contiguous memory)
• cn is the channel count (1 = grayscale, 3 = RGB, 4 = RGBA)
• Returns 0 (ACL_OK) on success; negative values are error codes
• Memory is allocated and freed by the caller; the library has zero implicit allocation
• Most operators do not support inplace (src == dst) and require a separately allocated output buffer; the few that support inplace are noted at the operator
• Operator calls require acl::init() to have returned 0; otherwise they return -1001 without performing any computation

Error Codes

#include <acl/err.h>

Code	Macro	Description
0	ACL_OK	Operation completed successfully
-1	ACL_ERR_GENERIC	Unclassified failure
-2	ACL_ERR_INVAL	Invalid parameter (null ptr, zero size, out-of-range enum)
-3	ACL_ERR_NOMEM	Out of memory / allocation failed
-4	ACL_ERR_NOSUP	Unsupported type / parameter combination
-5	ACL_ERR_IO	File / port open or I/O failure
-1001	ACL_ERR_LICENSE_INVALID	License file missing, corrupt, tampered with, or acl::init() has not yet succeeded
-1005	ACL_ERR_NOT_LICENSED	Tier mismatch: license.tier does not match the compiled library tier (detected by acl::init), or the requested operator is not available in the current tier (detected at call site)
-1006	ACL_ERR_RESOLUTION_LIMIT	Resolution does not match the Trial fixed size (1920×1280)

-1002, -1003, and -1004 are reserved in the ABI but never returned at runtime. All macros are defined in <acl/err.h>. See License Guide for detail on how -1001 / -1005 are raised from the license layer.

Type Definitions

#include <acl/typeDef.h>

Enums

RotateOrient

enum class RotateOrient {
    ROT_0,      // No rotation (copy)
    ROT_180,    // 180-degree rotation
    ROT_CW_90,  // Clockwise 90 degrees
    ROT_CCW_90, // Counter-clockwise 90 degrees
    FLIP_V,     // Vertical mirror (flip top-bottom)
    FLIP_H,     // Horizontal mirror (flip left-right)
    XPOSE       // Matrix transpose
};

InterpMode

enum class InterpMode {
    NEAREST,    // Nearest neighbor
    LINEAR2D,   // Bilinear interpolation
    AREA_AVG,   // Area-average (for downscaling)
    CUBIC4x4    // Bicubic (4x4 neighborhood)
};

BorderType

Border handling modes — how to fill out-of-bounds pixels when the kernel extends past the image. Example sequence abcdefgh (input):

enum class BorderType {
    BORDER_CONSTANT,    // 'iiiiii|abcdefgh|iiiiii' — fill with the constant parameter
    BORDER_REPLICATE,   // 'aaaaaa|abcdefgh|hhhhhh' — replicate edge pixels
    BORDER_REFLECT,     // 'fedcba|abcdefgh|hgfedc' — reflection including the edge pixel
    BORDER_WRAP,        // 'cdefgh|abcdefgh|abcdef' — wrap-around
    BORDER_REFLECT_101, // 'gfedcb|abcdefgh|gfedcb' — reflection excluding the edge pixel
    BORDER_DEFAULT = BORDER_REFLECT_101
};

BayerPattern

enum class BayerPattern { RGGB, GRBG, GBRG, BGGR };

ColorCvtGrayMode

enum class ColorCvtGrayMode {
    GRAY_LUMA,     // BT.601 luma (0.299R + 0.587G + 0.114B)
    GRAY_MAX,      // Per-pixel max of R, G, B
    GRAY_MIN,      // Per-pixel min of R, G, B
    GRAY_AVG,      // Simple average (R + G + B) / 3
    GRAY_WEIGHTED  // User-supplied weights (cR * R + cG * G + cB * B)
};

ThreshMode

enum class ThreshMode {
    THRESH_BINARY,     // dst = (src > thresh) ? maxVal : 0
    THRESH_BINARY_INV, // dst = (src > thresh) ? 0 : maxVal
    THRESH_TRUNC,      // dst = (src > thresh) ? thresh : src
    THRESH_TOZERO,     // dst = (src > thresh) ? src : 0
    THRESH_TOZERO_INV, // dst = (src > thresh) ? 0 : src
    THRESH_OTSU        // Automatic threshold (Otsu's method)
};

YUVEncodeStandard

enum class YUVEncodeStandard {
    STD_BT601,    // ITU-R BT.601 (SDTV)
    STD_BT709,    // ITU-R BT.709 (HDTV)
    STD_BT2020,   // ITU-R BT.2020 (UHDTV)
    STD_CUSTOM    // Caller-supplied 3x3 conversion matrix
};

NormType

enum class NormType { NORM_INF, NORM_L1, NORM_L2, NORM_MINMAX };

AdaptiveThreshMethod

enum class AdaptiveThreshMethod {
    ADAPTIVE_THRESH_MEAN_C,     // Mean within block
    ADAPTIVE_THRESH_GAUSSIAN_C  // Gaussian-weighted mean within block
};

MorphOp

enum class MorphOp {
    ERODE,   // Erosion (take minimum over kernel coverage)
    DILATE   // Dilation (take maximum over kernel coverage)
};

ValueRange

Used to specify the output value range (e.g. by normalize):

enum class ValueRange {
    STD_NEG1_TO_POS1,    // Result falls in [-1, 1]
    UNIT_INTERVAL,       // Result falls in [0, 1]
    NATIVE_FULL_SCALE    // Result falls in the full positive range of the output type (e.g. u8 → [0, 255])
};

TemplateMatchMethod

enum class TemplateMatchMethod {
    TM_SQDIFF, TM_SQDIFF_NORMED,
    TM_CCORR,  TM_CCORR_NORMED,
    TM_CCOEFF, TM_CCOEFF_NORMED
};

DftFlags

enum DftFlags { DFT_FORWARD = 0, DFT_INVERSE = 1, DFT_SCALE = 2 };

Data Structures (Geometry / Hough / Features / Color / Contour)

These structs are passed to operators as parameter bundles or returned as result containers. Grouped by purpose:

• Geometry primitives — Point2f, Point2i, Size2f, RotatedRect (used by minAreaRect / fitEllipse / findContours)
• Hough results — Vec2f, Vec3f, Vec4i (output formats for houghLines / houghCircles / houghLinesP)
• Features & Matching — KeyPoint, KeyPointORB, KeyPointExt, DMatch, HOGParams (Harris / FAST / ORB / SIFT / SURF / HOG / bfMatch / bfKnnMatch)
• Color conversion — YUVConvertParams (a single bundle that drives every rgb2YUV / yuv2RGB operator)
• Contour & Moments — HierarchyEntry, Moments (output of findContours / moments)

Common top-level acl:: namespace (<acl/typeDef.h>):

namespace acl {
    // 2D floating-point point (e.g. RotatedRect center)
    struct Point2f {
        float x, y;
        Point2f();
        Point2f(float x, float y);
    };

    // 2D floating-point size (e.g. RotatedRect size)
    struct Size2f {
        float width, height;
        Size2f();
        Size2f(float w, float h);
    };

    // Rotated rectangle — used by minAreaRect / fitEllipse
    struct RotatedRect {
        Point2f center;
        Size2f  size;       // Note: the order of width/height is determined by minAreaRect; the reader should not assume a size ordering
        float   angle;      // Rotation angle (degrees)
        RotatedRect();
        RotatedRect(Point2f c, Size2f s, float a);
    };

    // Descriptor match result — used by bfMatch / bfKnnMatch
    struct DMatch {
        int   queryIdx;     // Query descriptor index (default -1)
        int   trainIdx;     // Train descriptor index (default -1)
        float distance;     // Descriptor distance
        DMatch();
        DMatch(int q, int t, float d);
        bool operator<(const DMatch&) const;   // Sorted by distance
    };

    // Small vector types — used by houghLines / houghCircles / houghLinesP
    struct Vec2f { float val[2]; };   // (rho, theta) — houghLines
    struct Vec3f { float val[3]; };   // (cx, cy, radius) — houghCircles
    struct Vec4i { int   val[4]; };   // (x1, y1, x2, y2) — houghLinesP line segment

    // YUV ↔ RGB conversion parameter bundle — used by every rgb2YUV / yuv2RGB operator
    struct YUVConvertParams {
        YUVEncodeStandard yuv_std        = YUVEncodeStandard::STD_BT601;
        bool              yuv444_fmt     = true;   // true = 4:4:4 packed, false = 4:4:4 planar (only for the 4:4:4 ops)
        bool              nv21_fmt       = true;   // true = NV21 (V before U), false = NV12 (U before V) (only for the NV-series ops)
        bool              rgb_fmt        = true;   // true = RGB, false = BGR
        int               bit_depth      = 0;      // 0 = auto-detect from the pixel type (u8 = 8, u16 = 16)
        int               shift_right    = 0;      // optional output bit-shift (used by 16-bit pipelines)
        int               shift_left     = 0;      // optional input bit-shift (used by 16-bit pipelines)
        bool              yuv_full_range = true;   // true = full range (0–255), false = limited range (16–235)
        bool              rgb_full_range = true;   // true = full range, false = limited range
    };
}

The defaults match the common BT.601 8-bit full-range RGB pipeline. Pass an empty {} to take all defaults, or override only the fields that differ from your pipeline. See the Color Conversion section for examples.

All public structs and enums live in the single top-level acl:: namespace (no sub-namespaces):

namespace acl {
    // ── Geometry ────────────────────────────────────────────
    struct Point2i { int x, y; };

    // ── Contour / Moments ───────────────────────────────────
    struct HierarchyEntry { int next, prev, first_child, parent; };   // default -1
    struct Moments { double m00, m10, m01, m20, m11, m02, m30, m21, m12, m03; };
    enum DistanceType { DIST_L1 = 1, DIST_L2 = 2, DIST_LINF = 3 };
    enum ContourRetrMode {
        CONTOUR_RETR_EXTERNAL = 0,
        CONTOUR_RETR_LIST     = 1,
        CONTOUR_RETR_CCOMP    = 2,
        CONTOUR_RETR_TREE     = 3
    };
    enum ContourApproxMethod {
        CONTOUR_CHAIN_APPROX_NONE   = 1,
        CONTOUR_CHAIN_APPROX_SIMPLE = 2
    };

    // ── Features ────────────────────────────────────────────
    struct KeyPoint { int x, y; float response; };
    struct KeyPointORB { float x, y, response, scale, angle; uint8_t descriptor[32]; };
    struct KeyPointExt { float x, y, response, scale, angle; float descriptor[128]; };
    struct HOGParams {
        int cellSize, blockSize, nbins, blockStride;
        // Defaults: cellSize=8, blockSize=2, nbins=9, blockStride=1
    };

    // ── Filter mode tags ────────────────────────────────────
    enum EdgePreservingType {
        EDGE_PRESERVING_RECURSIVE = 1,  // Fast
        EDGE_PRESERVING_NORMCONV  = 2   // High quality
    };
}