Concepts Machine Modeling

This concepts page introduces machine-level modeling patterns using a small crane example.

Why use Components and Connections

In MachineModeling, both Components and Connections are modeled as Physics3D.System. This is a key step away from modeling directly with only RigidBody + Mate everywhere.

Instead of wiring low-level physics objects directly in your top-level machine, you encapsulate them:

a Component can internally contain one or many rigid bodies, sensors, connectors, and internal mates
a Connection can internally contain one or many interactions and evolve from simple to high-fidelity variants

This gives a much stronger specialization path:

start with MachineModeling.Connections.Pivot.Hinge
specialize with additional constraints/limits for operational range
upgrade to MachineModeling.Connections.Pivot.AxleBearings for bearing and axle force behavior

Likewise, a component can start as a simple primitive body and later be upgraded with:

extra rigid bodies
embedded sensors
internal mate structure

while still keeping the same external interface to the rest of the machine.

Goal

We will build the same crane in three steps:

two booms connected by a hinge, actuated by a linear cylinder
upgrade the hinge to an axle bearing connection
upgrade the cylinder-to-boom connection to a linked connection with guide and drive links

Type names can vary slightly between MachineModeling versions, but the progression pattern is the same.

Step 1: Two booms, hinge, and linear cylinder actuator

Start with two boom components connected by MachineModeling.Connections.Pivot.Hinge. Then add one MachineModeling.Actuators.Linear.Cylinder with a cylinder connection.

trait CylinderVisual:
    visual is Visuals.Geometries.Cylinder:
        radius: diameter/2
        height: length
        local_transform: cylinder.local_transform

CenteredBoomBody is Physics3D.Bodies.RigidBody:
    length is Real: 2.5
    box is Physics3D.Geometries.Box:
        size: visual.size
    visual is Visuals.Geometries.Box:
        size: {length, 0.25, 0.25}
    start is Physics3D.Interactions.MateConnector:
        position: {-length * 0.5, 0, 0}
    end is Physics3D.Interactions.MateConnector:
        position: {length * 0.5, 0, 0}
    actuator_connector is Physics3D.Interactions.MateConnector:
        position: {0.0, 0.0, 0.35}

CraneStep1 is Physics3D.System:
    base_boom is MachineModeling.Components.Primitive.Base:
        body becomes CenteredBoomBody
        local_transform.position: {0,0,0}
        local_transform.rotation: Math.Quat.angle_axis(-Math.PI/2, {0,0,-1})
    second_boom is MachineModeling.Components.Primitive.Base:
        body becomes CenteredBoomBody

    boom_connection is MachineModeling.Connections.Pivot.Hinge:
        from: base_boom.body.end
        to: second_boom.body.start
        hinge.initial_angle: 1.4

    lift_actuator is MachineModeling.Actuators.Linear.Cylinder:
        source.connectors: [base_boom.body.actuator_connector, second_boom.body.actuator_connector]
        barrel.body becomes Physics3D.Bodies.RigidBody with CylinderVisual:
            diameter: 0.12
        rod.body becomes Physics3D.Bodies.RigidBody with CylinderVisual:
            diameter: 0.06
        min_length: 1.5
        stroke_length: 1.5

    lift_connection is MachineModeling.Actuators.Linear.Connections.Cylinder:
        actuator: lift_actuator
        from: base_boom.body.actuator_connector
        to: second_boom.body.actuator_connector

In this first version, the mechanism is simple and easy to understand.

Two primitive machine components are connected so that the second_boom may pivot about the base_boom. Another component, the cylinder actuator is connected with a cylinder connection.

How `CylinderVisual` is used

In CraneStep1, CylinderVisual is a reusable trait that adds the visual cylinder definition based on the body dimensions:

radius: diameter/2
height: length
local_transform: cylinder.local_transform

The key part is that both actuator parts are specialized with the trait:

lift_actuator.barrel.body becomes Physics3D.Bodies.RigidBody with CylinderVisual:
    diameter: 0.12

lift_actuator.rod.body becomes Physics3D.Bodies.RigidBody with CylinderVisual:
    diameter: 0.06

This keeps one shared visual definition while still allowing different barrel and rod diameters.

Step 2: Upgrade hinge to axle bearing connection

In this step, the boom pivot is upgraded from a simple hinge to an axle-bearing assembly. Each boom gets a BearingPair, and the connection is specialized to MachineModeling.Connections.Pivot.AxleBearings. The two booms then pivot through a shared axle instead of directly against each other.

trait Bearings:
    start_pair is MachineModeling.Components.Composite.BearingPair:
        local_transform.position: body.start.position
        separation: 0.12
        local_axis: body.start.main_axis
        body: body
    end_pair is MachineModeling.Components.Composite.BearingPair:
        local_transform.position: body.end.position
        separation: 0.16
        local_axis: body.end.main_axis
        body: body

CraneStep2 is CraneStep1:
    base_boom becomes MachineModeling.Components.Primitive.Base with Bearings
    second_boom becomes MachineModeling.Components.Primitive.Base with Bearings
    base_boom.body becomes CenteredBoomBody
    second_boom.body becomes CenteredBoomBody

    boom_axle is MachineModeling.Components.Primitive.Axle.RigidCylindrical:
        diameter: 0.05
        length: 0.4

    boom_connection becomes MachineModeling.Connections.Pivot.AxleBearings:
        from_bearings: base_boom.end_pair
        to_bearings: second_boom.start_pair
        axle: boom_axle

This gives a higher-fidelity joint model:

one axle body carries the rotational interface
one bearing pair on each boom defines where the load is transferred
the original hinge-level abstraction is preserved, but the internals are physically richer

Step 3: Upgrade cylinder-to-boom connection to linked connection

In this step, the direct cylinder endpoint is replaced by a linked mechanism. Two link components (guide_link and drive_link) are introduced and connected using MachineModeling.Components.Primitive.Link.Connections.Base. The cylinder connection target is moved to a dedicated axle (cylinder_axle.central_connector), and the link pair is closed with a snap hinge (link_snap).

LinkWithGeometryAndVisual is MachineModeling.Components.Primitive.Link.Base:
    with MachineModeling.Components.Primitive.Link.Traits.ConvexShape

CraneStep3 is CraneStep2:
    base_boom.body.link_connector is Physics3D.Interactions.MateConnector:
        position: {base_boom.body.length*0.25, 0, 0.35}

    guide_link is LinkWithGeometryAndVisual:
        length: 0.8

    drive_link is LinkWithGeometryAndVisual:
        length: 0.7

    cylinder_axle is MachineModeling.Components.Primitive.Axle.RigidCylindrical:
        diameter: 0.05
        length: 0.4

    guide_boom_connection is MachineModeling.Components.Primitive.Link.Connections.Base:
        link: guide_link
        from: base_boom.body.link_connector
        to: cylinder_axle.central_connector

    drive_cylinder_connection is MachineModeling.Components.Primitive.Link.Connections.Base:
        link: drive_link
        from: second_boom.body.actuator_connector
        to: cylinder_axle.central_connector

    link_snap is MachineModeling.Connections.Pivot.Hinge:
        hinge.enabled: false
        from: guide_link.connector_2
        to: drive_link.connector_2
        range is Physics3D.Interactions.RotationalRange:
            connectors: link_snap.hinge.connectors
            enabled: false
            start: 0
            end: Math.PI

    lift_connection.to: cylinder_axle.central_connector
    lift_actuator.min_length: 0.6
    lift_actuator.stroke_length: 0.6

This model is closer to real boom-linkage layouts:

link geometry is modeled explicitly
the actuator drives an intermediate linkage instead of directly driving the boom
the mechanism can be tuned through link lengths, axle placement, and actuator stroke

Practical modeling pattern

Use this progression when building machinery:

begin with simpler connection models to validate structure
upgrade to bearing and linked connection models as realism needs increase
keep bodies reusable so only connection models evolve between concept stages