Modia3D Documentation

Modia3D is a Julia package that adds a multibody program and 3D shapes for visualization and collision handling to the Modia Modeling Language. 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.

Modia3D supports currently tree-structured multibody systems, but does not (yet) support kinematic loops.

Example videos:

• YouBot robots with gripping
• Billiard table with 16 balls
• Mobile with depthmax=8

Installation

Modia3D requires Julia 1.7 or later and is installed with

julia> ]add Modia3D

It is advised to also install Modia and at least one Modia plot package (for details see Installation of Modia).

Note, Modia3D reexports the following definitions

• using Modia
• using Unitful
• using DifferentialEquations
• and exports functions CVODE_BDF and IDA of Sundials.jl.

As a result, it is usually sufficient to have using Modia3D in a model to utilize the relevant functionalities of these packages.

Modia3D has various 3D animation features:

• With world = Object3D(feature=Scene(animationFile="filename.json")) the animation produced during a simulation run is exported in three.js JSON Object Scene format. The generated file can be imported into the open source web app three.js 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 format) and use any glb viewer (for example 3D-Viewer of Windows).

• With the default option world = Object3D(feature=Scene(enableVisualization=true)) the DLR Visualization Library (see the many examples from various research and industrial projects) is used, if installed, for online animation (during simulation), replays (after simulation), and the generation of mpg4-videos. This library is available as (free) Community Edition and as (commercial) Professional Edition (Web page to request download of DLR Visualization Library). After download, make the library available in the following way:
  • Set Julia environment variable ENV["DLR_VISUALIZATION"] = "<path-to-library>/Visualization/Extras/SimVis" or add it to the Julia startup.jl file. 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

Faster Startup

In order to speed up startup a sysimage can be generated by executing the following commands:

julia
using Modia3D
include("$(Modia3D.path)/create_Modia3D_sysimage.jl")
exit()

This will include a file Modia3D_sysimage.dll (on Windows) or Modia3D_sysimage.so (otherwise) in your current working directory that includes all packages of your current project and the following packages (these packages are added to your current project, if not yet included):

• Modia, Modia3D, SignalTablesInterface_PyPlot, PackageCompiler, Revise

Start julia with this sysimage in the following way:

julia -JModia3D_sysimage.dll (on Windows)
julia -JModia3D_sysimage.so  (otherwise)

Publications

Release Notes

Version 0.12.1

• Adapted to Modia 0.12.0 (arguments of buildFunction in ModiaInterface had been changed, as well as function names to define/access variables of built-in components)
• Absolute position (r_abs) and orientation (R_abs) of visible shapes are stored in the result data structure and can be plotted (see Modia3D/test/Basid/Pendulum.jl, Modia3D/test/Segmented/TwoStageRocket3D.jl)
• Manifest.toml file removed

Version 0.12.0

• Support for variable-structure systems where variables (states) can appear and disappear during simulation
  • A simulation run is partitioned into phases that are called segments or modes (multi-mode modeling)
  • The transition between modes is triggered by a full restart
  • The number of modes is usually not known in advance
  • Modia3D is a built-in component for Modia
  • Using segmented simulation for Modia3D models defined in an action program, the following actions trigger a full restart for next mode (segment)
    • ActionAttach, ActionReleaseAndAttach, ActionRelease, ActionDelete
  • Enable modeling and simulation of 3D mechanical systems with dynamically changing degrees of freedom during simulation, see corresponding paper: DOI: 10.3390/electronics12030500
    • All applications and models mentioned in this paper, can be found in Modia3D release v0.12.0 or Modia release v0.10.0
• Add Force Elements WorldForce and WorldTorque for force/torque vector application by functions of time.
• Enable Force Element results by interface extension (element path and simulation model).
• Improve efficiency of FileMesh contact (faster support point calculation).
• Fix Animation Export:
  • Update three.js geometry type names, e.g. "SphereBufferGeometry" -> "SphereGeometry".
  • Enable/fix FileMesh options useMaterialColor and doubleSided.
  • Disable double side rendering for standard objects.

Non-backwards compatible changes

• Requires Modia 0.10.0. Some internal interfaces have been changed (should not have an influence on user models).

Version 0.11.2

• Modia3D code generation improved for rheonomic joints.
• Require Modia 0.9.3

Version 0.11.1

• Bug fix: integrator IDA() can be used (especially to avoid solving large linear equation systems in the model).
  Extend some test models to use IDA().

Version 0.11.0

• Requires Modia 0.9.1 or later.

• Additional keyword arguments of Object3D: Object3D(..., fixedInParent=true, velocity=[0.0, 0.0, 0.0], angularVelocity=[0.0, 0.0, 0.0]), besides the existing parent, translation, rotation, feature. A freely moving Object3D is defined with Object3D(..., fixedInParent=false, ...), where velocity=.., angularVelocity=.. are the initial conditions (resolved in the parent frame). For more details, see Object3D.
  The states and other code for such Object3Ds are not part of the generated code (so compilation is faster, and the objects can be changed after code generation).

• The FreeMotion joints in all test models have been removed and replaced by Object3Ds with fixedInParent=false. A new test model test/Basic/FreeShaftAdaptiveRotSequenceWithFreeMotion.jl has been introduced with a FreeMotion joint, to still have one test for a FreeMotion joint.

• Revolute(..) and Prismatic(..) joints can define axis of rotation/translation optionally as vector, e.g., axis = [1.0, 2.0, 3.0].

• New function Modia3D.rot1(angle,v) which is an efficient implementation of Modia3D.rot1(angle)*v where rot1(angle) returns a transformation matrix and v is a vector and rot1(angle,v) returns the product of the transformation matrix and a vector in an efficient way. Correspondingly, there are new functions Modia3D.rot2(angle,v), Modia3D.rot3(angle,v), Modia3D.resolve1(rotation,v2), Modia3D.resolve2(rotation,v1).

• Simulation speed improved, if contact of FileMesh objects.

• contactPairMaterials.json updated with more material pairs (e.g. results in less warning messages for runtests).

• New file Modia3D.create_Modia3D_sysimage.jl to create a sysimage. Using this sysimage has the advantage that using Modia3D is nearly immediatedly executed (instead of > 30 seconds). For details, see README.md file.

• Internal: Timer included in Scene (scene.timer), so that a timer is more easily accessible for debugging.

• Internal: Cleanup and improvements of Modia3D/src/Frames.jl

Deprecated

• Joint FreeMotion is deprecated. Use instead Object3D(..., fixedInParent=false, ...). Note, Object3D has variables translation, rotation, velocity, angularVelocity, rotationXYZ instead of r, rot, v, w, isrot123 of FreeMotion. Furthermore, angularVelocity is resolved in the parent Object3D whereas w in FreeMotion(obj1=.., obj2=..., ..) is resolved in obj2 and not in obj1. This means in particular that the init/start value FreeMotion(.., w=Var(start=w_start)...) needs to be transformed in Object3D with Object3D(..., fixedInParent=false, rotation=XXX, angularVelocity = Modia3D.resolve1(XXX,w_start)) and the results of angularVelocity will be different to w because resolved in different coordinate systems.

Non-backwards compatible changes

• Since Modia3D 0.11.0 is based on Modia 0.9.0, the non-backwards compatible changes of Modia have also an effect on Modia3D (for details, see the release notes of Modia 0.9.0). Typically, this should give problems only in seldomly occuring corner cases.

Version 0.10.4

• Script Modia3D/create_Modia3D_sysimage.jl improved.

Version 0.10.3

• New script Modia3D/create_Modia3D_sysimage.jl to create a sysimage for a much faster startup (usage see Installation notes above or README.md file).

• New keyword Scene(provideAnimationHistory=true) in order to store animation data compactly during a simulation run. After simulate!(instantiatedModel, ...), the animation data of a Model3D(..) can be retrieved as dictionary via the new function get_animationHistory(instantiatedModel, modelPathAsString)

• Improvements of the MPR algorithm (which determines the distances between Object3Ds).

Version 0.10.2

• Model3D(..) with no degrees of freedom is now supported (previously, an error was triggered).

• Massless solid is now supported (previously, an error was triggered if Solid(..) had zero mass).

• SolidMaterial, MassProperties, VisualMaterial in Solid(..) and VisualMaterial in Visual(..) improved to handle corner cases:
  • SolidMaterial=="" is treated as SolidMaterial = nothing
  • VisualMaterial=="" is treated as Shapes.VisualMaterial(), that is the default VisualMaterial.
  • massProperties==nothing && solidMaterial==nothing is treated as MassProperties(), that is as massless solid.

• Error message improved, if closed kinematic loop is detected. Especially, the names of all Object3Ds in the kinematic loop are printed.

• Error message improved, if no Scene is defined.

• solid(..., contactSphereRadius::Union{Nothing,FloatType}=xxx) improved:
  • changed to contactSphereRadius::Union{Nothing,Number} (e.g. Int is also allowed).
  • contactSphereRadius <= 0 is the same as contactSphereRadius = nothing.

• Removed keyword "path" from the docu of Prismatic, Revolute, FreeMotion, since not to be set by the user (path is set when calling Model3D(..) to store the absolute path name in the joint).

• New function loadPalettes!. Example: Modia3D.loadPalettes!(solidMaterialPalette = "file1.json", contactPairMaterialPalette = "file2.json", visualMaterialPalette = "file3.json", log=true) to use the palettes from the provided files instead of the default palettes from Modia3D/palettes/*.json.

Version 0.10.1

• Reduce memory allocations, especially in case of collisions and FreeMotion joints.
• Require Modia 0.8.2 (drastically reduces memory allocations for FreeMotion joints).

Version 0.10.0

Non-backwards compatible changes:

The Modia packages are slightly restructured to allow more efficient operations. Previously, Modia was planned to include all the functionality with all model libraries. This is now changed and Modia includes now equation-oriented modeling and basic model libraries. Further model libraries, such as Modia3D (and other model libraries in the future) must be explicitly imported and are no longer automatically imported by Modia. To simplify the structuring, ModiaLang is merged into Modia and some functionality for the code generation is moved from ModiaBase to Modia. Overall, the benefit is that loading and compilation times are reduced, if Modia3D is not needed. Furthermore, the generated code contains only references to Modia functionality and no longer to ModiaBase. The effect on Modia3D is:

• Modia3D is removed from Modia (so when a model is using Modia3D, the package must be explicitly imported and is no longer automatically imported from Modia).

• In user models, all references to ModiaBase and to ModiaLang should be replaced by Modia (otherwise, it is highly likely that the model does not longer compile and/or simulate).

Version 0.9.1

• Require ModiaLang 0.11.3 (avoids unnecessary double instantiation of Model3D models).
• Reduce memory allocation of force elements.
• Update docu for contact force law (docs/src/internal/ContactForceLaw.md).

Version 0.9.0

Non-backwards compatible changes:

• Operator buildModia3D(..) is removed. Instead, the new constructor Model3D(..) must be used at the top level of a Modia3D definition. It is now possible to define several, independent multibody systems (currently, only one of them can have animation and animation export).
• If init/start vectors are defined (e.g. initial state of a FreeMotion joint), they must be defined as SVector{3,Float64}(..). Otherwise, errors occur during compilation.

Other changes

• All test models changed, due to the non-backwards compatible change.
• Code generation changed significantly, in order that the interface to Modia3D functions is type stable. As a result, simulation is more efficient and much less memory is allocated during simulation.
• Efficiency improvements for collisions (less memory is allocated during simulation + faster simulation).

Version 0.8.2

• Fix Cone contact detection
• Add rattleback test (Modia3D/test/Collisions/Rattleback.jl)

Version 0.8.1

• collisionSmoothingRadius: edges are smoothed with collisionSmoothingRadius
  • its default value is 0.001, if it is set to 0.0 no smoothing takes place
  • the edges of Box, Cylinder, Cone, and Beam are smoothened with collisionSmoothingRadius
• For using Herz' pressure contactSphereRadius is introduced for each shape
  • it can be user set
  • otherwise, it is calculated from shape geometry

Version 0.8.0

• Require ModiaLang 0.10.0 (e.g. require DifferentialEquations 7)
• Support animation export for FloatType = Measurements.XXX (animation is performed for the nominal value).
• Remove PathPlanning struct und functions (and instead use the functionality from ModiaLang 0.9.1).
• Reactivate test model test/old/Test_PathPlanning.jl
• Remove unused files: .codecov.yml, .travis.yml, appveyor.yml
• Fix import/using of some tests.

Version 0.7.0

• Modia3D is updated and restricted to Julia 1.7
• cyclic dependencies with Modia package are removed

Version 0.6.0

• Modia3D supports @instantiatedModel(FloatType = Float64, ...) as default FloatType. Now, further FloatTypes, such as Float32, DoubleFloats.Double64, Measurements.Measurement{Float64}, MonteCarloMeasurements.StaticParticles{Float64} are supported. If FloatType is not Float64, the default integrator selected from DifferentialEquations.jl is utilized and no longer Sundials.CVODEBDF (because CVODEBDF is only supported for Float64). Since ModiaLang does not yet support integrators with analytic Jacobians, integrators with this feature cannot be used, e.g., this feature needs to be switched off with option autodiff=false, if necessary. Recommendation: use QBDF(autodiff=false) if FloatType is not Float64. Note, Tsit5 usually does not work well for collisions, due to the stiff behavior in the contact area. Current limitations:
  • FloatType = Float32: usually fails when collisions occur
  • FloatType = Measurements.xxx, or MonteCarloMeasurements.xxx fail if events occur (e.g. collision handling, switching between different sequences of rotation angles)
  • FloatType = Measurements.xxx: Animation is performed for the nominal values (plots show nominal values and the area of the variances)
  • FloatType = MonteCarloMeasurements.yyy: Animation is automatically switched off with a warning message (due to severe performance issues that will be fixed in the future)
• Object3D: use vectors instead of matrices for rotation
• Scene
  • maximumContactDamping = 2000.0: The maximum damping used in the elastice response calculation (previously, this was set to the literal value of 1000 and could not be changed). This value is, for example, used if the normal contact velocity at contact start is small.
• Shape FileMesh is reading mesh-files with MeshIO.jl and no longer with an own parser. As a result, more input formats are supported, in particular also STL and OBJ with non-triangles. Furthermore, duplicate vertices in FileMesh are removed after reading a file. This reduces the computational effort of collision support point calculation.
• Collision handling slightly improved, e.g., if colliding shapes get in contact with a small normal contact velocity at contact start, the colliding shapes are quickly fixed relative to each other (previously, a lot of events occured in this phase).
• Updated documentation and some bugs fixed
• Internal
  • Changed most structs to parameterized structs with type parameter F (short for FloatType)
  • Changed some remaining vectors and matrices to SVector and SMatrix, respectively, to improve efficiency
  • Cleanup of Modia3D and of Modia (e.g. removed duplicate definition of ModiaInterface in Modia.jl)
  • Event handling slightly changed, in particular the large contact hysteresis in the order of 1e-8 was reduced to 1e-13, after ModiaLang was using the new option RightRootFind of DifferentialEquations.jl. As a result, unnecessary events (signaled via restart = NoRestart) should no longer occur
  • Elastic response calculation simplified and improved. In particular, if the normal contact velocity at contact start is below vsmall (default = 0.01 m/s), coefficient of restitution is set to zero and no longer to 0.001. As a result, colliding shapes are quickly fixed relative to each other
  • Bug fixed: In some rare situations, it was not correctly checked that a multibody system has exactly one Object3D without parent and with feature=Scene (and no other Object3D has feature=Scene)

Version 0.5.2

• version number and date updated

Version 0.5.1

• Collision handling - MPR algorithm improved to enhance speed and robustness
  • collision pairing material
    • at initialization: a warning is given if a collision pairing material is not defined
  • improve support points computation of
    • FileMesh: use SVectors and better computation of support points
    • Capsule: a Capsule is already smooth therefore collisionSmoothingRadius is removed
  • MPR algorithm
    • Double64 from DoubleFloats.jl package is used for mpr algorithm to increase accuracy
    • amount of iteration steps is increased if more are needed for phase 2 and phase 3
    • if it's not possible to quit with the predefined mprTolerance the iteration quits with the best possible tolerance instead
    • collisions between ellipsoids and other shapes are treated like collisions between spheres and other shapes
  • store information like centroid in Object3D
  • remove some type instabilities
• FreeMotion joint
  • enable adaptive rotation sequence
  • add test model
• Enable ForceElements
  • add infrastructure
  • add Bushing and SpringDamperPtP
  • add test models and documentation
• Animation export (three.js JSON object scene)
  • fix initial orientation
  • enable visualization of bounding boxes (AABB)
  • enable Beam support
  • enable Capsule support
  • enable inner cylinder radius support (pipe)
  • enable CoordinateSystem support
  • enable Grid support
• Visualization with DLR Visualization Library
  • add visual shape kind ModelicaShape
  • remove some type instabilities
• improve testing
  • enable short and complete test runs
  • add planar motion test
• update documentation and installation guide
• clean up: remove unused code snippets

Version 0.5.0

• Largely redesigned.
• Integrated into Modia.
• Not backwards compatible to previous versions.

Main developers

Andrea Neumayr, Martin Otter and Gerhard Hippmann,
DLR - Institute of System Dynamics and Control

License: MIT (expat)