# Interactive Ink runtime

This page shows you how to instantiate the iink runtime and configure it to fit your needs.

## Engine creation

The iink SDK runtime is represented by an Engine object.

This object will let you create other key objects, configure the recognition and fine-tune the SDK behavior.

It is instantiated via the create() static method of the Engine class:

In java, we strongly recommend to wrap the engine creation into a singleton.

import com.myscript.certificate.MyCertificate;
import com.myscript.iink.Engine;

public class IInkApplication extends Application
{
private static Engine engine;

public static synchronized Engine getEngine()
{
if (engine == null)
{
engine = Engine.create(MyCertificate.getBytes());
}

return engine;
}
}
Data provided in parameter corresponds to your activation certificate. If engine creation fails, please make sure that it was generated for your application identifier.

## Configuration

A new engine must be configured to let iink SDK know which kind of content is to be recognized.

Being a flexible toolkit, iink SDK also comes with many configuration parameters. While the default values make sense in most cases, it may sometimes be required to configure them to suit your needs.

### Accessing the configuration

The configuration can be obtained by calling getConfiguration() on the engine object.

It is possible to attach a listener implementing the IConfigurationListener interface to a given configuration object to get notified when configuration changes are made.

### Reading and writing configuration parameters

Interactive Ink SDK configuration is a ParameterSet object. It can be seen as a set of key/value pairs, where values themselves can be other ParameterSet objects.

You can read the value attached to an existing key, add new (key, value) pairs or remove existing ones. Supported value types are strings, numbers, booleans, arrays of strings, as well as other ParameterSet objects.

Here is a representation of such a structure:

{
"name": "iink SDK",
"interactive": true,
"version":
{
"major": 1,
"minor": 0
},
"parts": [ "Text", "Math", "Diagram", "Drawing", "Raw Content", "Text Document"]
}

The code below shows how to manipulate this structure when stored in a parameters variable:

import com.myscript.iink.ParameterSet;

// Access a section content
ParameterSet version = parameters.getSection("version");

// Read a value for a key using the section object
Number major = version.getNumber("major"); // -> 1

// Set a value for a key using the dot syntax
parameters.setNumber("version.major", major + 1); // -> 2

### Configuring the recognition

To recognize math, diagrams or text in any language, it is required to provide the engine with configuration files (*.conf) that specify required parameters and recognition assets to be loaded.

Interactive Ink SDK default configurations should be suitable for most needs.

The engine should be configured as follows:

1. Set the value of the configuration-manager.search-path key to the folder(s) containing the configuration files you need.
2. Set the value of the lang key to match the name of the configuration file that corresponds to the language you want to recognize (for instance, set it_IT for the Italian language, as corresponding resources are described in it_IT.conf).
import com.myscript.iink.Configuration;
import com.myscript.iink.Engine;
import java.io.File;

...
Engine engine = IInkApplication.getEngine();

// configure recognition
Configuration conf = engine.getConfiguration();
conf.setStringArray("configuration-manager.search-path", new String[] { "zip://" + getPackageCodePath() + "!/assets/conf" });
conf.setString("lang", "it_IT");
MyScript language names starts with a two-letter language code (using the ISO-639 standard), followed by an underscore and a two-letter country code (using the ISO-3166 standard). For example en_US for US English.

If you need to go further, you can learn how to modify or write your own configuration files (advanced).

Configuration files refer to binary files called resources (*.res) that host everything that the engine requires for the recognition. Make sure to properly deploy these files along your application as well. A good practice is to implement error management at editor level to be notified of recognition configuration error.

### Content-specific configuration

Interactive Ink SDK comes with many configuration options. Some are general, like the ability to choose the location of the temporary folder to store work data on the file system, and some depend on the type of content you manipulate. For instance, it is possible to activate or deactivate the solver for math equations.

The full list of supported configuration options can be found in the dedicated section.

### Editor-level configuration

Engine-level configuration corresponds to the default, global configuration. It is possible to override configuration values at editor-level, which is useful if you manage several parts with different configurations.

## Back to the example

To be able to recognize math, the engine of the example calculator needs to be created and pointed to the required assets. The easy way is to rely on the default configuration for math: You just need to set the right configuration option to the folder where the math.conf file provided with iink SDK is located.

In addition, it is recommended to provide a valid content-package.temp-folder configuration, which is further explained in the next step.

The solver component of the math back-end needs to be enabled, so that it can handle the computations when doing the conversion. The value of math.solver.enable is true by default, so there is nothing to do here.

Finally, for the sake of the example, you can change the floating point precision of the answer to 2 digits (it is 3 by default).

The code to create and configure the engine will thus be:

import com.myscript.iink.Configuration;
import com.myscript.iink.Engine;
import java.io.File;

public class Calculator {

private Engine engine;

/**
* @param packageCodePath when used from an AppCompatActivity object, getPackageCodePath() output.
* @param filesDirPath when used from an AppCompatActivity object, getFilesDir().getPath() output.
*/
public Calculator(String packageCodePath, String filesDirPath) {

//Creating engine and accessing the configuration object
engine = IInkApplication.getEngine();
Configuration configuration = engine.getConfiguration();

// set the recognition configuration
configuration.setStringArray("configuration-manager.search-path", new String[]{"zip://" + packageCodePath + "!/assets/conf"});

// set the temporary directory
String tempDir = filesDirPath + File.separator + "tmp";
configuration.setString("content-package.temp-folder", tempDir);

// set the math fractional part precision
configuration.setNumber("math.solver.fractional-part-digits", 2);
}
}

At this point, the engine is theoretically able to recognize math. The next step of this guide will show how to load and save content.