Matching, Recognition, Results

The Best-Performing Address Matching and Recognition Solutions for
Postal and Logistics Companies

BROIDI API

How to use the evaluation version of BROIDI API

How to use BROIDI API

The application programming interface is simple enough. There is one function that accepts an ImageInputStream as an input and outputs a list of RoiResults that are effectively just pairs of a Rectangle and a likelihood score (higher the value, the likelier the candidate).

The stream must contain a monochrome TIFF image, either uncompressed or with ITU-T Group4 (T.6) compression.

public interface BroidiAPI {
    List<RoiResult> findRoiCandidates(ImageInputStream imageInputStream) throws IOException;
}

 
We have one implementation of Broidi API in com.syslore.broidi.api.BroidiRunner. In case you want to write an application of your own using BROIDI, you need to

  • add broidia-all.jar to the class path, 
  • pass the BROIDI model filename to the loader to create BROIDI instance, and
  • pass the created the BROIDI instance to BroidiRunner.

The result could be as follows:

package com.bar.foo;
 
import java.io.File;
import java.io.FileWriter;
import java.io.FilenameFilter;
import java.io.IOException;
import java.io.Writer;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import javax.imageio.stream.FileImageInputStream;
import javax.imageio.stream.ImageInputStream;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.syslore.broidi.roi.Broidi;
import com.syslore.broidi.api.BroidiRunner;
import com.syslore.broidi.api.RoiResult;
 
public class TestRunner {
    public static final Logger LOGGER = LoggerFactory.getLogger(TestRunner.class);
 
    public static void main(String[] args) {
        if (args.length != 3) {
            System.err.println("USAGE: <broidi object file> <input_dir> <text output file>");
            System.exit(1);
        }
        String broidiModelFilename = args[0];
        String inputDirectoryName = args[1];
        String resultFilename = args[2];
        FilenameFilter imageFilenameFilter = new FilenameFilter() {
            public boolean accept(File directory, String filename) {
                return filename.toLowerCase().endsWith(".tif") || filename.toLowerCase()
					.endsWith(".tiff");
            }
        };
 
        File inputDirectory = new File(inputDirectoryName);
        if (!inputDirectory.exists() || !inputDirectory.canRead()) {
            System.err.println("Cannot read input directory '" + inputDirectoryName + "'");
            System.exit(1);
        }
 
        String[] imageFilenames = inputDirectory.list(imageFilenameFilter);
        LOGGER.debug("Found {} files.", imageFilenames.length);
        if (imageFilenames.length == 0) {
            System.err.println("Cannot find any input files.");
            System.exit(1);
        }
 
        try {
            LOGGER.info("Reading Broidi model file: " + broidiModelFilename);
            Broidi broidi = Broidi.load(broidiModelFilename);
            LOGGER.info(broidi.toString());
            BroidiRunner runner = new BroidiRunner(broidi);
            Writer writer = new FileWriter(new File(resultFilename));
            for (String filename : imageFilenames) {
                ImageInputStream imageInputStream = new FileImageInputStream(new 
					File(inputDirectoryName + File.separator + filename));
                List<RoiResult> roiResults = runner.findRoiCandidates(imageInputStream);
 
                // ---
                // Process the ROI results.
                // ---
 
                try {
                    imageInputStream.close();
                } catch (IOException exception) {
                    LOGGER.warn("The closing of an image stream resulted in an exception:"
						 + exception.getMessage());
                }
            }
            writer.close();
        } catch (Exception e) {
            LOGGER.error(e.getMessage(), e);
            System.exit(1);
        }
    }
}

 

Running BROIDI

The BroidiRunner implementation contains a main function that can be called from the command-line. You can process a set of images in a given input directory, and the tool will write its decisions in a given text file.

Running BROIDI on Windows platform

The trial package contains broidi_runner.bat batch file for running the BroidiRunner on Windows platform. Running broidi_runner.bat without arguments prints the usage of the script:

C:\Users\broidi\broidi-trial> broidi_runner.bat
Usage: broidi_runner <input_dir> <output file>

 
That is, the script takes the directory containing the images as the first argument, and the output file as the second argument.

Note!
  • The image filenames in the input directory must have the suffix .tif or .tiff.
  • Should there be several candidates, the output result file will contain one for each candidate. The candidates of the same image are in decreasing order of likelihood score.
  • The output file is written using UTF-8 character encoding.

Running BROIDI on Unix platform

The trial package contains broidi_runner.sh shell script for running the BroidiRunner on Unix platform. To execute the script the execute permissions must first be granted for the script file:

$> chmod u+x broidi_runner.sh


Running 
broidi_runner.sh without arguments prints the usage of the script: 

$> ./broidi_runner.sh
Usage: ./broidi_runner.sh <input directory> <output file>

 
That is, the script takes the directory containing the images as the first argument, and the output file as the second argument.

Note!
  • The image filenames in the input directory must have the suffix .tif or .tiff.
  • Should there be several candidates, the output result file will contain one for each candidate. The candidates of the same image are in decreasing order of likelihood score.
  • The output file is written using UTF-8 character encoding.

Running BROIDI with the included example images

The trial package contains a set of example images, which are stored at images directory. These images may be used for testing the BROIDI model included in the trial package. To execute BROIDI with the included example images on Windows platform, run:

C:\Users\broidi\broidi-trial> broidi_runner.bat images example_output.txt


On Unix platform, run:

$> ./broidi_runner.sh images example_output.txt


The both commands assume that the current working directory is the root of the trial package. 
The output file (example_output.txt) will produce output in the following tab-separated format:

mockimage_10.tif    0.6607527241330315  java.awt.Rectangle[x=298,y=523,width=205,height=130]
mockimage_11.tif    0.7900004836394765  java.awt.Rectangle[x=465,y=610,width=379,height=132]
mockimage_11.tif    0.1252683465143134  java.awt.Rectangle[x=467,y=470,width=461,height=188]
mockimage_12.tif    0.548323022888167   java.awt.Rectangle[x=1374,y=571,width=229,height=139]
mockimage_12.tif    0.37025345728676645 java.awt.Rectangle[x=1374,y=571,width=186,height=52]
mockimage_12.tif    0.08124364710235299 java.awt.Rectangle[x=969,y=571,width=634,height=262]
....


Note that for images 
mockimage_11.tif and mockimage_12.tif several results are reported. For each image, all the found candidates are reported in decreasing order of likelihood score.