visionforge/README.md

139 lines
4.9 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)
2020-08-08 18:09:29 +03:00
[![DOI](https://zenodo.org/badge/174502624.svg)](https://zenodo.org/badge/latestdoi/174502624)
![Gradle build](https://github.com/mipt-npm/visionforge/workflows/Gradle%20build/badge.svg)
2019-12-22 20:56:19 +03:00
2020-12-08 18:10:00 +03:00
[![Slack](https://img.shields.io/badge/slack-channel-green?logo=slack)](https://kotlinlang.slack.com/archives/CEXV2QWNM)
# 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)
* [Requirements](#requirements)
2020-02-15 13:36:40 +03:00
* [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)
2022-01-07 12:29:43 +03:00
* [Visualization for External Systems](#visualization-for-external-systems)
2020-02-15 15:01:04 +03:00
* [Demonstrations](#demonstrations)
2022-01-07 12:29:43 +03:00
* [Simple Example - Solid Showcase](#simple-example---solid-showcase)
* [Full-Stack Application Example - Muon Monitor](#full-stack-application-example---muon-monitor-visualization)
* [GDML Example](#gdml-example)
2019-07-10 11:49:21 +03:00
2020-02-15 13:36:40 +03:00
## Introduction
2022-01-07 12:29:43 +03:00
This repository contains a [DataForge](#about-dataforge)\-based framework
used for visualization in various scientific applications.
2020-02-15 13:36:40 +03:00
2022-01-07 12:29:43 +03:00
The main framework's use case for now is 3D visualization for particle physics experiments.
2020-02-15 13:36:40 +03:00
Other applications including 2D plots are planned for the future.
2022-01-07 12:29:43 +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
## Requirements
JVM backend requires JDK 11 or later
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:
2022-01-07 12:29:43 +03:00
* [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
2020-02-15 13:36:40 +03:00
## Modules contained in this repository
2020-01-02 15:18:26 +03:00
2022-01-07 12:29:43 +03:00
$modules
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
2021-01-27 15:41:46 +03:00
![](docs/images/class-diag-solid.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
2022-01-07 12:29:43 +03:00
also referred to as templates). The idea is that prototype geometry can be rendered once and reused
2020-02-15 15:01:04 +03:00
for multiple objects. This helps to significantly decrease memory usage.
2022-01-07 12:29:43 +03:00
The `prototypes` property tree is defined in `SolidGroup` class via `PrototypeHolder` interface, and
2020-11-15 15:00:54 +03:00
`SolidReference` class helps to reuse a template object.
2020-02-15 15:01:04 +03:00
##### Styles
2020-02-15 15:01:04 +03:00
2022-01-07 12:29:43 +03:00
`VisionGroup` has a `styleSheet` property that can optionally define styles at the Group's
2021-08-22 13:25:57 +03:00
level. Styles are applied to child (descendant) objects using `Vision.styles: List<String>` property.
2020-01-02 15:18:26 +03:00
2021-08-22 13:25:57 +03:00
### visionforge-threejs
2019-10-06 21:29:04 +03:00
2022-01-07 12:29:43 +03:00
## Visualization for External Systems
2020-05-08 00:42:10 +03:00
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.
2022-01-07 12:29:43 +03:00
2020-05-08 00:42:10 +03:00
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
2021-07-28 15:56:54 +03:00
### Simple Example - Solid 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.
2021-07-28 15:56:54 +03:00
[More details](demo/solid-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
2021-07-28 15:56:54 +03:00
![](docs/images/solid-showcase.png)
2020-02-12 20:48:37 +03:00
2020-05-07 16:52:57 +03:00
### Full-Stack Application Example - Muon Monitor Visualization
2020-01-02 15:18:26 +03:00
2022-01-07 12:29:43 +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
2021-01-27 15:41:46 +03:00
![](docs/images/muon-monitor.png)
2020-02-12 20:48:37 +03:00
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
2022-01-07 12:29:43 +03:00
Visualization example for geometry defined as GDML file.
2020-02-15 13:36:40 +03:00
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
2021-01-27 15:41:46 +03:00
![](docs/images/gdml-demo.png)
2020-08-08 18:09:29 +03:00
## Thanks and references
The original three.js bindings were made by [Lars Ivar Hatledal](https://github.com/markaren), but the project is discontinued right now.
2021-07-28 15:56:54 +03:00
All other libraries are explicitly shown as dependencies. We would like to express specific thanks to JetBrains Kotlin-JS team for consulting us during the work.