Merge pull request #14 from kiruma524/tutorial

Documantation of hierarchy, raw version №1

README.md

@@ -17,6 +17,11 @@
   * [visionforge-core](#visionforge-core)
   * [visionforge-solid](#visionforge-solid)
   * [visionforge-gdml](#visionforge-gdml)
+  * [visionforge-fx](#visionforge-fx)
+  * [visionforge-markdown](#visionforge-markdown)
+  * [visionforge-plotly](#visionforge-plotly)
+  * [visionforge-server](#visionforge-server)
+  * [visionforge-threejs](#visionforge-threejs)
 * [Visualization for External Systems](#visualization-for-external-systems)  
 * [Demonstrations](#demonstrations)
   * [Simple Example - Solid Showcase](#simple-example---solid-showcase)
@@ -65,6 +70,13 @@ To learn more about DataForge, please consult the following URLs:
 ## Modules contained in this repository
 
 ### visionforge-core
+> Core classes, algebra definitions, basic linear algebra
+>
+> **Maturity**: DEVELOPMENT
+>
+> **Features:**
+> - [vision](visionforge-core/src/commonMain/kotlin/space/kscience/visionforge/Vision.kt) : an architecture of visions.
+<hr/>
 
 Contains a general hierarchy of classes and interfaces useful for visualization. 
 This module is not specific to 3D-visualization.

build.gradle.kts

@@ -34,3 +34,7 @@ apiValidation {
     validationDisabled = true
     ignoredPackages.add("info.laht.threekt")
 }
+
+rootProject.plugins.withType(org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsRootPlugin::class.java) {
+    rootProject.the<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsRootExtension>().versions.webpackDevServer.version = "4.0.0-rc.0"
+}

docs/hierarchy.md

@@ -3,14 +3,41 @@
 ![](../docs/images/hierarchy.png)
 
 ### Vision
+* function `getPropertyValue(name: Name, inherit: Boolean = false, includeStyles: Boolean = true, includeDefaults: Boolean = true)` - get property value with given layer flags.
 
-* function `getProperty(name: Name, inherit: Boolean, includeStyles: Boolean, includeDefaults: Boolean)`. 
+* function `setProperty(name: Name, item: Any?)` - a convenient method to set property node or value. If `item` is null, then node is removed, not a value
+Sets the `item` property to the element with the `name` identification.
 
-It gets properties of element with `name` identification.
+### VisionBase
-`inherit` — toggles parent node property lookup. Null means inference from descriptor. Default is false.
-`includeStyles` — toggles inclusion of. Null means inference from descriptor. Default is true. 
-`includeDefaults` — default is false.
 
-* function `setProperty(name: Name, item: MetaItem?, notify: Boolean = true)`
+Basic vision implementation
 
-Sets the `item` property to the element with the `name` identification. `notify` is a value which toggles the necessity of the change notification. Default is true.
+### VisionGroup
+
+A group of Visions.
+
+### MutableVisionGroup
+
+Mutable version of VisionGroup.
+
+low structure changes of this group. Unconsumed changes are discarded.
+
+### Solid
+
+Interface for 3-dimensional Vision.
+
+### SolidGroup
+
+* function `getPrototype(name: Name)` - get a prototype redirecting the request to the parent if prototype is not found. If prototype is a ref, then it is unfolded automatically.
+
+* function `prototypes(builder: VisionContainerBuilder<Solid>.() -> Unit)` - create or edit prototype node as a group. 
+
+### SolidReferenceGroup
+
+A reference Solid to reuse a template object.
+
+### RootVisionGroup
+
+Non-serializable root group used to propagate manager to its children.
+
+* function Vision.root(manager: VisionManager) - designate this [VisionGroup] as a root group and assign a [VisionManager] as its parent.

docs/uml/Vision.puml

@@ -3,41 +3,50 @@
 
 interface Vision{
     val parent: VisionGroup?
-    fun getProperty(name):TypedMetaItem?
+    fun getPropertyValue(name,inherit,includeStyles,includeDefaults): Value?
-    fun setProperty(name, item)
 }
 
 interface Solid{
-    base of 3D geometries
+    The base for 3D geometry
 }
-Vision <- Solid
+Vision <-- Solid
 
 class VisionGroup{
-    a group of visions
+    A group of Visions
-}
 
+    val children: Map<NameToken, Vision>
+    val defaultTarget: String
+
+    fun content(target): Map<Name, Any>
+    fun get(name: Name): Vision?
+}
 Vision <-- VisionGroup
 
 class VisionBase{
-    basic vision
+    basic vision implementation
-    implementation
 }
-Vision <- VisionBase
+Vision <-- VisionBase
 
 
 class SolidLabel
 Solid <--- SolidLabel
 
-class SolidGroup
+class SolidGroup{
-Solid <--- SolidGroup
+    var properties: MutableMeta?
-MutableVisionGroup <-- SolidGroup
+    val children: Map<NameToken, Vision>
+    var prototypes: MutableVisionGroup?
 
+    fun getPrototype(name): Solid?
+    fun prototypes(builder)
+}
+Solid <--- SolidGroup
+VisionGroupBase <-- SolidGroup
 
 class SphereLayer
-GeometrySolid <-- SphereLayer
+Solid <-- SphereLayer
 
 class Sphere
-GeometrySolid <-- Sphere
+Solid <-- Sphere
 
 class Box
 Hexagon <-- Box
@@ -46,24 +55,21 @@ class GenericHexagon
 Hexagon <-- GenericHexagon
 
 class Extruded
-GeometrySolid <-- Extruded
+Solid <-- Extruded
 
 
 class PolyLine
 Solid <--- PolyLine
 
-interface GeometrySolid
-Solid <--- GeometrySolid
-
 
 interface Hexagon
-GeometrySolid <-- Hexagon
+Solid <-- Hexagon
 
 class ConeSegment
-GeometrySolid <-- ConeSegment
+Solid <-- ConeSegment
 
 class ConeSurface
-GeometrySolid <-- ConeSurface
+Solid <-- ConeSurface
 
 
 class Convex
@@ -73,29 +79,46 @@ class Composite
 Solid <--- Composite
 
 
-interface SolidReference
+interface SolidReference{
+    val prototype: Solid
+    fun getPropertyValue(name,inherit,includeStyles,includeDefaults): Value?
+}
 VisionGroup <---- SolidReference
 
-interface MutableVisionGroup
+class SolidReferenceGroup{
+    val refName: Name
+    var properties: MutableMeta?
+    val prototype: Solid
+    val children: Map<NameToken, Vision>
+    fun getPropertyValue(name,inherit,includeStyles,includeDefaults): Value?
+}
+VisionBase <-- SolidReferenceGroup
+
+interface MutableVisionGroup{
+    fun onStructureChanged(owner, block)
+    fun removeStructureListener(owner)
+}
 VisionGroup <---- MutableVisionGroup
 
-class SolidReferenceGroup
+class VisionGroupBase{
-VisionGroup <-- SolidReferenceGroup
+    val children: Map<NameToken, Vision>
-Solid <-- SolidReferenceGroup
+    fun set(name: Name?, child: Vision?)
-VisionBase <-- SolidReferenceGroup
+}
-SolidReference <-- SolidReferenceGroup
+VisionBase <-- VisionGroupBase
-
+MutableVisionGroup <-- VisionGroupBase
-class ReferenceChild
-VisionGroup <-- ReferenceChild
-Solid <-- ReferenceChild
-SolidReference <-- ReferenceChild
-
-
 
 class RootVisionGroup
-MutableVisionGroup <-- RootVisionGroup
+VisionGroupBase <-- RootVisionGroup
 
-
+class VisionOfPlotly{
-class VisionOfPlotly
+     var properties: MutableMeta?
+     val plot: Plot
+}
 VisionBase <-- VisionOfPlotly
+
+class VisionOfMarkup{
+    val format: String
+    var content: String?
+}
+VisionBase <-- VisionOfMarkup
 @enduml

visionforge-core/src/commonMain/kotlin/space/kscience/visionforge/Vision.kt

@@ -109,7 +109,7 @@ public fun Vision.getPropertyValue(
 ): Value? = getPropertyValue(Name.parse(key), inherit, includeStyles, includeDefaults)
 
 /**
- * A convenience method to set property node or value. If Item is null, then node is removed, not a value
+ * A convenient method to set property node or value. If Item is null, then node is removed, not a value
  */
 public fun Vision.setProperty(name: Name, item: Any?) {
     when (item) {

visionforge-solid/src/commonMain/kotlin/space/kscience/visionforge/solid/SolidGroup.kt

@@ -26,7 +26,7 @@ public interface PrototypeHolder {
 
 /**
  * Represents 3-dimensional Visual Group
- * @param prototypes A container for templates visible inside this group
+ * @param prototypes is a container for templates visible inside this group
  */
 @Serializable
 @SerialName("group.solid")