diff --git a/README.md b/README.md index 621f474f..032b7ee4 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,13 @@ * [About DataForge](#about-dataforge) * [Modules contained in this repository](#modules-contained-in-this-repository) * [visionforge-core](#visionforge-core) - * [visionforge-solid](#visionforge-solid) + * [visionforge-fx](#visionforge-fx) * [visionforge-gdml](#visionforge-gdml) + * [visionforge-markdown](#visionforge-markdown) + * [visionforge-plotly](#visionforge-plotly) + * [visionforge-server](#visionforge-server) + * [visionforge-solid](#visionforge-solid) + * [visionforge-threejs](#visionforge-threejs) * [Visualization for External Systems](#visualization-for-external-systems) * [Demonstrations](#demonstrations) * [Simple Example - Solid Showcase](#simple-example---solid-showcase) @@ -75,6 +80,17 @@ The `visionforge-core` module also includes configuration editors for JS (in `js ![](docs/images/class-diag-core.png) +### visionforge-fx + +### visionforge-gdml + +GDML bindings for 3D visualization (to be moved to gdml project). + +### visionforge-markdown + +### visionforge-plotly + +### visionforge-server ### visionforge-solid @@ -95,14 +111,10 @@ The `prototypes` property tree is defined in `SolidGroup` class via `PrototypeHo ##### Styles -`SolidGroup` has a `styleSheet` property that can optionally define styles at the Group's -level. Styles are applied to child (descendant) objects using `Vision.styles: List` property. - - -### visionforge-gdml - -GDML bindings for 3D visualization (to be moved to gdml project). +`VisionGroup` has a `styleSheet` property that can optionally define styles at the Group's +level. Styles are applied to child (descendant) objects using `Vision.styles: List` property. +### visionforge-threejs ## Visualization for External Systems diff --git a/docs/hierarchy.md b/docs/hierarchy.md index a4097221..720af5d2 100644 --- a/docs/hierarchy.md +++ b/docs/hierarchy.md @@ -1,17 +1,50 @@ # Hierarchy -![](../docs/images/hierarchy.png) -**the image will be changed** +![](../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. -`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. +### VisionBase -* 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 +3D Visual Group with a container for templates visible inside this group. It has an interface `PrototypeHolder` which stands for being a container with prototype support. + +* 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.() -> Unit)` - create or edit prototype node as a group. + +### SolidReferenceGroup + +A class with `SolidReference` interface with reference `Solid`s for template objects reuse. + +### VisionGroupBase + +Abstract implementation of mutable group of `Vision`. + +### RootVisionGroup + +Non-serializable root group used to propagate manager to its children. + +### MutableVisionGroup + +Just a mutable version of `VisionGroup` \ No newline at end of file diff --git a/docs/images/hierarchy.png b/docs/images/hierarchy.png index e202c6af..9e9394ac 100644 Binary files a/docs/images/hierarchy.png and b/docs/images/hierarchy.png differ diff --git a/docs/images/spatial-showcase-FX.png b/docs/images/solid-showcase-FX.png similarity index 100% rename from docs/images/spatial-showcase-FX.png rename to docs/images/solid-showcase-FX.png diff --git a/docs/images/spatial-showcase.png b/docs/images/solid-showcase.png similarity index 100% rename from docs/images/spatial-showcase.png rename to docs/images/solid-showcase.png diff --git a/docs/inheritance.md b/docs/inheritance.md index c156bbda..d99451f3 100644 --- a/docs/inheritance.md +++ b/docs/inheritance.md @@ -2,22 +2,21 @@ Inheritance is an ability of an element to transfer a pack of properties to its `children` elements 'wrapped inside'. -Properties have to be set in a specific order: -### Main properties' inheritance: -* styles -* parents +Properties, which can be inherited by objects, are `styles`, `prototypes` (if the object is a reference), `inherit` (it stands for the presence of `parent` objects), and `defaults`. + +All values of `styles` property are contained in class `StyleSheet`, where they all are defined at `Group`s level. The `prototypes` property tree is defined in `SolidGroup` class via `PrototypeHolder` interface, and +`SolidReference` class helps to reuse a template object. + +The order of inheritance of properties is set in function `getPropertyValue` in `VisionBase` class. +The order is this: +* own styles +* prototypes +* parent * parent's styles * defaults -As for `prototypes`, this property has to be set after styles, but before parents. So the order will be this: -### Reference properties' inheritance: -* styles -* prototypes -* parents -* parent's styles -* defaults ------------------------- -Let's take a closer look using a [Muon Monitor Visualization](demo/muon-monitor/README.md). + +Let's take a closer look using a [Muon Monitor Visualization](../demo/muon-monitor/README.md). Running the demo, we will see this: ![](../docs/images/inheritance-1.png) @@ -31,15 +30,15 @@ On the right, there is a list with changeable properties. ![](../docs/images/inheritance-properties.png) Properties, which can or cannot be inherited, are these: -* `visible` - toggles the visibility of an element. To be exact, the invisibility of an element is inheritable. +* `visible` – toggles the visibility of an element. To be exact, the invisibility of an element is inheritable. If a `parent` element is invisible, other elements are invisible as well, and they cannot be changed to visible mode. ![](../docs/images/inheritance-2-1-1.png) ![](../docs/images/inheritance-2-1-2.png) -* `material` - a group of properties, which can be inherited and which can be changed in `children` elements. - * `color` - color of an element. - * `opacity` - a number from 0 to 1 which represents percents of opacity (0 for 0%, 1 for 100%). - * `wireframe` - toggles the wireframe mode. +* `material` – a group of properties, which can be inherited and which can be changed in `children` elements. + * `color` – color of an element. + * `opacity` – a number from 0 to 1 which represents percents of opacity (0 for 0%, 1 for 100%). + * `wireframe` – toggles the wireframe mode. Let's see how elements of the `material` group inherit changing `color` property; ***other properties of this group inherit in the same way.*** @@ -51,7 +50,7 @@ Properties, which can or cannot be inherited, are these: ![](../docs/images/inheritance-2-2-2.png) It changes only, 'bottom' and 'middle' stays the same. - 'top' is a `parent` element as well: it has `children` - 'SC72', 'SC73', ... ,'SC80'. + 'top' is a `parent` element as well: it has `children` – 'SC72', 'SC73', ... ,'SC80'. Let's change the color of 'SC76': ![](../docs/images/inheritance-2-2-3.png) Again, only 'SC76' has changed among other 'siblings'. @@ -64,5 +63,5 @@ Properties, which can or cannot be inherited, are these: If after all those changes we set at the 'World' element grey color, changes won't disappear: ![](../docs/images/inheritance-2-2-5.png) -* `rotation` - rotation of an element. Here, it is set by `x` value. It is inheritable and unable to be changed in `children` elements. -* `position` - position of an element, cannot be inherited. +* `rotation` – rotation of an element. Here, it is set by `x` value. It is inheritable and unable to be changed in `children` elements. +* `position` – position of an element, cannot be inherited. diff --git a/docs/uml/Vision.puml b/docs/uml/Vision.puml index bb3143cc..04e873b9 100644 --- a/docs/uml/Vision.puml +++ b/docs/uml/Vision.puml @@ -1,108 +1,126 @@ @startuml 'https://plantuml.com/class-diagram -interface Vision +interface Vision{ + val parent: VisionGroup? + fun getPropertyValue(name,inherit,includeStyles,includeDefaults): Value? +} -interface Solid -Vision <- Solid +interface Solid{ + The base for 3D geometry +} +Vision <-- Solid +class VisionGroup{ + A group of Visions -class VisionGroup + val children: Map + val defaultTarget: String + + fun content(target): Map + fun get(name: Name): Vision? +} Vision <-- VisionGroup -class VisionBase -Vision <- VisionBase +class VisionBase{ + basic vision implementation +} +Vision <-- VisionBase class SolidLabel Solid <--- SolidLabel -SolidBase <-- SolidLabel -class SolidGroup +class SolidGroup{ + var properties: MutableMeta? + val children: Map + var prototypes: MutableVisionGroup? + + fun getPrototype(name): Solid? + fun prototypes(builder) +} Solid <--- SolidGroup VisionGroupBase <-- SolidGroup -class SolidBase -Solid <--- SolidBase -VisionBase <-- SolidBase - - class SphereLayer -SolidBase <-- SphereLayer -GeometrySolid <-- SphereLayer +Solid <-- SphereLayer class Sphere -SolidBase <-- Sphere -GeometrySolid <-- Sphere +Solid <-- Sphere class Box -SolidBase <-- Box Hexagon <-- Box class GenericHexagon -SolidBase <-- GenericHexagon Hexagon <-- GenericHexagon class Extruded -SolidBase <-- Extruded -GeometrySolid <-- Extruded +Solid <-- Extruded class PolyLine Solid <--- PolyLine -SolidBase <-- 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 Solid <--- Convex -SolidBase <-- Convex class Composite Solid <--- Composite -SolidBase <-- Composite -interface SolidReference +interface SolidReference{ + val prototype: Solid + fun getPropertyValue(name,inherit,includeStyles,includeDefaults): Value? +} VisionGroup <---- SolidReference +SolidReferenceGroup -- SolidReference -interface MutableVisionGroup +class SolidReferenceGroup{ + val refName: Name + var properties: MutableMeta? + val prototype: Solid + val children: Map + fun getPropertyValue(name,inherit,includeStyles,includeDefaults): Value? +} +VisionBase <-- SolidReferenceGroup +VisionGroup <-- SolidReferenceGroup + +interface MutableVisionGroup{ + fun onStructureChanged(owner, block) + fun removeStructureListener(owner) +} VisionGroup <---- MutableVisionGroup -class SolidReferenceGroup -VisionGroup <-- SolidReferenceGroup -Solid <-- SolidReferenceGroup -VisionBase <-- SolidReferenceGroup -SolidReference <-- SolidReferenceGroup - -class ReferenceChild -VisionGroup <-- ReferenceChild -Solid <-- ReferenceChild -SolidReference <-- ReferenceChild - - -class VisionGroupBase +class VisionGroupBase{ + val children: Map + fun set(name: Name?, child: Vision?) +} VisionBase <-- VisionGroupBase MutableVisionGroup <-- VisionGroupBase - - class 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 \ No newline at end of file diff --git a/gradle.properties b/gradle.properties index d472c5ef..0443442f 100644 --- a/gradle.properties +++ b/gradle.properties @@ -2,7 +2,6 @@ kotlin.code.style=official kotlin.mpp.stability.nowarn=true kotlin.jupyter.add.scanner=false -#kotlin.incremental.js.klib=false org.gradle.jvmargs=-XX:MaxMetaspaceSize=1G org.gradle.parallel=true \ No newline at end of file diff --git a/visionforge-core/src/commonMain/kotlin/space/kscience/visionforge/Vision.kt b/visionforge-core/src/commonMain/kotlin/space/kscience/visionforge/Vision.kt index 924dfdd1..1c8e3a28 100644 --- a/visionforge-core/src/commonMain/kotlin/space/kscience/visionforge/Vision.kt +++ b/visionforge-core/src/commonMain/kotlin/space/kscience/visionforge/Vision.kt @@ -36,7 +36,7 @@ public interface Vision : Described, Configurable { public val manager: VisionManager? get() = parent?.manager /** - * This Vision own properties (ignoring inheritance, styles and defaults + * This Vision own properties (ignoring inheritance, styles and defaults) */ override val meta: ObservableMutableMeta @@ -92,7 +92,7 @@ public val Vision.propertyChanges: Flow } /** - * Subscribe on property updates. The subscription is bound to the given [scope] and canceled when the scope is canceled + * Subscribe on property updates. The subscription is bound to the given scope and canceled when the scope is canceled */ public fun Vision.onPropertyChange(callback: Meta.(Name) -> Unit) { meta.onChange(null, callback) diff --git a/visionforge-core/src/commonMain/kotlin/space/kscience/visionforge/VisionBase.kt b/visionforge-core/src/commonMain/kotlin/space/kscience/visionforge/VisionBase.kt index 74f173ae..dce9bbd5 100644 --- a/visionforge-core/src/commonMain/kotlin/space/kscience/visionforge/VisionBase.kt +++ b/visionforge-core/src/commonMain/kotlin/space/kscience/visionforge/VisionBase.kt @@ -23,7 +23,7 @@ internal data class MetaListener( /** * A full base implementation for a [Vision] - * @param parent the parent object for this vision. Could ve set later. Not serialized. + * @param parent the parent object for this vision. Could've set later. Not serialized. */ @Serializable @SerialName("vision")