Merge branch 'main' into gh_freeMotionAdaptiveRotationSequence

Author: GerhardHippmann

README.md

@@ -5,33 +5,33 @@
 
 [Modia3D](https://github.com/ModiaSim/Modia3D.jl) is a Julia package that integrates a multibody program and 3D shapes for visualization and collision handling into the [Modia Modeling Language](https://github.com/ModiaSim/ModiaLang.jl). It is then, for example, possible to model the 3D mechanical part of a robot with Modia3D and the electrical motors and gearboxes that are driving the joints with the Modia language. Collision handling with elastic response calculation is performed for shapes that are defined with a contact material and have a convex geometry or are approximated by the convex hull of a concave geometry. For more details, see the [Modia3D Tutorial](https://modiasim.github.io/Modia3D.jl/stable/tutorial/Tutorial.html).
 
-The multibody program supports currently tree-structured multibody systems, but does not (yet) support kinematic loops.
+Modia3D supports currently tree-structured multibody systems, but does not (yet) support kinematic loops.
 
 Example videos:
 
-- [YouBot robots with gripping](https://modiasim.github.io/Modia3D.jl/resources/videos/YouBotsGripping.mp4)
+- [YouBot robots gripping a workpiece](https://modiasim.github.io/Modia3D.jl/resources/videos/YouBotsGripping.mp4)
 - [Billiard table with 16 balls](https://modiasim.github.io/Modia3D.jl/resources/videos/Billard16Balls.mp4)
-- [Mobile with depthmax=8](https://modiasim.github.io/Modia3D.jl/resources/videos/Mobile8.mp4)
+- [Mobile with 8 levels](https://modiasim.github.io/Modia3D.jl/resources/videos/Mobile8.mp4)
 
 
 ## 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
 
 ```julia
 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).
+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

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 |
+
 
 
 

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)

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")
 ```

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`