Merge pull request #33 from ModiaSim/an_docu_installationGuide

GerhardHippmann · web-flow · commit 05192b79516c · 2021-09-29T13:20:20.000+02:00
An docu installation guide
diff --git a/README.md b/README.md
@@ -16,7 +16,7 @@ Example videos:
 
 ## Installation
 
-Modia3D is included in [Modia](https://github.com/ModiaSim/Modia.jl) and is available, when Modia was installed.
+Modia3D is included in [Modia](https://github.com/ModiaSim/Modia.jl) and is available, when Modia was installed. Please, follow the [extensive installation guide](https://github.com/ModiaSim/Modia3D.jl/wiki/Full-Installation-Guide-for-Julia,-Modia3D,-Modia) or the [lightweight installation guide](https://github.com/ModiaSim/Modia3D.jl/wiki/Lightweight-Installation-Guide:-Julia-Modia3D) for Modia3D.
 
 A standalone Modia3D version is installed with
 
@@ -26,12 +26,12 @@ julia> ]add ModiaLang, Modia3D
 
 Modia3D animation can be exported in [three.js JSON Object Scene format](https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4) and then imported in the open source web app [three.js editor](https://threejs.org/editor/) and use all the features of three.js, for example to export in the widely used glb format (the binary version of the [glTF](https://www.khronos.org/gltf/) format) and use any glb viewer (for example 3D-Viewer of Windows 10).
 
-Additionally, the (free) community or the (commercial) professional version of the [DLR Visualization](http://www.systemcontrolinnovationlab.de/the-dlr-visualization-library/) library is supported that provides online animation (during simulation) and generation of mpg4-videos. To install the free version for *Windows* or for *Linux* perform the following steps:
+Additionally, Modia3D uses the (free) community or the (commercial) professional version of the [DLR Visualization Library](https://visualization.ltx.de/) for 3D simulations. It provides online animation (during simulation) and the generation of mpg4-videos. If you don't use the DLR Visualization Library result animation is switched of.
+Download and install the free DLR SimVis Community Edition, e.g. with [https://visualization.ltx.de/](https://visualization.ltx.de/) .
 
-1. Go to [https://visualization.ltx.de/](https://visualization.ltx.de/), provide your contact information and click on *Request download* for *Community Edition*. Afterwards, you get a link to download the library and you need to unzip the file.
-2. In your Julia **startup file** (`HOME/.julia/config/startup.jl`) include the environment variable `ENV["DLR_VISUALIZATION"] = "<path-to-library>/Visualization/Extras/SimVis"`. Make sure that the SimVis executable under this directory has execution rights. For example in Linux with command:`chmod ug+x <path-to-library>/Visualization/Extras/SimVis/linux/SimVis`
-3. Start Julia and run one of the tests, for example\
-   `include("$(Modia3D.path)/test/Basic/PendulumWithBar1.jl")`
+* Set an environment variable or add it to the [startup.jl file](https://github.com/ModiaSim/Modia3D.jl/wiki/Template-for-startup.jl). Please, read also the [installation guide](https://github.com/ModiaSim/Modia3D.jl/wiki/Full-Installation-Guide-for-Julia,-Modia3D,-Modia).
+   * `ENV["DLR_VISUALIZATION"] = "<path-to-library>/Visualization/Extras/SimVis"`
+   * Make sure that the SimVis executable under this directory has execution rights. For example in Linux with command: `chmod ug+x <path-to-library>/Visualization/Extras/SimVis/linux/SimVis`
 
 
 ## Main Developers and License
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -13,7 +13,7 @@ Example videos:
 
 ## Installation
 
-Modia3D is included in [Modia](https://github.com/ModiaSim/Modia.jl) and is available, when Modia was installed.
+Modia3D is included in [Modia](https://github.com/ModiaSim/Modia.jl) and is available, when Modia was installed. Please, follow the [extensive installation guide](https://github.com/ModiaSim/Modia3D.jl/wiki/Full-Installation-Guide-for-Julia,-Modia3D,-Modia) or the [lightweight installation guide](https://github.com/ModiaSim/Modia3D.jl/wiki/Lightweight-Installation-Guide:-Julia-Modia3D) for Modia3D.
 
 A standalone Modia3D version is installed with
 
@@ -23,12 +23,12 @@ julia> ]add ModiaLang, Modia3D
 
 Modia3D animation can be exported in threejs-json-format and then imported in the open source web app [threejs.org](https://threejs.org/editor/) and use all the features of threejs, for example to export in the widely used glb format (= the binary version of the [glTF](https://www.khronos.org/gltf/) format) and use any glb-viewer (for example 3D-Viewer of Windows 10).
 
-Additionally, the (free) community or the (commercial) professional version of the [DLR Visualization](http://www.systemcontrolinnovationlab.de/the-dlr-visualization-library/) library is supported that provides online animation (during simulation) and generation of mpg4-videos. To install the free version for *Windows* or for *Linux* perform the following steps:
+Additionally, Modia3D uses the (free) community or the (commercial) professional version of the [DLR Visualization Library](https://visualization.ltx.de/) for 3D simulations. It provides online animation (during simulation) and the generation of mpg4-videos. If you don't use the DLR Visualization Library result animation is switched of.
+Download and install the free DLR SimVis Community Edition, e.g. with [https://visualization.ltx.de/](https://visualization.ltx.de/) .
 
-1. Go to [https://visualization.ltx.de/](https://visualization.ltx.de/), provide your contact information and click on *Request download* for *Community Edition*. Afterwards, you get a link to download the library and you need to unzip the file.
-2. In your Julia **startup file** (`HOME/.julia/config/startup.jl`) include the environment variable `ENV["DLR_VISUALIZATION"] = "<path-to-library>/Visualization/Extras/SimVis"`. Make sure that the SimVis executable under this directory has execution rights. For example in Linux with command:`chmod ug+x <path-to-library>/Visualization/Extras/SimVis/linux/SimVis`
-3. Start Julia and run one of the tests, for example\
-   `include("$(Modia3D.path)/test/Basic/PendulumWithBar1.jl")`
+* Set an environment variable or add it to the [startup.jl file](https://github.com/ModiaSim/Modia3D.jl/wiki/Template-for-startup.jl). Please, read also the [installation guide](https://github.com/ModiaSim/Modia3D.jl/wiki/Full-Installation-Guide-for-Julia,-Modia3D,-Modia).
+   * `ENV["DLR_VISUALIZATION"] = "<path-to-library>/Visualization/Extras/SimVis"`
+   * Make sure that the SimVis executable under this directory has execution rights. For example in Linux with command: `chmod ug+x <path-to-library>/Visualization/Extras/SimVis/linux/SimVis`
 
 
 ## Release Notes
@@ -49,9 +49,11 @@ Additionally, the (free) community or the (commercial) professional version of t
 | [3] |*[Algorithms for Component-Based 3D Modeling](http://www.ep.liu.se/ecp/157/039/ecp19157039.pdf)*|[13th International Modelica Conference 2019, March](https://modelica.org/events/modelica2019)|[10.3384/ecp19157383](https://doi.org/10.3384/ecp19157383)|
 | [4a] |*[Modia3D: Modeling and Simulation of 3D-Systems in Julia](https://proceedings.juliacon.org/papers/10.21105/jcon.00043)*|[JuliaCon 2019, July](https://juliacon.org/2019/)|[10.21105/jcon.00043](https://doi.org/10.21105/jcon.00043)|
 | [4b] |*[Modia3D: Modeling and Simulation of 3D-Systems in Julia](https://proceedings.juliacon.org/papers/10.21105/jcon.00043)*|[JuliaCon 2019, July](https://juliacon.org/2019/)|[YouTube](https://www.youtube.com/watch?v=b3WfqXZRKpA)|
-| [5] |*Collision Handling with Elastic Response Calculation and Zero-Crossing Functions*|[EOOLT 2019, November](http://www.eoolt.org/2019/)|[10.1145/3365984.3365986](https://doi.org/10.1145/3365984.3365986)|
-| [6] |*Modia – Modeling Multidomain Engineering Systems with Julia*|[JuliaCon 2021, July](https://juliacon.org/2021/)|[YouTube](https://www.youtube.com/watch?v=N94si3rOl1g)|
-| [7] |*Modia – Equation Based Modeling and Domain Specific Algorithms*|[14th International Modelica Conference 2021, September](http://www.modelica.org/)|accepted for publication|
+| [5] |*[Collision Handling with Elastic Response Calculation and Zero-Crossing Functions](https://doi.org/10.1145/3365984.3365986)*|[EOOLT 2019, November](http://www.eoolt.org/2019/)|[10.1145/3365984.3365986](https://doi.org/10.1145/3365984.3365986)|
+| [6] |*[Modia – Modeling Multidomain Engineering Systems with Julia](https://www.youtube.com/watch?v=N94si3rOl1g)*|[JuliaCon 2021, July](https://juliacon.org/2021/)|[YouTube](https://www.youtube.com/watch?v=N94si3rOl1g)|
+| [7a] |*[Modia – Equation Based Modeling and Domain Specific Algorithms](https://doi.org/10.3384/ecp2118173)*|[14th International Modelica Conference 2021, September](http://www.modelica.org/)| [10.3384/ecp2118173](https://doi.org/10.3384/ecp2118173) |
+| [7b] |*[Modia – Equation Based Modeling and Domain Specific Algorithms](https://doi.org/10.3384/ecp2118173)*|[14th International Modelica Conference 2021, September](http://www.modelica.org/)| YouTube comming soon |
+
 
 
 
diff --git a/docs/src/tutorial/CollisionHandling.md b/docs/src/tutorial/CollisionHandling.md
@@ -36,6 +36,12 @@ plot(bouncingSphere, "free.r", figure=1)
 
 end
 ```
+or
+```julia
+julia> import Modia3D
+julia> include("$(Modia3D.path)/test/Tutorial/BouncingSphere.jl")
+```
+
 The commands above generate an instance of the model, simulate it and generate the following plot:
 
 ![Tutorial-Collision](../../resources/images/Tutorial/bouncingSphere.png)
diff --git a/docs/src/tutorial/GettingStarted.md b/docs/src/tutorial/GettingStarted.md
@@ -8,7 +8,7 @@ An [Object3D](@ref) constructor is the core element of Modia3D. It defines a coo
 
 ## 1. Pendulum
 
-In the following example a simple pendulum is defined. This example is a copy of: `$(Modia3D.path)/test/Tutorial/Pendulum1.jl`
+In the following example a simple pendulum is defined. This example is a copy of: `$(Modia3D.path)/test/Tutorial/Pendulum1.jl`. [Here](https://github.com/ModiaSim/Modia3D.jl/wiki/Full-Installation-Guide-for-Julia,-Modia3D,-Modia#running-julia-code-with-vs-codiumvs-code) is a short description of how to execute a Julia file in VS Code,
 
 ```julia
 module Pendulum1
@@ -30,10 +30,10 @@ plot(pendulum, "rev.phi")
 
 end
 ```
-or
+or execute it in the Julia `REPL`
 ```julia
-import Modia3D
-include("$(Modia3D.path)/test/Tutorial/Pendulum1.jl")
+julia> import Modia3D  # is only required for '$(Modia3D.path)' in the include command
+julia> include("$(Modia3D.path)/test/Tutorial/Pendulum1.jl")
 ```
 
 The `world` [Object3D](@ref) has feature [Scene](@ref) and is therefore the inertial system. The `body` Object3D is a [Solid](@ref) and defines the pendulum as a mass point with `mass = 1.0`. The `bodyFrame` Object3D defines a coordinate system on the `body` that is translated along the x-axis. A revolute joint connects `world` with `bodyFrame`.
@@ -73,8 +73,8 @@ end
 ```
 or
 ```julia
-import Modia3D
-include("$(Modia3D.path)/test/Tutorial/Pendulum2.jl")
+julia> import Modia3D
+julia> include("$(Modia3D.path)/test/Tutorial/Pendulum2.jl")
 ```
 
 Open the [three.js editor](https://threejs.org/editor/), import (File --> Import) the [json file](https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4) `Pendulum2.json` in your working directory and inspect the model:
@@ -122,8 +122,8 @@ end
 ```
 or
 ```julia
-import Modia3D
-include("$(Modia3D.path)/test/Tutorial/Pendulum3.jl")
+julia> import Modia3D
+julia> include("$(Modia3D.path)/test/Tutorial/Pendulum3.jl")
 ```
 
 The commands above generate an instance of the model, simulate it and generate the following plot:
@@ -136,20 +136,21 @@ The commands above generate an instance of the model, simulate it and generate t
 All examples of this tutorial are stored in `$(Modia3D.path)/test/Tutorial`.
 
 ```julia
-  include("$(Modia3D.path)/test/Tutorial/Pendulum1.jl")
-  include("$(Modia3D.path)/test/Tutorial/Pendulum2.jl")
-  include("$(Modia3D.path)/test/Tutorial/Pendulum3.jl")
-  include("$(Modia3D.path)/test/Tutorial/BouncingSphere.jl")
+julia> import Modia3D
+julia> include("$(Modia3D.path)/test/Tutorial/Pendulum1.jl")
+julia> include("$(Modia3D.path)/test/Tutorial/Pendulum2.jl")
+julia> include("$(Modia3D.path)/test/Tutorial/Pendulum3.jl")
+julia> include("$(Modia3D.path)/test/Tutorial/BouncingSphere.jl")
 ```
 
 To run all tests without graphics, execute:
 
 ```julia
-  include("$(Modia3D.path)/test/runtests.jl")
+julia> include("$(Modia3D.path)/test/runtests.jl")
 ```
 
 To run all tests with visualization and plots, execute:
 
 ```julia
-  include("$(Modia3D.path)/test/runtestsWithGraphics.jl")
+julia> include("$(Modia3D.path)/test/runtestsWithGraphics.jl")
 ```
diff --git a/docs/src/tutorial/Tutorial.md b/docs/src/tutorial/Tutorial.md
@@ -2,15 +2,39 @@
 
 This tutorial sketches the main features of Modia3D with examples. A detailed description is available in Modia3D Components.
 
-!!! info
-    Modia has an interface to various plot packages. A plot package can be
-    either selected by setting `ENV["MODIA_PLOT"] = XXX`, for example in the `config/startup.jl`
-    file of Julia or by command `Modia.usePlotPackage(XXX)`.
-    All examples assume that a plot package is defined.
-    Possible values for `XXX`:
-    - "[PyPlot](https://github.com/JuliaPy/PyPlot.jl)" (plots with Matplotlib from Python),
-    - "[GLMakie](https://github.com/JuliaPlots/GLMakie.jl)" (interactive plots in an OpenGL window),
-    - "[WGLMakie](https://github.com/JuliaPlots/WGLMakie.jl)" (interactive plots in a browser window),
-    - "[CairoMakie](https://github.com/JuliaPlots/CairoMakie.jl)" (static plots on file with publication quality),
-    - "NoPlot" (= all `plot(...)` calls are ignored), or
-    - "SilentNoPlot" (= NoPlot without messages).
+## Plotting
+
+Modia offers an interface to various plot packages. Please, read also the [installation guide](https://github.com/ModiaSim/Modia3D.jl/wiki/Full-Installation-Guide-for-Julia,-Modia3D,-Modia). Valid options are:
+
+| Environment option | Modia package | Description |
+|:---|:--------------|:---|
+|"[GLMakie](https://github.com/JuliaPlots/GLMakie.jl)"| [ModiaPlot_GLMakie](https://github.com/ModiaSim/ModiaPlot_GLMakie.jl) | interactive plots in an OpenGL window |
+|"[WGLMakie](https://github.com/JuliaPlots/WGLMakie.jl)"| [ModiaPlot_WGLMakie](https://github.com/ModiaSim/ModiaPlot_WGLMakie.jl) | interactive plots in a browser window |
+|"[CairoMakie](https://github.com/JuliaPlots/CairoMakie.jl)"| [ModiaPlot_CairoMakie](https://github.com/ModiaSim/ModiaPlot_CairoMakie.jl) | static plots on file with publication quality |
+|"[PyPlot](https://github.com/JuliaPy/PyPlot.jl)"| [ModiaPlot_PyPlot](https://github.com/ModiaSim/ModiaPlot_PyPlot.jl) | plots with Matplotlib from Python |
+|"NoPlot"| | all `plot(...)` calls are ignored |
+|"SilentNoPlot"| | like "NoPlot" without messages |
+
+First, you need to add the corresponding Modia package, e.g.
+```julia
+julia> ] add ModiaPlot_GLMakie
+```
+A plot package can be either selected by setting `ENV["MODIA_PLOT"] = "GLMakie"`, in the [startup.jl file](https://github.com/ModiaSim/Modia3D.jl/wiki/Template-for-startup.jl) of Julia or with command `Modia.usePlotPackage("GLMakie")`.
+
+
+## 3D Renderer
+
+### Three.js
+
+Modia3D animation can be exported in threejs-json-format and then imported in the open source web app [threejs.org](https://threejs.org/editor/) and use all the features of threejs, for example to export in the widely used glb format (= the binary version of the [glTF](https://www.khronos.org/gltf/) format) and use any glb-viewer (for example 3D-Viewer of Windows 10).
+
+Objects are visualized and exported for offline animation by defining `animationFile = "Pendulum2.json"` in [Scene](@ref), see [2. Pendulum with Animation](@ref).
+
+### The DLR Visualization Library
+
+Modia3D uses the (free) community or the (commercial) professional version of the [DLR Visualization Library](https://visualization.ltx.de/) for 3D simulations. It provides online animation (during simulation) and the generation of mpg4-videos. If you don't use the DLR Visualization Library result animation is switched of.
+Download and install the free DLR SimVis Community Edition, e.g. with [https://visualization.ltx.de/](https://visualization.ltx.de/) .
+
+* Set an environment variable or add it to the [startup.jl file](https://github.com/ModiaSim/Modia3D.jl/wiki/Template-for-startup.jl). Please, read also the [installation guide](https://github.com/ModiaSim/Modia3D.jl/wiki/Full-Installation-Guide-for-Julia,-Modia3D,-Modia).
+   * `ENV["DLR_VISUALIZATION"] = "<path-to-library>/Visualization/Extras/SimVis"`
+   * Make sure that the SimVis executable under this directory has execution rights. For example in Linux with command: `chmod ug+x <path-to-library>/Visualization/Extras/SimVis/linux/SimVis`
