diff --git a/README.md b/README.md index 83021789..ff2820f1 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,73 @@ [![JetBrains Research](https://jb.gg/badges/research.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) -# DataForge plugins for visualisation +# DataForge Visualisation Platform -## Common visualisation objects +This repository contains [DataForge](http://npm.mipt.ru/dataforge/) +(also [here](https://github.com/mipt-npm/dataforge-core)) components useful for visualization in +various scientific applications. Currently, the main application is 3D visualization for particle +physics experiments. -## JavaFX utilities for meta manipulations +The project is developed as a Kotlin multiplatform application, currently +targeting browser JavaScript and JVM. -## 3D visualisation +Main features: +- 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 +- Object tree with property editor +- Settings export and import +- Multiple platform support + -Includes common discription and serializers, JavaFX and Three.js implementations. +## Modules contained in this repository: -## GDML bindings for 3D visualisation (to be moved to gdml project) + +### dataforge-vis-common + +Common visualisation objects such as VisualObject and VisualGroup. + + +### dataforge-vis-spatial + +Includes common description and serializers for 3D visualisation, JavaFX and Three.js implementations. + + +### dataforge-vis-spatial-gdml + +GDML bindings for 3D visualisation (to be moved to gdml project). + + +### dataforge-vis-jsroot + +Some JSROOT bindings. + +Note: Currently, this part is experimental and put here for completeness. This module may not build. + + +### demo + +Several demonstrations of using the dataforge-vis framework: + +##### spatial-showcase + +Contains a simple demonstration (grid with a few shapes that you can rotate, move camera, etc.). + +To see the demo: run `demo/spatial-showcase/distribution/installJsDist` Gradle task, then open +`build/distribuions/spatial-showcase-js-0.1.0-dev/index.html` file in your browser. + +Other demos can be built similarly. + +##### muon-monitor + +A full-stack application example, showing the +[Muon Monitor](http://npm.mipt.ru/projects/physics.html#mounMonitor) experiment set-up. + +Includes server back-end generating events, as well as visualization front-end. + +To run full-stack app (both server and browser front-end), run +`demo/muon-monitor/application/run` task. + +##### gdml + +Visualization example for geometry defined as GDML file. diff --git a/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/AbstractVisualGroup.kt b/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/AbstractVisualGroup.kt index 3b93e602..889cb0dc 100644 --- a/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/AbstractVisualGroup.kt +++ b/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/AbstractVisualGroup.kt @@ -6,7 +6,7 @@ import kotlinx.serialization.Transient /** - * Abstract implementation of group of [VisualObject] + * Abstract implementation of mutable group of [VisualObject] */ abstract class AbstractVisualGroup : AbstractVisualObject(), MutableVisualGroup { @@ -24,6 +24,7 @@ abstract class AbstractVisualGroup : AbstractVisualObject(), MutableVisualGroup } } + // TODO Consider renaming to `StructureChangeListener` (singular) private data class StructureChangeListeners(val owner: Any?, val callback: (Name, VisualObject?) -> Unit) @Transient diff --git a/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/Colors.kt b/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/Colors.kt index 7577fa33..3335c086 100644 --- a/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/Colors.kt +++ b/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/Colors.kt @@ -6,7 +6,8 @@ import hep.dataforge.values.int import kotlin.math.max /** - * Taken from https://github.com/markaren/three.kt/blob/master/threejs-wrapper/src/main/kotlin/info/laht/threekt/math/ColorConstants.kt + * Definitions of common colors. Taken from + * https://github.com/markaren/three.kt/blob/master/threejs-wrapper/src/main/kotlin/info/laht/threekt/math/ColorConstants.kt */ object Colors { const val aliceblue = 0xF0F8FF @@ -184,6 +185,9 @@ object Colors { const val GREEN_KEY = "green" const val BLUE_KEY = "blue" + /** + * Convert color represented as Meta to string of format #rrggbb + */ fun fromMeta(item: MetaItem<*>): String { return when (item) { is MetaItem.NodeItem<*> -> { @@ -204,11 +208,17 @@ object Colors { } } + /** + * Convert Int color to string of format #rrggbb + */ fun rgbToString(rgb: Int): String { val string = rgb.toString(16).padStart(6, '0') return "#" + string.substring(max(0, string.length - 6)) } + /** + * Convert three bytes representing color to string of format #rrggbb + */ fun rgbToString(red: UByte, green: UByte, blue: UByte): String { fun colorToString(color: UByte): String { return color.toString(16).padStart(2, '0') @@ -221,6 +231,9 @@ object Colors { } } + /** + * Convert three bytes representing color to Meta + */ fun rgbToMeta(r: UByte, g: UByte, b: UByte): Meta = buildMeta { RED_KEY put r.toInt() GREEN_KEY put g.toInt() diff --git a/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/VisualGroup.kt b/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/VisualGroup.kt index bddfae6f..467616c3 100644 --- a/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/VisualGroup.kt +++ b/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/VisualGroup.kt @@ -3,6 +3,9 @@ package hep.dataforge.vis.common import hep.dataforge.names.* import hep.dataforge.provider.Provider +/** + * Represents a group of [VisualObject] instances + */ interface VisualGroup : Provider, Iterable, VisualObject { /** * A map of top level named children @@ -61,7 +64,9 @@ data class StyleRef(val group: VisualGroup, val styleName: Name) val VisualGroup.isEmpty: Boolean get() = this.children.isEmpty() - +/** + * Mutable version of [VisualGroup] + */ interface MutableVisualGroup : VisualGroup { /** diff --git a/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/VisualObject.kt b/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/VisualObject.kt index a5e47b6f..6aad894a 100644 --- a/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/VisualObject.kt +++ b/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/VisualObject.kt @@ -69,11 +69,17 @@ interface VisualObject : Configurable { //const val META_KEY = "@meta" //const val TAGS_KEY = "@tags" - } } +/** + * Get [VisualObject] property using key as a String + */ fun VisualObject.getProperty(key: String, inherit: Boolean = true): MetaItem<*>? = getProperty(key.toName(), inherit) + +/** + * Set [VisualObject] property using key as a String + */ fun VisualObject.setProperty(key: String, value: Any?) = setProperty(key.toName(), value) /** diff --git a/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/valueWidget.kt b/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/valueWidget.kt index fb4d5f32..8c45686f 100644 --- a/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/valueWidget.kt +++ b/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/valueWidget.kt @@ -3,12 +3,18 @@ package hep.dataforge.vis.common import hep.dataforge.descriptors.ValueDescriptor import hep.dataforge.meta.* +/** + * Extension property to access the "widget" key of [ValueDescriptor] + */ var ValueDescriptor.widget: Meta get() = this.config["widget"].node?: EmptyMeta set(value) { this.config["widget"] = value } +/** + * Extension property to access the "widget.type" key of [ValueDescriptor] + */ var ValueDescriptor.widgetType: String? get() = this["widget.type"].string set(value) { diff --git a/dataforge-vis-spatial/src/commonMain/kotlin/hep/dataforge/vis/spatial/Extruded.kt b/dataforge-vis-spatial/src/commonMain/kotlin/hep/dataforge/vis/spatial/Extruded.kt index 7255b7ef..18dac3d0 100644 --- a/dataforge-vis-spatial/src/commonMain/kotlin/hep/dataforge/vis/spatial/Extruded.kt +++ b/dataforge-vis-spatial/src/commonMain/kotlin/hep/dataforge/vis/spatial/Extruded.kt @@ -62,7 +62,7 @@ class Extruded( override fun toGeometry(geometryBuilder: GeometryBuilder) { val shape: Shape2D = shape - if (shape.size < 3) error("Extruded shape requires more than points per layer") + if (shape.size < 3) error("Extruded shape requires more than 2 points per layer") /** * Expand the shape for specific layers diff --git a/dataforge-vis-spatial/src/commonMain/kotlin/hep/dataforge/vis/spatial/VisualGroup3D.kt b/dataforge-vis-spatial/src/commonMain/kotlin/hep/dataforge/vis/spatial/VisualGroup3D.kt index 2983ff33..44717f4d 100644 --- a/dataforge-vis-spatial/src/commonMain/kotlin/hep/dataforge/vis/spatial/VisualGroup3D.kt +++ b/dataforge-vis-spatial/src/commonMain/kotlin/hep/dataforge/vis/spatial/VisualGroup3D.kt @@ -24,6 +24,9 @@ import kotlinx.serialization.Serializable import kotlinx.serialization.UseSerializers import kotlin.collections.set +/** + * Represents 3-dimensional Visual Group + */ @Serializable @SerialName("group.3d") class VisualGroup3D : AbstractVisualGroup(), VisualObject3D { diff --git a/dataforge-vis-spatial/src/commonMain/kotlin/hep/dataforge/vis/spatial/VisualObject3D.kt b/dataforge-vis-spatial/src/commonMain/kotlin/hep/dataforge/vis/spatial/VisualObject3D.kt index 78b7c88f..db95754a 100644 --- a/dataforge-vis-spatial/src/commonMain/kotlin/hep/dataforge/vis/spatial/VisualObject3D.kt +++ b/dataforge-vis-spatial/src/commonMain/kotlin/hep/dataforge/vis/spatial/VisualObject3D.kt @@ -14,6 +14,9 @@ import hep.dataforge.vis.spatial.VisualObject3D.Companion.LAYER_KEY import hep.dataforge.vis.spatial.VisualObject3D.Companion.VISIBLE_KEY import kotlinx.serialization.UseSerializers +/** + * Interface for 3-dimensional [VisualObject] + */ interface VisualObject3D : VisualObject { var position: Point3D? var rotation: Point3D? diff --git a/dataforge-vis-spatial/src/jsMain/kotlin/hep/dataforge/vis/spatial/three/ThreeCompositeFactory.kt b/dataforge-vis-spatial/src/jsMain/kotlin/hep/dataforge/vis/spatial/three/ThreeCompositeFactory.kt index b6ee8852..8b88208d 100644 --- a/dataforge-vis-spatial/src/jsMain/kotlin/hep/dataforge/vis/spatial/three/ThreeCompositeFactory.kt +++ b/dataforge-vis-spatial/src/jsMain/kotlin/hep/dataforge/vis/spatial/three/ThreeCompositeFactory.kt @@ -6,7 +6,7 @@ import info.laht.threekt.core.BufferGeometry import info.laht.threekt.objects.Mesh /** - * This should be inner, becaulse it uses object builder + * This should be inner, because it uses object builder */ class ThreeCompositeFactory(val three: ThreePlugin) : MeshThreeFactory(Composite::class) { diff --git a/dataforge-vis-spatial/src/jsMain/kotlin/hep/dataforge/vis/spatial/three/csg.kt b/dataforge-vis-spatial/src/jsMain/kotlin/hep/dataforge/vis/spatial/three/csg.kt index fa9a1c5b..036f729a 100644 --- a/dataforge-vis-spatial/src/jsMain/kotlin/hep/dataforge/vis/spatial/three/csg.kt +++ b/dataforge-vis-spatial/src/jsMain/kotlin/hep/dataforge/vis/spatial/three/csg.kt @@ -16,6 +16,9 @@ import info.laht.threekt.math.Matrix4 import info.laht.threekt.math.Vector3 import info.laht.threekt.objects.Mesh +/** + * Constructive Solid Geometry + */ open external class CSG { open var polygons: Array open fun clone(): CSG