cavis/deeplearning4j/deeplearning4j-ui-parent/deeplearning4j-play/developerReadme.md

Deeplearning4j UI (deeplearning4j-play) Developer Readme

The deeplearning4j UI utilizes an embedded Play server for hosting web pages. This guide documents some basic information about the design, and how new pages can be added.

Overview

As of DL4J 0.7.2, version 2.4 is utilized for scala 2.10 compatibility, which was dropped in Play 2.5 and later. Due to DL4J being managed by Maven, not all features of Play (such as conf/routes approach to routing configuration, and the default internationalization mechanism) are supported.

Some key concepts:

• The actual HTML pages are defined in the main/views/org.deeplearning4j.ui.views.* directory
  • These views are based on Twirl template engine: in practice, templates are mostly HTML with a little scala code mixed in
  • The views themselves need to be rendered to a scala class (under main/scala). This is currently done manually, see the 'building templates' section.
• Routing is somewhat non-standard in DL4J, compared to a typical Play application
  • The DL4J has the concept of a 'UI module': a related set of pages to serve via the UI
  • Each module implements the UIModule interface, which defines a set of routes, and how to handle page requests
  • Custom modules are supported: this is not enabled by default. See PlayUIServer UI_CUSTOM_MODULE_PROPERTY for details.
• Internationalization (i.e., multiple languages) is supported, but not using the standard Play mechanisms
• The main class and entry point is PlayUIServer

Building Templates

The current setup (using Maven + Play) means that the HTML templates need to be built manually. Just run mvn compile -P buildUiTemplates on the command line to do this - this will generate the Scala classes from all of the HTML files (in the views directory) and copy them to the appropriate location in the scala directory.

Adding New Pages

Adding a new (built-in) page to the UI can be done using the following approach:

• Define a new module in org.deeplearning4j.ui.module, that implements the UIModule interface
  • Provide routes: these are the endpoints that the user will be able to query, and define what methods will be used to get the result to return for that page. See for example TrainModule for details
  • Each route needs to specify the method to call to get the result (must return a play.mvc.Result object)
  • Supplier: used to return results with no args; Function: 1 arg; BiFunction and Function3: 2 and 3 args respectively. For function/bifunction etc, the arguments are specified with semicolons, like "/myRoute/:myArg"; the called method should have an appropriate number of arguments to match this.
  • Optionally: add code to handle callbacks, storage events, stats storage. See the section below.
• Add the module to the others, in the PlayUIServer. Should be 1 line: uiModules.add(new MyNewModule());

Assets

Again (due to issues with Maven + Play support), DL4J defines a custom Assets serving system. Assets are static files such as images, CSS, javascript files, etc. The contents of /resources/deeplearning4jUiAssets/* get mapped to /assets/* on the running server. To add a new asset, simply add it to the assets folder, and then reference it as normal in the HTML templates or elsewhere.

StatsStorage, Callbacks, and Getting Network and Other Info from DL4J

The Deeplearning4j UI supports callbacks from StatsStorage. StatsStorage instances are objects/interfaces that store training information - some of it may be static/stored, some of it may be streaming in, in real-time.

When a user calls UIServer.getInstance().attach(StatsStorage) the provided StatsStorage instance will provide callbacks to the UI whenever something changes. For example, new information from a trained network is added to the StatsStorage from the StatsListener, the modules that are registered for callbacks (of that type) will be notified. The UI modules can then query the StatStorage instance (or not) to get the relevant information for displaying in the UI.

Each UI module specifies the callbacks it wants to receive via Strings (UIModule.getCallbackTypeIDs). Each String is a key that must match the TypeID of the data to listen for; consequently, there is a correspondence between the TypeID of the generating class (StatsListener, for example) and the TypeID that the UI module wants to receive. UI modules may specify zero or more callback type IDs. Any information that is not relevant to the UI module (i.e., doesn't match a specified TypeID for the module) won't be forwarded on to the UI module.

Internationalization

The Play framework does provide an internationalization mechanism, though this was found to be problematic when running Play via a Maven project. Consequently, DL4J defines its own I18N implementation, that is functionally similar to the Play mechanism.

The I18N interface, and the DefaultI18N class define getMessage(String) methods. For example, getMessage() Currently (as of 0.7.2), the language setting is server side not client side - thus only one language can be shown per UI server. Furthermore, the implementation is currently set to fall back to English.

The actual content for internationalization is present under the resources/dl4j_i18n directory. Each file within this directory should contain an ISO639 language code (en, ja, de etc) as the extension. Conceptually, the files may be separated; in practice, the contents of all files (for the relevant language) are In practice, just add a snippet such as @i18n.getMessage("train.pagetitle") to the HTML template to get the appropriate entry for the current language. See the train module UI pages for more examples.

Note also that it is necessary to provide an I18N instance to the templates. See the TrainModule routing section for an example on how to do this.