Equation Composer, Windows

Command

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 | eps | png> specifies the format for the image gif
-noimage supresses the generation of the image file if present generate the image
-pointsize <double> specifies the base font point size for the equation 12.0
-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 white
-fg <CSS color name | #rrggbb> specifies the foreground color for the equation black
-breakwidth <int> specifies the width for line wrapping long equations - value should include valid MathML units. 1024px
-basefont <fontname> specifies the font to use as the base font for alpha numeric characters "Times New Roman"
-fontconfig <filename> specifies the path and file name of a file that contains a list of font face names none
-fontinfo <filename> specifies the path and file name of a file that provides additional font information none
-fontencodingsdir <dirpath> specifies the path to a directory with font encoding files <fontinfo directory>, if fontinfo is specified
-useantialias <true | false | automatic> specifies whether to use antialiasing if possible, not to use it, or use it if heuristics thinks it helps none
-scriptsatsameheight <true | false> specifies if nested msup/msub etc. may have scripts at same height false
-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
-speechstring [<filepath>] generates a .txt file with the equation's speech string. Use together with -noimage to only generate speech string files. The optional <filepath> can be either a full path to a directory (if no extension) or a file a path relative to the <imagefolder> one, for a directory (if no extension) or a file do not generate file. If speechstring is present and <filepath> is not specified, it defaults to imagefolder+imagename+".txt"
-speechrulesdir <dir> specifies the location of the rules that specify how an expression is spoken <version>\auxiliary\
SpeechRules
-speechlang <lang> specifies the ISO 639-1 two-letter code for the language to be spoken (e.g., it for Italian, es for Spanish, zh for Chinese) en
-speechstyle <style> specifies a named speech style to use for speaking expressions in a given language Simple Speech
-tts <ttsname> specifies the text-to-speech (TTS) engine standard to use for speech controls.  This is useful if the text is meant to be spoken by a known voices and results in better quality speech (with pauses, pitch, and pronunciation changes). Legal values are "None", "SAPI4" (older voices), "SAPI5" (newer voices), "SSML" (very new voices) None
-opdict <filename> specifies the path and file name of the configurable operator dictionary. See Configuring the Operator Dictionary for more information. None

Examples (Windows 64-bit)

EquationComposer64 -license "dessci.lic" -mathml "<math><mi>x</mi></math>"
EquationComposer64 -license "dessci.lic" -mathml "<math><mi>x</mi></math>" -noimage -speechstring
EquationComposer64 -license "dessci.lic" -mathml "<math><mi>x</mi></math>" -speechstring "eq_speech"
EquationComposer64 -license "<license key>" -mathml aFile.mml
EquationComposer64 -license "dessci.lic" --imgtype eps -mathml "<math><mi>x</mi></math>"
EquationComposer64 -license "dessci.lic" --imgtype gif -mathml "<math><mi>x</mi></math>"
EquationComposer64 -license "dessci.lic" --size 12 -mathml "<math><mi>x</mi></math>"

The MathFlow SDK includes DLL libraries for the Equation and Document Composers. In this example, we'll show how to use the Equation Composer in a simple ASP.NET website.

Requirements

You will need Microsoft Visual Studio .NET 2005 with a correctly configured web server such as IIS in order to run this example. You will also need basic familiarity with Visual Basic, but the example can be refactored into any .NET language.

Registering the DLL

The EquationComposer.dll exposes a MathFlowSDK.EquationComposer COM object that provides COM clients with a way of generating images from MathML. In order to make use of the EquationComposer object, the EquationComposer.dll must first be registered. From a DOS command prompt or the Run dialog from the Start Menu, issue the following command:

regsvr32 <path to EquationComposer.dll>

A dialog box will display indicating that the registration was successful. Once registered, the EquationComposer can be instantiated just like any other COM object.

Setting up and running the example

  1. Create a new ASP.net VS 2005 project.
    1. Open Visual Studio .NET 2005
    2. Choose File > New > Web Site
    3. Select "ASP.NET Web Site"
    4. Choose a location
    5. Choose a language (this example uses Visual Basic)
  2. Include the DLL into the project
    1. In the Solution Explorer, select the "Developer Web Server" object just below the "solution". This looks something like this:
      Developer web server
    2. Right-click the "Developer Web Server" object and select "Add Reference..." from the contextual menu. This will bring up a dialog that looks like this:
      Add reference dialog
    3. Switch to the COM tab and select the "MathFlowSDK EquationComposer 1.0 Type Library" and click OK.
  3. Insert a button into the default web page that will execute the EquationComposer
    1. Open the default web page that appears in the project (Default.aspx).
    2. Go to the View menu and choose Designer to enter Design View.
    3. Click on the toolbox button "" to allow you to drag a Button onto your page.
    4. Double click the button.
  4. Insert code into the Button1_Click subroutine. Since this is Visual Basic code, type in the following, changing the paths to those of your preference:
    Dim iw As EquationComposerLib.EquationComposer
    iw = New EquationComposerLib.EquationComposer
    iw.SetLicense("C:\Program Files\MathFlow SDK\2.1\windows\samples\dessci.lic")
    iw.SetMathML("‹math›‹mi›x‹/mi›‹/math›")
     
    iw.SetImageFolder("C:\Program Files\MathFlow SDK\2.1\windows\samples")
    iw.SetImageName("asptest")
    iw.SetImageType("png")
    iw.GenerateImageFile()
  5. Run the example
    1. Click on the start debugging button.
    2. In the resulting web page click on the button.
  6. Check for an image. If all went well, there is an image called "asptest.gif" sitting in the location you specified using the SetImageFolder() command. In real life, you would obviously do something with the image, such as display it to the user, or store it somewhere.

Using the command line

To illustrate the use of the Equation Composer, there are two files located in the samples directory that demonstrate how to call it from command line:

<path-to-mathflow-sdk>/windows/samples/equation_composer32_cmd.bat (for 32-bit systems)
<path-to-mathflow-sdk>/windows/samples/equation_composer64_cmd.bat (for 64-bit systems)

About the script

The equation_composer32_cmd.bat (or equation_composer64_cmd.bat) file calls EquationComposer32 (or EquationComposer64), which is located in the bin directory, with several options. The bat script contains the following commands (formatted for clarity):

"../bin/EquationComposer<32 or 64>"
-license "dessci.lic"
-mathmlfile "test.mml"
-imagename "test"
-imagetype "png"
IMPORTANT NOTES:
  • Your license, dessci.lic, is a FlexNet license file that is located in the same directory as equation_composer32_cmd.bat (or equation_composer64_cmd.bat). This option is always required.
  • MathML is read from a file named test.mml, also located in the same directory as the .bat file. Either a mathml or mathmlfile option is always required. If both are supplied, mathmlfile will take precedence over the mathml value.
  • The name of the image file will be test.png (imagename.imagetype). If this file already exists, it will be overwritten.

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

Sample VB.NET application

The sample Visual Basic program below illustrates how to use the EquationComposer, (EquationComposer32, or EquationComposer64 for Windows operating systems) class to generate images from MathML. We've provided the source code so you can experiment with different techniques for use in your own programs.

Prerequisites for running the program

  • You must have the .NET 2.0 Framework installed.
  • The EquationComposer32.dll (for Windows 32-bit systems) or EquationComposer64.dll (for Windows 64-bit systems) must be registered. Use the command regsvr32 <path to your operating system's specific DLL> to register it.
  • The dessci.lic file should be (but doesn't have to be¹) in the same directory as the sample code executable. (¹If the license is not in the same directory as the executable, you must provide the path to the license in the space provided in the application for "License File".)

Running the program

We don't provide a sample application to illustrate the use of the Equation Composer, but since we provide the source code, it should be a simple matter to build your own sample application.

To run the sample application after you build it, double-click the file. 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. Note that while you can't view an EPS (encapsulated postscript) generated image, the image is saved as an EPS file.

Equation Composer Windows

Source code

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

<path-to-mathflow-sdk>/windows/samples/EquationComposerApplication/src/EquationComposerApplication

Use Visual Studio to open the EquationComposerApplication32.sln or EquationComposerApplication64.sln solution file.

Programming notes

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

New()

  • Instantiates a MathFlowSDK.EquationComposer object, which is used throughout the program.
  • Initializes the program controls with default values
  • Sets the options for the Equation Composer using the values of the program controls

GenerateImageFile()

Within a Try/Catch block:

  • Sets the options for the Equation Composer using the values of the program controls
  • Calls 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:
    • 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, call the SetOption method again with an empty string to tell the system not to use that option and continue processing

Note this is only one way in which you can set the Equation Composer options. 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.