ArtiSynth Modeling Guide

Contents

• Preface
  • How to read this guide
• 1 ArtiSynth Overview
  • 1.1 System structure
    • 1.1.1 Model components
    • 1.1.2 The RootModel
    • 1.1.3 Component path names
    • 1.1.4 Model advancement
    • 1.1.5 MechModel
  • 1.2 Physics simulation
  • 1.3 Basic packages
    • 1.3.1 maspack
    • 1.3.2 artisynth.core
    • 1.3.3 artisynth.demos
  • 1.4 Properties
    • 1.4.1 Querying and setting property values
    • 1.4.2 Property handles and paths
    • 1.4.3 Composite and inheritable properties
  • 1.5 Creating an application model
    • 1.5.1 Implementing the build() method
    • 1.5.2 Making models visible to ArtiSynth
    • 1.5.3 Loading and running a model
• 2 Supporting classes
  • 2.1 Vectors and matrices
  • 2.2 Rotations and transformations
  • 2.3 Points and Vectors
  • 2.4 Spatial vectors and inertias
  • 2.5 Meshes
    • 2.5.1 Mesh creation
    • 2.5.2 Setting normals, colors, and textures
    • 2.5.3 Automatic creation of normals and hard edges
    • 2.5.4 Vertex and feature coloring
    • 2.5.5 Reading and writing mesh files
    • 2.5.6 Reading and writing normal and texture information
    • 2.5.7 Constructive solid geometry
  • 2.6 Reading source relative files
  • 2.7 Reading and caching remote files
• 3 Mechanical Models I
  • 3.1 Springs and particles
    • 3.1.1 Axial springs and materials
    • 3.1.2 Example: a simple particle-spring model
    • 3.1.3 Dynamic, parametric, and attached components
    • 3.1.4 Custom axial materials
    • 3.1.5 Damping parameters
  • 3.2 Rigid bodies
    • 3.2.1 Frame markers
    • 3.2.2 Example: a simple rigid body-spring model
    • 3.2.3 Creating rigid bodies
    • 3.2.4 Pose and velocity
    • 3.2.5 Inertia and the surface mesh
    • 3.2.6 Coordinate frames and the center of mass
    • 3.2.7 Damping parameters
    • 3.2.8 Rendering rigid bodies
    • 3.2.9 Multiple meshes
    • 3.2.10 Example: a composite rigid body
  • 3.3 Mesh components
    • 3.3.1 Fixed mesh bodies
    • 3.3.2 Example: adding mesh bodies to MechModel
  • 3.4 Joints and connectors
    • 3.4.1 Joints and coordinate frames
    • 3.4.2 Joint coordinates, constraints, and errors
    • 3.4.3 Creating joints
    • 3.4.4 Working with coordinates
    • 3.4.5 Coordinate limits and locking
    • 3.4.6 Example: a simple hinge joint
    • 3.4.7 Constraint forces
    • 3.4.8 Compliance and regularization
    • 3.4.9 Example: an overconstrained linkage
    • 3.4.10 Rendering joints
  • 3.5 Joint components
    • 3.5.1 Hinge joint
    • 3.5.2 Slider joint
    • 3.5.3 Cylindrical joint
    • 3.5.4 Slotted hinge joint
    • 3.5.5 Universal joint
    • 3.5.6 Skewed universal joint
    • 3.5.7 Gimbal joint
    • 3.5.8 Spherical joint
    • 3.5.9 Planar joint
    • 3.5.10 Planar translation joint
    • 3.5.11 Ellipsoid joint
      • 3.5.11.1 OpenSim compatibility
    • 3.5.12 Solid joint
    • 3.5.13 Planar Connector
    • 3.5.14 Segmented Planar Connector
    • 3.5.15 Legacy Joints
    • 3.5.16 Example: multijointed arm
  • 3.6 Frame springs
    • 3.6.1 Frame spring coordinate frames
    • 3.6.2 Frame materials
    • 3.6.3 Creating frame springs
    • 3.6.4 Example: two bodies connected by a frame spring
  • 3.7 Other point-based forces
    • 3.7.1 Forces between points and planes or meshes
    • 3.7.2 Example: point plane forces
    • 3.7.3 Example: point mesh forces
  • 3.8 Attachments
    • 3.8.1 Point attachments
    • 3.8.2 Example: model with particle attachments
    • 3.8.3 Frame attachments
    • 3.8.4 Example: model with frame attachments
• 4 Mechanical Models II
  • 4.1 Simulation control properties
    • 4.1.1 Simulation step size
    • 4.1.2 Integrator
    • 4.1.3 Position stabilization
  • 4.2 Units
    • 4.2.1 Scaling units
  • 4.3 Render properties
    • 4.3.1 Render property taxonomy
    • 4.3.2 Setting render properties
    • 4.3.3 Texture mapping
  • 4.4 Custom rendering
    • 4.4.1 Component render() methods
    • 4.4.2 Implementing custom rendering
    • 4.4.3 Example: rendering body forces
    • 4.4.4 The prerender() method
  • 4.5 Point-to-point muscles, tendons and ligaments
    • 4.5.1 Simple muscle materials
      • 4.5.1.1 SimpleAxialMuscle
      • 4.5.1.2 ConstantAxialMuscle
      • 4.5.1.3 LinearAxialMuscle
      • 4.5.1.4 PeckAxialMuscle
      • 4.5.1.5 BlemkerAxialMuscle
    • 4.5.2 Example: muscle attached to a rigid body
    • 4.5.3 Equilibrium muscles
    • 4.5.4 Equilibrium muscle materials
      • 4.5.4.1 Millard2012AxialMuscle
      • 4.5.4.2 Thelen2003AxialMuscle
    • 4.5.5 Tendons and ligaments
      • 4.5.5.1 Millard2012AxialTendon
      • 4.5.5.2 Thelen2003AxialTendon
      • 4.5.5.3 Blankevoort1991AxialLigament
    • 4.5.6 Example: muscles with separate tendons
  • 4.6 Distance Grids and Components
  • 4.7 Transforming geometry
    • 4.7.1 Nonlinear transformations
    • 4.7.2 Example: the FemModelDeformer class
    • 4.7.3 Implementation and behavior
    • 4.7.4 Use in model registration
  • 4.8 General component arrangements
    • 4.8.1 Container components
    • 4.8.2 Example: a net formed from balls and springs
    • 4.8.3 Adding containers to other models
  • 4.9 Custom Joints
    • 4.9.1 Joint constraints
    • 4.9.2 Unilateral constraint engagement
    • 4.9.3 Implementing a custom joint
    • 4.9.4 Implementing a custom coupling
    • 4.9.5 Example: a simple custom joint
• 5 Simulation Control
  • 5.1 Control Panels
    • 5.1.1 General principles
    • 5.1.2 Example: Creating a simple control panel
    • 5.1.3 Example: Controlling properties in multiple components
  • 5.2 Custom properties
    • 5.2.1 Adding properties to a component
    • 5.2.2 Example: a visibility property
  • 5.3 Controllers and monitors
    • 5.3.1 Implementation
      • 5.3.1.1 Target positions and velocities
    • 5.3.2 Example: A controller to move a point
  • 5.4 Probes
    • 5.4.1 Numeric probe structure
    • 5.4.2 Creating probes in code
    • 5.4.3 Example: probes connected to SimpleMuscle
    • 5.4.4 Data file format
    • 5.4.5 Adding input probe data in code
      • 5.4.5.1 Extending data to the start and end
    • 5.4.6 Tracing probes
    • 5.4.7 Position probes
    • 5.4.8 Velocity probes
    • 5.4.9 Example: controlling a point and frame
    • 5.4.10 Numeric monitor probes
    • 5.4.11 Numeric control probes
  • 5.5 Working with TRC data
    • 5.5.1 TRC reader
    • 5.5.2 TRC writer
    • 5.5.3 Example: moving MultiJointedArm with TRC data
  • 5.6 Application-Defined Menu Items
    • 5.6.1 Smoothing probe data
• 6 Finite Element Models
  • 6.1 Overview
    • 6.1.1 FemModel3d
    • 6.1.2 Component Structure
      • 6.1.2.1 Nodes
      • 6.1.2.2 Elements
      • 6.1.2.3 Shell elements
      • 6.1.2.4 Meshes
    • 6.1.3 Materials
    • 6.1.4 Boundary conditions
  • 6.2 FEM model creation
    • 6.2.1 Factory methods
    • 6.2.2 Loading external FEM meshes
    • 6.2.3 Generating from surfaces
    • 6.2.4 Building elements in code
    • 6.2.5 Example: a simple beam model
  • 6.3 FEM Geometry
    • 6.3.1 Surface meshes
    • 6.3.2 Embedding geometry within an FEM
    • 6.3.3 Example: a beam with an embedded sphere
  • 6.4 Connecting FEM models to other components
    • 6.4.1 Connecting nodes to rigid bodies or particles
    • 6.4.2 Example: connecting a beam to a block
    • 6.4.3 Connecting nodes directly to elements
    • 6.4.4 Example: connecting two FEMs together
    • 6.4.5 Finding which nodes to attach
    • 6.4.6 Selecting nodes in the viewer
    • 6.4.7 Example: two bodies connected by an FEM “spring”
    • 6.4.8 Nodal-based attachments
    • 6.4.9 Example: element vs. nodal-based attachments
  • 6.5 FEM markers
    • 6.5.1 Example: attaching an FEM beam to a muscle
  • 6.6 Frame attachments
    • 6.6.1 Example: attaching frames to an FEM beam
    • 6.6.2 Adding joints to FEM models
    • 6.6.3 Example: two FEM beams connected by a joint
  • 6.7 Incompressibility
    • 6.7.1 Volume regions and locking
    • 6.7.2 Hard incompressibility
    • 6.7.3 Soft incompressibility
    • 6.7.4 Incompressibility and linear materials
    • 6.7.5 Using incompressibility in practice
  • 6.8 Varying and augmenting material behaviors
    • 6.8.1 Example: FEM sheet with a stiff spine
  • 6.9 Muscle activated FEM models
    • 6.9.1 FemMuscleModel
      • 6.9.1.1 Bundles
      • 6.9.1.2 Exciters
    • 6.9.2 Fibre-based muscles
    • 6.9.3 Material-based muscles
    • 6.9.4 Example: toy FEM muscle model
    • 6.9.5 Example: comparison with two beam examples
  • 6.10 Material types
    • 6.10.1 Linear
      • 6.10.1.1 LinearMaterial
      • 6.10.1.2 TransverseLinearMaterial
      • 6.10.1.3 AnisotropicLinearMaterial
    • 6.10.2 Hyperelastic materials
      • 6.10.2.1 St Venant-Kirchoff material
      • 6.10.2.2 Neo-Hookean material
      • 6.10.2.3 Incompressible neo-Hookean material
      • 6.10.2.4 Mooney-Rivlin material
      • 6.10.2.5 Ogden material
      • 6.10.2.6 Fung orthotropic material
      • 6.10.2.7 Yeoh material
      • 6.10.2.8 Arruda-Boyce material
      • 6.10.2.9 Veronda-Westmann material
      • 6.10.2.10 Incompressible material
    • 6.10.3 Muscle materials
      • 6.10.3.1 Generic muscle
      • 6.10.3.2 Blemker muscle
      • 6.10.3.3 Full Blemker muscle
      • 6.10.3.4 Simple force muscle
  • 6.11 Stress, strain and strain energy
    • 6.11.1 Computing nodal values
    • 6.11.2 Scalar stress/strain measures
    • 6.11.3 Strain energy
  • 6.12 Rendering and Visualizations
    • 6.12.1 Nodes
    • 6.12.2 Elements
    • 6.12.3 Surface and other meshes
    • 6.12.4 FEM-based muscles
    • 6.12.5 Color bars
    • 6.12.6 Example: stress/strain plotting with color bars
    • 6.12.7 Cut planes
    • 6.12.8 Example: FEM model with a cut plane
• 7 Fields
  • 7.1 Grid fields
  • 7.2 FEM fields
    • 7.2.1 Nodal fields
    • 7.2.2 Element fields
    • 7.2.3 Sub-element fields
  • 7.3 Mesh fields
    • 7.3.1 Vertex fields
    • 7.3.2 Face fields
  • 7.4 Fields for VectorNd, MatrixNd and Vector3d
  • 7.5 Binding material properties
    • 7.5.1 Example: FEM with variable stiffness
    • 7.5.2 Example: specifying FEM muscle directions
  • 7.6 Visualizing fields
    • 7.6.1 Scalar fields
    • 7.6.2 Vector fields
    • 7.6.3 Grid fields
    • 7.6.4 Render meshes
    • 7.6.5 Example: Visualizing a scalar nodal field
    • 7.6.6 Examples: Visualizing other fields
• 8 Contact and Collision
  • 8.1 Enabling collisions
    • 8.1.1 Collisions between specific bodies
    • 8.1.2 Default collisions between groups
    • 8.1.3 Example: collision with a plane
    • 8.1.4 Collisions for FEM models
    • 8.1.5 Example: FEM models and rigid bodies
  • 8.2 Collision behaviors and collidability
    • 8.2.1 Collision behaviors
    • 8.2.2 Collidability
  • 8.3 Collision meshes and compound collidables
    • 8.3.1 Example: redefining a rigid body collision mesh
    • 8.3.2 Compound collidables and self-collision
    • 8.3.3 Example: FEM model with self-collision
    • 8.3.4 Collidable bodies
    • 8.3.5 Nested MechModels
  • 8.4 Implementation
    • 8.4.1 Contact methods
      • 8.4.1.1 Contour region
      • 8.4.1.2 Vertex penetration
      • 8.4.1.3 Setting the contact method
    • 8.4.2 Collider types
      • 8.4.2.1 Collision meshes and signed distance grids
  • 8.5 Contact rendering
    • 8.5.1 Example: rendering normals and contours
    • 8.5.2 Example: rendering a color map
    • 8.5.3 Example: rendering contact pressures
  • 8.6 Overconstrained contact
    • 8.6.1 Constraint reduction
  • 8.7 Contact regularization
    • 8.7.1 Compliant contact
    • 8.7.2 Contact force behaviors
      • 8.7.2.1 Computing forces based on pressure
    • 8.7.3 Elastic foundation contact
    • 8.7.4 Example: elastic foundation contact of a ball in a bowl
    • 8.7.5 Example: binding EFC properties to fields
  • 8.8 Monitoring collisions
    • 8.8.1 Collision responses
    • 8.8.2 Available information
    • 8.8.3 Example: monitoring contact forces
    • 8.8.4 Example: forces and pressures on mesh vertices
  • 8.9 Tips and limitations
    • 8.9.1 Contact jitter
    • 8.9.2 Passing through objects
    • 8.9.3 Stray vertices
    • 8.9.4 Coulomb friction and stability
• 9 Muscle Wrapping and Via Points
  • 9.1 Via Points
    • 9.1.1 Example: a muscle with via points
  • 9.2 Obstacle Wrapping
    • 9.2.1 Example: wrapping around a cylinder
  • 9.3 General Surfaces and Distance Grids
    • 9.3.1 Example: wrapping around a bone
  • 9.4 Initializing the Wrap Path
    • 9.4.1 Example: wrapping around a torus
  • 9.5 Alternate Wrapping Surfaces
    • 9.5.1 Example: wrapping for a finger joint
    • 9.5.2 Example: toy muscle arm with wrapping
  • 9.6 Tuning the Wrapping Behavior
• 10 Inverse Simulation
  • 10.1 Overview
    • 10.1.1 Tracking controller operation
    • 10.1.2 Motion tracking
      • 10.1.2.1 Chase control
      • 10.1.2.2 PD control
    • 10.1.3 Generating excitations using a quadratic program
    • 10.1.4 Force tracking
    • 10.1.5 Incremental computation
    • 10.1.6 Setting up the tracking controller
    • 10.1.7 Example: moving a point with multiple Muscles
  • 10.2 Tracking controller components
    • 10.2.1 Exciters
      • 10.2.1.1 Excitation coloring
    • 10.2.2 Motion targets
      • 10.2.2.1 Motion target term
      • 10.2.2.2 Motion target rendering
    • 10.2.3 Regularization
      • 10.2.3.1 L2 Regularization
      • 10.2.3.2 Excitation damping
    • 10.2.4 Example: controlling ToyMuscleArm
    • 10.2.5 Example: controlling an FEM muscle model
    • 10.2.6 Force effector targets
      • 10.2.6.1 Force effector term
    • 10.2.7 Example: controlling tension in a spring
    • 10.2.8 Target components
    • 10.2.9 Point and frame exciters
    • 10.2.10 Example: controlling ToyMuscleArm with FrameExciters
  • 10.3 Tracking controller structure and settings
    • 10.3.1 Controller structure
    • 10.3.2 Controller properties
    • 10.3.3 Motion term properties
    • 10.3.4 Properties for other cost terms
  • 10.4 Managing probes and control panels
    • 10.4.1 Inverse simulation probes
    • 10.4.2 Example: using InverseManager probes
    • 10.4.3 Inverse control panel
  • 10.5 Inverse kinematics
    • 10.5.1 Inverse kinematics solver
    • 10.5.2 Creating probes with IKSolver
    • 10.5.3 Using IKSolver in a simulation context
    • 10.5.4 Example: moving MultiJointedArm with an IKProbe
    • 10.5.5 Example: controlling ToyMuscleArm with inverse kinematics
  • 10.6 Caveats and limitations
• 11 Skinning
  • 11.1 Implementation
  • 11.2 Creating a skin mesh
    • 11.2.1 Example: skinning over rigid bodies
  • 11.3 Computing weights
    • 11.3.1 Setting weights explicitly
  • 11.4 Markers and point attachments
    • 11.4.1 Markers
    • 11.4.2 Point attachments
    • 11.4.3 Example: skinning rigid bodies and FEM models
    • 11.4.4 Mesh-based markers and attachments
  • 11.5 Resolution and Limitations
  • 11.6 Collisions
    • 11.6.1 Example: collision with a cylinder
  • 11.7 Application to muscle wrapping
    • 11.7.1 Example: wrapping for a finger joint
• 12 DICOM Images
  • 12.1 The DICOM file format
  • 12.2 The DICOM classes
    • 12.2.1 DicomElement
    • 12.2.2 DicomHeader
    • 12.2.3 DicomPixelBuffer
    • 12.2.4 DicomSlice
    • 12.2.5 DicomImage
  • 12.3 Loading a DicomImage
    • 12.3.1 Time-dependent images
    • 12.3.2 Image formats
  • 12.4 The DicomViewer
  • 12.5 DICOM example
• A Mathematical Review
  • A.1 Rotation transforms
  • A.2 Rigid transforms
  • A.3 Affine transforms
  • A.4 Rotational velocity
  • A.5 Spatial velocities and forces
  • A.6 Spatial inertia