visionforge/README.md

153 lines
5.0 KiB
Markdown
Raw Normal View History

2019-12-22 20:56:19 +03:00
[![JetBrains Research](https://jb.gg/badges/research.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
# DataForge Visualization Platform
2019-07-10 11:49:21 +03:00
2020-05-07 16:52:57 +03:00
## Table of Contents
2019-07-10 11:49:21 +03:00
2020-02-15 13:36:40 +03:00
* [Introduction](#introduction)
* [Features](#features)
2020-02-15 15:01:04 +03:00
* [About DataForge](#about-dataforge)
2020-02-15 13:36:40 +03:00
* [Modules contained in this repository](#modules-contained-in-this-repository)
2020-08-05 22:03:47 +03:00
* [visionforge-common](#visionforge-common)
* [visionforge-spatial](#visionforge-spatial)
* [visionforge-spatial-gdml](#visionforge-spatial-gdml)
* [visionforge-jsroot](#visionforge-jsroot)
2020-05-08 00:42:10 +03:00
* [Visualization for External Systems](#visualization-for-external-systems)
2020-02-15 15:01:04 +03:00
* [Demonstrations](#demonstrations)
2020-05-08 00:42:10 +03:00
* [Simple Example - Spatial Showcase](#simple-example---spatial-showcase)
* [Full-Stack Application Example - Muon Monitor](#full-stack-application-example---muon-monitor-visualization)
2020-02-15 15:01:04 +03:00
* [GDML Example](#gdml-example)
2019-07-10 11:49:21 +03:00
2020-02-15 13:36:40 +03:00
## Introduction
This repository contains a [DataForge](#about-dataforge)\-based framework
used for visualization in various scientific applications.
The main framework's use case for now is 3D visualization for particle physics experiments.
Other applications including 2D plots are planned for the future.
2020-05-08 00:42:10 +03:00
The project is developed as a [Kotlin multiplatform](https://kotlinlang.org/docs/reference/multiplatform.html)
2020-05-07 16:52:57 +03:00
application, currently targeting browser JavaScript and JVM.
2020-02-15 13:36:40 +03:00
2020-02-15 13:36:40 +03:00
## Features
The main framework's features for now include:
2020-01-02 15:18:26 +03:00
- 3D visualization of complex experimental set-ups
- Event display such as particle tracks, etc.
- Scales up to few hundred thousands of elements
- Camera move, rotate, zoom-in and zoom-out
- Scene graph as an object tree with property editor
2020-01-02 15:18:26 +03:00
- Settings export and import
- Multiple platform support
2020-02-15 13:36:40 +03:00
## About DataForge
2019-07-10 11:49:21 +03:00
2020-02-15 13:36:40 +03:00
DataForge is a software framework for automated scientific data processing. DataForge Visualization
Platform uses some of the concepts and modules of DataForge, including: `Meta`, `Configuration`, `Context`,
`Provider`, and some others.
To learn more about DataForge, please consult the following URLs:
* [Kotlin multiplatform implementation of DataForge](https://github.com/mipt-npm/dataforge-core)
* [DataForge documentation](http://npm.mipt.ru/dataforge/)
* [Original implementation of DataForge](https://bitbucket.org/Altavir/dataforge/src/default/)
2020-02-15 13:36:40 +03:00
## Modules contained in this repository
2020-01-02 15:18:26 +03:00
2020-08-05 22:03:47 +03:00
### visionforge-common
2019-10-06 21:29:04 +03:00
2020-02-15 13:36:40 +03:00
Contains a general hierarchy of classes and interfaces useful for visualization.
2020-02-15 15:01:04 +03:00
This module is not specific to 3D-visualization.
2019-10-06 21:29:04 +03:00
2020-08-05 22:03:47 +03:00
The `visionforge-common` module also includes configuration editors for JS (in `jsMain`) and JVM (in `jvmMain`).
2020-02-15 15:01:04 +03:00
2020-08-05 15:24:39 +03:00
**Class diagram:**
2020-02-12 20:48:37 +03:00
![](doc/resources/class-diag-common.png)
2020-02-15 15:01:04 +03:00
2020-08-05 22:03:47 +03:00
### visionforge-spatial
2020-02-12 20:48:37 +03:00
Includes common classes and serializers for 3D visualization, Three.js and JavaFX implementations.
2019-10-06 21:29:04 +03:00
2020-08-05 15:24:39 +03:00
**Class diagram:**
2020-01-02 15:18:26 +03:00
![](doc/resources/class-diag-3d.png)
2020-02-12 20:48:37 +03:00
2020-02-15 15:01:04 +03:00
##### Prototypes
One of the important features of the framework is support for 3D object prototypes (sometimes
also referred to as templates). The idea is that prototype geometry can be rendered once and reused
for multiple objects. This helps to significantly decrease memory usage.
The `prototypes` property tree is defined in `VisualGroup3D` class, and `Proxy` class helps to reuse a template object.
##### Styles
2020-02-15 15:01:04 +03:00
`VisualGroup3D` has a `styleSheet` property that can optionally define styles at the Group's
level. Styles are applied to child (descendant) objects using `styles: List<String>` property defined
in `VisualObject`.
2020-01-02 15:18:26 +03:00
2020-08-05 22:03:47 +03:00
### visionforge-spatial-gdml
2020-01-02 15:18:26 +03:00
GDML bindings for 3D visualization (to be moved to gdml project).
2020-01-02 15:18:26 +03:00
2019-10-06 21:29:04 +03:00
2020-08-05 22:03:47 +03:00
### visionforge-jsroot
2019-10-06 21:29:04 +03:00
Some JSROOT bindings.
2020-01-02 15:18:26 +03:00
Note: Currently, this part is experimental and put here for completeness. This module may not build.
2019-10-06 21:29:04 +03:00
2020-05-08 00:42:10 +03:00
## Visualization for External Systems
2020-08-05 22:03:47 +03:00
The `visionforge` framework can be used to visualize geometry and events from external,
2020-05-08 00:42:10 +03:00
non-Kotlin based systems, such as ROOT. This will require a plugin to convert data model
2020-08-05 22:03:47 +03:00
of the external system to that of `visionforge`. Performing such integration is a work
2020-05-08 00:42:10 +03:00
currently in progress.
2020-02-15 13:36:40 +03:00
## Demonstrations
2019-10-06 21:29:04 +03:00
2020-08-05 22:03:47 +03:00
The `demo` module contains several example projects (demonstrations) of using the `visionforge` framework.
2020-05-08 00:42:10 +03:00
They are briefly described in this section, for more details please consult the corresponding per-project
README file.
2020-01-02 15:18:26 +03:00
2020-05-07 16:52:57 +03:00
### Simple Example - Spatial Showcase
2020-01-02 15:18:26 +03:00
2020-02-15 13:36:40 +03:00
Contains a simple demonstration with a grid including a few shapes that you can rotate, move camera, and so on.
2020-05-07 16:52:57 +03:00
Some shapes will also periodically change their color and visibility.
[More details](demo/spatial-showcase/README.md)
2020-01-02 15:18:26 +03:00
2020-08-05 15:24:39 +03:00
**Example view:**
2020-01-02 15:18:26 +03:00
2020-02-12 20:48:37 +03:00
![](doc/resources/spatial-showcase.png)
2020-05-07 16:52:57 +03:00
### Full-Stack Application Example - Muon Monitor Visualization
2020-01-02 15:18:26 +03:00
A full-stack application example, showing the
2020-05-08 00:42:10 +03:00
[Muon Monitor](http://npm.mipt.ru/en/projects/physics#mounMonitor) experiment set-up.
2019-10-06 21:29:04 +03:00
2020-05-07 16:52:57 +03:00
[More details](demo/muon-monitor/README.md)
2019-10-06 21:29:04 +03:00
2020-08-05 15:24:39 +03:00
**Example view:**
2020-02-15 13:36:40 +03:00
2020-02-12 20:48:37 +03:00
![](doc/resources/muon-monitor.png)
2020-05-07 16:52:57 +03:00
2020-02-15 15:01:04 +03:00
### GDML Example
2020-02-15 13:36:40 +03:00
Visualization example for geometry defined as GDML file.
2020-05-07 16:52:57 +03:00
[More details](demo/gdml/README.md)
2019-07-10 11:49:21 +03:00
2020-02-15 15:01:04 +03:00
##### Example view:
2020-02-12 20:48:37 +03:00
2020-02-15 13:36:40 +03:00
![](doc/resources/gdml-demo.png)