tessl/maven-org-bytedeco--tesseract-platform

JavaCPP platform aggregator for Tesseract OCR native libraries providing cross-platform OCR capabilities in Java applications

—

Pending

Overview

Eval results

Files

Output Renderers

Name: tessl/maven-org-bytedeco--tesseract-platform
Author: tessl

Configurable pipeline system for generating OCR results in multiple output formats including plain text, structured markup (hOCR, ALTO, PAGE), searchable PDF, and specialized training data formats. Renderers can be chained together to produce multiple outputs simultaneously.

Capabilities

Renderer Base Class

All output renderers inherit from the TessResultRenderer base class which provides common functionality for document processing and output generation.

public abstract class TessResultRenderer {
    // Renderer chaining
    public void insert(TessResultRenderer next);
    public TessResultRenderer next();
    
    // Document processing lifecycle
    public boolean BeginDocument(String title);
    public boolean AddImage(TessBaseAPI api);
    public boolean EndDocument();
    
    // Renderer properties
    public String file_extension();
    public String title();
    public boolean happy();           // Check if renderer is in good state
    public int imagenum();           // Get current image number
}

Usage Pattern

// Create renderer chain
TessResultRenderer textRenderer = new TessTextRenderer("output");
TessResultRenderer pdfRenderer = new TessPDFRenderer("output", "/usr/share/tessdata", false);
textRenderer.insert(pdfRenderer);

// Process document
if (textRenderer.BeginDocument("Document Title")) {
    textRenderer.AddImage(api);  // Add each page/image
    textRenderer.EndDocument();
}

Text Output Renderers

Generate plain text and formatted text outputs from OCR results.

// Plain text output
public class TessTextRenderer extends TessResultRenderer {
    public TessTextRenderer(String outputbase);
}

// Tab-separated values with coordinates and confidence
public class TessTsvRenderer extends TessResultRenderer {
    public TessTsvRenderer(String outputbase);
}

// UNLV format for research and evaluation
public class TessUnlvRenderer extends TessResultRenderer {
    public TessUnlvRenderer(String outputbase);
}

Output Formats:

Text (.txt): Plain UTF-8 text with line breaks
TSV (.tsv): Tab-separated values with level, page, block, paragraph, line, word, confidence, x, y, width, height, text columns
UNLV (.unlv): University of Nevada Las Vegas evaluation format

Usage Example

// Generate plain text output
TessTextRenderer textRenderer = new TessTextRenderer("document");

api.SetImage(image);
if (textRenderer.BeginDocument("My Document")) {
    textRenderer.AddImage(api);
    textRenderer.EndDocument();
}
// Creates: document.txt

// Generate TSV with coordinates
TessTsvRenderer tsvRenderer = new TessTsvRenderer("analysis");
// Creates: analysis.tsv with detailed position data

Structured Markup Renderers

Generate XML and HTML outputs with detailed structure and metadata.

// hOCR HTML format with word coordinates
public class TessHOcrRenderer extends TessResultRenderer {
    public TessHOcrRenderer(String outputbase);
    public TessHOcrRenderer(String outputbase, boolean font_info);
}

// ALTO XML format (Library of Congress standard)
public class TessAltoRenderer extends TessResultRenderer {
    public TessAltoRenderer(String outputbase);
}

// PAGE XML format (European digitization standard)
public class TessPAGERenderer extends TessResultRenderer {  
    public TessPAGERenderer(String outputbase);
}

Format Descriptions:

hOCR (.hocr): HTML with microformat annotations, word bounding boxes, confidence scores
ALTO (.xml): Library standard with detailed layout structure, fonts, styles
PAGE (.xml): European standard for digitized documents with regions, baselines, reading order

Usage Example

// Generate hOCR with font information
TessHOcrRenderer hocrRenderer = new TessHOcrRenderer("webpage", true);

api.SetImage(image);
if (hocrRenderer.BeginDocument("Web Page Content")) {
    hocrRenderer.AddImage(api);
    hocrRenderer.EndDocument();
}
// Creates: webpage.hocr

// Sample hOCR structure:
// <div class='ocr_page' id='page_1' title='bbox 0 0 800 600'>
//   <div class='ocr_par' id='par_1_1' title='bbox 50 50 750 100'>
//     <span class='ocr_line' id='line_1_1' title='bbox 50 50 750 80'>
//       <span class='ocrx_word' id='word_1_1' title='bbox 50 50 100 80; x_size 20; x_conf 95'>
//         Hello
//       </span>
//     </span>
//   </div>
// </div>

PDF Renderer

Generate searchable PDF documents with selectable text overlay.

public class TessPDFRenderer extends TessResultRenderer {
    public TessPDFRenderer(String outputbase, String datadir);
    public TessPDFRenderer(String outputbase, String datadir, boolean textonly);
}

Parameters:

outputbase: Output filename prefix
datadir: Path to tessdata directory for font information
textonly: If true, create text-only PDF without original image

Usage Example

// Generate searchable PDF with original image
TessPDFRenderer pdfRenderer = new TessPDFRenderer("document", 
                                                  "/usr/share/tessdata", 
                                                  false);

api.SetImage(image);
if (pdfRenderer.BeginDocument("Scanned Document")) {
    pdfRenderer.AddImage(api);
    pdfRenderer.EndDocument();
}
// Creates: document.pdf (searchable, with image background)

// Generate text-only PDF
TessPDFRenderer textPdf = new TessPDFRenderer("textonly", 
                                             "/usr/share/tessdata", 
                                             true);
// Creates PDF with only text, no background image

Training Data Renderers

Generate specialized formats for training and improving OCR models.

// Box files for training (character coordinates)
public class TessBoxTextRenderer extends TessResultRenderer {
    public TessBoxTextRenderer(String outputbase);
}

// LSTM box files for neural network training
public class TessLSTMBoxRenderer extends TessResultRenderer {
    public TessLSTMBoxRenderer(String outputbase);
}

// Word string box files  
public class TessWordStrBoxRenderer extends TessResultRenderer {
    public TessWordStrBoxRenderer(String outputbase);
}

// Orientation and script detection output
public class TessOsdRenderer extends TessResultRenderer {
    public TessOsdRenderer(String outputbase);
}

Training Formats:

Box (.box): Character-level coordinates for traditional training
LSTM Box (.lstmbox): Optimized format for LSTM neural network training
Word String Box (.wordstrbox): Word-level training data
OSD (.osd): Orientation and script detection results

Usage Example

// Generate training data
TessBoxTextRenderer boxRenderer = new TessBoxTextRenderer("training");

api.SetImage(trainingImage);
if (boxRenderer.BeginDocument("Training Data")) {
    boxRenderer.AddImage(api);
    boxRenderer.EndDocument();
}
// Creates: training.box

// Sample box format:
// H 50 750 75 780 0
// e 75 750 90 780 0  
// l 90 750 95 780 0
// l 95 750 100 780 0
// o 100 750 120 780 0
// (char x1 y1 x2 y2 page)

Renderer Chaining

Combine multiple renderers to generate multiple output formats simultaneously.

Usage Example

// Create comprehensive output pipeline
TessTextRenderer textOut = new TessTextRenderer("document");
TessHOcrRenderer hocrOut = new TessHOcrRenderer("document", true);
TessPDFRenderer pdfOut = new TessPDFRenderer("document", "/usr/share/tessdata", false);
TessTsvRenderer tsvOut = new TessTsvRenderer("document");

// Chain renderers
textOut.insert(hocrOut);
hocrOut.insert(pdfOut);
pdfOut.insert(tsvOut);

// Process multiple images with all renderers
if (textOut.BeginDocument("Multi-page Document")) {
    for (String imagePath : imageFiles) {
        PIX image = pixRead(imagePath);
        api.SetImage(image);
        textOut.AddImage(api);
        pixDestroy(image);
    }
    textOut.EndDocument();
}

// Creates:
// - document.txt (plain text)
// - document.hocr (HTML with coordinates)  
// - document.pdf (searchable PDF)
// - document.tsv (tab-separated analysis)

Batch Processing Integration

Combine renderers with TessBaseAPI batch processing methods.

public class TessBaseAPI {
    // Process multiple pages from file
    public boolean ProcessPages(String filename, String retry_config,
                               int timeout_millisec, TessResultRenderer renderer);
    
    // Process single page  
    public boolean ProcessPage(PIX pix, int page_index, String filename,
                              String retry_config, int timeout_millisec,
                              TessResultRenderer renderer);
}

Usage Example

// Setup renderer chain
TessResultRenderer mainRenderer = new TessTextRenderer("output");
mainRenderer.insert(new TessPDFRenderer("output", "/usr/share/tessdata", false));

// Process multi-page TIFF or PDF
boolean success = api.ProcessPages("document.tiff", 
                                  null,           // no retry config
                                  60000,          // 60 second timeout
                                  mainRenderer);

if (success) {
    System.out.println("Successfully processed document");
    // Output: output.txt, output.pdf
} else {
    System.err.println("Processing failed");
}

Error Handling and Validation

Check renderer status and handle processing errors.

public abstract class TessResultRenderer {
    public boolean happy();          // Check if renderer is functional
    public String title();           // Get document title
    public int imagenum();          // Get current image number
}

Usage Example

TessResultRenderer renderer = new TessPDFRenderer("output", "/usr/share/tessdata", false);

if (!renderer.happy()) {
    System.err.println("Renderer initialization failed");
    return;
}

if (renderer.BeginDocument("Test Document")) {
    api.SetImage(image);
    
    if (!renderer.AddImage(api)) {
        System.err.println("Failed to add image " + renderer.imagenum());
    }
    
    if (!renderer.EndDocument()) {
        System.err.println("Failed to finalize document");
    }
} else {
    System.err.println("Failed to begin document");
}

C API Functions

Direct C API access for renderer management (alternative to object-oriented approach).

// Renderer creation functions
public static TessResultRenderer TessTextRendererCreate(String outputbase);
public static TessResultRenderer TessHOcrRendererCreate(String outputbase);
public static TessResultRenderer TessAltoRendererCreate(String outputbase);
public static TessResultRenderer TessPAGERendererCreate(String outputbase);
public static TessResultRenderer TessTsvRendererCreate(String outputbase);
public static TessResultRenderer TessPDFRendererCreate(String outputbase, String datadir, boolean textonly);
public static TessResultRenderer TessUnlvRendererCreate(String outputbase);
public static TessResultRenderer TessBoxTextRendererCreate(String outputbase);
public static TessResultRenderer TessLSTMBoxRendererCreate(String outputbase);
public static TessResultRenderer TessWordStrBoxRendererCreate(String outputbase);
public static TessResultRenderer TessOsdRendererCreate(String outputbase);

// Renderer management
public static void TessDeleteResultRenderer(TessResultRenderer renderer);
public static boolean TessResultRendererBeginDocument(TessResultRenderer renderer, String title);
public static boolean TessResultRendererAddImage(TessResultRenderer renderer, TessBaseAPI api);
public static boolean TessResultRendererEndDocument(TessResultRenderer renderer);

Usage Example

// C API style renderer usage
TessResultRenderer renderer = TessHOcrRendererCreate("webpage");

if (TessResultRendererBeginDocument(renderer, "Web Content")) {
    api.SetImage(image);
    TessResultRendererAddImage(renderer, api);
    TessResultRendererEndDocument(renderer);
}

TessDeleteResultRenderer(renderer);

Types

Renderer Chain Structure

// Base renderer interface
public abstract class TessResultRenderer {
    // Internal renderer chain linkage (opaque)
    // Each renderer maintains reference to next renderer in chain
}

Output File Extensions

// File extensions for different renderer types
// TessTextRenderer: ".txt"
// TessHOcrRenderer: ".hocr"  
// TessAltoRenderer: ".xml"
// TessPAGERenderer: ".xml"
// TessTsvRenderer: ".tsv"
// TessPDFRenderer: ".pdf"
// TessUnlvRenderer: ".unlv"
// TessBoxTextRenderer: ".box"
// TessLSTMBoxRenderer: ".lstmbox"
// TessWordStrBoxRenderer: ".wordstrbox"
// TessOsdRenderer: ".osd"

Install with Tessl CLI

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

docs

tessl/maven-org-bytedeco--tesseract-platform