Getting Started

You can use ShapeLogic Java in different ways:

  • User mode for ImageJ image processing plugin
  • Development mode for ImageJ plugin
  • As an image processing library for your application
  • As a lazy stream library

Testing ShapeLogic as a user is very simple and only takes a few minutes after ImageJ is installed.

Lazy stream library

ShapeLogic contains functional and declarative constructs that can be used independently of the image processing code.

To use this just download the shapelogic_-1.6.jar and add it to your class path. If running from command line: -cp .;shapelogic_-1.6.jar

For examples of how to use this to solve mathematical problems see Project Euler solution.

Image processing user mode with ImageJ

Steps to get ShapeLogic working from within ImageJ, from binary distribution

  • Install ImageJ
  • Download
  • Unzip it
  • This will create a directory named shapelogicplugin1.6/shapelogicplugin
  • Inside this there are 2 dirs: ShapeLogic and ShapeLogicOld and 6 jar files
  • Take these 2 dirs and all the jar files from this directory and copy it into ./ImageJ/plugins/

Testing ShapeLogic particle counter or particle analyzer from within ImageJ

  • Open a particle image
  • Under the shapelogic plugin menu select Particle Counter or Color Particle Analyzer
  • Enter input parameters in dialog
  • A result table with geometric information for each particle will be displayed

For more information see Particle Counter and Analyzer page.

Testing ShapeLogic letter matching from within ImageJ

  • Open ImageJ
  • Create a new image, 100 x 100 pixels works well
  • Draw a letter in black on white background

Go to the shapelogic menu and select the macro CapitalLettersMatch, which does the following

  • Convert the image to a binary image
  • Call ImageJ's build in Skeletonize
  • Call the ShapeLogic plugin Stream Vectorizer

If you already have a skeletonized lines you can also call Stream Vectorizer directly, which does the following

  • Vectorize into bitmap into polygon
  • Clean up the vectorized polygon
  • Then annotate the polygon
  • Then match the polygon against all the rules for all the capital letters
  • With a little luck you will see a dialog box saying what letter was matched
  • If more than one letter matches, the match will fail
  • If the match fails then all the properties of the polygon will be written to the console for debugging

Input dialog

When you press CapitalLettersMatch or Stream Vectorizer an input dialog will prompt you for input:

CapitalLettersMatch menu item

DisplayInputDialog: If you uncheck this next time run CapitalLettersMatch this menu will not show up

DisplayResultTable: If this is checked you will see a result table with geometric features for each polygon

DisplayInternalInfo: Print out polygon, points and their annotations

UseNeuralNetwork: Use neural network for classification otherwise a rule set will be used

ShowFileDialog: If this is checked the user will be prompted with a file dialog to select categorizer setup file

CategorizerSetupFile: File path to the categorizer setup file containing neural networks, rules or column selection list

Result of match

Dialog with results of match

M match

Vectorized M with skeletonized letter in black and polygon in gray

M vectorized

For more information see Letter Match page.

Steps to get ShapeLogic working from within ImageJ manually

If you need a different version of shapelogic_-1.6.jar, e.g. one compiled for JDK 1.7.

  • Create a ShapeLogic dir under ImageJ: ./ImageJ/plugins/ShapeLogic
  • Take the jar file for ShapeLogic: shapelogic_-1.6.jar, and move it to that directory
  • Add the jar files that ShapeLogic is dependent on to the ImageJ/plugin dir:
    • antlr-runtime-3.0.jar
    • commons-collections-3.2.jar
    • commons-jexl-1.1.jar
    • commons-logging-1.0.4.jar
    • commons-math-1.1.jar
    • guice-1.0.jar

These jar file can be found on any Maven 2 repository:

E.g. commons-math-1.1.jar can be found here:

Or they can be taken out of the

When you open ImageJ there will be a ShapeLogic menu containing commands.

You can get the binary distribution from the download page or compile it yourself.

User defined rules in ShapeLogic

Starting in ShapeLogic 1.0 it is simpler to make user define rules for matching for use in Letter Matcher or the Particle Analyzer.

How user can change Letter Matcher to recognize numbers instead

Until ShapeLogic 1.5 this demanded programming. Now you just load the categorizer setup file src/test/resources/data/neuralnetwork/polygon_digit_recognizer_with_rules_print.txt containing some simple rules:

========== def 0
holeCount == 1
tJunctionCount == 0
endPointCount == 0
multiLineCount == 1
curveArchCount > 0
hardPointCount == 0
softPointCount > 0

========== def 1
holeCount == 0
tJunctionLeftCount == 0
tJunctionRightCount == 0
endpointBottomPointCount == 1
horizontalLineCount == 0
verticalLineCount == 1
endPointCount == 2
multiLineCount == 0
softPointCount == 0
aspectRatio < 0.4

========== PRINTS


Future plans for user defined rules in ShapeLogic

Add the ability of the user to define lazy data stream in the categorizer setup file.

The rule sets and neural networks that are now defined in categorizer setup file could just as well be defined in a database.

Development mode

ShapeLogic is built using Maven 2.

This makes several build tasks very easy, and is recommended, but the code should run fine without Maven.

Currently the project is set up to work directly with Eclipse 3.3 - 3.4, NetBeans 6.0 - 6.5, Java 1.5, but you can use: IntelliJ, JBuilder, emacs or vi.

  • Steps to compile and run unit tests

Check ShapeLogic out into a local directory.

Do a cd into that directory.


  • mvn test runs the unit tests locally
  • mvn package runs the unit tests locally, and if they passes it will create the jar file
  • Changing JDK version when building with Maven

You will have to change the JDK target in pom.xml: