Concepts Mates and MateConnectors

This concepts page explains how to connect moving parts:

defining mate connectors
creating mates between bodies
structuring constraints for clean model design
validating connector and mate organization

Start with MateConnectors

A Physics3D.Interactions.MateConnector defines a local attachment frame on a body or system. When owned by a body, the mate connector will be local with the body, and move with it. When owned by a system, the mate connector will be fixed relative the world frame, but in the initial local position of the owning system.

The key attributes of a MateConnector are:

position: local position of the connector in the owning model
main_axis: primary direction for the mate (for example hinge axis)
normal: secondary direction used to orient the connector frame

normal should be orthogonal to main_axis. If not specified, a orthogonal vector is computed by: Math.Vec3.get_orthogonal_unit_vector(), which is useful when this direction does not matter.

WheelBody is Physics3D.Bodies.RigidBody:
    geometry is Physics3D.Geometries.Cylinder:
        radius: 0.3
        height: 0.12
    visual is Visuals.Geometries.Cylinder:
        radius: geometry.radius
        height: geometry.height
    hub_connector is Physics3D.Interactions.MateConnector:
        position: Math.Vec3.from_xyz(0.0, 0.0, 0.0)
        main_axis: Math.Vec3.Y_AXIS()
        normal: Math.Vec3.Z_AXIS()

In this example, the connector is centered in the wheel and oriented so the wheel spins around Y.

How a Mate aligns two MateConnectors

A mate uses two connectors. The mate aligns the connector frames, then constrains motion based on mate type:

Lock: constrains all 6 DOF
Hinge: allows rotation around the connector main_axis

WheelBody is Physics3D.Bodies.RigidBody:
    geometry is Physics3D.Geometries.Cylinder:
        radius: 0.3
        height: 0.12
    visual is Visuals.Geometries.Cylinder:
        radius: geometry.radius
        height: geometry.height
    hub_connector is Physics3D.Interactions.MateConnector:
        main_axis: Math.Vec3.Y_AXIS()
        normal: Math.Vec3.Z_AXIS()

AxleBody is Physics3D.Bodies.RigidBody:
    geometry is Physics3D.Geometries.Cylinder:
        radius: 0.05
        height: 0.8
    visual is Visuals.Geometries.Cylinder:
        radius: geometry.radius
        height: geometry.height
    wheel_connector is Physics3D.Interactions.MateConnector:
        main_axis: Math.Vec3.Y_AXIS()
        normal: Math.Vec3.Z_AXIS()

LockedPair is Physics3D.System:
    wheel is WheelBody
    axle is AxleBody
    wheel_to_axle is Physics3D.Interactions.Lock:
        connectors: [wheel.hub_connector, axle.wheel_connector]

wheel_to_axle aligns the connector frames and keeps the two bodies rigidly attached.

SNAP and system assembly

SNAP is the automatic assembly algorithm used by Physics3D. Given mates, it computes missing local transforms in a system hierarchy by aligning connector frames.

Important practical rule:

if a body or system already has an explicit local_transform, that transform is fixed
SNAP solves for bodies/systems where transforms are not explicitly set

This lets you model mechanisms from relationships instead of manually placing every body.

Motorcycle with mates

This model is an alternative to motorcycle structure from the rigid-body concepts. Instead of explicitly positioning each rigid body, we let SNAP put the pieces in place using Mates. The result will be a simulation ready model.

Let’s add connectors and mates so:

front wheel locks to front axle
front axle hinges to frame
rear wheel hinges to frame

To reduce duplication, both wheels and axles are based on one reusable CylindricalBody template.

CylindricalBody is Physics3D.Bodies.RigidBody:
    geometry is Physics3D.Geometries.Cylinder:
        radius: 0.2
        height: 0.12
    visual is Visuals.Geometries.Cylinder:
        radius: geometry.radius
        height: geometry.height
    center_connector is Physics3D.Interactions.MateConnector:
        main_axis: Math.Vec3.Y_AXIS()
        normal: Math.Vec3.Z_AXIS()

WheelBody is CylindricalBody:
    geometry.radius: 0.33

FrontAxleBody is CylindricalBody:
    geometry.radius: 0.05
    geometry.height: 0.2
    frame_hinge_connector is Physics3D.Interactions.MateConnector:
        position: Math.Vec3.from_xyz(-0.3, 0.0, 0.45)
        main_axis: Math.Vec3.Z_AXIS()
        normal: Math.Vec3.X_AXIS()

Frame is Physics3D.System:
    main_beam is Physics3D.Bodies.RigidBody:
        kinematics.local_transform.position: {0,0,0}
        geometry is Physics3D.Geometries.Box:
            size: Math.Vec3.from_xyz(1.4, 0.15, 0.12)
        visual is Visuals.Geometries.Box:
            size: main_beam.geometry.size
        steering_head_mount_connector is Physics3D.Interactions.MateConnector:
            position: Math.Vec3.from_xyz(0.6, 0.0, 0.1)
            main_axis: Math.Vec3.Z_AXIS()
            normal: Math.Vec3.X_AXIS()
        rear_wheel_hinge_connector is Physics3D.Interactions.MateConnector:
            position: Math.Vec3.from_xyz(-0.7, 0.0, -0.2)
            main_axis: Math.Vec3.Y_AXIS()
            normal: Math.Vec3.Z_AXIS()
    steering_head is CylindricalBody:
        geometry.radius: 0.06
        geometry.height: 0.5
        frame_lock_connector is Physics3D.Interactions.MateConnector:
            main_axis: Math.Vec3.Z_AXIS()
            normal: Math.Vec3.X_AXIS()
        steering_hinge_connector is Physics3D.Interactions.MateConnector:
            main_axis: Math.Vec3.Z_AXIS()
            normal: Math.Vec3.X_AXIS()

MotorCycle is Physics3D.System:
    front_wheel is WheelBody
    rear_wheel is WheelBody:
        geometry.height: 0.14
    front_axle is FrontAxleBody
    frame is Frame:
        local_transform.position: {0,0,0}

    front_wheel_to_axle_lock is Physics3D.Interactions.Lock:
        connectors: [front_wheel.center_connector, front_axle.center_connector]

    front_axle_to_frame_hinge is Physics3D.Interactions.Lock:
        connectors: [front_axle.frame_hinge_connector, frame.steering_head.steering_hinge_connector]

    steering_head_to_main_beam_lock is Physics3D.Interactions.Hinge:
        connectors: [frame.steering_head.frame_lock_connector, frame.main_beam.steering_head_mount_connector]

    rear_wheel_to_frame_hinge is Physics3D.Interactions.Hinge:
        connectors: [rear_wheel.center_connector, frame.main_beam.rear_wheel_hinge_connector]

Adjust the initial state

Now create one model named MotorCycleTurningLeft that inherit from MotorCycle.

MotorCycleTurningLeft is MotorCycle:
    steering_head_to_main_beam_lock.initial_angle: -0.5