CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-bytedeco--leptonica-platform

JavaCPP bindings for Leptonica image processing library with cross-platform support

—

Pending
Overview
Eval results
Files

image-io.mddocs/

Image I/O Operations

Comprehensive image reading, writing, and format conversion capabilities supporting all major image formats with automatic format detection and cross-platform compatibility.

Capabilities

Image Reading

Read images from files, streams, or memory with automatic format detection and comprehensive format support.

/**
 * Read image from file with automatic format detection
 * @param filename - Path to image file
 * @return PIX image or null on failure
 */
PIX pixRead(String filename);
PIX pixRead(BytePointer filename);

/**
 * Read image from stream with format hint
 * @param fp - Input stream
 * @param hint - Format hint (IFF_* constant or 0 for auto-detect)
 * @return PIX image or null on failure
 */
PIX pixReadStream(InputStream fp, int hint);

/**
 * Read image from memory buffer
 * @param data - Image data buffer
 * @param size - Size of data buffer in bytes
 * @return PIX image or null on failure
 */
PIX pixReadMem(BytePointer data, long size);

/**
 * Read image with color palette preserved
 * @param filename - Path to image file
 * @return PIX image with original colormap or null on failure
 */
PIX pixReadWithHint(String filename, int hint);

/**
 * Read image header information only (no pixel data)
 * @param filename - Path to image file
 * @param pformat - Returns detected format
 * @param pw - Returns image width
 * @param ph - Returns image height
 * @param pbps - Returns bits per sample
 * @param pspp - Returns samples per pixel  
 * @param piscmap - Returns 1 if colormap present
 * @return 0 on success, 1 on failure
 */
int pixReadHeader(String filename, IntPointer pformat, IntPointer pw, IntPointer ph, 
                  IntPointer pbps, IntPointer pspp, IntPointer piscmap);

Usage Examples:

import org.bytedeco.leptonica.*;
import static org.bytedeco.leptonica.global.leptonica.*;

// Read image with automatic format detection
PIX pix = pixRead("image.jpg");
if (pix == null) {
    System.err.println("Failed to read image");
    return;
}

// Read from memory buffer
byte[] imageData = Files.readAllBytes(Paths.get("image.png"));
BytePointer buffer = new BytePointer(imageData);
PIX pixFromMem = pixReadMem(buffer, imageData.length);

// Get image info without loading pixel data
IntPointer format = new IntPointer(1);
IntPointer width = new IntPointer(1);  
IntPointer height = new IntPointer(1);
IntPointer bps = new IntPointer(1);
IntPointer spp = new IntPointer(1);
IntPointer iscmap = new IntPointer(1);

int result = pixReadHeader("image.tiff", format, width, height, bps, spp, iscmap);
if (result == 0) {
    System.out.println("Image: " + width.get() + "x" + height.get() + 
                      ", " + bps.get() + " bps, " + spp.get() + " spp");
}

Image Writing

Write images to files, streams, or memory with format-specific options and quality settings.

/**
 * Write image to file with specified format
 * @param filename - Output file path
 * @param pix - Image to write
 * @param format - Output format (IFF_* constant)
 * @return 0 on success, 1 on failure
 */
int pixWrite(String filename, PIX pix, int format);
int pixWrite(BytePointer filename, PIX pix, int format);

/**
 * Write image to stream
 * @param fp - Output stream
 * @param pix - Image to write
 * @param format - Output format (IFF_* constant)
 * @return 0 on success, 1 on failure
 */
int pixWriteStream(OutputStream fp, PIX pix, int format);

/**
 * Write image to memory buffer
 * @param pix - Image to write
 * @param psize - Returns size of generated data
 * @param format - Output format (IFF_* constant)
 * @return BytePointer to image data or null on failure
 */
BytePointer pixWriteMem(PIX pix, long[] psize, int format);

/**
 * Write image with format-specific parameters
 * @param filename - Output file path
 * @param pix - Image to write  
 * @param format - Output format
 * @param quality - JPEG quality (1-100) or PNG compression (0-9)
 * @return 0 on success, 1 on failure
 */
int pixWriteImpliedFormat(String filename, PIX pix, int quality, int progressive);

Usage Examples:

// Write image in PNG format
int result = pixWrite("output.png", pix, IFF_PNG);
if (result != 0) {
    System.err.println("Failed to write PNG");
}

// Write JPEG with quality setting
result = pixWriteImpliedFormat("output.jpg", pix, 85, 0);

// Write to memory buffer
long[] size = new long[1];
BytePointer buffer = pixWriteMem(pix, size, IFF_PNG);
if (buffer != null) {
    System.out.println("Generated " + size[0] + " bytes of PNG data");
    
    // Save buffer to file or process further
    byte[] imageBytes = new byte[(int)size[0]];
    buffer.get(imageBytes);
    Files.write(Paths.get("output.png"), imageBytes);
}

Format Constants

Supported image format identifiers for reading and writing operations.

// Primary image formats
static final int IFF_UNKNOWN = 0;
static final int IFF_BMP = 1;
static final int IFF_JFIF_JPEG = 2;
static final int IFF_PNG = 3;
static final int IFF_TIFF = 4;
static final int IFF_TIFF_PACKBITS = 5;
static final int IFF_TIFF_RLE = 6;
static final int IFF_TIFF_G3 = 7;
static final int IFF_TIFF_G4 = 8;
static final int IFF_TIFF_LZW = 9;
static final int IFF_TIFF_ZIP = 10;
static final int IFF_PNM = 11;
static final int IFF_PS = 12; 
static final int IFF_GIF = 13;
static final int IFF_JP2 = 14;
static final int IFF_WEBP = 15;
static final int IFF_LPDF = 16;
static final int IFF_DEFAULT = 17;

// TIFF compression formats
static final int IFF_TIFF_JPEG = 18;

// Legacy aliases
static final int IFF_JPEG = IFF_JFIF_JPEG;

Format-Specific Functions

Specialized functions for format-specific operations and advanced I/O control.

// JPEG operations
PIX pixReadJpeg(String filename, int cmflag, int reduction, IntPointer pnwarn, int hint);
int pixWriteJpeg(String filename, PIX pix, int quality, int progressive);

// PNG operations  
PIX pixReadPng(String filename, int hint);
int pixWritePng(String filename, PIX pix, float gamma);

// TIFF operations
PIX pixReadTiff(String filename, int n);
int pixWriteTiff(String filename, PIX pix, int comptype, String modestring);
PIXA pixaReadMultipageTiff(String filename);
int pixaWriteMultipageTiff(String filename, PIXA pixa);

// GIF operations
PIX pixReadGif(String filename);
int pixWriteGif(String filename, PIX pix);

// WebP operations  
PIX pixReadWebP(String filename);
int pixWriteWebP(String filename, PIX pix, int quality, int lossless);

// PNM (PPM/PGM/PBM) operations
PIX pixReadPnm(String filename);
int pixWritePnm(String filename, PIX pix);

// PostScript operations
int pixWritePS(String filename, PIX pix, BOX box, int res, int scale);
int pixWritePSEmbed(String filename, PIX pix, BOX box);

// PDF operations
int pixWritePdf(String filename, PIX pix, int res, String title, IntPointer plpd);

Usage Examples:

// Read JPEG with specific options
IntPointer warnings = new IntPointer(1);
PIX jpegPix = pixReadJpeg("photo.jpg", 0, 2, warnings, 0); // 1/4 size reduction
if (warnings.get() > 0) {
    System.out.println("JPEG read with " + warnings.get() + " warnings");
}

// Write high-quality JPEG
pixWriteJpeg("output.jpg", pix, 95, 1); // 95% quality, progressive

// Read multi-page TIFF
PIXA pages = pixaReadMultipageTiff("document.tiff");
int pageCount = pixaGetCount(pages);
System.out.println("Document has " + pageCount + " pages");

// Write WebP with lossless compression
pixWriteWebP("output.webp", pix, 100, 1); // lossless

// Write PostScript with specific resolution
BOX fullPage = boxCreate(0, 0, pixGetWidth(pix), pixGetHeight(pix));
pixWritePS("output.ps", pix, fullPage, 300, 1);

Image Information and Validation

Functions for querying image properties and validating image data.

/**
 * Get image format from file
 * @param filename - Path to image file
 * @return Format constant (IFF_*) or IFF_UNKNOWN
 */
int pixGetInputFormat(PIX pix);
String getImagelibVersions();

/**
 * Determine if file contains valid image data
 * @param filename - Path to file
 * @return 1 if valid image, 0 otherwise
 */
int pixGetImageIOVersion();

/**
 * Check if specific format is supported
 * @param format - Format to check (IFF_* constant)
 * @return 1 if supported, 0 otherwise  
 */
int formatSupported(int format);

Usage Examples:

// Check image format
int format = pixGetInputFormat(pix);
switch (format) {
    case IFF_PNG:
        System.out.println("PNG image");
        break;
    case IFF_JPEG:
        System.out.println("JPEG image");
        break;
    case IFF_TIFF:
        System.out.println("TIFF image");
        break;
    default:
        System.out.println("Unknown or unsupported format");
}

// Get library version information
String versions = getImagelibVersions();
System.out.println("Image libraries: " + versions);

// Check format support
if (formatSupported(IFF_WEBP) == 1) {
    System.out.println("WebP format is supported");
}

Error Handling

I/O functions follow consistent error handling patterns:

  • Return Values: 0 indicates success, 1 indicates failure for write operations
  • Null Returns: PIX reading functions return null on failure
  • Validation: Always check return values and null pointers
// Proper error handling pattern
PIX pix = pixRead("input.jpg");
if (pix == null) {
    System.err.println("Failed to read input.jpg");
    return;
}

int result = pixWrite("output.png", pix, IFF_PNG);
if (result != 0) {
    System.err.println("Failed to write output.png");
    return;
}

System.out.println("Image conversion successful");

Performance Considerations

  • Format Detection: Automatic detection adds minimal overhead
  • Memory Reading: pixReadMem() is efficient for pre-loaded data
  • Streaming: Use streams for large files or network sources
  • Header Reading: pixReadHeader() avoids loading pixel data for metadata-only operations
  • Quality Settings: Higher JPEG quality increases file size significantly
  • Compression: PNG and TIFF compression trades CPU time for smaller files

Install with Tessl CLI

npx tessl i tessl/maven-org-bytedeco--leptonica-platform

docs

collections.md

connected-components.md

core-images.md

geometry.md

image-io.md

image-processing.md

index.md

morphology.md

text-recognition.md

utilities.md

tile.json