Equation Composer, Java

Command

java EquationComposer -license <filename | license_key> -mathml <'MathML_string'> | -mathmlfile <filename> [options]

Parameters/Options

Parameter/OptionDescriptionDefault value
-license <filename | license_key> specifies the path and filename for the license file or a license key required input
-mathml <'MathML_string'> specifies the MathML string required input (if mathmlfile is not supplied)
-mathmlfile <filename> specifies the path and filename for the MathML file required input (overrides -mathml)
-imagefolder <dirpath> specifies the path to a directory that will contain the image files none
-imagename <filename> specifies the file name for the resulting image img
-imagetype <gif | png> specifies the format for the image gif
-antialiasingoff <true | false> Controls whether images will be created with antialiasing or without false
-pointsize <int> specifies the base font point size for the equation 12
-dpi <int> specifies the resolution of the resulting image in dots per inch 96
-bg <CSS color name | transparent | #rrggbb> specifies the background color for the equation (Background transparency is not currently implemented for the GenerateImageData method) white
-fg <CSS color name | #rrggbb> specifies the foreground color for the equation black
-breakwidth <int> specifies the width for line wrapping long equations 0
-padding <int> specifies the padding around the border of the equation image 0
-fontmapping <filename> specifies the path and file name for the font mapping file - If the file does not exist, "FontMapping.opt" will be used instead. If this also does not exist or if a file is invalid, the font associations will remain at their previous values. See Java Rendering Engine for more information. none
-charmap <filename> specifies the full path and file name for a character mapping file none
-logfile <filename> specifies the path and file name for a log file none
-verbosity <mute | normal | debug> specifies what processing messages should be displayed; mute - none; normal - any error messages and whether the image was generated successfully; debug - additional processing information normal
-readoptions <filename> specifies the path and file name of an XML file for reading in options values none
-saveoptions <filename> specifies the path and file name of an XML file for saving out options values none
-opdict <filename> specifies the path and file name of the configurable operator dictionary. See Configuring the Operator Dictionary for more information. none

Using the Command Line (Java)

We've provided a sample application to illustrate the use of the Equation Composer (for Java) from the command line.

<path-to-mathflow-sdk>/java/samples/equation_composer_cmd.bat (on Windows systems)
<path-to-mathflow-sdk>/java/samples/equation_composer_cmd.sh (on non-Windows systems)

About the Script

The Equation Composer batch file (or shell script) calls EquationComposer with several options. It contains the following command (formatted for clarity):

java -classpath .;../MathFlow.jar
com/dessci/mathflow/sdk/composer/EquationComposer
-license dessci.lic
-mathmlfile test.mml
-imagefolder images
-imagename test
-imagetype png
-fontmapping FontMapping.opt
IMPORTANT NOTES:
  • There is only one .jar file, and it must be on the classpath are as shown above.
  • Within the MathFlow.jar file, the EquationComposer program is located at com/dessci/mathflow/sdk/composer/EquationComposer.
  • Your license, dessci.lic, is a FlexNet license file that is located in the same directory as the Equation Composer shell script. This option is always required.
  • MathML is read from a file named test.mml, located in the same directory as the batch file or shell script. Either a mathml or mathmlfile option is always required. If both are supplied, mathmlfile takes precedence over the mathml value.
  • The name of the image file will be test.png, (imagename.imagetype, which will be written to the images subdirectory. If this file already exists, it will be overwritten.
  • A fontmapping file, FontMapping.opt, located in the same directory as the batch file or shell script, will be used. This fontmapping file specifies the following fonts to be used for each class of symbols (see Java Rendering Engine for more information):
    100=Times New Roman (ALPHA_NUMERIC)
    101=Euclid Symbol (SYMBOL)
    102=Code2000 (EXTRA_SYMBOL)
    103=Euclid Symbol (GREEK)

For a complete list of the command line options, see Command Line Parameters.

The sample Java program below illustrates how to use the EquationComposer class to generate images from MathML. The source code is provided so that you can experiment with different techniques for use in your own programs.

Prerequisites for Running the Program

  • Java 1.6 or higher
  • The dessci.lic file needs to be in the same directory as the sample code batch file or shell script.
  • The required .jar file needs to be on the classpath: MathFlow.jar (all MathFlow SDK classes)

Running the Program

<path-to-mathflow-sdk>/java/samples/equation_composer_app.bat (on Windows systems)
<path-to-mathflow-sdk>/java/samples/equation_composer_app.sh (on non-Windows systems)

The sample program allows you to change the input parameters used to generate an equation image (see below). After changing the input parameters and telling the program where to save the generated image, click the Generate Image File button. This will refresh the image shown and save the image to a file, and the Clear Image button will remove the image and any text in the status bar.

Java Equation Composer

About the Script

The batch file (or shell script) calls EquationComposerApplication.

java -classpath .;../MathFlow.jar

com/yourcompany/samplecode/composer/EquationComposerApplication

Note that the source code for the sample program is located in the following directory:

<path-to-mathflow-sdk>java/samples/com/yourcompany/samplecode/composer/EquationComposerApplication.java

Programming Notes

The main functions/subroutines in this program are as follows:

generateImageFile()

Uses a Try/Catch block to

  • Call setOptions to set the options for the Equation Composer using the values of the program controls
  • Call the method to generate the image

setOptions()

  • Sets the value of each option for the Equation Composer from the corresponding program control
  • The general strategy in the sample application for handling exceptions in the SetOption methods is as follows:
    • If an option is required (i.e., license, mathml or mathmlfile) and an exception is thrown by the SetOption method, throw an exception with the error message returned from the SetOption method.
    • If an option is optional and has a default value (e.g., pointsize), catch any exception thrown by the SetOption method, retain the warning message for display later and continue processing, using the default value for that option
    • If an option is optional and does not have a default value (e.g., logfile), catch any exception thrown by the SetOption method, retain the resulting message for display later and continue processing

Note that this is only one way in which the options for an Equation Composer can be set. Another possible approach would be to call each set method when the value of a program control changes.

getOptions()

Sets the value of the program controls from the corresponding options of the Equation Composer

readOptions()

Uses a Try/Catch block to

  • Call the method to read the options from an XML file
  • Call getOptions to set the value of the program controls using the options for the Equation Composer

saveOptions()

Uses a Try/Catch block to

  • Call setOptions to set the options for the Equation Composer using the values of the program controls
  • Call the method to save the options to an XML file

Prerequisites for Running the Program

There is only one required .jar file to include on the classpath of your servlet container:

  • MathFlow.jar (all MathFlow SDK classes)

Creating and Using the Servlet

You can find the servlet in the following location:

<path-to-mathflow-sdk>/java/samples/servlets/MathFlowSDKServlet.java

To illustrate how servlets can use the MathFlow SDK, the sample servlet uses MathML to generate an image. Once you have generated the image, you can save it to a file and display. Specifically, the sample servlet does the following:

  • Creates an instance of the EquationComposer component using a license key.
  • Sets various options for generating the image.
  • Generates the image and writes it out as a file.
  • If there are no errors, it displays the image.
  • If there are errors, it displays an error message.
IMPORTANT NOTES
  • A valid MathFlow SDK license for an Equation Composer must be supplied by using a license key or FlexNet license file with the SetLicense method.
  • You can set options for generating the image by calling instance methods on the EquationComposer object.