Skip to content

Developers Manual

Jump to bottom Edit New page
Fabrizio Nunnari edited this page Feb 21, 2023 · 32 revisions

Visual Scene Maker - Developers manual

Setting up the development environment

  • The suggested IDE for develop the VSM is IntelliJ Idea.
  • IntelliJ comes bundled with JDK 11 (tested on v2020.2), which is required for working with VSM. To simply install the JDK, for example to develop with another editor, you can get it here.
  • Clone the VSM repository using git clone https://github.com/SceneMaker/VisualSceneMaker.git.
  • Open the project directory from IntelliJ .

The VSM uses gradle as its build tool. In the project root folder, you can find the build file build.gradle. IntelliJ detects this automatically and downloads all the needed dependencies at first build.

Running from within the editor

  • In IntelliJ you can launch VSM from the Scenemaker3.main() method. You can navigate to the class (src/main/java/de/dfki/vsm/) and click the green arrow next to the method. The run configuration should look like this. running from the editor

  • And an example from IntelliJ 2022. running from the editor IntelliJ 2022

  • In the VM options you might want to add a -ea in order to enable assertions check (Modify options -> Add VM options -> -ea)

Troubleshooting

  • If, while opening a project, you get a message related to CUPS, caused by java.lang.ClassNotFoundException: de.dfki.vsm.model.scenescript.CUP$ScriptParser$actions, it is because the parser generation has not been run yet. This is a flaw in the building/running procedure. See Issue 216.

    • As a workaround solution, run in order the following gradle tasks:
      • build clean
      • build classes

  • In case of a java.lang.UnsupportedClassVersionError upon importing the project the Gradle JVM needs to be set to Java 11 under Gradle settings: Menu IntelliJ Idea -> Preferences... -> Build, Execution, Deployment --> Build Tools -> Gradle -> Gradle JVM.

    grade settings

Running with extended logging

To keep the console output clean VSM does not ouput all log messages by default. The log level can be increased for Debugging via the environment variable LOG_LEVEL. Available options are:

  • OFF
  • SEVERE
  • WARNING
  • INFO
  • CONFIG
  • FINE
  • FINER
  • FINEST
  • ALL

Writing an Extension for Visual Scene Maker

For instructions on how to write an extension, please see the dedicated manual: Writing an Extension

We also have a page dedicated on how to write an extension to read data from the Social Signal Interpretation (SSI, https://hcm-lab.de/projects/ssi/) tool from the University of Augsburg. See here: Writing an SSI plugin

Building a new release

  • Update the version of the release in:
  • Navigate to the gradle tool window (tiny elefant icon). From the VisualSceneMaker gradle project, follow the hierarchy of Tasks and locate Tasks -> build -> build.
    • gradle build task location
  • Double click to start the building process.
  • The VSM executable is located in the folder build->libs
    • VSM jar location

Using the VisualSceneMaker in a Java application.

Basically there are 2 ways how to employ the VisualSceneMaker in an existing Java application.

VisualSceneMaker Editor mode

The following code snipped can be used in Java applications to create the graphical user interface of the VisualSceneMaker. The needed parameter file should point to a VisualSceneMaker project directory.

// Get the singelton editor instance
final EditorInstance sEditor = EditorInstance.getInstance();
// Get an editor project from file
sEditor.openProject(file);
// Show the singelton editor instance
sEditor.setVisible(true);

VisualSceneMaker Runtime mode

This code snippet can be used in order to execute an existing Sceneflow+Scene model (a project) without the graphical user interface. The needed parameter file should point to a VisualSceneMaker project directory.

// Get an editor project from file
final RunTimeProject data = new RunTimeProject(file);
// Get the singelton runtime instance
final RunTimeInstance sRunTime = RunTimeInstance.getInstance();
// Launch the runtime with the project
if (sRunTime.launch(data)) {
  // Start the runtime with the project
  if (sRunTime.start(data)) {
    // Wait until user aborts execution
    System.err.println("Press Key To Abort ...");
    // TODO: Stop waiting if execution
    // has been aborted in another way
    try {
      final int in = System.in.read();
      if (in != -1) {
        // Aborting the execution now
      }
    } catch (final IOException exc) {
      // Do nothing
    } finally {
      // Abort the runtime with the project
      sRunTime.abort(data);
      // Unload the project from the runtime
      sRunTime.unload(data);
    }
  }
}

Compared to the editor mode, the project is registered by sRunTime.launch(data) in the VisualSceneMaker runtime for execution. The (obvious) next step is to execute the project by sRunTime.start(data). The projects ends if it gets aborted sRunTime.abort(data). There are methods to stop, pause and resume (see API). In order to cleanup the project is unregistered sRunTime.unload(data).

Updating the parsers

VSM internally contains a couple of parsers that are used to define the syntax for the scene scripts and for the mathematical expressions on the nodes. The parsers are generated by the Flex/JCup libraries.

The scene script parser

The syntax/grammar of the scene flow is defined by:

core/src/main/java/de/dfki/vsm/model/scenescript/
    lexxer.jflex
    parser.jcup

Whenever one of those two files is updated, the lever and the parser must be rescanned and the parser files regenerated:

core/src/main/java/de/dfki/vsm/model/scenescript/
    ScriptLexxer.java
    ScriptFields.java
    ScriptParser.java

File updateParsers.sh at top level invokes the required pair of command lines.

The scene flow parser

TODO

Maintaining the Documentation

We maintain the documentation of Visual Scene Maker through Wiki pages of the main code repository (https://github.com/SceneMaker/VisualSceneMaker/wiki).

The documentation language is hence MarkDown: https://daringfireball.net/projects/markdown/syntax

The suggested way for adding significant contributions (text, images, and other binary stuff) to the documentation is by cloning the wiki on your local computer, editing everything locally, and the commit/push back to the repository.

git clone https://github.com/SceneMaker/VisualSceneMaker.wiki.git
cd VisualSceneMaker.wiki
...
# For example, to add local stuff
git pull
mkdir images  # if needed
# ... edit your stuff, add images
git add images newpage.md
git commit -m 'added tons of docs'
git push

The suggested tool for editing MarkDown is Visual Studio Code (https://code.visualstudio.com/) plus the markdownlint extension (https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint).

Additional resources, Papers

Add a custom footer
Add a custom sidebar
Clone this wiki locally