From f49ad3ee2cb8485bed4ae571be26c1ddc4176f6e Mon Sep 17 00:00:00 2001 From: Peter Klimai Date: Wed, 9 Oct 2019 18:26:14 +0300 Subject: [PATCH] Doc updates --- README.md | 2 +- .../hep/dataforge/vis/common/AbstractVisualGroup.kt | 3 ++- .../hep/dataforge/vis/common/AbstractVisualObject.kt | 6 ++++++ .../kotlin/hep/dataforge/vis/common/Colors.kt | 9 ++++++++- .../hep/dataforge/vis/common/MutableVisualGroup.kt | 6 ++++++ .../kotlin/hep/dataforge/vis/common/VisualObject.kt | 10 ++++++++++ .../kotlin/hep/dataforge/vis/common/valueWidget.kt | 6 ++++++ .../kotlin/hep/dataforge/vis/spatial/Extruded.kt | 2 +- .../kotlin/hep/dataforge/vis/spatial/VisualGroup3D.kt | 3 +++ .../kotlin/hep/dataforge/vis/spatial/VisualObject3D.kt | 3 +++ .../vis/spatial/three/ThreeCompositeFactory.kt | 2 +- .../kotlin/hep/dataforge/vis/spatial/three/csg.kt | 3 +++ 12 files changed, 50 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 434dea40..dbddf3f7 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # DataForge Plugins for Visualisation -This repository contains [DataForge](http://www.inr.ru/~nozik/dataforge/) +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 accelerator experiments. 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 fda6c7fc..ca100ac8 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 @@ -8,7 +8,7 @@ import kotlinx.serialization.Transient /** - * Abstract implementation of group of [VisualObject] + * Abstract implementation of mutable group of [VisualObject] */ abstract class AbstractVisualGroup : AbstractVisualObject(), MutableVisualGroup { @@ -60,6 +60,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/AbstractVisualObject.kt b/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/AbstractVisualObject.kt index 01e2c770..12043a27 100644 --- a/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/AbstractVisualObject.kt +++ b/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/AbstractVisualObject.kt @@ -12,6 +12,9 @@ internal data class PropertyListener( val action: (name: Name, oldItem: MetaItem<*>?, newItem: MetaItem<*>?) -> Unit ) +/** + * Abstract implementation of [VisualObject] + */ abstract class AbstractVisualObject : VisualObject { @Transient @@ -19,6 +22,9 @@ abstract class AbstractVisualObject : VisualObject { abstract override var properties: Config? + /** + * Style(s) of the object + */ override var style: List get() = properties?.let { it[STYLE_KEY].stringList } ?: emptyList() set(value) { 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 1f42d87c..2e77fa45 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 @@ -3,7 +3,8 @@ package hep.dataforge.vis.common 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 @@ -177,11 +178,17 @@ object Colors { const val yellow = 0xFFFF00 const val yellowgreen = 0x9ACD32 + /** + * 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') diff --git a/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/MutableVisualGroup.kt b/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/MutableVisualGroup.kt index f3b1ca7d..8aa3e8d5 100644 --- a/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/MutableVisualGroup.kt +++ b/dataforge-vis-common/src/commonMain/kotlin/hep/dataforge/vis/common/MutableVisualGroup.kt @@ -4,6 +4,9 @@ import hep.dataforge.meta.Meta 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 @@ -52,6 +55,9 @@ interface VisualGroup : Provider, Iterable, VisualObject { } } +/** + * 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 4a5ce8b3..93f368a4 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 @@ -67,9 +67,19 @@ interface VisualObject : MetaRepr, Configurable { } } +/** + * 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) +/** + * Apply style to [VisualObject] by adding it to the [style] list + */ fun VisualObject.applyStyle(name: String) { style = style + name } \ No newline at end of file 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 32e8082d..6ae1f917 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 d960cfc7..7cea1f28 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 @@ -27,6 +27,9 @@ import kotlinx.serialization.Serializable import kotlinx.serialization.UseSerializers import kotlin.collections.set +/** + * Represents 3-dimensional Visual Group + */ @Serializable 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 cd9b22b3..0410677e 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.SELECTED_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