body-creation

name	body_creation
description	Create rigid bodies with mass, geometry, collision shapes, and visual assets.
compatibility	pychrono >= 8.0
metadata	{"domain":"mbs"}

Skill: MBS Body Creation

Purpose

Create rigid bodies — using easy factory functions or manually — with mass, geometry, collision shapes, and visual assets.

When to Use

When populating a simulation with floors, objects, cranks, pistons, pendulum arms, or any physical part.

---

PyChrono Defaults — Know Before Customizing

Shape / Factory	Cylinder axis (body-local)	Visual auto-added?
ChVisualShapeCylinder (manual)	Z	No — must call AddVisualShape explicitly
ChBodyEasyCylinder(ChAxis_Y, ...)	Y	Yes — do NOT call AddVisualShape again
ChBodyEasyCylinder(ChAxis_X, ...)	X	Yes — do NOT call AddVisualShape again
ChBodyEasyCylinder(ChAxis_Z, ...)	Z	Yes — do NOT call AddVisualShape again

Rule: Easy factory bodies already have a visual shape built in. Never call AddVisualShape on an easy factory body for the same shape — that creates a duplicate visual.

---

Easy Factory vs Manual — Choose Before Writing Code

Use ChBodyEasyBox / ChBodyEasySphere freely for any body shape.

Use ChBodyEasyCylinder only when:

• The body is a fixed or structural element (post, column, ground pin) whose axis-aligned orientation (ChAxis_X/Y/Z) directly matches the world orientation without further SetRot
• OR the simulation doesn't require re-orienting the body during the run

Use ChBody + ChVisualShapeCylinder for:

• Any link body whose orientation is non-trivial or changes during simulation (crank, connecting rod, pendulum arm, any rotating or translating link)
• Reason: manual setup gives full control; the two-step visual formula below applies only to manual ChBody + ChVisualShapeCylinder — not to easy factory bodies

---

Easy Factory Bodies (simplest approach)

These create the ChBody, add a visual shape, optionally add a collision shape, and set the mass from density — all in one call.

# Box: x, y, z extents (full sizes), density, visualize, collide, material
box_sx = float       # box width [m]
box_sy = float       # box height [m]
box_sz = float       # box depth [m]
box_density = float  # material density [kg/m³]
body = chrono.ChBodyEasyBox(box_sx, box_sy, box_sz, box_density, True, True, mat)

# Cylinder: axis enum, radius, height, density, visualize, collide, material
# Axis enum sets which body-local axis the cylinder points along.
# Visual shape is created automatically — do NOT call AddVisualShape after.
cyl_radius = float   # cylinder radius [m]
cyl_height = float   # cylinder height [m]
cyl_density = float  # material density [kg/m³]
body = chrono.ChBodyEasyCylinder(chrono.ChAxis_Y, cyl_radius, cyl_height, cyl_density, True, True, mat)

# Sphere: radius, density, visualize, collide, material
sph_radius = float   # sphere radius [m]
sph_density = float  # material density [kg/m³]
body = chrono.ChBodyEasySphere(sph_radius, sph_density, True, True, mat)

After factory creation:

body.SetPos(chrono.ChVector3d(x, y, z))
body.SetFixed(True)          # immovable (floor/wall)
sys.Add(body)
# Do NOT call AddVisualShape — the factory already added one.

---

Manual Body Setup (full control)

Use this path for any link body (crank, rod, pendulum arm, etc.):

mass = float         # total body mass [kg]
inertia_xx = float   # moment of inertia about X [kg·m²]
pos_x = float        # x position [m]
pos_y = float        # y position [m]
pos_z = float        # z position [m]
body = chrono.ChBody()
body.SetMass(mass)
body.SetInertiaXX(chrono.ChVector3d(inertia_xx, inertia_xx, inertia_xx))
body.SetPos(chrono.ChVector3d(pos_x, pos_y, pos_z))
body.EnableCollision(False)  # or True
sys.AddBody(body)

---

Cylinder Orientation — General Rule (manual ChBody only)

Goal: make the cylinder visual point along the link's physical axis in the world.

Convention: define body-local X as the link direction. Then apply two steps:

Step 1 — Body rotation:
    body.SetRot(rotation_that_points_body_local_X_along_link_direction)
    → encodes the link direction in world space

Step 2 — Visual offset (always the same formula):
    cyl = chrono.ChVisualShapeCylinder(radius, height)
    body.AddVisualShape(cyl, chrono.ChFramed(chrono.VNULL, chrono.QuatFromAngleY(chrono.CH_PI_2)))
    → rotates cylinder axis from body-local Z to body-local X

Why it works:

• ChVisualShapeCylinder default axis is body-local Z
• QuatFromAngleY(CH_PI_2) rotates Z → X
• So the cylinder ends up pointing along body-local X, which Step 1 aligned with the link
• ChFramed position = VNULL when body.SetPos() is at the link's midpoint (body COM)

Never invent per-body magic ChFramed rotations. Use SetRot to encode orientation, and always use the same ChFramed(VNULL, QuatFromAngleY(CH_PI_2)) offset for the visual.

---

Step 1 Rotation by Case

# Planar mechanism — link at angle θ from world X, rotating in XY plane:
body.SetRot(chrono.QuatFromAngleZ(theta))
# → body-local X points at angle θ in the XY plane
# Step 2 formula unchanged

# Link initially along world X (angle 0):
body.SetRot(chrono.QUNIT)   # body-local X = world X already
# Step 2 formula unchanged

# Vertical link along world Z:
# Option A — use ChBodyEasyCylinder(ChAxis_Z, ...) for a fixed vertical rod (no manual visual needed)
# Option B — manual body: skip the QuatFromAngleY rotation and attach with QUNIT
#   body.AddVisualShape(cyl, chrono.ChFramed(chrono.VNULL, chrono.QUNIT))
#   (cylinder default Z is already vertical)

# 3D link along arbitrary unit vector — align body-local X with that vector:
body.SetRot(chrono.QuatFromAngleAxis(angle, axis_vector))
# Step 2 formula unchanged

Rotation helpers (quaternion constants and functions)

chrono.QUNIT                            # identity rotation
chrono.QuatFromAngleZ(angle_rad)        # rotate about world Z by angle (use for planar links)
chrono.QuatFromAngleY(angle_rad)        # rotate about Y (used in Step 2 visual offset)
chrono.QuatFromAngleX(angle_rad)        # rotate about X
chrono.QuatFromAngleAxis(angle_rad, chrono.VECT_X)  # arbitrary rotation about X
chrono.Q_ROTATE_Y_TO_Z                 # cylinder axis Y → Z direction (easy factory only)
chrono.Q_ROTATE_Y_TO_X                 # cylinder axis Y → X direction (easy factory only)
chrono.Q_ROTATE_Z_TO_X                 # frame Z → X (used for prismatic joints)

---

Visual Shapes (attach to manual ChBody)

vs_sx = float  # visual box width [m]
vs_sy = float  # visual box height [m]
vs_sz = float  # visual box depth [m]
box_shape = chrono.ChVisualShapeBox(vs_sx, vs_sy, vs_sz)
box_shape.SetTexture(chrono.GetChronoDataFile('textures/concrete.jpg'))
body.AddVisualShape(box_shape)

vs_radius = float  # visual sphere radius [m]
sph_shape = chrono.ChVisualShapeSphere(vs_radius)
body.AddVisualShape(sph_shape, chrono.ChFramed(chrono.ChVector3d(offset_x, 0, 0)))

# Cylinder — default axis is body-local Z.
# For any link body, use the two-step formula above (Step 1 SetRot + Step 2 AddVisualShape):
cyl_shape = chrono.ChVisualShapeCylinder(radius, height)
body.AddVisualShape(cyl_shape, chrono.ChFramed(chrono.VNULL, chrono.QuatFromAngleY(chrono.CH_PI_2)))

---

Texture / Visual Material

# Simple texture on easy body:
body.GetVisualShape(0).SetTexture(chrono.GetChronoDataFile("textures/bluewhite.png"))

# Full visual material:
vis_mat = chrono.ChVisualMaterial()
vis_mat.SetKdTexture(chrono.GetChronoDataFile("textures/concrete.jpg"))
body.GetVisualShape(0).SetMaterial(0, vis_mat)