Merge pull request #26 from pklimai/readme-update

Readme update #25

README.md

@@ -2,7 +2,7 @@
 
 # DataForge Visualization Platform
 
-## Table of contents
+## Table of Contents
 
 * [Introduction](#introduction)
 * [Features](#features)
@@ -12,9 +12,10 @@
   * [dataforge-vis-spatial](#dataforge-vis-spatial)
   * [dataforge-vis-spatial-gdml](#dataforge-vis-spatial-gdml)
   * [dataforge-vis-jsroot](#dataforge-vis-jsroot)
+* [Visualization for External Systems](#visualization-for-external-systems)  
 * [Demonstrations](#demonstrations)
-  * [Spatial Showcase](#spatial-showcase)
-  * [Muon Monitor](#muon-monitor-visualization)
+  * [Simple Example - Spatial Showcase](#simple-example---spatial-showcase)
+  * [Full-Stack Application Example - Muon Monitor](#full-stack-application-example---muon-monitor-visualization)
   * [GDML Example](#gdml-example)
 
 
@@ -26,8 +27,8 @@ used for visualization in various scientific applications.
 The main framework's use case for now is 3D visualization for particle physics experiments. 
 Other applications including 2D plots are planned for the future.
 
-The project is being developed as a Kotlin multiplatform application, currently targeting browser 
-JavaScript and JVM.
+The project is developed as a [Kotlin multiplatform](https://kotlinlang.org/docs/reference/multiplatform.html) 
+application, currently targeting browser JavaScript and JVM.
 
 
 ## Features
@@ -103,44 +104,49 @@ Some JSROOT bindings.
 Note: Currently, this part is experimental and put here for completeness. This module may not build.
 
 
+## Visualization for External Systems 
+
+The `dataforge-vis` framework can be used to visualize geometry and events from external,
+non-Kotlin based systems, such as ROOT. This will require a plugin to convert data model
+of the external system to that of `dataforge-vis`. Performing such integration is a work 
+currently in progress.
+ 
+
 ## Demonstrations
 
-The `demo` module contains several demonstrations of using the `dataforge-vis` framework:
+The `demo` module contains several example projects (demonstrations) of using the `dataforge-vis` framework.
+They are briefly described in this section, for more details please consult the corresponding per-project
+README file.
 
-### Spatial Showcase
+### Simple Example - Spatial Showcase
 
 Contains a simple demonstration with a grid including a few shapes that you can rotate, move camera, and so on.
 Some shapes will also periodically change their color and visibility.
 
-To see the demo: run `demo/spatial-showcase/Tasks/distribution/installJsDist` Gradle task, then open
-`build/distribuions/spatial-showcase-js-0.1.0-dev/index.html` file in your browser.
+[More details](demo/spatial-showcase/README.md)
 
 ##### Example view:
 
 ![](doc/resources/spatial-showcase.png)
 
-### Muon Monitor Visualization
+
+### Full-Stack Application Example - Muon Monitor Visualization
 
 A full-stack application example, showing the 
-[Muon Monitor](http://npm.mipt.ru/projects/physics.html#mounMonitor) experiment set-up.
+[Muon Monitor](http://npm.mipt.ru/en/projects/physics#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.
+[More details](demo/muon-monitor/README.md)
 
 ##### Example view:
 
 ![](doc/resources/muon-monitor.png)
 
+
 ### GDML Example
 
 Visualization example for geometry defined as GDML file. 
 
-To build the app, run `demo/gdml/Tasks/distribution/installJsDist` task, then open
-`build/distribuions/gdml-js-0.1.0-dev/index.html` file in your browser, and
-drag-and-drop GDML file to the window to see visualization. For an example file, use 
-`demo/gdml/src/jsMain/resources/cubes.gdml`.
+[More details](demo/gdml/README.md)
 
 ##### Example view:
 

demo/gdml/README.md

@@ -0,0 +1,15 @@
+
+### GDML Example
+
+Visualization example for geometry defined as GDML file. 
+
+##### Building project
+
+To build the app, run `demo/gdml/Tasks/distribution/jsBrowserDistribution` Gradle task, then open
+`demo/gdml/build/distribuions/gdml-js-0.1.3-dev/index.html` file in your browser, and
+drag-and-drop GDML file to the window to see visualization. For an example file, you can use 
+`demo/gdml/src/jsMain/resources/cubes.gdml`.
+
+##### Example view:
+
+![](../../doc/resources/gdml-demo.png)

demo/muon-monitor/README.md

@@ -0,0 +1,33 @@
+
+### Muon Monitor Visualization
+
+This directory contains a full-stack application example built with `dataforge-vis`.
+It is visualizing the 
+[Muon Monitor](http://npm.mipt.ru/projects/physics.html#mounMonitor) experiment set-up,
+including experiment's geometry and events (particle tracks).
+
+#### Reusing code and going Full-Stack with Kotlin Multiplatform
+
+The application includes both server back-end generating events, as well as client 
+visualization front-end.
+
+As is common for Kotlin multiplatform projects, the code base of this simple application 
+is put in the following main directories:
+* `commonMain` - common code, used by both JS client and JVM server. For example, the `Monitor`
+object describes general geometry definitions needed in all parts of the application.
+* `jsMain` - JavaScript client code. It performs visualization and reads events from the server.  
+* `jvmMain` - JVM server code. It runs `ktor` HTTP server, responding with event data when
+client requests them.
+
+Note that in a more traditional approach when client and server are developed separately
+and possibly using different languages, there would be no benefit of reusing common code. 
+
+##### Building project
+
+To run full-stack Muon Monitor Visualization application (both JVM server and Web browser front-end), 
+run `demo/muon-monitor/application/run` task.
+
+##### Example view:
+
+![](../../doc/resources/muon-monitor.png)
+

demo/spatial-showcase/README.md

@@ -0,0 +1,19 @@
+### Spatial Showcase
+
+Contains a simple demonstration with a grid including a few shapes that you can rotate, move camera, and so on.
+Some shapes will also periodically change their color and visibility.
+
+##### Building project
+ 
+To see the JS demo: run `demo/spatial-showcase/Tasks/distribution/jsBrowserDistribution` Gradle task, then open
+`build/distribuions/spatial-showcase-js-0.1.3-dev/index.html` file in your browser.
+
+To see Java FX demo, run `main()` from `FXDemoApp.kt`.
+
+##### Example view for JS:
+
+![](../../doc/resources/spatial-showcase.png)
+
+##### Example view for Java FX:
+
+![](../../doc/resources/spatial-showcase-FX.png)