Enable CoordinateSystem support in animation export

- Enable support for shape kind CoordinateSystem.
- Add moving CoordinateSystems in test Collision/BouncingBeams.jl.
- Update docu.
- Improve animation export info in README.md.

Author: GerhardHippmann

README.md

@@ -5,13 +5,13 @@
 
 [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
@@ -24,7 +24,7 @@ A standalone Modia3D version is installed with
 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:
 

src/AnimationExport/exportAnimation.jl

@@ -4,49 +4,57 @@ function name2uuid(name::String)
     return string(UUIDs.uuid5(u4, name))
 end
 
+const coSysMaterialRed   = (; name="coordinateSystem.red", uuid=name2uuid("coordinateSystem.red"), type="MeshPhongMaterial", color=((255*256 + 0)*256 + 0), opacity=1, transparent=false, shininess=0.5)
+const coSysMaterialGreen = (; name="coordinateSystem.green", uuid=name2uuid("coordinateSystem.green"), type="MeshPhongMaterial", color=((255*0 + 255)*256 + 0), opacity=1, transparent=false, shininess=0.5)
+const coSysMaterialBlue  = (; name="coordinateSystem.blue", uuid=name2uuid("coordinateSystem.blue"), type="MeshPhongMaterial", color=((255*0 + 0)*256 + 255), opacity=1, transparent=false, shininess=0.5)
+
 
 function exportObject(object, elements, obj::Modia3D.Composition.Object3D, sphere::Modia3D.Shapes.Sphere, initPos, initRot)
     r_obj = Modia3D.ZeroVector3D
     R_obj = Modia3D.NullRotation
-    name = String(Modia3D.fullName(obj)) * ".geometry"
-    geometry = (; name=name, uuid=name2uuid(name), type="SphereBufferGeometry", radius=sphere.diameter/2, heightSegments=16, widthSegments=32)
+    name = Modia3D.fullName(obj)
+    geometryName = name * ".geometry"
+    geometry = (; name=geometryName, uuid=name2uuid(geometryName), type="SphereBufferGeometry", radius=sphere.diameter/2, heightSegments=16, widthSegments=32)
     material = printVisuMaterialToJSON(obj, obj.visualMaterial)
-    objectInfo = getObjectInfo(obj, geometry, material, initPos, initRot)
+    objectInfo = getObjectInfo(name, geometry, material, initPos, initRot)
     printInfoToFile(object, elements, geometry, material, nothing, objectInfo)
     return (r_obj, R_obj)
 end
 
 function exportObject(object, elements, obj::Modia3D.Composition.Object3D, ellipsoid::Modia3D.Shapes.Ellipsoid, initPos, initRot)
     r_obj = Modia3D.ZeroVector3D
     R_obj = Modia3D.NullRotation
-    name = String(Modia3D.fullName(obj)) * ".geometry"
-    geometry = (; name=name, uuid=name2uuid(name), type="SphereBufferGeometry", radius=ellipsoid.lengthX/2, heightSegments=16, widthSegments=32)
+    name = Modia3D.fullName(obj)
+    geometryName = name * ".geometry"
+    geometry = (; name=geometryName, uuid=name2uuid(geometryName), type="SphereBufferGeometry", radius=ellipsoid.lengthX/2, heightSegments=16, widthSegments=32)
     material = printVisuMaterialToJSON(obj, obj.visualMaterial)
-    objectInfo = getObjectInfo(obj, geometry, material, initPos, initRot, scale=[1.0, ellipsoid.lengthY/ellipsoid.lengthX, ellipsoid.lengthZ/ellipsoid.lengthX])
+    objectInfo = getObjectInfo(name, geometry, material, initPos, initRot, scale=[1.0, ellipsoid.lengthY/ellipsoid.lengthX, ellipsoid.lengthZ/ellipsoid.lengthX])
     printInfoToFile(object, elements, geometry, material, nothing, objectInfo)
     return (r_obj, R_obj)
 end
 
 function exportObject(object, elements, obj::Modia3D.Composition.Object3D, box::Modia3D.Shapes.Box, initPos, initRot)
     r_obj = Modia3D.ZeroVector3D
     R_obj = Modia3D.NullRotation
-    name = String(Modia3D.fullName(obj)) * ".geometry"
-    geometry = (; name=name, uuid=name2uuid(name), type="BoxBufferGeometry", width=box.lengthX, height=box.lengthY, depth=box.lengthZ)
+    name = Modia3D.fullName(obj)
+    geometryName = name * ".geometry"
+    geometry = (; name=geometryName, uuid=name2uuid(geometryName), type="BoxBufferGeometry", width=box.lengthX, height=box.lengthY, depth=box.lengthZ)
     material = printVisuMaterialToJSON(obj, obj.visualMaterial)
-    objectInfo = getObjectInfo(obj, geometry, material, initPos, initRot)
+    objectInfo = getObjectInfo(name, geometry, material, initPos, initRot)
     printInfoToFile(object, elements, geometry, material, nothing, objectInfo)
     return (r_obj, R_obj)
 end
 
 function exportObject(object, elements, obj::Modia3D.Composition.Object3D, cylinder::Modia3D.Shapes.Cylinder, initPos, initRot)
-    name = String(Modia3D.fullName(obj)) * ".geometry"
+    name = Modia3D.fullName(obj)
+    geometryName = name * ".geometry"
     material = printVisuMaterialToJSON(obj, obj.visualMaterial)
     if cylinder.innerDiameter == 0.0
         r_obj = Modia3D.ZeroVector3D
         R_obj = Shapes.rotateAxis2y(cylinder.axis, Modia3D.NullRotation)
         shape = nothing
-        geometry = (; name=name, uuid=name2uuid(name), type="CylinderBufferGeometry", radiusBottom=cylinder.diameter/2, radiusTop=cylinder.diameter/2, height=cylinder.length, radialSegments=32, heightSegments=1)
-        objectInfo = getObjectInfo(obj, geometry, material, initPos, initRot, R_obj=R_obj)
+        geometry = (; name=geometryName, uuid=name2uuid(geometryName), type="CylinderBufferGeometry", radiusBottom=cylinder.diameter/2, radiusTop=cylinder.diameter/2, height=cylinder.length, radialSegments=32, heightSegments=1)
+        objectInfo = getObjectInfo(name, geometry, material, initPos, initRot, R_obj=R_obj)
     else
         if cylinder.axis == 1
             r_obj = @SVector[-cylinder.length/2, 0.0, 0.0]
@@ -63,8 +71,8 @@ function exportObject(object, elements, obj::Modia3D.Composition.Object3D, cylin
         shapeUuid = name2uuid(shapeName)
         shape = (; name=shapeName, uuid=shapeUuid, type="Shape", curves=curves, holes=holes, currentPoint=[0, 0])
         options = (; depth=cylinder.length, bevelEnabled=false)
-        geometry = (; name=name, uuid=name2uuid(name), type="ExtrudeGeometry", shapes=[shapeUuid], options=options)
-        objectInfo = getObjectInfo(obj, geometry, material, initPos, initRot, r_obj=r_obj, R_obj=R_obj)
+        geometry = (; name=geometryName, uuid=name2uuid(geometryName), type="ExtrudeGeometry", shapes=[shapeUuid], options=options)
+        objectInfo = getObjectInfo(name, geometry, material, initPos, initRot, r_obj=r_obj, R_obj=R_obj)
     end
     printInfoToFile(object, elements, geometry, material, shape, objectInfo)
     return (r_obj, R_obj)
@@ -79,18 +87,20 @@ function exportObject(object, elements, obj::Modia3D.Composition.Object3D, cone:
         r_obj = @SVector[0.0, 0.0, cone.length/2]
     end
     R_obj = Shapes.rotateAxis2y(cone.axis, Modia3D.NullRotation)
-    name = String(Modia3D.fullName(obj)) * ".geometry"
-    geometry = (; name=name, uuid=name2uuid(name), type="CylinderBufferGeometry", radiusBottom=cone.diameter/2, radiusTop=cone.topDiameter/2, height=cone.length, radialSegments=32, heightSegments=1)
+    name = Modia3D.fullName(obj)
+    geometryName = name * ".geometry"
+    geometry = (; name=geometryName, uuid=name2uuid(geometryName), type="CylinderBufferGeometry", radiusBottom=cone.diameter/2, radiusTop=cone.topDiameter/2, height=cone.length, radialSegments=32, heightSegments=1)
     material = printVisuMaterialToJSON(obj, obj.visualMaterial)
-    objectInfo = getObjectInfo(obj, geometry, material, initPos, initRot, r_obj=r_obj, R_obj=R_obj)
+    objectInfo = getObjectInfo(name, geometry, material, initPos, initRot, r_obj=r_obj, R_obj=R_obj)
     printInfoToFile(object, elements, geometry, material, nothing, objectInfo)
     return (r_obj, R_obj)
 end
 
 function exportObject(object, elements, obj::Modia3D.Composition.Object3D, capsule::Modia3D.Shapes.Capsule, initPos, initRot)
     r_obj = Modia3D.ZeroVector3D
     R_obj = Shapes.rotateAxis2y(capsule.axis, Modia3D.NullRotation)
-    name = String(Modia3D.fullName(obj)) * ".geometry"
+    name = Modia3D.fullName(obj)
+    geometryName = name * ".geometry"
     points = []
     for i in -9:0
         angle = i/9 * pi/2
@@ -102,9 +112,9 @@ function exportObject(object, elements, obj::Modia3D.Composition.Object3D, capsu
         point = (; x=capsule.diameter/2*cos(angle), y=capsule.length/2+capsule.diameter/2*sin(angle))
         push!(points, point)
     end
-    geometry = (; name=name, uuid=name2uuid(name), type="LatheGeometry", points=points, phiStart=0, phiLength=2*pi, segments=32)
+    geometry = (; name=geometryName, uuid=name2uuid(geometryName), type="LatheGeometry", points=points, phiStart=0, phiLength=2*pi, segments=32)
     material = printVisuMaterialToJSON(obj, obj.visualMaterial)
-    objectInfo = getObjectInfo(obj, geometry, material, initPos, initRot, R_obj=R_obj)
+    objectInfo = getObjectInfo(name, geometry, material, initPos, initRot, R_obj=R_obj)
     printInfoToFile(object, elements, geometry, material, nothing, objectInfo)
     return (r_obj, R_obj)
 end
@@ -118,27 +128,80 @@ function exportObject(object, elements, obj::Modia3D.Composition.Object3D, beam:
         r_obj = @SVector[0.0, -beam.thickness/2, 0.0]
     end
     R_obj = Shapes.rotateAxis2x(beam.axis, Modia3D.NullRotation)
-    name = String(Modia3D.fullName(obj)) * ".geometry"
+    name = Modia3D.fullName(obj)
+    geometryName = name * ".geometry"
     curves = [
         (; type="LineCurve", v1=[-beam.length/2, -beam.width/2], v2=[beam.length/2, -beam.width/2]),
         (; type="EllipseCurve", aX=beam.length/2, aY=0, xRadius=beam.width/2, yRadius=beam.width/2, aStartAngle=-pi/2, aEndAngle=pi/2, aClockwise=false, aRotation=0),
         (; type="LineCurve", v1=[beam.length/2, beam.width/2], v2=[-beam.length/2, beam.width/2]),
         (; type="EllipseCurve", aX=-beam.length/2, aY=0, xRadius=beam.width/2, yRadius=beam.width/2, aStartAngle=pi/2, aEndAngle=-pi/2, aClockwise=false, aRotation=0)
     ]
-    shapeName = String(Modia3D.fullName(obj)) * ".shape"
+    shapeName = name * ".shape"
     shapeUuid = name2uuid(shapeName)
     shape = (; name=shapeName, uuid=shapeUuid, type="Shape", curves=curves, holes=[], currentPoint=[0, 0])
     options = (; depth=beam.thickness, bevelEnabled=false)
-    geometry = (; name=name, uuid=name2uuid(name), type="ExtrudeGeometry", shapes=[shapeUuid], options=options)
+    geometry = (; name=geometryName, uuid=name2uuid(geometryName), type="ExtrudeGeometry", shapes=[shapeUuid], options=options)
     material = printVisuMaterialToJSON(obj, obj.visualMaterial)
-    objectInfo = getObjectInfo(obj, geometry, material, initPos, initRot, r_obj=r_obj, R_obj=R_obj)
+    objectInfo = getObjectInfo(name, geometry, material, initPos, initRot, r_obj=r_obj, R_obj=R_obj)
     printInfoToFile(object, elements, geometry, material, shape, objectInfo)
     return (r_obj, R_obj)
 end
 
+function exportObject(object, elements, obj::Modia3D.Composition.Object3D, coordinateSystem::Modia3D.Shapes.CoordinateSystem, initPos, initRot)
+    r_obj = Modia3D.ZeroVector3D
+    R_obj = Modia3D.NullRotation
+    name = Modia3D.fullName(obj)
+    group = (; name=name, uuid=name2uuid(name), type="Group", children=[], position=initPos, rotation=Modia3D.rot123fromR(initRot), scale=ones(3))
+
+    geometryName = name * ".axis.geometry"
+    geometryUuid = name2uuid(geometryName)
+    geometry = (; name=geometryName, uuid=geometryUuid, type="CylinderBufferGeometry", radiusBottom=coordinateSystem.length/50, radiusTop=coordinateSystem.length/50, height=coordinateSystem.length, radialSegments=8, heightSegments=1)
+    push!(elements.geometries, geometry)
+
+    r_geo = @SVector[coordinateSystem.length/2, 0.0, 0.0]
+    R_geo = Shapes.rotateAxis2y(1, Modia3D.NullRotation)
+    child = (; type="Mesh", geometry=geometryUuid, material=coSysMaterialRed.uuid, position=r_geo, rotation=Modia3D.rot123fromR(R_geo), scale=ones(3))
+    push!(group.children, child)
+
+    r_geo = @SVector[0.0, coordinateSystem.length/2, 0.0]
+    R_geo = Shapes.rotateAxis2y(2, Modia3D.NullRotation)
+    child = (; type="Mesh", geometry=geometryUuid, material=coSysMaterialGreen.uuid, position=r_geo, rotation=Modia3D.rot123fromR(R_geo), scale=ones(3))
+    push!(group.children, child)
+
+    r_geo = @SVector[0.0, 0.0, coordinateSystem.length/2]
+    R_geo = Shapes.rotateAxis2y(3, Modia3D.NullRotation)
+    child = (; type="Mesh", geometry=geometryUuid, material=coSysMaterialBlue.uuid, position=r_geo, rotation=Modia3D.rot123fromR(R_geo), scale=ones(3))
+    push!(group.children, child)
+
+    geometryName = name * ".tip.geometry"
+    geometryUuid = name2uuid(geometryName)
+    geometry = (; name=geometryName, uuid=geometryUuid, type="CylinderBufferGeometry", radiusBottom=coordinateSystem.length/25, radiusTop=0.0, height=coordinateSystem.length/10, radialSegments=8, heightSegments=1)
+    push!(elements.geometries, geometry)
+
+    r_geo = @SVector[1.05*coordinateSystem.length, 0.0, 0.0]
+    R_geo = Shapes.rotateAxis2y(1, Modia3D.NullRotation)
+    child = (; type="Mesh", geometry=geometryUuid, material=coSysMaterialRed.uuid, position=r_geo, rotation=Modia3D.rot123fromR(R_geo), scale=ones(3))
+    push!(group.children, child)
+
+    r_geo = @SVector[0.0, 1.05*coordinateSystem.length, 0.0]
+    R_geo = Shapes.rotateAxis2y(2, Modia3D.NullRotation)
+    child = (; type="Mesh", geometry=geometryUuid, material=coSysMaterialGreen.uuid, position=r_geo, rotation=Modia3D.rot123fromR(R_geo), scale=ones(3))
+    push!(group.children, child)
+
+    r_geo = @SVector[0.0, 0.0, 1.05*coordinateSystem.length]
+    R_geo = Shapes.rotateAxis2y(3, Modia3D.NullRotation)
+    child = (; type="Mesh", geometry=geometryUuid, material=coSysMaterialBlue.uuid, position=r_geo, rotation=Modia3D.rot123fromR(R_geo), scale=ones(3))
+    push!(group.children, child)
+
+    push!(object.children, group)
+    return (r_obj, R_obj)
+end
+
 function printInfoToFile(object, elements, geometry, material, shape, objectInfo)
     push!(elements.geometries, geometry)
-    push!(elements.materials, material)
+    if !isnothing(material)
+        push!(elements.materials, material)
+    end
     if !isnothing(shape)
         push!(elements.shapes, shape)
     end
@@ -186,8 +249,7 @@ function getObjectInfoMesh(obj, initPos, initRot, scale, R_obj, meshInfo)
     return meshInfo
 end
 
-function getObjectInfo(obj, geometry, material, initPos, initRot; r_obj=Modia3D.ZeroVector3D, R_obj=Modia3D.NullRotation, scale=ones(3))
-    name = String(Modia3D.fullName(obj))
+function getObjectInfo(name, geometry, material, initPos, initRot; r_obj=Modia3D.ZeroVector3D, R_obj=Modia3D.NullRotation, scale=ones(3))
     return (; name=name, uuid=name2uuid(name), type=:Mesh, geometry=get(geometry, :uuid, nothing), material=get(material, :uuid, ""), position=initPos+initRot'*r_obj, rotation=Modia3D.rot123fromR(R_obj*initRot), scale=scale)
 end
 
@@ -236,6 +298,10 @@ function printObjectToJSON(object, elements, obj; initPos=obj.r_abs, initRot=obj
         beam::Modia3D.Shapes.Beam = obj.shape
         (r_obj, R_obj) = exportObject(object, elements, obj, beam, initPos, initRot)
 
+    elseif shapeKind == Modia3D.CoordinateSystemKind
+        coordinateSystem::Modia3D.Shapes.CoordinateSystem = obj.shape
+        (r_obj, R_obj) = exportObject(object, elements, obj, coordinateSystem, initPos, initRot)
+
     elseif shapeKind == Modia3D.FileMeshKind
         fileMesh::Modia3D.Shapes.FileMesh = obj.shape
         (r_obj, R_obj) = exportObject(object, elements, obj, fileMesh, initPos, initRot)
@@ -334,6 +400,10 @@ function exportAnimation(scene)
         (r_Camera, R_Camera) = Modia3D.cameraPosition(options.cameraDistance, options.cameraLongitude, options.cameraLatitude, cameraUpDir, sceneUpDir)
         addCameras!(object, uuid, r_Camera, R_Camera)
 
+        push!(elements.materials, coSysMaterialRed)
+        push!(elements.materials, coSysMaterialGreen)
+        push!(elements.materials, coSysMaterialBlue)
+
         if !isnothing(animation) && length(animation) != 0
             iobj = 0
             tracks = []

src/Composition/object3D.jl

@@ -115,7 +115,7 @@ mutable struct Object3D <: Modia3D.AbstractObject3D
     hasChildJoint::Bool        # = true if its child has a joint
     computeAcceleration::Bool  # = true if acceleration needs to be computed
 
-    # internal shortcuts to avoid costly dynamic multiple dispatch
+    # internal shortcuts to avoid costly runtime dispatch
     shapeKind::Shapes.ShapeKind             # marks the defined shape
     shape::Modia3D.AbstractShape            # stores shape defined in Solid or Visual
     visualMaterial::Shapes.VisualMaterial   # stores visualMaterial defined in Solid or Visual

src/Shapes/shape.jl

@@ -6,9 +6,6 @@ The reference frame = Object3D frame coincides with the coordinate system.
 
 # Arguments
 - `length` defines the length of the coordinate system axes.
-
-# Notes
-- CoordinateSystem is [not supported by animation export](https://github.com/ModiaSim/PrivateModia3D.jl/issues/77).
 """
 mutable struct CoordinateSystem <: Modia3D.AbstractShape
     length::Float64