moro
moro is a Python library for symbolic modeling, analysis, and
visualization of serial robot manipulators.
It is designed primarily for robotics education and for workflows that benefit from symbolic kinematics and dynamics.
Getting Started
User Guide
- Robot Modeling
- Transformations
- Elementary rotations
- General rotation helper
- Euler angles
- Axis-angle representation
- Skew-symmetric matrices
- Homogeneous translations and rotations
- Building homogeneous transformations
- Extracting rotation and translation
- Inverting homogeneous transformations
- Denavit-Hartenberg transformations
- A worked example
- Notes and conventions
- See also
- Forward Kinematics
- Jacobians
- Inverse Kinematics
- Solving a position target
- Providing numerical model parameters
- Choosing a solver
- Initial guess and joint limits
- Convergence and stagnation
- Inspecting an IK solution
- Solving a position trajectory
- Inspecting a trajectory solution
- Handling unsuccessful solutions
- Validating a solution with forward kinematics
- A worked example
- Notes and limitations
- See also
- Dynamics
- Defining the dynamic model
- Link masses
- Center-of-mass positions
- Inertia tensors
- Gravity
- Inspecting the model state
- Center-of-mass kinematics
- Kinetic and potential energy
- The inertia matrix
- Coriolis and gravity terms
- Equations of motion
- Evaluating symbolic dynamics
- A worked example
- Notes and limitations
- See also
- Visualization
- Creating a visualizer
- Plotting a robot configuration
- Providing numerical values
- Choosing a backend
- Matplotlib visualization
- Interactive Three.js visualization
- Customizing the visualization
- Animating robot configurations
- Matplotlib animations
- Three.js animations
- Showing the end-effector trajectory
- Animating an inverse-kinematics trajectory
- A worked example
- Notes and limitations
- See also
Examples
- Planar 2R Manipulator
- Anthropomorphic RRR Manipulator
- Position Inverse Kinematics
- Problem
- Robot model
- Defining a reachable target
- Solving the inverse kinematics problem
- Inspecting the solution
- Validating with forward kinematics
- Multiple inverse-kinematics solutions
- Comparing IK methods
- Joint limits
- Random initialization
- Visualizing the solution
- Comparing the reference and recovered configurations
- Handling unsuccessful solutions
- Discussion
- See also
- Cartesian Trajectory with Inverse Kinematics
- Problem
- Robot model
- Defining the Cartesian path
- Choosing the initial configuration
- Solving the IK trajectory
- Inspecting the trajectory solution
- Inspecting the joint trajectory
- Validating the trajectory
- Preparing the animation
- Visualizing the robot motion
- Showing the end-effector path
- Tracing the path progressively
- Handling an unsuccessful trajectory
- Changing the numerical method
- Discussion
- See also
- Dynamic Model of a Planar 2R Manipulator
- Problem
- Robot model
- Dynamic parameters
- Inspecting the dynamic model
- Center-of-mass kinematics
- Kinetic energy
- Potential energy
- Inertia matrix
- Coriolis and centrifugal terms
- Gravity vector
- Equations of motion
- Matrix form
- Computing the torque expression
- Numerical evaluation
- Evaluating individual contributions
- Reusing the symbolic model
- Discussion
- See also
API Reference
Theory
- Mathematical notation and conventions
- Rotations
- Rotation matrices
- Properties of rotation matrices
- Geometric interpretation
- Elementary rotations
- Composition of reference-frame orientations
- Active rotations and coordinate transformations
- Successive rotations about fixed axes
- Successive rotations about moving axes
- Intrinsic and extrinsic rotation sequences
- Euler angles
- Proper Euler angles
- Tait–Bryan angles
- Canonical Euler-angle ranges
- Euler-angle singularities
- Axis–angle representation
- Skew-symmetric matrix
- Rodrigues’ rotation formula
- Canonical axis–angle representation
- Summary of conventions used by Moro
- Homogeneous transformations
- Pose between reference frames
- Cartesian and homogeneous coordinates
- Transforming a point
- Relative position vectors
- Free vectors and homogeneous coordinates
- Rigid transformations and SE(3)
- Composition of homogeneous transformations
- Inverse of a homogeneous transformation
- Pure translations
- Pure rotations
- Fixed and moving transformations
- Noncommutativity
- Notation for generic transformations
- Summary of conventions
- Denavit–Hartenberg convention
- Classic Denavit–Hartenberg formulation
- Assignment of reference frames
- Geometric meaning of the DH parameters
- Revolute and prismatic joints
- The base frame
- The terminal frame
- DH parameter tables
- Forward composition
- Sign conventions
- Units
- Special geometric cases
- Non-uniqueness of DH assignments
- Example: planar 2R manipulator
- Summary of conventions used by Moro
- Forward kinematics
- Differential kinematics
- Geometric Jacobian
- Geometric and analytical Jacobians
- Jacobian of an arbitrary point
- Column-by-column construction
- Joints that do not affect the point
- End-effector Jacobian
- Linear Jacobian from forward kinematics
- Angular velocity and rotation matrices
- Differential motion
- Jacobian rank
- Physical meaning of singularities
- Task-dependent singularities
- Null space
- Example: planar 2R manipulator
- Differential kinematics in Moro
- Related kinematic quantities in Moro
- Summary of conventions
- Inverse kinematics
- Position inverse kinematics in Moro
- Position error
- Multiple inverse-kinematics solutions
- Numerical inverse kinematics
- Initial configuration
- Joint limits
- Newton method
- Levenberg–Marquardt
- Cyclic Coordinate Descent
- CCD for revolute joints
- CCD for prismatic joints
- Convergence and termination
- Maximum iterations
- Stagnation by joint step
- Stagnation by lack of error improvement
- Numerical failures
- Position IK result
- Solving a sequence of position targets
- Trajectory IK result
- Inverse kinematics in Moro
- Example: planar 2R manipulator
- Example: sequence of targets
- Scope and limitations
- Summary of conventions
- Dynamics
- Scope of dynamics in Moro
- Physical parameters of a link
- Link mass
- Center of mass
- Inertia tensor
- Gravity vector
- Kinetic energy of a link
- Kinetic energy and Jacobians
- Potential energy
- Lagrangian
- Euler–Lagrange equations
- Time-dependent joint variables
- Matrix form of the dynamic model
- Inertia matrix
- Christoffel symbols
- Coriolis matrix
- Gravity generalized-force vector
- Complete matrix formulation
- Energy and matrix formulations
- Dynamic parameter assumptions
- Model state
- Dynamic quantities in Moro
- Example workflow
- Scope and limitations
- Summary of conventions
Development
- Contributing
- Development setup
- Python environment
- Installing development tools
- Repository structure
- Running the tests
- Writing tests
- Building the documentation
- Documentation structure
- Documentation style
- Naming conventions
- Public API
- Docstrings
- Symbolic computations
- Numerical algorithms
- Visualization
- Adding dependencies
- Changelog
- Submitting changes
- Pull requests
- Reporting issues
- Scope of contributions
- Moro Naming Conventions
- 1. General principles
- 2. Default frame convention
- 3. Transformations and rotations between frames
- 4. Quantities that have meaningful representations in different frames
- 5. Avoid redundant symbolic indices
- 6. Scalar accessors and collections
- 7. Time derivatives
- 8. Center-of-mass notation
- 9. Linear and angular Jacobians
- 10. Public names should describe semantic distinctions
- 11. Prefer readability over excessive compactness
- 12. Current API examples
- 13. Backward compatibility
- 14. Checklist for new API names
- Summary