Generating a SAMSON Extension

SAMSON provides the ability to generate a template for a SAMSON Extension with all necessary classes, which significantly reduces development time. This is done thanks to the SAMSON SDK Extension Generator provided with the SAMSON SDK. The generated source code compiles immediately, and the compiled SAMSON Extension runs as is (although it is still minimal and probably not yet what you want it to do). Comments in the source code provide guidance during development.

To generate a new SAMSON Extension, you first need to add SAMSON SDK Extension Generator. After adding it, launch SAMSON. If it is already running, relaunch it so that SAMSON can download and install the newly added extension.

Running the Extension Generator

In the SAMSON menu, go to Home > Apps > Developer > Generate a new extension.

Let us now follow the generation procedure.

Once you open the Generate a new extension app, click the Generate a new SAMSON Extension button. This starts the generation wizard.

The first page (seen below) lets you enter the path to the folder where you develop SAMSON Extensions. For your first SAMSON Extension, create an empty folder somewhere and indicate the path to it (click the Browse... button if necessary). This development folder may be distinct from the folder where SAMSON SDK is stored. When you later create more SAMSON Extensions, you may reuse this folder again. For convenience, once specified the path will be retained for the next time you run the SAMSON Extension Generator.

The second page lets you enter the name of your new SAMSON Extension and its description. The name will be included in generated class names and should not contain any whitespace (this is automatically removed for you). More precisely, if the name of your SAMSON Extension is MyElement, all generated files will begin with SEMyElement (SE stands for SAMSON Extension). Both a name and a description must be entered before moving to the next page. When you are done, click Next.

You may now add classes to your new SAMSON Extension on the third page of the Extension Generator (shown below). Choose the type of class you want to add to your SAMSON Extension from the combo box. You can add one or several of the following class types (each one plays a specific role; please check out the SAMSON Extension section to learn more):

• App - a class that may provide any type of functionality.
• Editor - a class that receives user interaction events (e.g. mouse and keyboard events) from SAMSON, which may be used to provide potentially complex editing functionality.
• Exporter - a class dedicated to exporting content from the SAMSON Data Graph to files.
• Importer - a class dedicated to parsing and importing files.
• Interaction model - a class responsible for computing energies and forces and is used in SAMSON to perform various modeling and simulation tasks.
• State updater - a class devoted to implementing state updates and responsible for, e.g., updating atom positions.
• Visual model - a class whose sole purpose is to provide visual representations in the SAMSON viewport.
• Node - a class for implementing custom nodes that can be used in the SAMSON's data graph.

As in the figure below, give each class a distinct name. The name will be part of the corresponding generated files. For example, if you call a class VisualModel, generated files will include SEMyElementVisualModel in their names. Press Next to reach the generation page.

The generation page (below) is pretty simple to use, and only contains a Generate button. The window shows the contents of the folder where your SAMSON Extension will be generated.

Press the Generate button, and voilà, the Extension Generator creates a compilable, workable SAMSON Extension that you may now complete.

Directory structure

The SAMSON SDK Extension Generator generates a SAMSON Extension with a specific directory structure. In the Elements folder, you should now have two subfolders (build and MyElement) and a CMakeLists.txt file. As the name indicates, the build folder is used to build your SAMSON Extensions, while the MyElement folder contains the code generated by the Extension Generator. The CMakeLists.txt file tells CMake how to generate a project for your preferred development environment. When you later generate new SAMSON Extensions, they will be added as subfolders in the Elements folder, and the CMakeLists.txt file will be automatically updated to include them in the development project.

Each generated SAMSON Extension folder contains at least six sub-folders (some empty), and a CMakeLists.txt file indicating to CMake how to build the SAMSON Extension:

• data: this folder is initially empty, but should be used to store data that should be distributed with the SAMSON Extension (for example, a parameter file for an interaction model).
• doc: this folder is initially empty, and should contain html documentation about your SAMSON Extension.
• form: this folder contains the Qt forms (*.ui) that help users interact with your SAMSON Extension (for example, the GUI of an App).
• include: this folder contains the header files (*.hpp) of your SAMSON Extension.
• resource: this folder contains various resources for your SAMSON Extension (e.g. translation files and icons corresponding to your classes GUIs).
• source: this folder contains the source files (*.cpp) of your SAMSON Extension.

Translations and icons

Translations are handled through Qt's internationalization mechanism, while icons are image files that you should replace to personalize your user interface. For example, the icon of an app is visible in Home > Apps, while the icon of a visual model is visible in the title bar of its property window.

Generated code

The generated code contains comments to help you complete functions. Search for SAMSON Extension generator pro tip to determine which functions you may want to complete to achieve specific things.

Tip

See the Tutorials section for examples of various extensions.

Now let's build a SAMSON Extension.