tessl/maven-org-bytedeco--leptonica-platform
JavaCPP bindings for Leptonica image processing library with cross-platform support
—
Pending
image-processing.mddocs/
Image Processing
Core image processing operations including scaling, rotation, color space conversion, filtering, and enhancement techniques for comprehensive image manipulation.
Capabilities
Scaling and Geometric Transformations
Scale, rotate, and transform images with various interpolation methods and boundary handling options.
/**
* Scale image by specified factors
* @param pixs - Source image
* @param scalex - Horizontal scaling factor
* @param scaley - Vertical scaling factor
* @return Scaled PIX or null on failure
*/
PIX pixScale(PIX pixs, float scalex, float scaley);
/**
* Scale to specific dimensions
* @param pixs - Source image
* @param wd - Target width
* @param hd - Target height
* @return Scaled PIX or null on failure
*/
PIX pixScaleToSize(PIX pixs, int wd, int hd);
/**
* Scale with area mapping (high quality)
* @param pixs - Source image
* @param scalex - Horizontal scaling factor
* @param scaley - Vertical scaling factor
* @return Scaled PIX or null on failure
*/
PIX pixScaleAreaMap(PIX pixs, float scalex, float scaley);
/**
* Rotate image by specified angle
* @param pixs - Source image
* @param angle - Rotation angle in radians
* @param type - Rotation type (L_ROTATE_* constants)
* @param incolor - Fill color for background
* @param width - Output width (0 for auto)
* @param height - Output height (0 for auto)
* @return Rotated PIX or null on failure
*/
PIX pixRotate(PIX pixs, float angle, int type, int incolor, int width, int height);
/**
* Rotate by specific angles (optimized)
* @param pixs - Source image
* @param quads - Number of 90-degree rotations (1, 2, or 3)
* @return Rotated PIX or null on failure
*/
PIX pixRotateOrth(PIX pixs, int quads);
/**
* Affine transformation
* @param pixs - Source image
* @param vc - 6-element transformation matrix
* @param incolor - Fill color for background
* @return Transformed PIX or null on failure
*/
PIX pixAffine(PIX pixs, FloatPointer vc, int incolor);
/**
* Projective transformation
* @param pixs - Source image
* @param vc - 8-element transformation matrix
* @param incolor - Fill color for background
* @return Transformed PIX or null on failure
*/
PIX pixProjective(PIX pixs, FloatPointer vc, int incolor);Usage Examples:
import org.bytedeco.leptonica.*;
import static org.bytedeco.leptonica.global.leptonica.*;
// Scale image to half size
PIX scaled = pixScale(sourcePix, 0.5f, 0.5f);
// Scale to specific dimensions (thumbnail)
PIX thumbnail = pixScaleToSize(sourcePix, 200, 150);
// High-quality scaling using area mapping
PIX highQuality = pixScaleAreaMap(sourcePix, 2.0f, 2.0f);
// Rotate 45 degrees
PIX rotated = pixRotate(sourcePix, (float)(Math.PI / 4), L_ROTATE_AREA_MAP,
L_BRING_IN_WHITE, 0, 0);
// Rotate 90 degrees (optimized)
PIX rotated90 = pixRotateOrth(sourcePix, 1);
// Affine transformation (shear)
float[] matrix = {1.0f, 0.2f, 0.0f, 1.0f, 0.0f, 0.0f};
FloatPointer affine = new FloatPointer(matrix);
PIX sheared = pixAffine(sourcePix, affine, L_BRING_IN_WHITE);Color Space Conversion
Convert between different color spaces and bit depths with various algorithms and options.
/**
* Convert RGB to grayscale with weighted averaging
* @param pixs - Source RGB image
* @param rwt - Red weight (typically 0.3)
* @param gwt - Green weight (typically 0.6)
* @param bwt - Blue weight (typically 0.1)
* @return Grayscale PIX or null on failure
*/
PIX pixConvertRGBToGray(PIX pixs, float rwt, float gwt, float bwt);
/**
* Convert grayscale to RGB
* @param pixs - Source grayscale image
* @return RGB PIX or null on failure
*/
PIX pixConvertGrayToColormap(PIX pixs);
/**
* Convert to 8-bit depth
* @param pixs - Source image
* @param cmapflag - 1 to use colormap, 0 for direct conversion
* @return 8-bit PIX or null on failure
*/
PIX pixConvertTo8(PIX pixs, int cmapflag);
/**
* Convert to 32-bit RGB
* @param pixs - Source image
* @return 32-bit RGB PIX or null on failure
*/
PIX pixConvertTo32(PIX pixs);
/**
* Remove alpha channel from RGBA image
* @param pixs - Source RGBA image
* @return RGB PIX or null on failure
*/
PIX pixRemoveAlpha(PIX pixs);
/**
* Add alpha channel to RGB image
* @param pixs - Source RGB image
* @param fract - Alpha value as fraction (0.0-1.0)
* @param delta - Alpha variation
* @return RGBA PIX or null on failure
*/
PIX pixAddAlphaToBlend(PIX pixs, float fract, int delta);
/**
* Convert RGB to HSV color space
* @param pixd - Destination (can be null)
* @param pixs - Source RGB image
* @return HSV PIX or null on failure
*/
PIX pixConvertRGBToHSV(PIX pixd, PIX pixs);
/**
* Convert HSV to RGB color space
* @param pixd - Destination (can be null)
* @param pixs - Source HSV image
* @return RGB PIX or null on failure
*/
PIX pixConvertHSVToRGB(PIX pixd, PIX pixs);Usage Examples:
// Convert RGB to grayscale with standard weights
PIX gray = pixConvertRGBToGray(rgbPix, 0.299f, 0.587f, 0.114f);
// Convert to 8-bit with colormap optimization
PIX eightBit = pixConvertTo8(sourcePix, 1);
// Convert any format to 32-bit RGB
PIX rgb32 = pixConvertTo32(sourcePix);
// Remove alpha channel
PIX rgb = pixRemoveAlpha(rgbaPix);
// Add semi-transparent alpha
PIX rgba = pixAddAlphaToBlend(rgbPix, 0.8f, 0);
// HSV conversion for color manipulation
PIX hsv = pixConvertRGBToHSV(null, rgbPix);
// ... modify HSV values ...
PIX modifiedRgb = pixConvertHSVToRGB(null, hsv);Filtering and Enhancement
Apply various filters and enhancement operations to improve image quality and extract features.
/**
* Gaussian blur filter
* @param pixs - Source image
* @param sigmax - Horizontal standard deviation
* @param sigmay - Vertical standard deviation
* @return Blurred PIX or null on failure
*/
PIX pixGaussianBlur(PIX pixs, float sigmax, float sigmay);
/**
* Unsharp masking for image sharpening
* @param pixs - Source image
* @param halfwidth - Mask half-width
* @param fract - Unsharp fraction
* @return Sharpened PIX or null on failure
*/
PIX pixUnsharpMasking(PIX pixs, int halfwidth, float fract);
/**
* Median filter for noise reduction
* @param pixs - Source image
* @param halfwidth - Filter half-width
* @param halfheight - Filter half-height
* @return Filtered PIX or null on failure
*/
PIX pixMedianFilter(PIX pixs, int halfwidth, int halfheight);
/**
* Rank filter (generalized median)
* @param pixs - Source image
* @param halfwidth - Filter half-width
* @param halfheight - Filter half-height
* @param rank - Rank value (0.0-1.0, 0.5 = median)
* @return Filtered PIX or null on failure
*/
PIX pixRankFilter(PIX pixs, int halfwidth, int halfheight, float rank);
/**
* Edge detection using Sobel operator
* @param pixs - Source grayscale image
* @return Edge map PIX or null on failure
*/
PIX pixSobelEdgeFilter(PIX pixs, int orientflag);
/**
* Convolution with custom kernel
* @param pixs - Source image
* @param kel - Convolution kernel
* @param outdepth - Output depth (8, 16, or 32)
* @param normflag - 1 to normalize, 0 otherwise
* @return Convolved PIX or null on failure
*/
PIX pixConvolve(PIX pixs, L_KERNEL kel, int outdepth, int normflag);
/**
* Bilateral filter for noise reduction with edge preservation
* @param pixs - Source image
* @param spatial_stdev - Spatial standard deviation
* @param range_stdev - Range standard deviation
* @param ncomps - Number of components
* @param reduction - Size reduction factor
* @return Filtered PIX or null on failure
*/
PIX pixBilateralFilter(PIX pixs, float spatial_stdev, float range_stdev, int ncomps, int reduction);Usage Examples:
// Apply Gaussian blur
PIX blurred = pixGaussianBlur(sourcePix, 2.0f, 2.0f);
// Sharpen image with unsharp masking
PIX sharpened = pixUnsharpMasking(sourcePix, 3, 0.3f);
// Remove noise with median filter
PIX denoised = pixMedianFilter(sourcePix, 1, 1);
// Edge detection
PIX edges = pixSobelEdgeFilter(grayPix, L_ALL_EDGES);
// Bilateral filter for advanced noise reduction
PIX filtered = pixBilateralFilter(sourcePix, 10.0f, 20.0f, 1, 1);
// Custom convolution with edge detection kernel
L_KERNEL kernel = kernelCreateFromString(3, 3, 1, 1, "-1 -1 -1; -1 8 -1; -1 -1 -1", 1.0f, "edge");
PIX convolved = pixConvolve(sourcePix, kernel, 8, 1);Thresholding and Binarization
Convert grayscale images to binary with various thresholding methods and adaptive algorithms.
/**
* Threshold to binary using fixed value
* @param pixs - Source grayscale image
* @param thresh - Threshold value (0-255)
* @return Binary PIX or null on failure
*/
PIX pixThresholdToBinary(PIX pixs, int thresh);
/**
* Otsu's automatic threshold selection
* @param pixs - Source grayscale image
* @param sx - Tile width for local adaptation
* @param sy - Tile height for local adaptation
* @param smoothx - Smoothing in x direction
* @param smoothy - Smoothing in y direction
* @param scorefract - Score fraction for validation
* @param pthresh - Returns computed threshold
* @return Binary PIX or null on failure
*/
PIX pixOtsuAdaptiveThreshold(PIX pixs, int sx, int sy, int smoothx, int smoothy,
float scorefract, IntPointer pthresh);
/**
* Sauvola's local adaptive thresholding
* @param pixs - Source grayscale image
* @param whsize - Window half-size
* @param factor - Sauvola factor (typically 0.35)
* @param addborder - 1 to add border, 0 otherwise
* @return Binary PIX or null on failure
*/
PIX pixSauvolaOnContrastNorm(PIX pixs, int whsize, float factor, int addborder);
/**
* Threshold with hysteresis (dual threshold)
* @param pixs - Source grayscale image
* @param lowthresh - Low threshold value
* @param highthresh - High threshold value
* @return Binary PIX or null on failure
*/
PIX pixThresholdWithHysteresis(PIX pixs, int lowthresh, int highthresh);Usage Examples:
// Simple fixed threshold
PIX binary = pixThresholdToBinary(grayPix, 128);
// Otsu's adaptive threshold
IntPointer threshold = new IntPointer(1);
PIX otsuBinary = pixOtsuAdaptiveThreshold(grayPix, 32, 32, 0, 0, 0.1f, threshold);
System.out.println("Otsu threshold: " + threshold.get());
// Sauvola's local adaptive threshold for documents
PIX sauvolaBinary = pixSauvolaOnContrastNorm(grayPix, 25, 0.35f, 1);
// Hysteresis thresholding for edge maps
PIX hysteresis = pixThresholdWithHysteresis(edgeMap, 50, 100);Histogram Operations
Analyze and manipulate image histograms for exposure correction and analysis.
/**
* Compute image histogram
* @param pixs - Source image
* @param factor - Sampling factor (1 = all pixels)
* @return NUMA array containing histogram or null on failure
*/
NUMA pixGetGrayHistogram(PIX pixs, int factor);
/**
* Histogram equalization
* @param pixd - Destination (can be null)
* @param pixs - Source grayscale image
* @return Equalized PIX or null on failure
*/
PIX pixEqualizeHistogram(PIX pixd, PIX pixs);
/**
* Histogram specification (matching)
* @param pixs - Source image
* @param nahisto - Target histogram as NUMA
* @return Matched PIX or null on failure
*/
PIX pixHistogramSpecification(PIX pixs, NUMA nahisto);
/**
* Linear transform: out = gain * in + offset
* @param pixd - Destination (can be null)
* @param pixs - Source image
* @param gain - Multiplicative factor
* @param offset - Additive offset
* @return Transformed PIX or null on failure
*/
PIX pixLinearTransform(PIX pixd, PIX pixs, float gain, float offset);Usage Examples:
// Get histogram for analysis
NUMA histogram = pixGetGrayHistogram(grayPix, 1);
int[] histArray = numaGetIArray(histogram);
// Histogram equalization for contrast enhancement
PIX equalized = pixEqualizeHistogram(null, grayPix);
// Brightness/contrast adjustment
PIX adjusted = pixLinearTransform(null, grayPix, 1.2f, 10.0f); // +20% contrast, +10 brightnessConvolution and Advanced Filtering
High-performance convolution operations using custom kernels for edge detection, blurring, sharpening, and feature extraction.
/**
* Convolution kernel for image filtering operations
*/
class L_KERNEL extends Pointer {
int sy(); // kernel height
int sx(); // kernel width
int cy(); // y location of kernel origin
int cx(); // x location of kernel origin
FloatPointer data(int i); // kernel data access
// Manual cleanup
void destroy();
}
// Kernel creation functions
L_KERNEL kernelCreate(int height, int width, int cy, int cx);
L_KERNEL kernelCreateFromString(int h, int w, int cy, int cx, String kdata);
L_KERNEL kernelCreateFromFile(String filename);
// Convolution operations
PIX pixConvolve(PIX pixs, L_KERNEL kel, int outdepth, int normflag);
PIX pixConvolveSep(PIX pixs, L_KERNEL kelx, L_KERNEL kely, int outdepth, int normflag);
PIX pixConvolveRGB(PIX pixs, L_KERNEL kel);
PIX pixConvolveRGBSep(PIX pixs, L_KERNEL kelx, L_KERNEL kely);
// Edge detection filters
PIX pixSobelEdgeFilter(PIX pixs, int orientflag);
PIX pixTwoSidedEdgeFilter(PIX pixs, int orientflag);
// Image enhancement
PIX pixUnsharpMasking(PIX pixs, int halfwidth, float fract);Usage Examples:
// Create a Gaussian blur kernel
L_KERNEL gaussKernel = kernelCreateFromString(5, 5, 2, 2,
"1 4 6 4 1 " +
"4 16 24 16 4 " +
"6 24 36 24 6 " +
"4 16 24 16 4 " +
"1 4 6 4 1");
// Apply Gaussian blur
PIX pixBlurred = pixConvolve(pixSource, gaussKernel, 8, L_NORMALIZED);
// Edge detection with Sobel filter
PIX pixEdges = pixSobelEdgeFilter(pixSource, L_ALL_EDGES);
// Unsharp masking for sharpening
PIX pixSharp = pixUnsharpMasking(pixSource, 5, 0.3f);Image Blending and Compositing
Advanced blending operations for combining multiple images with various blend modes and transparency effects.
// Basic blending operations
PIX pixBlend(PIX pixs1, PIX pixs2, int x, int y, float fract);
PIX pixBlendMask(PIX pixd, PIX pixs1, PIX pixs2, int x, int y, float fract, int type);
PIX pixBlendColor(PIX pixd, PIX pixs1, PIX pixs2, int x, int y, float fract, int transparent, int transpix);
PIX pixBlendColorByChannel(PIX pixd, PIX pixs1, PIX pixs2, int x, int y, float rfract, float gfract, float bfract, int transparent, int transpix);
// Advanced blend modes
PIX pixBlendHardLight(PIX pixd, PIX pixs1, PIX pixs2, int x, int y, float fract);
PIX pixBlendWithGrayMask(PIX pixs1, PIX pixs2, PIX pixg, int x, int y);
PIX pixBlendGrayAdapt(PIX pixd, PIX pixs1, PIX pixs2, int x, int y, float fract, int shift);
// Colormap blending
int pixBlendCmap(PIX pixs, PIX pixb, int x, int y, int sindex);Usage Examples:
// Load images for blending
PIX background = pixRead("background.jpg");
PIX overlay = pixRead("overlay.png");
// Simple alpha blending
PIX blended = pixBlend(background, overlay, 100, 50, 0.7f);
// Color blending with transparency (white pixels become transparent)
PIX colorBlend = pixBlendColor(null, background, overlay, 0, 0, 0.5f, 1, 0xffffff);
// Hard light blend mode for dramatic effects
PIX hardLight = pixBlendHardLight(null, background, overlay, 0, 0, 0.8f);Processing Constants
Key constants for image processing operations:
// Rotation types
static final int L_ROTATE_SHEAR = 1;
static final int L_ROTATE_AREA_MAP = 2;
static final int L_ROTATE_SAMPLING = 3;
// Background fill colors
static final int L_BRING_IN_WHITE = 1;
static final int L_BRING_IN_BLACK = 2;
// Edge orientations
static final int L_HORIZONTAL_EDGES = 0;
static final int L_VERTICAL_EDGES = 1;
static final int L_ALL_EDGES = 2;
// Color channels
static final int COLOR_RED = 0;
static final int COLOR_GREEN = 1;
static final int COLOR_BLUE = 2;
static final int L_ALPHA_CHANNEL = 3;Performance Tips
- In-place Operations: Use
pixdparameter when available for memory efficiency - Sampling: Use
factorparameter in histogram functions to sample large images - Bit Depth: Convert to appropriate bit depth before processing (8-bit for most operations)
- Filter Size: Larger filter kernels provide better quality but slower processing
- Gaussian vs Median: Gaussian blur is faster but median filter better preserves edges
Install with Tessl CLI
npx tessl i tessl/maven-org-bytedeco--leptonica-platform