diff --git a/README.md b/README.md index 88fef9746b..0e7bd889f8 100644 --- a/README.md +++ b/README.md @@ -4,64 +4,28 @@ [![Build status](https://ci.appveyor.com/api/projects/status/jrtnh313libyy3vj/branch/master?svg=true)](https://ci.appveyor.com/project/megamolservice/megamol/branch/master) -MegaMol is a visualization middleware used to visualize point-based molecular data sets. This software is developed within the ​Collaborative Research Center 716, subproject ​D.3 at the ​[Visualization Research Center (VISUS)](https://www.visus.uni-stuttgart.de/en) of the University of Stuttgart and at the ​Computer Graphics and Visualization Group of the TU Dresden. +MegaMol is a visualization middleware used to visualize point-based molecular data sets. This software is developed within the Collaborative Research Center 716, subproject ​D.3 at the ​[Visualization Research Center (VISUS)](https://www.visus.uni-stuttgart.de/en) of the University of Stuttgart and at the ​Computer Graphics and Visualization Group of the TU Dresden. -MegaMol succeeds ​MolCloud, which has been developed at the University of Stuttgart in order to visualize point-based data sets. MegaMol is written in C++, and uses an OpenGL as Rendering-API and GLSL-Shader. It supports the operating systems Microsoft Windows and Linux, each in 32-bit and 64-bit versions. In large parts, MegaMol is based on VISlib, a C++-class library for scientific visualization, which has also been developed at the University of Stuttgart. +MegaMol succeeds MolCloud, which has been developed at the University of Stuttgart in order to visualize point-based data sets. MegaMol is written in C++, and uses an OpenGL as Rendering-API and GLSL-Shader. It supports the operating systems Microsoft Windows and Linux, each in 64-bit version. In large parts, MegaMol is based on VISlib, a C++-class library for scientific visualization, which has also been developed at the University of Stuttgart. -## Changelog -​See [changelog](https://github.com/UniStuttgart-VISUS/megamol/wiki/Changelog) for newly available features in the current version of MegaMol. - - -## Building MegaMol -### Linux -1. Clone the MegaMol repository -2. Create a build folder -3. Invoke `cmake` inside the build folder -4. Execute `make` to build MegaMol -5. Run `make install` to create your MegaMol installation -6. Test Megamol with - - $ ./megamol.sh -p ../examples/testspheres.lua - +## Manual -### Windows -1. Clone the MegaMol repository -2. Use the cmake GUI to configure MegaMol - 1. The configuration creates a `sln` file inside the build folder -3. Open the `sln` file with *Visual Studio* -4. Use the `ALL_BUILD` target to build MegaMol -5. Use the `INSTALL` target to create your MegaMol installation -6. Test Megamol with +See the [manual](docs/manual.md) for detailed instructions on how to build and use MegaMol. - > mmconsole.exe -p ..\examples\testspheres.lua - - -## MegaMol Configurator -MegaMol offers a configurator GUI (C#) that runs with .Net Framework 4. -It runs also on Linux with Mono 3.2.8 (except for the analysis function and indirect-start functions). +## Changelog -## How to use MegaMol -For a detailed description have a look at the [manual](docs/manual.md). +​See the [changelog](https://github.com/UniStuttgart-VISUS/megamol/wiki/Changelog) for newly available features in the current version of MegaMol. +## License -## Using the plugin template -1. Copy the template folder -2. Rename the copied folder to the intended plugin name -3. Execute the instawiz.pl script inside the new folder - 1. The script detects the plugin name - 2. Autogenerate the GUID -4. Remove instawiz.pl -5. Add libraries/dependencies to `CMakeLists.txt` (optional) -6. Implement the content of your plugin -7. Write a `Readme.md` for your plugin (mandatory) -8. Add the folder to your local git +See the [license](LICENSE) file. ## Citing MegaMol -Please use one of the following methods to reference the MegaMol project. +Please use one of the following methods to reference the MegaMol project. **MegaMol – A Comprehensive Prototyping Framework for Visualizations** P. Gralka, M. Becher, M. Braun, F. Frieß, C. Müller, T. Rau, K. Schatz, C. Schulz, M. Krone, G. Reina, T. Ertl @@ -140,7 +104,7 @@ In Proceedings of IEEE Pacific Visualization Symposium 2009: 65 - 72, 2009 } # -**MegaMol™ project website** +**MegaMol project website** [https://megamol.org](https://megamol.org) @misc{megamol, diff --git a/console/extra/megamolconfig.lua.in b/console/extra/megamolconfig.lua.in index 0654a7d9e5..de33f31db1 100644 --- a/console/extra/megamolconfig.lua.in +++ b/console/extra/megamolconfig.lua.in @@ -1,11 +1,11 @@ -- Standard MegaMol Configuration File -- - -print("I am the Standard MegaMol configuration!") +print("Standard MegaMol Configuration:") basePath = "${CMAKE_INSTALL_PREFIX}/" mmSetLogLevel("*") -- LogLevel: None=0,Error=1,Warn=100,INFO=200,ALL=* mmSetEchoLevel("*") +-- mmSetLogFile("") mmSetAppDir(basePath .. "${MMPLG_DIR}") mmAddShaderDir(basePath .. "share/shaders") mmAddResourceDir(basePath .. "share/shaders") @@ -21,4 +21,3 @@ mmSetConfigValue("fullscreen", "off") mmSetConfigValue("vsync", "off") mmSetConfigValue("useKHRdebug", "off") mmSetConfigValue("arcball", "off") - diff --git a/docs/devguide/devguide.md b/docs/devguide/devguide.md index aabd6c3415..96c82215a8 100644 --- a/docs/devguide/devguide.md +++ b/docs/devguide/devguide.md @@ -6,15 +6,54 @@ This guide is intended to give MegaMol developers a useful insight into the inte ## Contents -- [MegaMol Developer Guide](#megamol-developer-guide) - - [Bi-Directional Communication across Modules](#bi-directional-communication-across-modules) - - [Synchronized Selection across Modules](#synchronized-selection-across-modules) - - [Graph Manipulation](#graph-manipulation) - - [Build System](#build-system) -- [License](#license) +- [Create new Plugin](#create-new-plugin) + - [Add own plugin using the template](#add-own-plugin-using-the-template) +- [Bi-Directional Communication across Modules](#bi-directional-communication-across-modules) + - [Recipe](#recipe) + - [Usage: ```DATACallRead```](#usage-datacallread) + - [Usage: ```DataCallWrite```](#usage-datacallwrite) +- [Synchronized Selection across Modules](#synchronized-selection-across-modules) + - [FlagStorage](#flagstorage) + - [FlagStorage_GL](#flagstorage_gl) +- [Graph Manipulation](#graph-manipulation) + - [Graph Manipulation Queues](#graph-manipulation-queues) +- [Build System](#build-system) + - [External dependencies](#external-dependencies) + - [Using external dependencies](#using-external-dependencies) + - [Adding new external dependencies](#adding-new-external-dependencies) + - [Header-only libraries](#header-only-libraries) + - [Built libraries](#built-libraries) +- [GUI Parameter Widgets](#gui-parameter-widgets) + + + + +----- +## Create new Plugin + + + +### Add own plugin using the template +1. Copy the template folder `../megamol/plugins/template`. +2. Rename the copied folder to the intended plugin name. +3. Execute the `instawiz.pl` script inside the new folder. + 1. The script detects the plugin name. + 2. Autogenerate the GUID. +4. Remove `instawiz.pl`from the new plugins folder. +5. Add libraries/dependencies to `CMakeLists.txt` (optional, see [external dependencies](#external-dependencies)). +6. Implement the content of your plugin. +7. Write a `Readme.md` for your plugin (mandatory). +8. Add the folder to your local git. + + + +----- ## Bi-Directional Communication across Modules Bi-Directional Communication, while in principle enabled on any Call in MegaMol, has severe implications when data can be changed at an arbitrary end and multiple Modules work on the data that is passed around. The current state of knowledge is described here and should be used for any and all Calls moving forward. @@ -54,6 +93,9 @@ A module with slots for both directions by convention should first execute the r - **ALWAYS** set the data in the call, supplying your version. - issue the Call: ```(*call)(DATACallRead::CallGetData)``` or your specialized version + + +----- ## Synchronized Selection across Modules You can and should use one of the ```FlagStorage``` variants to handle selection. These modules provide an array of ```uint32_t``` that is implicitly index-synchronized (think row, record, item) to the data available to a renderer. Indices are accumulated across primitives and primitive groups, so if you employ these, you need to take care yourself that you always handle Sum_Items flags and apply proper **offsets** across, e.g., particle lists. @@ -68,6 +110,9 @@ The flags here are stored uniquely, resembling a unique pointer or Rust-like mem This FlagStorage variant relies on a shader storage buffer and does not move any data around. It is implicitly synchronized by single-threaded execution in OpenGL. You still need to synchronize with the host if you want to download the data though. It still keeps track of proper versions so you can detect and act on changes, for example when synchronizing a FlagStorage and a FlagStorage_GL. + + +----- ## Graph Manipulation There are appropriate methods in the ```megamol::core::CoreInstance``` to traverse, search, and manipulate the graph. @@ -108,21 +153,33 @@ It causes the graph updater to stop at the indicated event and delay further gra |paramSetRequestsFlushIndices| |groupParamSetRequestsFlushIndices| + + +----- ## Build System -For building MegaMol, CMake is used. For developers, two aspects are of importance: adding new plugins, and [adding and using external dependencies](#external-dependencies). +For building MegaMol, CMake is used. For developers, two aspects are of importance: [adding new plugins](#create-new-plugin), and [adding and using external dependencies](#external-dependencies). ### External dependencies +**All externals must be build STATIC now!** +The installation of shared libraries was removed, therefore the megamol binary will not find the so/dll files of externals if they are used as SHARED library. + The system for including external dependencies in MegaMol is a process split into two phases, corresponding to CMake configuration and the build process. -In the CMake configuration run, in which the external is first requested, it is downloaded from a git repository by providing a URL and tag (or commit hash), and configured in a separate process and folder. This is done to prevent global CMake options from clashing. In later CMake configuration runs, this configuration of the external dependencies is not re-run, except when manually requested by setting the appropriate CMake cache variable ```EXTERNAL__NEW_VERSION``` to ```TRUE```, or when the URL, tag or build type change. +In the CMake configuration run, in which the external is first requested, it is downloaded from a git repository by providing a URL and tag (or commit hash), and configured in a separate process and folder. +This is done to prevent global CMake options from clashing. +In later CMake configuration runs, this configuration of the external dependencies is not re-run, except when manually requested by setting the appropriate CMake cache variable ```EXTERNAL__NEW_VERSION``` to ```TRUE```, or when the URL, tag or build type change. -When building MegaMol, all external dependencies are only built if they have not been built before. Afterwards, only by setting ```EXTERNAL__NEW_VERSION``` to ```TRUE``` can the build process be triggered again. This ensures that they are not rebuilt unnecessarily, but built when their version change. +When building MegaMol, all external dependencies are only built if they have not been built before. +Afterwards, only by setting ```EXTERNAL__NEW_VERSION``` to ```TRUE``` can the build process be triggered again. +This ensures that they are not rebuilt unnecessarily, but built when their version change. #### Using external dependencies -External dependencies are split into two categories: header-only libraries and libraries that have to be built into a static (```.a```/```.lib```) or dynamic (```.so```/```.dll```) library. Both kinds are defined in the ```CMakeExternals.cmake``` file in the MegaMol main directory and can be requested in the plugins using the command ```require_external()```. Generally, this command makes available the target ``````, which provides all necessary information on where to find the library and include files. +External dependencies are split into two categories: header-only libraries and libraries that have to be built into a static (```.a```/```.lib```) library. +Both kinds are defined in the ```CMakeExternals.cmake``` file in the MegaMol main directory and can be requested in the plugins using the command ```require_external()```. +Generally, this command makes available the target ``````, which provides all necessary information on where to find the library and include files. #### Adding new external dependencies @@ -148,7 +205,8 @@ add_external_headeronly_project( | `````` | Relative directory where the include files can be found, usually ```include```. Defaults to the main source directory. | | `````` | Targets this library depends on, if any. | -In the following example, the library Delaunator is downloaded from ```https://github.com/delfrrr/delaunator-cpp.git``` in its version ```v0.4.0```. The header files can be found in the folder ```include```. +In the following example, the library Delaunator is downloaded from ```https://github.com/delfrrr/delaunator-cpp.git``` in its version ```v0.4.0```. +The header files can be found in the folder ```include```. ``` add_external_headeronly_project(Delaunator @@ -169,12 +227,13 @@ Additionally, information about the header-only libraries can be queried with th ##### Built libraries -Libraries that are built into static or dynamic libraries, follow a process executing two different commands. The first command is responsible for setting up the project, while the second command creates the interface targets. +Libraries that are built into static libraries, follow a process executing two different commands. +The first command is responsible for setting up the project, while the second command creates the interface targets. Similarly to the header-only libraries, the setup uses a command specifying the source and type of the library, additionally providing information for the configuration and build processes: ``` -add_external_project( SHARED|STATIC +add_external_project( STATIC GIT_REPOSITORY [GIT_TAG ] [PATCH_COMMAND ...] @@ -188,7 +247,7 @@ add_external_project( SHARED|STATIC | Parameter | Description | | ----------------------------- | ----------- | | `````` | Project name, usually the official name of the library or its abbreviation. | -| ```SHARED \| STATIC``` | Indicate to build a shared (```.so```/```.dll```) or static (```.a```/```.lib```) library. Shared libraries are always built as Release, static libraries according to user selection. | +| ```STATIC``` | Indicate to build a static (```.a```/```.lib```) library. Static libraries are always built according to user selection. | | `````` | URL of the git repository. | | `````` | Tag or commit hash for getting a specific version, ensuring compatibility. Default behavior is to get the latest version. | | `````` | Command that is run before the configuration step and is mostly used to apply patches or providing a modified ```CMakeLists.txt``` file. | @@ -213,39 +272,36 @@ add_external_library( [PROJECT ] | `````` | Target name, for the main target this is usually the official name of the library or its abbreviation. | | `````` | If the target name does not match the name provided in the ```add_external_project``` command, the project has to be set accordingly. | | `````` | The created library file, in case of a shared library a ```.so``` or ```.dll``` file, or ```.a``` or ```.lib``` for a static library. | -| `````` | If the library is a shared library, this defines the import library (```.lib```) on Windows systems. This has to be set for shared libraries. | | `````` | Additional libraries the external library depends on. | | `````` | Specify a suffix for the debug version of the library. The position of this suffix has to be specified by providing `````` in the library name and has to match the debug suffix provided to the ```add_external_project``` command. | -An example for a dynamic library is as follows, where the ```tracking``` library ```v2.0``` is defined as a dynamic library and downloaded from the VISUS github repository at ```https://github.com/UniStuttgart-VISUS/mm-tracking```. It builds two libraries, ```tracking``` and ```NatNetLib```, and uses the CMake flag ```-DCREATE_TRACKING_TEST_PROGRAM=OFF``` to prevent the building of a test program. Both libraries are created providing the paths to the respective dynamic and import libraries. Note that only the ```NatNetLib``` has to specify the project as its name does not match the external library. - -``` -add_external_project(tracking SHARED - GIT_REPOSITORY https://github.com/UniStuttgart-VISUS/mm-tracking - GIT_TAG "v2.0" - BUILD_BYPRODUCTS - "/bin/tracking.dll" - "/lib/tracking.lib" - "/bin/NatNetLib.dll" - "/lib/NatNetLib.lib" - CMAKE_ARGS - -DCREATE_TRACKING_TEST_PROGRAM=OFF) -``` - -``` -add_external_library(tracking - LIBRARY "bin/tracking.dll" - IMPORT_LIBRARY "lib/tracking.lib") -``` +An example for a static library is as follows, where the ```tracking``` library ```v2.0``` is defined as a static library and downloaded from the VISUS github repository at ```https://github.com/UniStuttgart-VISUS/mm-tracking```. +It builds two libraries, ```tracking``` and ```NatNetLib```, and uses the CMake flag ```-DCREATE_TRACKING_TEST_PROGRAM=OFF``` to prevent the building of a test program. +Both libraries are created providing the paths to the respective import libraries. +Note that only the ```NatNetLib``` has to specify the project as its name does not match the external library. ``` -add_external_library(natnet - PROJECT tracking - LIBRARY "bin/NatNetLib.dll" - IMPORT_LIBRARY "lib/NatNetLib.lib") + set(TRACKING_LIB "lib/tracking.lib") + set(TRACKING_NATNET_LIB "lib/NatNetLib.lib") + + add_external_project(tracking STATIC + GIT_REPOSITORY https://github.com/UniStuttgart-VISUS/mm-tracking.git + GIT_TAG "v2.0" + BUILD_BYPRODUCTS + "/${TRACKING_LIB}" + "/${TRACKING_NATNET_LIB}" + CMAKE_ARGS + -DCREATE_TRACKING_TEST_PROGRAM=OFF) + + add_external_library(tracking + LIBRARY ${TRACKING_LIB}) + + add_external_library(natnet + PROJECT tracking + LIBRARY ${TRACKING_NATNET_LIB}) ``` -Further examples on how to include dynamic and static libraries can be found in the ```CMakeExternals.cmake``` file in the MegaMol main directory. +Further examples on how to include static libraries can be found in the ```CMakeExternals.cmake``` file in the MegaMol main directory. Additionally, information about the libraries can be queried with the command ```external_get_property( )```, where variable has to be one of the provided variables in the following table, and at the same time is used as local variable name for storing the queried results. @@ -259,16 +315,9 @@ Additionally, information about the libraries can be queried with the command `` | SHARED | Indicates that the library was built as a dynamic library if ```TRUE```, or a static library otherwise. | | BUILD_TYPE | Build type of the output library on single-configuration systems. | -# License -MegaMol is freely and publicly available as open source following the terms of the BSD License. -Copyright (c) 2015, MegaMol Team TU Dresden, Germany Visualization Research Center, University of Stuttgart (VISUS), Germany -Alle Rechte vorbehalten. -All rights reserved. -Redistribution and use in source and binary forms, with or without modification, are permitted -provided that the following conditions are met: -- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. -- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. -- Neither the name of the MegaMol Team, TU Dresden, University of Stuttgart, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. + +----- +## GUI Parameter Widgets -THIS SOFTWARE IS PROVIDED BY THE MEGAMOL TEAM "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE MEGAMOL TEAM BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +See separate [developer information for GUI plugin](../../plugins/gui#information-for-developers). diff --git a/docs/manual.md b/docs/manual.md index 1641211a55..857ff04ed4 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -4,17 +4,45 @@ ## Contents -- [Contents](#contents) - - [Overview](#overview) - - [Installation and Setup](#installation-and-setup) - - [Viewing Data Sets](#viewing-data-sets) - - [Jobs: Converting Data](#jobs) - - [Advanced Usage](#advanced-usage) +- [Overview](#overview) +- [Installation and Setup](#installation-and-setup) + - [Building from Source](#building-from-source) + - [Microsoft Windows](#microsoft-windows) + - [Linux (Ubuntu)](#linux-ubuntu) + - [Command Line Arguments](#command-line-arguments) + - [Configuration File](#configuration-file) + - [General Settings](#general-settings) + - [Logging](#logging) + - [Application, Shaders and Resources](#application-shaders-and-resources) + - [Plugins](#plugins) + - [Global Settings](#global-settings) + - [Test Installation](#test-installation) + - [Examples](#examples) +- [Viewing Data Sets](#viewing-data-sets) + - [Modules, Views and Calls](#modules-views-and-calls) + - [Modules and Calls](#modules-and-calls) + - [Views](#views) + - [View Interaction](#view-interaction) +- [Project Files](#project-files) +- [Making High-Resolution Screenshots](#making-high-resolution-screenshots) + - [GUI](#gui) + - [Project File](#project-file) + - [Framebuffer Size](#framebuffer-size) + - [ScreenShooter Module](#screenshooter-module) +- [Making Simple Videos](#making-simple-videos) +- [Reproducibility](#reproducibility) + + - + +----- ## Overview MegaMol is a visualization middleware used to visualize point-based molecular datasets. @@ -22,514 +50,643 @@ The MegaMol project was started in the Collaborative Research Center 716, subpro Today, it is governed by a number of teams at the TU Dresden and the University of Stuttgart. The goal of the project is to provide a software base for visualization research and to provide a stable environment to deploy newest visualization prototypes to application domain researchers. MegaMol is not a visualization tool. MegaMol is a platform for visualization research. -Visit the project [website](https://github.com/UniStuttgart-VISUS/megamol.git "Megamol Homepage") for downloads and more information. +Visit the project [website](https://megamol.org/ "MegaMol Homepage") for downloads and more information. -### License +**If you faced any trouble during installation or if you have any further questions concerning MegaMol, we encourage you to contact the developer team by opening an [issue](https://github.com/UniStuttgart-VISUS/megamol/issues/new) on github!** -MegaMol is freely and publicly available as open source following the terms of the BSD License. -Copyright (c) 2015, MegaMol Team TU Dresden, Germany Visualization Research Center, University of Stuttgart (VISUS), Germany -Alle Rechte vorbehalten. -All rights reserved. -Redistribution and use in source and binary forms, with or without modification, are permitted -provided that the following conditions are met: -- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. -- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. -- Neither the name of the MegaMol Team, TU Dresden, University of Stuttgart, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE MEGAMOL TEAM "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE MEGAMOL TEAM BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - + +----- ## Installation and Setup -This chapter discusses installation and setup of MegaMol , either from the pre-built binary packages or the source code. -The latter is, however, meant for experienced users. MegaMol targets Microsoft Windows (Windows 7 or newer, x86 and x64) and Linux (x64) as supported environments. +This chapter discusses installation and setup of MegaMol from source code. +MegaMol targets Microsoft Windows (Windows 7 or newer, x64) and Linux (x64) as supported environments. Currently, Ubuntu is used as Linux distribution for development. -Further platforms are not considered during the development. While MegaMol might work on further platforms, the development team will currently not grant any support for problems with these environments. +Further platforms are not considered during the development. +While MegaMol might work on further platforms, the development team will currently not grant any support for problems with these environments. + ### Building from Source -#### Windows +It is recommended to use the latest [release 1.3](https://github.com/UniStuttgart-VISUS/megamol/releases/tag/v1.3) version of the source code. +All bleeding edge features are available in the current [main branch](https://github.com/UniStuttgart-VISUS/megamol/tree/master). + +**Note**: +The *OSPRay plugin* is currently disabled by default. +See the plugins' [readme](https://github.com/UniStuttgart-VISUS/megamol/blob/master/plugins/OSPRay_plugin/Readme.md) for additional instructions on how to enable it. -For Windows, you have to install [CMake](https://cmake.org/), and load the `CMakeLists.txt` present in the root directory of the repository. -Next, click `Configure` a few times (until all red entries disappear). -Then click `Generate` to generate the build files. + +#### Microsoft Windows -
- -CMake Windows -

-Screenshot of `cmake-gui` after generating build files. -

-
+1. Download and unzip the source code of the latest [release](https://github.com/UniStuttgart-VISUS/megamol/releases/tag/v1.3) into a new directory (e.g. `megamol`). +2. You have to install [CMake](https://cmake.org/), and load the `CMakeLists.txt` present in the root directory of the repository. +3. Create a new `build` directory. +4. As generator, it is recommended to use the latest version of [Visual Studio](https://visualstudio.microsoft.com/downloads/) (Community Edition is free to use) with default native compilers and for the platform x64. +5. Next, click `Configure` a few times (until all red entries disappear). +6. Change the `CMAKE_INSTALL_PREFIX` in order to change the destination directory of the installed files and configure once more. +7. Then click `Generate` to generate the build files. +8. The configuration creates a `megamol.sln` file inside the build directory. +9. Open the `megamol.sln` file with *Visual Studio*. +10. Use the `ALL_BUILD` target to build MegaMol. +11. Afterwards, use the `INSTALL` target to create your MegaMol installation. +12. The binary `megamol.exe` is located in the default installation path `../megamol/build/install/bin`. -Note: the *OSPRay plugin* is currently disabled by default, since you need to install its dependencies manually and locate them manually as well. Ideally, you just download [OSPRay](https://www.ospray.org/downloads.html) and adjust the `CMAKE_PREFIX_PATH`. However, if you want to compile OSPRay yourself, you need to install [ISPC](https://ispc.github.io/), [TBB](https://www.threadingbuildingblocks.org/), and [Embree](https://embree.github.io/) first (binary versions are okay). +![CMake Windows](pics/cmake_windows.png) +*Screenshot of `cmake-gui` after generating build files.* -#### Linux + +#### Linux (Ubuntu) -Tested with: +Since the full support of some C++17 functionality is required (e.g. *std::filesystem*), a `gcc` version equal or greater than **8** is required (with `CMAKE_CXX_FLAGS` appended by `--std=c++17`). +**Latest tested version:** $ cat /proc/version - Linux version 4.4.0-93-generic (buildd@lgw01-03) (gcc version 5.4.0 20160609 (Ubuntu 5.4.0-6ubuntu1~16.04.4) ) #116-Ubuntu SMP Fri Aug 11 21:17:51 UTC 2017 + Linux version 5.8.0-41-generic (buildd@lgw01-amd64-003) (gcc (Ubuntu 9.3.0-17ubuntu1~20.04) 9.3.0, GNU ld (GNU Binutils for Ubuntu) 2.34) #46~20.04.1-Ubuntu SMP Mon Jan 18 17:52:23 UTC 2021 -As prerequisites, following packages from the repository are required: +1. As prerequisites, following packages from the repository are required: - $ sudo apt install cmake-curses-gui git libgl1-mesa-dev libncurses5-dev \ - uuid-dev libexpat-dev libunwind-dev libxrandr-dev \ - libxinerama-dev libxcursor-dev libxi-dev libglu1-mesa-dev + `$ sudo apt install cmake-curses-gui git libgl1-mesa-dev libncurses5-dev uuid-dev libexpat-dev libunwind-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libglu1-mesa-dev` +2. First, download the source code from GitHub: -First, download the software package from GitHub: + `$ mkdir megamol` + `$ git clone https://github.com/UniStuttgart-VISUS/megamol.git megamol/` + `$ cd megamol/` - $ git clone https://github.com/UniStuttgart-VISUS/megamol.git +3. Checkout the latest release: -Create a build folder and switch to it: + `$ git checkout tags/v1.3 -b latest_release` - $ mkdir build; cd build +4. Create a build directory and switch to it: -Start the ncurses gui for cmake: + `$ mkdir build; cd build` - $ ccmake ../ +5. Check for required dependencies: + + `$ cmake ..` -Hit `c` a couple of times until the screen does not change, then hit `g` to generate build files. -On the console prompt, start `make`: +6. Start the ncurses gui for cmake: - $ make + `$ ccmake .` -### Configuration + - Configure the project repeatedly using `c` (and `e`) until no more changes are marked. + - Change the `CMAKE_INSTALL_PREFIX` in order to change the destination directory of the installed files. + - Then hit `g` to generate the build files. -After successfully installing or compiling MegaMol you should have all executable files inside your bin folder. Some setup still needs to be done. -Create a file `megamolconfig.lua` in this bin directory, with the following content (it may already exist). You will need to adjust the paths accordingly: +7. On the console prompt, start the building: -```lua - print('Hi, I am the megamolconfig.lua!') + `$ make && make install` - mmSetAppDir(".") + - Hint: Use the `-j` option for `make` to run the build in parallel threads. - mmSetLogFile("") - mmSetLogLevel(0) - mmSetEchoLevel('*') +8. The binary `megamol` is located in the default installation path `../megamol/build/install/bin`. + + +### Command Line Arguments - mmAddShaderDir("U:/home/user/src/megamol-dev/share/shaders") - mmAddResourceDir("U:/home/user/src/megamol-dev/share/resources") +Providing additional command line arguments allow individual configuration of global MegaMol behavior and settings. + - mmPluginLoaderInfo("U:/home/user/src/megamol-dev/bin", "*.mmplg", "include") +The following command line arguments are available: - mmSetConfigValue("*-window", "w720h720") - mmSetConfigValue("consolegui", "on") +**Note:** The *khrdebug* option is currently ignored and not applied. +``` + megamol.exe [OPTION...] + + --host arg address of lua host server, default: + tcp://127.0.0.1:33333 + --example load minimal test spheres example project + --khrdebug enable OpenGL KHR debug messages + --vsync enable VSync in OpenGL window + --window arg set the window size and position, accepted format: + WIDTHxHEIGHT[+POSX+POSY] + --fullscreen open maximized window + --nodecoration open window without decorations + --topmost open window that stays on top of all others + --nocursor do not show mouse cursor inside window + --help print help +``` + + +### Configuration File - mmSetConfigValue("LRHostEnable", "true") +After successfully compiling and installing MegaMol, you should have all executable files inside your `bin` directory (default: `../megamol/build/install/bin`). + +In the `bin` directory, you can find the default configuration file `megamolconfig.lua`: - return "Done with megamolconfig.lua. Bye!" +```lua + -- Standard MegaMol Configuration File -- + print("Standard MegaMol Configuration:") + + basePath = "C:/megamol/build/install/" + + mmSetLogLevel("*") -- LogLevel: None=0,Error=1,Warn=100,INFO=200,ALL=* + mmSetEchoLevel("*") + -- mmSetLogFile("") + mmSetAppDir(basePath .. "bin") + mmAddShaderDir(basePath .. "share/shaders") + mmAddResourceDir(basePath .. "share/shaders") + mmAddResourceDir(basePath .. "share/resources") + mmPluginLoaderInfo(basePath .. "bin", "*.mmplg", "include") + + computer = mmGetMachineName() + + mmSetConfigValue("*-window", "x5y35w1280h720") + mmSetConfigValue("consolegui", "on") + mmSetConfigValue("topmost", "off") + mmSetConfigValue("fullscreen", "off") + mmSetConfigValue("vsync", "off") + mmSetConfigValue("useKHRdebug", "off") + mmSetConfigValue("arcball", "off") ``` -The following paragraphs explain the essential steps of preparing a script in more detail. +The following paragraphs explain the essential steps of configuring MegaMol in more detail. + #### General Settings -Locate line 3 containing the tag `mmSetAppDir`. Both relative and absolute path should work here fine, it is recommended to change the path in this line to the global path to the MegaMol application bin directory, e.g.: - +Locate line 3 containing the variable `basePath`. +Both relative and absolute path should work here fine. +This path is set automatically and always has to fit the currently used execution path! ```lua - mmSetAppDir("U:/home/user/src/megamol-dev/bin") + basePath = "C:/megamol/build/install/" ``` -#### Logging -Line 6-8 configures the logging mechanism of MegaMol . Adjusting the value of *EchoLevel* changes the amount of log information printed on the console. Specifying a log file and the level informs MegaMol to write a log file and print the messages of the requested level into that file. The *LogLevel* is a numeric value. All messages with lower numeric values will be printed (or saved). The asterisk `*` stands for the highest numeric value, thus printing all messages. + +#### Logging +Line 4-6 configures the logging mechanism of MegaMol. +Adjusting the value of *EchoLevel* changes the amount of log information printed on the console. +Specifying a log file and the level informs MegaMol to write a log file and print the messages of the requested level into that file. +The *LogLevel* is a numeric value. +All messages with lower numeric values will be printed (or saved). +The asterisk `*` stands for the highest numeric value, thus printing all messages. ```lua - mmSetLogFile("") - mmSetLogLevel(0) + mmSetLogLevel('*') -- LogLevel: None=0,Error=1,Warn=100,INFO=200,ALL=* mmSetEchoLevel('*') + -- mmSetLogFile("") ``` -#### Shaders and Resources - -Line 9+10 show how to set your shader and resource directories. + +#### Application, Shaders and Resources +Line 7-10 define the application, shader and resource directories: ```lua - mmAddShaderDir("U:/home/user/src/megamol-dev/share/shaders") - mmAddResourceDir("U:/home/user/src/megamol-dev/share/resources") + mmSetAppDir(basePath .. "bin") + mmAddShaderDir(basePath .. "share/shaders") + mmAddResourceDir(basePath .. "share/shaders") + mmAddResourceDir(basePath .. "share/resources") ``` +The *Add...Dir* commands set the paths for the respective resources. -The *AddDir* commands set the paths for the respective resources. - + #### Plugins -Extend the configuration if you introduce new plugins into your installation. Although there are different ways to specify the plugins to be loaded, the tags in the example configuration file are the most secure way. Each `mmPluginLoaderInfo` tag requires three attributes: +Since we switched to static linking of plugin libraries into the MegaMol binary, the configuration of `mmPluginLoaderInfo` is ***DEPRECATED*** and no longer required. -- `path` should be the path to find the plugin. The example configuration file assumes -to find the plugins in the same directory as the MegaMol executable (which is the -case for Windows installations. On Linux systems, you need to change this path, e.g., to `../../lib/megamol`. -- `name` is the file name of the plugin. -- `action` refers to an internal parameter of MegaMol and should always be included. + + #### Global Settings -The configuration file also specifies global settings variables which can modify the behavior of different modules. Two such variables are set in the example configuration file. -In line 14 the variable `*-window` is set. This variable specifies the default position and size for all rendering windows MegaMol will create. The asterisk represents any window name. If you set a variable with a specific name, windows with exactly this name will respect the settings variable. For example, `test-window` will specify the value for the window created by the view instance test. +The configuration file also specifies global settings variables which can modify the behavior of different modules. +- The following settings variable activates (or deactivates) the *arcball* (orbiting) camera behavior. Set this option to `on` in order to use the *arcball* camera navigation. ```lua - mmSetConfigValue("*-window", "w720h720") + mmSetConfigValue("arcball", "off") ``` -The value itself contains five variables: -- The first two variables are prefixed with `x` and `y` and specify the location of the window in screen pixel coordinates. -- The second two variables are prefixed with `w` and `h` and specify the size of the client area of the window in pixels. -- The last variable `nd` (stands for no decorations) will remove all window decorations, buttons, and border from the created window. -This variable allows us to create borderless windows filling the complete screen for full-screen rendering. +All other configuration options are ***DEPRECATED*** and have currently no effect! -The second settings variable, specified on line 15, activates (or deactivates) the GUI of the console front end, that is the AntTweakBar. + + +This concludes the information on building and the options on how to configure MegaMol. Test your installation following the description in the following section. - -### Tests + +----- +## Test Installation -To test MegaMol simply start the front end executable. Open a console and change your working directory to the MegaMol install directory. Start -the MegaMol start script: +In order to test the installation, simply run the frontend executable. +Open a console (e.g *Linux Terminal* or *Windows Powershell*) and change your working directory to the MegaMol install directory containing the `bin` folder (default: `../megamol/build/install/bin`) and execute the MegaMol binary: -Linux: +**Windows:** +``` + > megamol.exe +``` - $ ./megamol.sh +**Linux:** -Windows: +``` + $ ./megamol +``` + +If additional external libraries are required (e.g. when using the OSPRay plugin), for Linux you have to run the provided shell script `./megamol.sh` instead. +This script adds the required library path: - > mmconsole.exe +```bash + #!/bin/bash + # + # MegaMol startup script + # Copyright 2020, https://megamol.org/ + # -The resulting output should look something like this: + BIN_DIR=$(dirname "$(readlink -f "${BASH_SOURCE[0]}")") + cd "$BIN_DIR" - 0200|MegaMol� Console - 0200|Console: (Ver.: 1.2.cef9ff221ce4-dirty) 64 Bit Linux - 0300|MegaMol Core API "cef9ff221ce4-dirty"; - 0200|Core "MegaMol Core (Evolution Chamber)" (Ver.: 1.2.cef9ff221ce4-dirty) 64 Bit Linux - 0300| - 0200|Started Fri Sep 29 14:31:38 2017 + LD_LIBRARY_PATH=../lib:$LD_LIBRARY_PATH ./megamol "$@" +``` + +MegaMol should start and print several messages to the console and an empty rendering window should appear. +You can either check the console log messages or the messages printed in the *Log Console* window. +The leading number of each line is the log level. +There should be no error messages (log level **1**). +Some warnings (log level **100**) might occur but are *normal* and indicate no failed installation or execution. - MegaMol� Console - Copyright (c) 2006 - 2017 by MegaMol Team: VISUS (Universitaet Stuttgart, Germany), TU Dresden (Dresden, Germany) - Alle Rechte vorbehalten. - All rights reserved. - - 0200|Called: /nethome/user/software/megamol/bin/mmconsole - 250|Path "/nethome/user/software/megamol/share/shaders" added as shader search path. - 250|Configuration value "*-window" set to "w1280h720". - 250|Configuration value "consolegui" set to "on". - 350|Directory "application" is "/nethome/user/software/megamol/bin" - 200|Configuration sucessfully loaded from "/nethome/user/software/megamol/bin/megamol.cfg" - 200|Default LRHostAddress = "tcp://*:33333" - 200|Default LRHostEnable = "true" - 200|Installed service "LuaRemote" [1] - 200|LRH Server socket opened on "tcp://*:33333" - 200|Auto-enabled service "LuaRemote" [1] - 200|Plugin CinematicCamera loaded: 4 Modules, 1 Calls - 200|Plugin "CinematicCamera" (/nethome/user/software/megamol/lib/libcinematiccamera.mmplg) loaded: 4 Modules, 1 Calls registered - 200|Plugin infovis loaded: 3 Modules, 2 Calls - 200|Plugin "infovis" (/nethome/user/software/megamol/lib/libinfovis.mmplg) loaded: 3 Modules, 2 Calls registered - 200|Plugin mdao2 loaded: 1 Modules, 0 Calls - 200|Plugin "mdao2" (/nethome/user/software/megamol/lib/libmdao2.mmplg) loaded: 1 Modules, 0 Calls registered - 200|Plugin mmstd_datatools loaded: 43 Modules, 4 Calls - 200|Plugin "mmstd_datatools" (/nethome/user/software/megamol/lib/libmmstd_datatools.mmplg) loaded: 43 Modules, 4 Calls registered - 200|Plugin mmstd_moldyn loaded: 16 Modules, 1 Calls - 200|Plugin "mmstd_moldyn" (/nethome/user/software/megamol/lib/libmmstd_moldyn.mmplg) loaded: 16 Modules, 1 Calls registered - 200|Plugin mmstd_trisoup loaded: 12 Modules, 4 Calls - 200|Plugin "mmstd_trisoup" (/nethome/user/software/megamol/lib/libmmstd_trisoup.mmplg) loaded: 12 Modules, 4 Calls registered - 200|Plugin "mmstd.volume" (/nethome/user/software/megamol/lib/libmmstd_volume.mmplg) loaded: 7 Modules, 0 Calls registered - 200|Plugin Protein loaded: 55 Modules, 9 Calls - 200|Plugin "Protein" (/nethome/user/software/megamol/lib/libprotein.mmplg) loaded: 55 Modules, 9 Calls registered - 200|Plugin Protein_Calls loaded: 0 Modules, 10 Calls - 200|Plugin "Protein_Calls" (/nethome/user/software/megamol/lib/libprotein_calls.mmplg) loaded: 0 Modules, 10 Calls registered - 200|Core Instance destroyed - 200|LRH Server socket closed + +### Examples -Alternatively, you can descend into the bin directory and start the front end directly. Doing so, you must ensure that the additional shared objects can be found and loaded. Enter the commands. To test this, try: +The [example project script files](https://github.com/UniStuttgart-VISUS/megamol-examples) are automatically available in the `examples` directory, which is installed next to the `bin` directory. - cd bin - LD_LIBRARY_PATH=../lib ./mmconsole +For a better test, you should invoke MegaMol loading an example project script requesting a simple rendering. +Then you can be sure that the graphics drivers, graphics libraries, and shader codes are correctly found and are working. +To do this, try: -This direct invocation is not recommended. Thus, the remaining examples in this manual will assume that you use the start shell script. MegaMol should start and print several messages to the console. The leading number of each line is the log level. There should be no output of warnings (log level of 100 or less) or errors (log level 1). The output should match the one above. For a better test, you should invoke MegaMol requesting a simple rendering. Then you can be sure that the graphics drivers, graphics libraries, and shader codes are correctly found and are working. To do this, try: +**Linux:** -Linux: + $ ./megamol ../examples/testspheres_megamol.lua - $ ./megamol.sh -p ../examples/testspheres.lua +**Windows:** -Windows: + > megamol.exe ..\examples\testspheres_megamol.lua - > mmconsole.exe -p ..\examples\testspheres.lua +MegaMol should now open a rendering window showing a generated dataset with several colored spheres and the outline of the bounding box. +Hitting the `space` key starts and stops the animation playback. +In the GUI window *Parameters* you can find all available parameters of the running MegaMol instance grouped by the modules. +For example, you can find the parameter `speed` in the group `inst::view::anim`. +With this parameter, you can adjust the playback speed of the animation. +In the parameter group `anim` of the `view` module you can adjust the animation speed. -
- -First test results -

-Screenshot MegaMol running the test spheres instance. -The highlighted option in the AntTweak-Bar on the right side of the window adjusts the animation speed. -

-
+Alternatively, you can also open an empty MegaMol rendering window and load the above example project script file via the menu `File / Load Project`. -Do not mind the `Ignoring Xlib error: error code n request code m` messages. -MegaMol should now open a rendering window showing a generated dataset with several colored spheres. Hitting the `space` key starts and stops the animation playback. In the *AntTweakBar*, on the left side of the window, you can adjust all parameters of the running MegaMol instance. For example, you can find the parameter `Speed` in the group `inst::view::anim` (cf. [test run figure](#testrunpic)). With this parameter, you can adjust the playback speed of the animation. +All available options provided via the graphical user interface are described separately in the readme file of the [GUI plugin](../plugins/gui). - +![Test Project](pics/testspheres.png) +*Screenshot of MegaMol running the test spheres instance.* -## Viewing Data Sets -In this chapter, we discuss the principle usage of the prepared project files for data set viewing. This project script files are available in the *script and example* package from the MegaMol project website. + +----- +## MegaMol Graph - +In this chapter, we show the operating principle of MegaMol which is required to creating own custom projects for MegaMol. + ### Modules, Views and Calls -The runtime functionality of MegaMol is constructed by *modules* and *calls*. These two type of objects are instantiated at runtime, interconnected and build the *module graph*. The figure [Example Graph](#examplegraph) shows an example module graph containing a rendering content of a window *view*, a *renderer*, a *data source*, and two modules providing additional information for the renderer. The modules, shown as blue boxes, are interconnected by *call* objects, shown as gray boxes. The connection endpoints at the modules are *CallerSlots*, shown as red triangles, and *CalleeSlots* shown as green triangles. +The runtime functionality of MegaMol is constructed by *modules* and *calls*. +These two types of objects are instantiated at runtime, interconnected and build the *module call graph*. +The figure given below, shows an example module call graph containing a *view*, the rendering content of a window, a *renderer*, a *data source*, and some modules providing additional information for the renderer. +The modules are interconnected by the *call* objects. +The connection endpoints at the modules are *CallerSlots* (outgoing, located on the right side of modules) or *CalleeSlots* (incoming, located on the left side of modules) shown as circled dots. + +The module call graph follows the pull pattern. +This means that modules request function invocation by other modules. +For example, the *view* module needs to update the window content. +The *view* module thus invokes the *renderer* module to provide a new rendering. +The *renderer* calls the data source if new data is available or to provide the old cached data. -
- -Example graph -

-An example module graph. Left-most module view of class View3D represents the rendering content of a window. The center module renderer of class SphererRenderer is called by the window using the corresponding call of type CallRenderer3D. The right modules provide data and additional information for the renderer, namely a color map function and a clip plane.An example module graph. -

-
+Left-most module view of class `View3D_2` represents the rendering content of a window. +The center module renderer of class `BoundingBoxRenderer` and `SphererRenderer` are called subsequently by the window using the corresponding call of type `CallRenderer3D_2`. +The right modules provide data and additional information for the renderer, namely a color map transfer function and a clipping plane. -The module graph follows the pull pattern. This means that modules request function invocation by other modules. For example, the *view* module needs to update the window content. The *view* module thus invokes the *renderer* module to provide a new rendering. The *renderer* calls the data source if new data is available or to provide the old cached data. +![Example Graph](pics/example_graph.png) -#### Modules and calls +*Example module call graph.* -*Modules* are the functional entities of MegaMol . They provide several programmatic access points, the *slots*. Two types of these slots are shown in figure [Example Graph](#examplegraph) as colored arrowheads. + +#### Modules and Calls -*CalleeSlots* are access points of modules, through which these can be called to perform a function. For example, modules of class `SphererRenderer` provide a CalleeSlot rendering through which the rendering function can be invoked.The counterparts are CallerSlots which are outgoing access points. These allow modules to call other modules. Modules of class `View3D` provide a corresponding slot `rendering` to call a connected renderer. -These two types of slots are connected using objects of *call* classes. These are shown as gray boxes in figure [Example Graph](#examplegraph). Both *CalleeSlots* and *CallerSlots* specify types of calls they are compatible with. In the case of the above examples of renderings-relates slots, this is the type `CallRender3D`. +*Modules* are the functional entities of MegaMol. +They provide several programmatic access points, the *slots*. +Two types of these slots are shown in the above figure of an example graph as circled dots. -*Calls* should be lightweight. Instead, they are thin interfaces meant for data transport. For example, data to be visualized is loaded by data source modules. In [Example Graph](#examplegraph) the module *data* of class *MMPLDDataSource* loads a specified data set into main memory and provides the data through its CalleeSlot*. The data is accessed through a *MultiParticleDataCall*. The call, however, does not copy the data but provides access to the data in terms of memory pointers, and metadata. This avoidance of copy operations is most important and one of the core design ideas of MegaMol . +*CalleeSlots* are access points of modules, through which these can be called to perform a function. +For example, modules of class `SphererRenderer` provide a CalleeSlot `rendering` through which the rendering function can be invoked. +The counterparts are CallerSlots which are outgoing access points. +These allow modules to call other modules. +View modules of class `View3D_2` provide a corresponding slot `rendering` to call a connected renderer. +These two types of slots are connected using objects of *call* classes. +Both *CalleeSlots* and *CallerSlots* specify types of calls they are compatible with. +In the case of the above examples of renderings-relates slots, this is the type `CallRender3D_2`. -*Parameter slots* are the third type of slots. These are access points to exposed parameters controlling the functionality. Such parameters are automatically included in the front end’s GUI. Examples of such parameters are the setup of the virtual camera and light source in modules of type `View3D` or the dataset file name in data source modules. +*Calls* should be lightweight. +They are thin interfaces meant for data transport. +For example, data to be visualized is loaded by data source modules. +In the example graph figure the module *data* of class *MMPLDDataSource* loads a specified data set into main memory and provides the data through its *CalleeSlot*. +The data is accessed through a *MultiParticleDataCall*. +The call, however, does not copy the data but provides access to the data in terms of memory pointers, and metadata. +This avoidance of copy operations is most important and one of the core design ideas of MegaMol. -The *module graph* is configured for MegaMol using a project file. These files define modules -and interconnecting calls for different instance specifications. There are two types of instances: -views (see section [Views](#views)) and jobs (see section [Jobs](#jobs)). The starting command line of the console front-end loads project files (using `-p`) and requests instantiation of views and jobs (using `-i`). +*Parameter Slots* are the third type of slots. +These are access points to exposed parameters controlling the functionality. +Such parameters are automatically included in the frontend’s GUI. +An example of such parameters is the setup of the virtual camera in modules of type `View3D_2` or the dataset file name in data source modules. +The *module call graph* is configured for MegaMol using a project file. +These files define modules and interconnecting calls for different instance specifications. + + + + #### Views - -*Views* are one of the two instance types MegaMol can run. They are specified by the corresponding tag in a MegaMol project file (see section [Project Files](#project-files)). When a view is instantiated, a corresponding namespace will be created, and all modules instantiated as part of the view will be created inside this namespace. For example, the project file seen in next section ([Project Files](#project-files)) defines the module data as part of the view dataview. If this view is instantiated by the command line note (note that files might need some path adjustments): +*Views* are one of the two instance types MegaMol can run. +They are specified by the corresponding tag in a MegaMol project file (see section [Project Files](#project-files)). +When a view is instantiated, a corresponding namespace will be created, and all modules instantiated as part of the view will be created inside this namespace. + + + + +### View Interaction - +The primary interaction with a view is controlling the camera with mouse and keyboard. +The keyboard mapping is implemented by button parameters of the view module, also available in the GUI. +Most parameters can be found in the sub-namespace `viewKey` inside the view name, e.g. `RotLeft`. +The corresponding parameter button in the GUI also shows the associated hotkey. +In the configuration file `megamolconfig.lua` the camera behaviour can be change be switching the *arcball* option on or off. -### Project Files + +Some useful controls assuming the *arcball* option is set to **on**: -Project files are the primary method to start up MegaMol . The snippets below show the content of the project file `simple_siff.mmprj` and `pdbcartoonview.mmprj` which can be used to view the sample particle datasets. +- Hitting *Home* (aka *Pos1*) is associated with the button *resetView*. This function resets the view to default. +- Hold the *Left Mouse Button* and move your mouse to rotate the view around the look-at point. + The look-at point initially is placed in the center of the bounding box of the data set. +- Hold *Shift* while holding and dragging the *Left Mouse Button* rolls the camera around the viewing direction. +- Hold *Control* while holding and dragging the *Left Mouse Button* rotates the camera around its center point. +- Hold *Alt* while holding and dragging the *Left Mouse Button* moves the camera orthogonally to the viewing direction. +- Hold the *Middle Mouse Button* and move your mouse up or down to zoom the view by move the camera forwards or backwards. + Note that if you zoom in too much, parts of the data set will be clipped by the near-clipping plane. +- Hold *Alt* while holding and dragging the *Middle Mouse Button* zoom the view by changing the opening angle of the camera. +- Hold *Control* while holding and dragging the *Middle Mouse Button* moves the look-at point forwards or backwards, changing the center of the corresponding rotation. + Use the parameter `showLookAt` of the view to visualize the look-at point for better adjustment. + + + +----- +## Project Files + +Project files are [`lua`](https://www.lua.org/) scripts using special custom functions to define any module graph for MegaMol. +Some predefined example project script files are available in the `examples` directory, which is installed next to the `bin` directory. +Here you can see the example project script `..\examples\testspheres_megamol.lua`: -Although, it is possible to host multiple instance descriptions in a single project file it is recommended to only have one description per file. Both files define a *view*, which is the only node in the top level node `MegaMol`. The other keywords describe the behavior of this view. +```lua + mmCreateView("testspheres", "View3D_2","::view") -Example 1: `simple_siff.mmprj` -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` + mmCreateModule("BoundingBoxRenderer","::bbox") + mmCreateModule("DistantLight","::distantlight") + mmCreateModule("SphereRenderer","::renderer") + mmCreateModule("TestSpheresDataSource", "::data") -Example 2: `pdbcartoonview.mmprj` -```xml - - - - - - - - - - - - - - - + mmSetParamValue("::renderer::renderMode", [=[Simple]=]) + mmCreateCall("CallRender3D_2", "::view::rendering", "::bbox::rendering") + mmCreateCall("CallRender3D_2","::bbox::chainRendering","::renderer::rendering") + mmCreateCall("MultiParticleDataCall", "::renderer::getData", "::data::getData") + mmCreateCall("CallLight","::renderer::lights","::distantlight::deployLightSlot") ``` -### Code Walkthrough - -After the data sources, the renderer is defined: +Project files can easily be created using the built in *Configurator*. +It can be opened via the menu `Windows / Configurator`. +You can either edit the currently running MegaMol graph (which might be empty) or you can create a new project starting a module graph by adding the main view module `View3D_2`. +A detailed description of the configurator can be found in the readme file of the [GUI plugin](../plugins/gui#configurator). -```xml - - - - -``` + -After this, the *view* module is specified. -All used data source modules use mainly slots with the same names, i.e. a *ParameterSlot* named `filename` and a *CalleeSlot* named `getdata`, compatible with MultiParticleDataCall, providing access to the loaded data. Specifying the right config set variable thus allows the caller to use data sets from different file formats with this project file. See the online documentation for more information on these file formats. The recommended file format for MegaMol currently is MMPLD, and the corresponding data source module is thus the default module. + +----- +## Making High-Resolution Screenshots -```xml - - - - - - - - - - - -``` +### GUI -One important function of project files can be seen in the code for `simple_siff.mmprj`: specifying parameter values. You can specify values for parameter slots of modules using the `` tag inside the `` tag. Use attributes to select the name and value for the corresponding parameter. +The GUI menu option `Screenshot` (hotkey `F2`) provides a basic screenshot functionality using the current viewport size. +If screenshots are taken consecutively, the given file name is prepended by an incrementing suffix. +This way, no new file name has to be set after each screenshot. -The following block deals with the modules being interconnected using call objects. The corresponding tags specify the class of the call, the source *CallerSlot* to connect `from`, and the targetted *CalleeSlot* to connect `to`. The slot identifiers consist of module instance name (as defined in the project file, here its `cartoonren` and `::pdbdata`, while the slot name is as defined by the implementation (i.e. `rendering`, `getdata` and `dataout`). Specifying the full name would require the instance name this view will be instantiated as. Searching for the slots does, therefore, work using relative names. +### Project File -```xml - - - - - - - - -``` +Within the LUA project file a screenshot can be triggered using the command `mmScreenShot("screenshot_filename.png")`. -Additionally, the `simple_siff.mmprj` project includes the module *ScreenShooter*. As parameters, the connected view must be specified, which is done by setting the `view` parameter to `inst` which is the name of the view instance given on the command line. +The following example shows how to take screenshots of various time steps: -```xml - - - - +```lua +for i=0,1 do + mmSetParamValue("::View3D_2_1::anim::time", tostring(i)) + mmRenderNextFrame() + mmScreenShot("screenshot_timestep_" .. string.format("%04d",i) .. ".png") +end ``` +#### Framebuffer Size -Note: If you experience problems with one of the renderers, for example, due to problems with your graphics card or graphics driver, try to select another one by specifying it in line 7, i.e., change the *class* value from `SphererRenderer` to `SimpleGeoSphereRenderer`. +The actual framebuffer size to use for a screenshot can be set in the following ways: -### View Interaction +**LUA Project File:** +`mmSetFramebufferSize(width, height)` +e.g. mmSetFramebufferSize(100, 100). -The primary interaction with a view is controlling the camera with mouse and keyboard. The keyboard mapping is implemented by button parameters of the view module, also available in the GUI. Most parameters can be found in the sub-namespace `viewKey` inside the view name, e.g. `RotLeft`. Hovering with the mouse over the corresponding button reveals the associated hot key in the GUI’s status text line. -Some useful controls: -- Hitting *Home* (aka *Pos1*) is associated with the button *resetView*. This function resets the view to default. -- Hold the *left mouse button* and move your mouse to rotate the view around the look-at point. The look-at point initially is placed in the center of the bounding box of the data set. -- Hold *shift* while holding and dragging the *left mouse button* rolls the camera around the viewing direction. -- Hold *control* while holding and dragging the *left mouse button* rotates the camera around its center point. -- Hold *alt* while holding and dragging the *left mouse button* moves the camera orthogonally to the viewing direction. -- Hold the *middle mouse button* and move your mouse up or down to zoom the view by move the camera forwards or backwards. Note that if you zoom in too much, parts of the data set will be clipped by the near-clipping plane. -- Hold *alt* while holding and dragging the *middle mouse button* zoom the view by changing the opening angle of the camera. -- Hold *control* while holding and dragging the *middle mouse button* moves the look-at point forwards or backwards, changing the center of the corresponding rotation. Use the parameter -`showLookAt` of the view to visualize the look-at point for better adjustment. - - +**CLI Option:** +`--window wxh+x+y` + e.g. ./megamol.sh --window 100x100 for a window of size 100 x 100 pixels. + Also see help output: `./megamol.sh -h` -### Making High-Resolution Screenshots +### ScreenShooter Module -MegaMol has special functions to create high-resolution screen shoots of any rendering, namely the `ScreenShooter` module. The provided starting scripts add this module. If you create a project file of your own, remember to add the `ScreenShooter` module. The corresponding settings can be found in the AntTweakBar in the groups `inst::screenshooter` and `inst::screenshooter::anim` (see figure [ScreenShooter](#screenshooter)). +Offering more flexible options and special functions to create high-resolution screenshots of any rendering, you can add the `ScreenShooter` module to you project. +The corresponding settings can be found in the modules parameters provided in the GUI (see figure of `ScreenShooter` parameters below). -To connect the `ScreenShooter` with your view, you need to set the instance name of your view instance in the corresponding variable `inst::screenshooter::anim` (e.g. to `inst`). When making single screen shots, set the option `makeAnim` in the group `inst::screenshooter::anim` to `disabled`, as shown in the figure. Ignore the remaining options in that group. These options will be explained in section [Making Simple Videos](#makevideo), as they are used to produce videos. +In order to connect the `ScreenShooter` with your *view*, you need to set the **module name** of your view module in the corresponding variable `::screenshooter::view` (e.g. to `::View3D_2_1`). +When making single screenshots, set the option `makeAnim` in the group `::screenshooter::anim` to `disabled`, as shown in the figure. +Ignore the remaining options in that group. +These options will be explained in section [Making Simple Videos](#making-simple-videos), as they are used to produce videos. -The parameters `imgWidth` and `imgHeight` specify the size of the screenshot to be rendered. These values are not limited to the window size and can be, in theory, arbitrarily large. If these values are getting large, the image can be rendered in several tiles, i.e., sub-images. The size for these tiles is specified by `tileWidth` and `tileHeight`. However, many renderers have problems with producing these tiled images. It is, thus, recommended to set `tileWidth` and `tileHeight` to be at least as large as `imgWidth` and `imgHeight`. The values for `tileWidth` and `tileHeight` are limited by the maximum texture size, maximum frame buffer object size and graphics memory size of your graphics card. Thus, these values are often limited. +The parameters `imgWidth` and `imgHeight` specify the size of the screenshot to be rendered. +These values are not limited to the window size and can be, in theory, arbitrarily large. +If these values are getting large, the image can be rendered in several tiles, i.e., sub-images. +The size for these tiles is specified by `tileWidth` and `tileHeight`. +However, many renderers have problems with producing these tiled images. +It is, thus, recommended to set `tileWidth` and `tileHeight` to be at least as large as `imgWidth` and `imgHeight`. +The values for `tileWidth` and `tileHeight` are limited by the maximum texture size, maximum frame buffer object size and graphics memory size of your graphics card. +Thus, these values are often limited. +The parameter file name specifies the path to the image file to be created. +MegaMol only creates PNG files. +Hit the button trigger to have MegaMol create the requested screenshot. -
- -Screenshooter -

-The parameter filename specifies the path to the image file to be created. MegaMol only creates PNG files. Hit the button trigger to have MegaMol create the requested screenshot. -

-
+![ScreenShooter](pics/screenshooter.png) -### Reproducibility -MegaMol stores the active project and all parameter settings in the EXIF field of the saved screenshots. Please note that this field currently contains a simple zero-terminated string with the LUA code required to reproduce the state when the screenshot is taken, and **not** valid EXIF data. Such a project can be restored by just loading the PNG: -``` -$ mmconsole -p something.png -``` -Also note that only Views with direct access to camera parameters (like View3D2, but unlike the original View3D, which requires explicit serialization of camera parameters) can be properly restored. + +----- +## Making Simple Videos - +MegaMol cannot create video files directly. +However, MegaMol can create a sequence of screenshots of a time-dependent data set showing the different points-in-time. +This functionality is provided and further described in the [*Cinematic* plugin](../plugins/cinematic#usage). -### Making simple Videos + + + + - - @@ -543,133 +700,21 @@ The entry module for data conversion is of class `DataWriterJob`, see line 11. T $ mmconsole -p makemmpld.mmprj -i convjob j -v j::data::filename inputfile.siff -v j::writer::filename outputfile.mmpld -The input file name and output file name are explicitly specified using the -v arguments. The job execution starts immediately. After data is written, MegaMol terminates itself. The console output should be similar to this listing: - - 0200|MegaMol� Console - 0200|Console: (Ver.: 1.2.cef9ff221ce4-dirty) 64 Bit Linux - 0300|MegaMol Core API "cef9ff221ce4-dirty"; - 0200|Core "MegaMol Core (Evolution Chamber)" (Ver.: 1.2.cef9ff221ce4-dirty) 64 Bit Linux - 0300| - 0200|Started Fri Sep 29 16:16:56 2017 - - MegaMol� Console - Copyright (c) 2006 - 2017 by MegaMol Team: VISUS (Universitaet Stuttgart, Germany), TU Dresden (Dresden, Germany) - Alle Rechte vorbehalten. - All rights reserved. - - 0200|Called: /nethome/user/software/megamol/bin/mmconsole -p ../docs/lua/makemmpld.mmprj -i convjob j -v j::data::filename ../samples/MegaMol/sampledata/exp2mill.00010.siff -v j::writer::filename outputfile.mmpld - 250|Path "/nethome/user/software/megamol/share/shaders" added as shader search path. - 250|Configuration value "*-window" set to "w1280h720". - 250|Configuration value "consolegui" set to "on". - 350|Directory "application" is "/nethome/user/software/megamol/bin" - 200|Configuration sucessfully loaded from "/nethome/user/software/megamol/bin/megamol.cfg" - 200|Default LRHostAddress = "tcp://*:33333" - 200|Default LRHostEnable = "true" - 200|Installed service "LuaRemote" [1] - 200|LRH Server socket opened on "tcp://*:33333" - 200|Auto-enabled service "LuaRemote" [1] - 200|Plugin CinematicCamera loaded: 4 Modules, 1 Calls - 200|Plugin "CinematicCamera" (/nethome/user/software/megamol/lib/libcinematiccamera.mmplg) loaded: 4 Modules, 1 Calls registered - 200|Plugin infovis loaded: 3 Modules, 2 Calls - 200|Plugin "infovis" (/nethome/user/software/megamol/lib/libinfovis.mmplg) loaded: 3 Modules, 2 Calls registered - 200|Plugin mdao2 loaded: 1 Modules, 0 Calls - 200|Plugin "mdao2" (/nethome/user/software/megamol/lib/libmdao2.mmplg) loaded: 1 Modules, 0 Calls registered - 200|Plugin mmstd_datatools loaded: 43 Modules, 4 Calls - 200|Plugin "mmstd_datatools" (/nethome/user/software/megamol/lib/libmmstd_datatools.mmplg) loaded: 43 Modules, 4 Calls registered - 200|Plugin mmstd_moldyn loaded: 16 Modules, 1 Calls - 200|Plugin "mmstd_moldyn" (/nethome/user/software/megamol/lib/libmmstd_moldyn.mmplg) loaded: 16 Modules, 1 Calls registered - 200|Plugin mmstd_trisoup loaded: 12 Modules, 4 Calls - 200|Plugin "mmstd_trisoup" (/nethome/user/software/megamol/lib/libmmstd_trisoup.mmplg) loaded: 12 Modules, 4 Calls registered - 200|Plugin "mmstd.volume" (/nethome/user/software/megamol/lib/libmmstd_volume.mmplg) loaded: 7 Modules, 0 Calls registered - 200|Plugin Protein loaded: 55 Modules, 9 Calls - 200|Plugin "Protein" (/nethome/user/software/megamol/lib/libprotein.mmplg) loaded: 55 Modules, 9 Calls registered - 200|Plugin Protein_Calls loaded: 0 Modules, 10 Calls - 200|Plugin "Protein_Calls" (/nethome/user/software/megamol/lib/libprotein_calls.mmplg) loaded: 0 Modules, 10 Calls registered - 200|Loading project file "../docs/lua/makemmpld.mmprj" - 550|Created module "N7megamol9stdplugin6moldyn2io14SIFFDataSourceE" - 550|Created module "SIFFDataSource" (::j::data) - 550|Created module "N7megamol4core3job13DataWriterJobE" - 550|Created module "DataWriterJob" (::j::job) - 550|Created module "N7megamol4core6moldyn11MMPLDWriterE" - 550|Created module "MMPLDWriter" (::j::writer) - 550|Call "DataWriterCtrlCall" instantiated from "::j::job::writer" to "::j::writer::control" - 550|Call "MultiParticleDataCall" instantiated from "::j::writer::data" to "::j::data::getdata" - 200|Setting parameter "::j::data::filename" to "../samples/MegaMol/sampledata/exp2mill.00010.siff" - 200|Setting parameter "::j::writer::filename" to "outputfile.mmpld" - 200|Job "job" started ... - 200|Starting DataWriterJob "::j::job" - 200|Started writing data frame 0 - 200|Completed writing data - 200|DataWriterJob "::j::job" complete - 250|Job instance j terminating ... - 550|Released module "N7megamol9stdplugin6moldyn2io14SIFFDataSourceE" - 550|Released module "N7megamol4core3job13DataWriterJobE" - 550|Released module "N7megamol4core6moldyn11MMPLDWriterE" - 200|Core Instance destroyed - 200|LRH Server socket closed +The input file name and output file name are explicitly specified using the -v arguments. +The job execution starts immediately. +After data is written, MegaMol terminates itself. To convert from other file formats, for which a corresponding loader does exist, you should be able to adjust this project file. - - -## Advanced Usage - -This chapter discusses advanced usage of MegaMol . - - - -### Configurator (Windows) - -The Configurator is a utility application for editing MegaMol project files. More specifically, it allows us to edit the modules, calls, and parameters to be instantiated and set for view instances (see sections [Modules, View, and Calls](#modules-views-calls) and [Project Files](#project-files)). The [image](#configurator-pic) below shows the main GUI window of the application. - -
- -Configurator -

-The Configurator main GUI. -

-
- -The Configurator is written in C#. The Configurator can be run on Linux using Mono 1. However, we never tested the Configurator with Mono and thus will not support it. The right editing pane allows you to place modules and interconnect their *CallerSlots* and *CalleeSlots* with matching calls. The tabs above that pane allow to open and edit several project files at once. On the left side, you have the list of modules available and, below, the parameters of the currently selected module (which is marked in the editing pane by a dashed border). The menu strip contains direct access to all functions. The Configurator is a stand-alone editor for MegaMol project files. There is no way to connect the editor to a running instance of MegaMol , e.g., to edit parameters on the fly. - -### Class Data Base - -To fill the left list of available modules, the Configurator requires a database containing all classes of the MegaMol module graph engine. This file is called the state file. You can load and save the state file using the Settings menu. There, you can also view a summary of the contents of the loaded state file. The MegaMol release package contains a state file of all modules and classes available in the released MegaMol binary. You can directly load this state file. - -On Windows operating systems you can also analyze MegaMol binaries to generate a state file containing their classes. You find this function also in the Settings menu. This function relies on system DLLs and native, unmanaged code. So, this function will not work on Linux with Mono. A dialog window will open in which you can select the folder to analyze. After a short time, the list in this dialog will show you all compatible MegaMol binaries, including versions of the core library and all plugins. Select all binaries you want to be included in the state file. Be aware that you can only select binaries which depend on the exact same core library. Select Ok, and -the new state file will be created and loaded. Per default, a dialog will appear, allowing you to save the newly generated state file. - -### Editing - -Project files can be saved and loaded using the corresponding functions for the menu bar. Save will always ask you for a file name, but will use the last file name as the default value. New creates a new editing tab. To close a tab use the x button on the right or click a tab with the middle mouse button. - -#### Modules - -To add a new module to the current project, double-click on the corresponding entry in the module list. The module will be created in the upper left corner and will be automatically selected. To select a module click it with any mouse button. You can move all modules by simple dragging and dropping them with the mouse. This has no influence on the functionality. To delete the selected module hit the `Del` key. -While a module is selected, the parameter editor on the left shows all parameters of that module. In addition to the parameters exposed by *parameter slots*, there are some management parameters. You can edit the name of all module instances. For view modules, you can select if this module is the main view module for the whole project. -Click on a free space to deselect any module, call or slot. This will select the project itself. -You can now edit project parameters in the parameter editor on the left. - -#### Calls - -To select a *CallerSlot* (red triangles) or a *CalleeSlot* (green triangles), click the corresponding triangle of the module. The selected slot will be highlighted in yellow. All matching slots that are compatible with the selected slot are highlighted by a yellow outline. If the *Filter Compatible* option is active, the module list will then only show modules which have compatible slots. To connect two slots, drag with your mouse a line from one onto the other. The drag direction does not matter. If both slots are compatible, a matching call object is created and shown by a gray box. These call boxes are placed automatically. If the connection could be established by different call classes, a dialog window will appear asking to you select the call class to be used. To delete a call, select it by clicking on its box and press the `Del` key. -A (red) *CallerSlot* can only have a single outgoing call, while (green) *CalleeSlots* may be connected by multiple calls. Therefore, if you drag from a *CallerSlot* to a *CalleeSlot* which already has incoming connections, a new connection is added. If you, however, drag from a *CalleeSlot to a *CallerSlot* which already has an outgoing connection, this connection is replaced. - -### Starting MegaMol - -The Configurator allows you to directly start MegaMol with the currently selected project file. Remember: the Configurator is only an editor for project files and has no online connection to a running MegaMol instance. You thus need to remember to save your edited project files before starting MegaMol . +--> -
- -Start Arguments -

-MegaMol startup arguments dialog. -

-
+ +----- +## Reproducibility -After launching the Configurator, selecting the menu item `MegaMol Start Arguments...` opens the dialog window shown in the above [figure](#configurator-start). Here you can edit all start settings. The menu item `Start MegaMol` directly starts MegaMol with these settings. So does the `Start` button in this dialog window. The `Ok` button stores changes to the settings and closes the dialog window without starting MegaMol . The top line of elements controls the way MegaMol starts. Tick directly to directly spawn the MegaMol process from the configurator. This is the only working option for Linux operating systems. Tick `in Cmd` or `in Windows Powershell` and the configurator will first start the corresponding shell and then spawn the MegaMol process inside this shell. Tick the `Keep Open` option to start these shells in a way that they will remain open after the MegaMol process terminates. +MegaMol stores the active project and all parameter settings in the EXIF field of the saved screenshots. +Please note that this field currently contains a simple zero-terminated string with the LUA code required to reproduce the state when the screenshot is taken, and **not** valid EXIF data. Such a project can be restored by simply loading the PNG file: -This configuration is useful in case of errors which cause MegaMol to instantly terminate. The next text box control holds the full path to the MegaMol front-end executable. This should be set by the state file. You can then use the directory of this executable as the working directory for the MegaMol process, or you can specify another one. Specifying another working directory is not recommended, as it influences the way the paths inside configuration file will be interpreted. The last text box control holds the command line arguments for the MegaMol process. The last used command line arguments are available via the drop-down list. The start button gives -you access to the default command lines for your project. + $ megamol.exe .png -The whole process command line can be copied to the clipboard using the remaining menu items in the Start menu. The differences for Cmd shell and Powershell are only the way how special characters and strings are escaped. +Also note that only Views with direct access to camera parameters (like `View3D_2`) can be properly restored. diff --git a/docs/MMPLD Specification.pdf b/docs/mmpld/MMPLD Specification.pdf similarity index 100% rename from docs/MMPLD Specification.pdf rename to docs/mmpld/MMPLD Specification.pdf diff --git a/docs/MegaMol Simple Particle Data File Format Specification.pdf b/docs/mmpld/MegaMol Simple Particle Data File Format Specification.pdf similarity index 100% rename from docs/MegaMol Simple Particle Data File Format Specification.pdf rename to docs/mmpld/MegaMol Simple Particle Data File Format Specification.pdf diff --git a/docs/MegaMol Simple Particle Data File Format.docx b/docs/mmpld/MegaMol Simple Particle Data File Format.docx similarity index 100% rename from docs/MegaMol Simple Particle Data File Format.docx rename to docs/mmpld/MegaMol Simple Particle Data File Format.docx diff --git a/docs/SpecMMPLD.docx b/docs/mmpld/SpecMMPLD.docx similarity index 100% rename from docs/SpecMMPLD.docx rename to docs/mmpld/SpecMMPLD.docx diff --git a/docs/pics/cmake_windows.png b/docs/pics/cmake_windows.png index 9a2d0538b5..abf22b8a9a 100644 Binary files a/docs/pics/cmake_windows.png and b/docs/pics/cmake_windows.png differ diff --git a/docs/pics/configurator-start.png b/docs/pics/configurator-start.png deleted file mode 100644 index 3850e010b5..0000000000 Binary files a/docs/pics/configurator-start.png and /dev/null differ diff --git a/docs/pics/configurator.png b/docs/pics/configurator.png deleted file mode 100644 index 620143b7df..0000000000 Binary files a/docs/pics/configurator.png and /dev/null differ diff --git a/docs/pics/example_graph.png b/docs/pics/example_graph.png index 45a150fcac..a5b2d18aee 100644 Binary files a/docs/pics/example_graph.png and b/docs/pics/example_graph.png differ diff --git a/docs/pics/screenshooter.png b/docs/pics/screenshooter.png index de65cf6df8..26a167e628 100644 Binary files a/docs/pics/screenshooter.png and b/docs/pics/screenshooter.png differ diff --git a/docs/pics/testspheres.png b/docs/pics/testspheres.png index ce136e6a11..e854940400 100644 Binary files a/docs/pics/testspheres.png and b/docs/pics/testspheres.png differ diff --git a/plugins/OSPRay_plugin/Readme.md b/plugins/OSPRay_plugin/Readme.md index a0255e7395..ac3066df36 100644 --- a/plugins/OSPRay_plugin/Readme.md +++ b/plugins/OSPRay_plugin/Readme.md @@ -1,21 +1,39 @@ -# OSPRay plugin -[OSPRay](http://ospray.org) is a CPU ray tracing engine and is one project of the Software Defined Disualization (SDVis) open source initiative of Intel (http://sdvis.org/). +# MegaMol Plugin: OSPRay + +[OSPRay](http://ospray.org) is a CPU ray tracing engine and is one project of the Software Defined Visualization (SDVis) open source initiative of Intel (http://sdvis.org/). It builds on top of the high-performance ray tracing kernels of [Embree](https://embree.github.io/) and the [ISPC](https://ispc.github.io/) SPMD compiler. In this plugin, most of the functionality of OSPRay is covered and can be used via MegaMol modules and MegaMol calls. This plugin supports the chain paradigm that allows lights and structures to be stacked arbitrarily. -The figure below shows a common OSPRay module graph in MegaMol. +The figure below shows a common OSPRay module call graph in MegaMol. ![](ospray_configurator.png) -## Building -[OSPRay](http://ospray.org) is not included in this package, however it is required for this plugin to build. - -Step 1: Get and build OSPRay. Follow the instructions on the OSPRay website (http://ospray.org) or the OSPRay GitHub page (https://github.com/ospray/ospray). Make sure `OSPRAY_INSTALL_DEPENDENCIES` is enabled, otherwise Embree and TBB DLLs will not be installed and unavailable for the plugin. The plugin always uses the release version of OSPRay. -Step 2: Make sure you enable the plugin in CMake. Either use `-DBUILD_OSPRAY_PLUGIN` as configuration argument or use the graphical user interface `ccmake`. +## Building -If OSPRay is not automatically found set the appropriate `ospray_DIR`. Hint: The CMake configuration files of OSPRay are usually found in a subdirectory of the `lib` install directory. +[OSPRay](http://ospray.org) is not included in this package, however it is required for this plugin to be build. +The currently supported OSPRay versions are **2.4** and **2.5**. +In order to get all dependencies installed at once, we strongly recommend to build [OSPRay](https://www.ospray.org/downloads.html) following the **CMake Superbuild** instructions. +The current dependencies are: [rekcommon](https://github.com/ospray/rkcommon), [openvkl](https://www.openvkl.org/), [ISPC](https://ispc.github.io/), [TBB](https://www.threadingbuildingblocks.org/) ([oneTBB](https://github.com/oneapi-src/oneTBB)), and [Embree](https://embree.github.io/). +*Installing the precompiled binaries is not sufficient!* + +- Step 1: **OSPRay:** + - Download the source code to a new folder `git clone https://github.com/ospray/ospray.git ospray` and configure OSPRay with CMake using the CMake file located in `../scripts/superbuild`. + - In order to speed up the build process, uncheck the option `BUILD_EMBREE_FROM_SOURCE` since the binary version of Embree is sufficient. + - Build OSPRay following further instructions for the CMake Superbuild. + +- Step 2: **MegaMol:** + - Make sure you enable the plugin in CMake by checking the option `BUILD_OSPRAY_PLUGIN_PLUGIN`. + Either use `-DBUILD_OSPRAY_PLUGIN_PLUGIN` as configuration argument or use the graphical user interface `ccmake`. + - If OSPRay is not automatically found during configuration of MegaMol, set the appropriate `ospray_DIR`. + *Hint:* The CMake configuration files of OSPRay are usually found in a subdirectory of the install directory: `../build/install/ospray/lib/cmake/...` + - CMake subsequently asks for the build files of the following dependencies: + - rkcommon: `../build/install/rkcommon/lib/cmake/...` + - TBB root directory: `../build/install/tbb` + - Build and install MegaMol. + - In order to test OSPRay, start MegaMol using the example project file `..build/install/examples/testspheres_ospray_megamol.lua`. + *Note:* On Linux, you have to run MegaMol using the `megamol.sh` script in order to additionally set the required path to the shared libraries of OSPRay. ## Modules diff --git a/plugins/OSPRay_plugin/ospray_configurator.png b/plugins/OSPRay_plugin/ospray_configurator.png index 942b623113..540f0197f3 100644 Binary files a/plugins/OSPRay_plugin/ospray_configurator.png and b/plugins/OSPRay_plugin/ospray_configurator.png differ diff --git a/plugins/OSPRay_plugin/src/AbstractOSPRayRenderer.cpp b/plugins/OSPRay_plugin/src/AbstractOSPRayRenderer.cpp index bb282f7152..bf99bee475 100644 --- a/plugins/OSPRay_plugin/src/AbstractOSPRayRenderer.cpp +++ b/plugins/OSPRay_plugin/src/AbstractOSPRayRenderer.cpp @@ -1052,7 +1052,7 @@ namespace ospray { auto count = mesh.second.indices.byte_size / mesh::MeshDataAccessCollection::getByteSize(mesh.second.indices.type); - unsigned long long stride = 3 * sizeof(unsigned int); + size_t stride = 3 * sizeof(unsigned int); auto osp_type = OSP_VEC3UI; if (mesh_type == mesh::MeshDataAccessCollection::QUADS) { diff --git a/plugins/OSPRay_plugin/src/OSPRayRenderer.cpp b/plugins/OSPRay_plugin/src/OSPRayRenderer.cpp index 34675df4e9..0a16cbe445 100644 --- a/plugins/OSPRay_plugin/src/OSPRayRenderer.cpp +++ b/plugins/OSPRay_plugin/src/OSPRayRenderer.cpp @@ -23,7 +23,6 @@ #include #include -#include using namespace megamol::ospray; diff --git a/plugins/cinematic/README.md b/plugins/cinematic/README.md index 7a64247a1b..cad4e44de1 100644 --- a/plugins/cinematic/README.md +++ b/plugins/cinematic/README.md @@ -1,50 +1,32 @@ -# MegaMol Plugin: "Cinematic" +# MegaMol Plugin: Cinematic This plugin allows the video rendering (separate file per frame) of any rendering output in MegaMol. By defining fixed keyframes for desired camera positions and specific animation times, arbitrary tracking shots can be created. ![cinematic demo picture](demo.png) + +## Contents +- [Module Descriptions](#module-descriptions) + - [KeyframeKeeper](#keyframekeeper) + - [TrackingShotRenderer](#trackingshotrenderer) + - [CinematicView](#cinematicview) + - [TimeLineRenderer](#timelinerenderer) + - [ReplacementRenderer](#replacementrenderer) +- [Usage](#usage) + - [Example](#example) + - [How to use the cinematic editor](#How-to-use-the-cinematic-editor) + --- ## Module Descriptions This plugin provides the modules `KeyframeKeeper`, `TrackingShotRenderer`, `CinematicView`, `TimeLineRenderer` and `ReplacementRenderer`. -#### KeyframeKeeper: +#### KeyframeKeeper This module maintains the keyframes and their properties centralised. The modules `TrackingShotRenderer`, `CinematicView` and `TimeLineRenderer` have to be connected with the same `KeyframeKeeper` (see module call graph below). -#### TrackingShotRenderer: - -This module shows the spatial position of the defined keyframes and the resulting tracking shot. -It allows the direct selection of keyframes by left mouse button. -The position and direction of the camera parameters of a keyframe can be altered by drag & drop with left mouse button on shown manipulators. -There are two modes for showing differnt manipulators for a selected keyframe. - -#### CinematicView: - -This module provides the preview of the final view to be rendered. -Here a desired camera view can be chosen. -The desired view can be applied to an existing selected keyframe or a new keyframe. -By running the animation as preview one can audit the final view of the video. -The complete final video is defined by the resolution and the number of frames per second and can be rendered to png files. - -#### TimeLineRenderer: - -This module shows the temporal position of the keyframes on the animation time axis and the simulation time axis in an two-dimensional diagram. -The keyframes can be selected (left mouse button) or they can be shifted along the simulation or animation time axis per drag and drop (right mouse button). -The time axes can be zoomed (middle mouse button) and shifted (right mouse button) independently at the current mouse position. - -#### ReplacementRenderer: - -This module offers replacement rendering for models with performance too low for interactivly creating the tracking shot. -Therefore only a coloured bounding box of the model is drawn. - ---- - -## Parameters - The module `KeyframeKeeper` exposes the following parameters: (The values in brackets indicate the default values.) @@ -68,6 +50,13 @@ The module `KeyframeKeeper` exposes the following parameters: * `storage::save` (Assigned key: `SHIFT + s`): Save keyframes to file. * `storage::load` (Assigned key: `SHIFT + l`): Load keyframes from file. +#### TrackingShotRenderer + +This module shows the spatial position of the defined keyframes and the resulting tracking shot. +It allows the direct selection of keyframes by left mouse button. +The position and direction of the camera parameters of a keyframe can be altered by drag & drop with left mouse button on shown manipulators. +There are two modes for showing differnt manipulators for a selected keyframe. + The module `TrackingShotRenderer` exposes the following parameters: (The values in brackets indicate the default values.) @@ -77,6 +66,14 @@ The module `TrackingShotRenderer` exposes the following parameters: * `manipulators::visibleGroup`: Select visible manipulator group. * `manipulators::showOutsideBBox` (Assigned key: `SHIFT + w`): Show manipulators always outside of model bounding box. +#### CinematicView + +This module provides the preview of the final view to be rendered. +Here a desired camera view can be chosen. +The desired view can be applied to an existing selected keyframe or a new keyframe. +By running the animation as preview one can audit the final view of the video. +The complete final video is defined by the resolution and the number of frames per second and can be rendered to png files. + The module `CinematicView` exposes the following parameters: (The values in brackets indicate the default values.) @@ -96,6 +93,12 @@ The module `CinematicView` exposes the following parameters: * `cinematic::stereo_eye` (`Left`) Eye position (for stereo view). * `cinematic::stereo_projection` (`Mono Perspective`) Camera projection. +#### TimeLineRenderer + +This module shows the temporal position of the keyframes on the animation time axis and the simulation time axis in an two-dimensional diagram. +The keyframes can be selected (left mouse button) or they can be shifted along the simulation or animation time axis per drag and drop (right mouse button). +The time axes can be zoomed (middle mouse button) and shifted (right mouse button) independently at the current mouse position. + The module `TimeLineRenderer` exposes the following parameters: (The values in brackets indicate the default values.) @@ -103,6 +106,11 @@ The module `TimeLineRenderer` exposes the following parameters: * `gotoLeftFrame` (Assigned key: `left arrow`): Move to left animation time frame. * `resetAxes` (Assigned key: `SHIFT + x`): Reset all shifted and scaled time axes. +#### ReplacementRenderer + +This module offers replacement rendering for models with performance too low for interactivly creating the tracking shot. +Therefore only a coloured bounding box of the model is drawn. + The module `ReplacementRenderer` exposes the following parameters: (The values in brackets indicate the default values.) @@ -113,23 +121,27 @@ The module `ReplacementRenderer` exposes the following parameters: --- -## How to use the modules +## Usage + +The modules for a complete cinematic editor should be connected as shown in the *Cinematic Editor* module group below. +The renderer module and the data source module in the *External Project* group can be replaced by any other suitable modules. -The modules should be connected as shown in the module call graph below. -The yellow-tagged renderer module and the data source module can be replaced by any other suitable modules. -Note: The renderer module has to be connected to the `TrackingShotRenderer` as well as to the `CinematicView`. -For simplification the preferred way of adding the cinematic graph to a new project is to use the predefined cinematic module call graph via the `examples/cinematic/cinematic_editor.lua` project (see example below). +**Note:** The renderer module has to be connected to the `TrackingShotRenderer` as well as to the `CinematicView`. +For simplification the preferred way of adding the cinematic graph to a new project is to use the predefined cinematic editor project `examples/cinematic/cinematic_editor_megamol.lua` project (see example below). ![megamol example module call graph](graph.png) ### Example -In order to run the example change to the `bin` folder of the megamol executables in a shell and start the program with the following command: -*Under Windows:* `.\mmconsole.exe -p ../examples/cinematic/cinematic_editor.lua` -*Under Linux:* `./megamol.sh -p ../examples/cinematic/cinematic_editor.lua` +In order to run the example change to the `bin` folder of the megamol executable in a (bash/powershell) shell and start the program with the following command: + +*Under Windows:* `.\megamol.exe ../examples/cinematic/cinematic_editor_megamol.lua` + +*Under Linux:* `./megamol.sh ../examples/cinematic/cinematic_editor_megamol.lua` + +### How to use the cinematic editor -#### How it works -In the `cinematic_editor.lua` project file the testsphere project `examples/testsphere.lua` is automatically appended to the cinematic module graph (see yellow modules in graph above). +In the `cinematic_editor_megamol.lua` project file, the test sphere project `examples/testsphere_megamol.lua` is automatically appended to the cinematic module graph (see *External Project* module group in graph above). Additionally the corresponding keyframe file for the testsphere project `examples/cinematic/cinematic_keyframes.kf` is loaded. -Any other `lua` project file can be included by changing the appropriate line in `cinematic_editor.lua`. -The keyframe file can be set to the empty string for the initial loading of a new project and can be set to a newly created keyframe file later. +Any other `lua` project file can be included by changing the variable `project_file` to the projects file path you want to use. +The keyframe file can be set to the empty string `""` for the initial loading of a new project and can be set to a newly created keyframe file later. diff --git a/plugins/cinematic/graph.png b/plugins/cinematic/graph.png index 5c3ab2b419..6f43d853a0 100644 Binary files a/plugins/cinematic/graph.png and b/plugins/cinematic/graph.png differ diff --git a/plugins/gui/README.md b/plugins/gui/README.md index 0fd4596881..3365b80370 100644 --- a/plugins/gui/README.md +++ b/plugins/gui/README.md @@ -1,4 +1,4 @@ -# MegaMol GUI Plugin +# MegaMol Plugin: GUI This is the plugin providing the GUI for MegaMol. @@ -10,9 +10,9 @@ See bug and feature tracker [#539](https://github.com/UniStuttgart-VISUS/megamol ## Contents -- [1) Graphical User Interface (GUI)](#1-graphical-user-interface-gui) - - [[1] Main Menu](#1-main-menu) - - [[2] Configurator](#2-configurator) +- [Graphical User Interface (GUI)](#graphical-user-interface-gui) + - [Main Menu](#main-menu) + - [Configurator](#configurator) - [Main Menu](#main-menu) - [*Module Stock List* Sidebar](#module-stock-list-sidebar) - [*Module Parameters* Sidebar](#module-parameters-sidebar) @@ -21,22 +21,22 @@ See bug and feature tracker [#539](https://github.com/UniStuttgart-VISUS/megamol - [Graph](#graph) - [Module Groups](#module-groups) - [Module Group Interface Slots](#module-group-interface-slots) -- [2) Modules](#2-modules) - - [[1] GUIView](#1-guiview) - - [[2] OverlayRenderer](#2-overlayrenderer) +- [Modules](#modules) + - [GUIView](#guiview) + - [OverlayRenderer](#overlayrenderer) - [Parameters](#parameters) -- [3) Information for Developers](#3-information-for-developers) - - [[1] New Parameter Widgets](#1-new-parameter-widgets) +- [Information for Developers](#information-for-developers) + - [New Parameter Widgets](#new-parameter-widgets) - [How to add a new parameter widget](#how-to-add-a-new-parameter-widget) - [How to add a new parameter group widget](#how-to-add-a-new-parameter-group-widget) - - [[2] Default GUI State ](#2-default-gui-state) - - [[3] Graph Data Structure](#3-graph-data-structure) - - [[4] Class Dependencies](#4-class-dependencies) + - [Default GUI State ](#default-gui-state) + - [Graph Data Structure](#graph-data-structure) + - [Class Dependencies](#class-dependencies) --- -## 1) Graphical User Interface (GUI) +## Graphical User Interface (GUI) The GUI of MegaMol is based on [Dear ImGui](https://github.com/ocornut/imgui). @@ -44,7 +44,7 @@ The GUI of MegaMol is based on [Dear ImGui](https://github.com/ocornut/imgui). * Hotkeys use the key mapping of the US keyboard layout. Other keyboard layouts are currently not considered or recognized. Consider possible transposed `z` and `y` which are used in `undo` and `redo` hotkeys on text input. * Parameter values in the lua command `mmSetParamValue` must have the value enclosed in `[=[`and `]=]` delimiters. String delimiters `"` for parameter values are not supported any more. -### [1] Main Menu +### Main Menu The main menu provides the following options: (Assigned hotkeys are given in brackets.) @@ -74,7 +74,7 @@ The main menu provides the following options: * `Help` * `About`: Some information and links concerning the currently running MegaMol. -### [2] Configurator +### Configurator The project configurator is part of the GUI and can be opened via the main menu: `Windows`/`Configurator`. @@ -185,15 +185,15 @@ Interface slots are stored in project files as part of the configurators state p --- -## 2) Modules +## Modules Additional modules provided by the GUI plugin: -### [1] GUIView +### GUIView The GUIView module is deprecated. It was required for using the GUI with the former MegaMol frontend provided by mmconsole.exe / mmconsole.sh. -### [2] OverlayRenderer +### OverlayRenderer The `OverlayRenderer` is a rendering module which provides overlay rendering like textures, text, parameter values and transport control icons. Prepend the `OverlayRenderer` module any other existing 3D renderer module you want to have an overlay for. @@ -222,9 +222,9 @@ The `OverlayRenderer` is a rendering module which provides overlay rendering lik --- -## 3) Information for Developers +## Information for Developers -### [1] New Parameter Widgets +### New Parameter Widgets Parameter widgets can be defined for the `local` or the `global` scope. The widgets of the local scope are shown inside the parameter list in the `All Parameters` window. The global scope of a parameter widget can contain arbitrary ImGui code. There are widgets for the basic parameter types defined in `gui/src/graph/Parameter.h`and there are group widgets bundling parameters of the same namespace in `gui/src/graph/ParameterGroups.h`. The parameters namespace is a prefix in the parameters, name delimited with `::`. The presentation of a parameter (group) can be changed by switching to `expert` mode in the `All Parameters` window an clicking on the 'circle button'. @@ -253,7 +253,7 @@ The function should be named like: `bool check_group_widget_(.. * Add a new group widget data set of the type `GroupWidgetData` in the ctor and register above functions as callbacks. * Identification of parameter widget groups. Currently by name of namespace and name and type of expected parameters. -### [2] Default GUI State +### Default GUI State This is the default GUI state stored as JSON string in the lua project file: @@ -261,10 +261,10 @@ This is the default GUI state stored as JSON string in the lua project file: -- {"ConfiguratorState":{"module_list_sidebar_width":250.0,"show_module_list_sidebar":true},"GUIState":{"font_file_name":"","font_size":13,"menu_visible":true,"scale":1.0,"style":2},"WindowConfigurations":{"Configurator":{"log_force_open":true,"log_level":4294967295,"ms_max_history_count":20,"ms_mode":0,"ms_refresh_rate":2.0,"ms_show_options":false,"param_extended_mode":false,"param_module_filter":0,"param_modules_list":[],"param_show_hotkeys":false,"tfe_active_param":"","tfe_view_minimized":false,"tfe_view_vertical":false,"win_callback":6,"win_collapsed":false,"win_flags":1032,"win_hotkey":[300,0],"win_position":[0.0,0.0],"win_reset_position":[0.0,0.0],"win_reset_size":[1440.0,810.0],"win_show":false,"win_size":[1440.0,810.0]},"Log Console":{"log_force_open":true,"log_level":4294967295,"ms_max_history_count":20,"ms_mode":0,"ms_refresh_rate":2.0,"ms_show_options":false,"param_extended_mode":false,"param_module_filter":0,"param_modules_list":[],"param_show_hotkeys":false,"tfe_active_param":"","tfe_view_minimized":false,"tfe_view_vertical":false,"win_callback":7,"win_collapsed":false,"win_flags":3072,"win_hotkey":[298,0],"win_position":[0.0,634.0],"win_reset_position":[0.0,634.0],"win_reset_size":[1440.0,176.0],"win_show":false,"win_size":[1440.0,176.0]},"Parameters":{"log_force_open":true,"log_level":4294967295,"ms_max_history_count":20,"ms_mode":0,"ms_refresh_rate":2.0,"ms_show_options":false,"param_extended_mode":false,"param_module_filter":0,"param_modules_list":[],"param_show_hotkeys":false,"tfe_active_param":"","tfe_view_minimized":false,"tfe_view_vertical":false,"win_callback":1,"win_collapsed":false,"win_flags":8,"win_hotkey":[299,0],"win_position":[0.0,18.0],"win_reset_position":[0.0,0.0],"win_reset_size":[400.0,500.0],"win_show":true,"win_size":[400.0,500.0]},"Performance Metrics":{"log_force_open":true,"log_level":4294967295,"ms_max_history_count":20,"ms_mode":0,"ms_refresh_rate":2.0,"ms_show_options":false,"param_extended_mode":false,"param_module_filter":0,"param_modules_list":[],"param_show_hotkeys":false,"tfe_active_param":"","tfe_view_minimized":false,"tfe_view_vertical":false,"win_callback":3,"win_collapsed":false,"win_flags":65,"win_hotkey":[296,0],"win_position":[720.0,0.0],"win_reset_position":[720.0,0.0],"win_reset_size":[0.0,0.0],"win_show":false,"win_size":[0.0,0.0]},"Transfer Function Editor":{"log_force_open":true,"log_level":4294967295,"ms_max_history_count":20,"ms_mode":0,"ms_refresh_rate":2.0,"ms_show_options":false,"param_extended_mode":false,"param_module_filter":0,"param_modules_list":[],"param_show_hotkeys":false,"tfe_active_param":"","tfe_view_minimized":false,"tfe_view_vertical":false,"win_callback":5,"win_collapsed":false,"win_flags":64,"win_hotkey":[297,0],"win_position":[400.0,0.0],"win_reset_position":[400.0,0.0],"win_reset_size":[0.0,0.0],"win_show":false,"win_size":[0.0,0.0]}}} ``` -### [3] Graph Data Structure +### Graph Data Structure ![gui graph structure](graph_structure.png) -### [4] Class Dependencies +### Class Dependencies ![gui plugin class dependencies](class_dependencies.png)