Manipulator3D — 3-DOF Two-Link Robot Arm (Analytic IK + Pick&Place) — Rust

A Rust simulation and visualization project for a 3-DOF, two-link manipulator with a fixed base in 3D space. The arm executes a simple pick-and-place loop using an analytic inverse kinematics solver and a linear end-effector trajectory.

• Joint 0 (base): revolute yaw about the +Z axis at the origin (0,0,0).
• Joints 1–2 (links): revolute pitch angles defining motion in the arm’s vertical plane (relative to the X–Y plane).
• IK: reduces the 3D target to a 2D planar problem in (r,z), solves with the law of cosines, and supports elbow-up / elbow-down branches.
• Visualization: rendered with raylib, including an overlay panel and a simple suction-tool “ball” pick-and-place animation.
• User input: START/GOAL are entered in the UI overlay (no console prompts). Press PLAY to start; press PAUSE to edit inputs.

Build system: Cargo • Rendering: raylib • Language: Rust (Edition 2021) • IK: Closed-form

---

• About this repository
• Repository structure
• Robotics: kinematics, dynamics, and inverse kinematics
• Building the project
• Operating system guides (Windows / macOS / Linux)
• Running the simulator
• Repository file guide (full explanation)
• Simulation video
• Troubleshooting

---

About this repository

This project simulates a 3-DOF, two-link manipulator mounted on a fixed base at the origin:

• The base joint rotates around the Z axis (yaw).
• The two link joints rotate as pitch angles (relative to the X–Y plane) in the arm’s vertical plane.
• The end-effector (EE) tracks a sequence of target points with analytic inverse kinematics.
• A small “ball” is used to visualize a pick-and-place loop:
  1. HOME → START
  2. PICK at START (attach ball)
  3. START → GOAL
  4. PLACE at GOAL (detach ball)
  5. GOAL → HOME
  6. wait briefly and repeat

User inputs (via overlay panel):

• START position (x y z) and GOAL position (x y z)
• Constraint enforced by IK: z must be ≥ 0
• Reachability enforced by IK: |p| must be within the arm’s reachable shell.

Controls / interaction

• Mouse wheel: zoom camera
• F11: toggle fullscreen
• Overlay includes a PAUSE/PLAY button, editable START/GOAL fields, and reachability feedback

---

Repository structure

Manipulator3D_Rust/
  Cargo.toml
  Cargo.lock
  README.md
  .cargo/
    config.toml
  resources/
    fonts/
      Inter-Regular.ttf
  src/
    main.rs
    robot/
      mod.rs
      robot_arm.rs
    sim/
      mod.rs
      trajectory.rs
    ui/
      mod.rs
      overlay.rs
    render/
      mod.rs
      draw_utils.rs

About .cargo/config.toml (important)

This repository includes a .cargo/config.toml tuned for slow/unstable networks and environments where Cargo downloads time out. If your network is stable, you can keep it as-is (it does not change runtime behavior), or adjust the values.

Typical improvements it provides:

• avoids flaky HTTP/2 multiplexing
• increases timeouts/retries
• relaxes low-speed limits for very slow links
• uses the git crates.io index protocol to avoid sparse-index issues

---

Robotics: kinematics, dynamics, and inverse kinematics

1) Coordinate frames and joint conventions

• World frame origin is at the center of the base revolute joint: (0,0,0).
• Joint angles:
  • q0_yaw : rotation about +Z (sets the arm’s radial direction in the X–Y plane)
  • q1_pitch: shoulder elevation angle relative to the X–Y plane
  • q2_pitch: elbow pitch angle (relative bend in the same vertical plane)

We use the radial unit direction in the X–Y plane:

$$\mathbf{u} = \begin{bmatrix} \cos(q_0)\\\ \sin(q_0)\\\ 0 \end{bmatrix}, \quad \mathbf{k} = \begin{bmatrix} 0\\\ 0\\\ 1 \end{bmatrix}.$$

2) Forward kinematics (FK)

Let link lengths be $L_1$ and $L_2$. Then:

• Elbow position:

$$\mathbf{p}_1 = L_1\cos(q_1)\,\mathbf{u} + L_1\sin(q_1)\,\mathbf{k}$$

• End-effector position:

$$\mathbf{p}_{ee} = \mathbf{p}_1 + L_2\cos(q_1+q_2)\,\mathbf{u} + L_2\sin(q_1+q_2)\,\mathbf{k}$$

3) Workspace (reachability) check

This manipulator is effectively a 2-link arm in a vertical plane, rotated by yaw. Therefore the reachable radius must satisfy:

$$r_{\min} = |L_1 - L_2|,\quad r_{\max} = L_1 + L_2$$ $$\|\mathbf{p}\| \in [r_{\min}, r_{\max}]$$

The implementation enforces:

• target.z >= 0
• |p| within [MinReach(), MaxReach()]

4) Analytic inverse kinematics (IK): how it works here

Given target $\mathbf{p} = (x,y,z)$:

Step A — base yaw

$$q_0 = \mathrm{atan2}(y, x)$$

Step B — reduce to planar IK in $(r,z)$

$$r = \sqrt{x^2 + y^2}$$

Now solve a 2-link planar problem for the triangle formed by $L_1$, $L_2$, and $\sqrt{r^2+z^2}$.

Step C — elbow angle from law of cosines

$$\cos(q_2) = \frac{r^2 + z^2 - L_1^2 - L_2^2}{2L_1L_2}$$

Clamp to $[-1,1]$ for numerical safety, then:

$$q_2 = \pm \arccos(\cos(q_2))$$

This sign is the elbow-up / elbow-down branch selection.

Step D — shoulder angle

Define:

$$k_1 = L_1 + L_2\cos(q_2),\quad k_2 = L_2\sin(q_2)$$

Then:

$$q_1 = \mathrm{atan2}(z, r) - \mathrm{atan2}(k_2, k_1)$$

---

Building the project

Dependencies

• Rust toolchain (Rustup recommended)
• A native C/C++ toolchain (raylib is built natively via raylib-sys)
  • Windows: Visual Studio Build Tools / MSVC
  • macOS: Xcode Command Line Tools
  • Linux: build-essential (GCC/Clang + make)

Build commands (recommended)

From the repository root (where Cargo.toml is):

cargo clean
cargo build --release

---

Operating system guides (Windows / macOS / Linux)

Windows 10/11 (MSVC toolchain)

This project targets the MSVC Rust toolchain on Windows. The most reliable approach is to build from the Developer PowerShell for VS 2022 (or the x64 Native Tools Command Prompt), because it pre-configures the MSVC compiler + linker environment.

Recommended workflow (Developer PowerShell)

1. Install prerequisites:

• Rust (Rustup) using the x86_64-pc-windows-msvc toolchain
• Visual Studio 2022 Build Tools with the workload: Desktop development with C++
• Windows 10/11 SDK (installed with the Build Tools when selected)

2. Open: Developer PowerShell for VS 2022.

3. Build and run:

cd path\to\Manipulator3D_Rust
cargo fetch
cargo run --release

If you see linker errors (kernel32.lib not found / wrong link.exe)

Some Windows environments (especially when MSYS2 / Git Bash is installed) can accidentally pick up a non-MSVC link.exe. If you see errors referencing paths like C:\msys64\usr\bin\link.exe, you can explicitly configure the MSVC libraries and linker inside PowerShell before building.

Run the following PowerShell commands (edit the version/path to match your machine):

# 1) MSVC version you have (taken from your MSVC folder name)
#    Change this to match your system.
#    How to find it:
#      Open:   C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\
#      Pick the newest folder name (example: 14.44.35207)
$msvcVer = "14.44.35207"

# 2) MSVC lib directory (x64)
$msvcLib = "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\$msvcVer\lib\x64"

# 3) Windows SDK (Windows Kits) library directories
$sdkRoot = "C:\Program Files (x86)\Windows Kits\10\Lib"
$sdkVer  = (Get-ChildItem $sdkRoot -Directory | Sort-Object Name -Descending | Select-Object -First 1).Name

$umLib   = Join-Path $sdkRoot "$sdkVer\um\x64"
$ucrtLib = Join-Path $sdkRoot "$sdkVer\ucrt\x64"

# 4) Sanity checks (should print True / True)
Test-Path (Join-Path $umLib "kernel32.lib")
Test-Path (Join-Path $msvcLib "msvcrt.lib")

# 5) Tell the linker where to find .lib files
$env:LIB = "$msvcLib;$ucrtLib;$umLib;$env:LIB"

# 6) Force Cargo to use MSVC's linker (NOT MSYS2/Git's link.exe)
$env:CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_LINKER = "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207\bin\Hostx64\x64\link.exe"

# 7) Build and run from the repository root (where Cargo.toml is)
cd "$env:USERPROFILE\Desktop\Manipulator3D_Rust"

cargo clean
cargo fetch
cargo run --release

macOS

1. Install Rust (or verify it is installed):

rustc --version
cargo --version

2. Ensure build tools are available (Xcode Command Line Tools):

xcode-select --install

3. Run:

cd path/to/Manipulator3D_Rust
cargo fetch
cargo run --release

Linux (Ubuntu/Debian)

1. Install Rust (or verify it is installed):

rustc --version
cargo --version

2. Install native build dependencies:

sudo apt-get update
sudo apt-get install -y build-essential pkg-config

3. Run:

cd path/to/Manipulator3D_Rust
cargo fetch
cargo run --release

---

Running the simulator

From the repository root:

cargo fetch
cargo run --release

Controls / interaction

• Mouse wheel: zoom camera
• F11: toggle fullscreen
• Overlay:
  • edit START and GOAL when paused
  • press PLAY to start the simulation
  • press PAUSE to stop and edit inputs again

---

Repository file guide (full explanation)

This section explains every important file in the repository and its role.

Cargo.toml

• Declares the package and dependencies.
• Uses raylib crate (which pulls raylib-sys for native compilation).

---

.cargo/config.toml

• Cargo networking configuration tuned for slow/unstable connections.
• Useful when downloads repeatedly timeout or reset.

---

src/main.rs

Runtime loop + simulation state machine:

• reads START/GOAL from overlay input fields
• validates reachability using IK for:
  • fixed HOME EE point
  • START
  • GOAL
• runs a pick-and-place finite-state machine:
  • HOME → START → PICK → GOAL → PLACE → HOME → WAIT → LOOP
• generates a linear Cartesian trajectory between targets
• runs IK each frame to get joint angles for the current EE target
• calls FK for rendering joint/link positions
• renders:
  • robot geometry, axes, ball, suction tool
  • overlay panel (inputs, parameters, status, play/pause)

---

src/robot/robot_arm.rs

Implements analytic FK and IK:

• IK:
  • rejects invalid targets (z < 0)
  • checks radius bounds (min/max reach)
  • computes yaw from atan2(y,x)
  • reduces to planar IK in (r,z)
  • solves elbow angle via law of cosines
  • solves shoulder angle via triangle decomposition
• FK:
  • constructs radial axis from yaw
  • builds elbow and EE positions from link lengths and pitch angles

---

src/sim/trajectory.rs

Minimal trajectory generator:

• linear interpolation with normalized time:
  • $\alpha = \mathrm{clamp}(t/T, 0, 1)$
• position:
  • $\mathbf{p}(\alpha) = \mathbf{a} + (\mathbf{b}-\mathbf{a})\alpha$

---

src/ui/overlay.rs

Overlay rendering and interaction:

• editable START and GOAL input boxes
• reachability checks and status display
• PLAY/PAUSE button:
  • PLAY validates inputs and starts a new simulation
  • PAUSE stops simulation so inputs can be edited

---

src/render/draw_utils.rs

Rendering helpers:

• text helpers (small and bold)
• robot visuals:
  • base pedestal + flange
  • joint housings
  • tapered links
  • suction tool

---

Simulation video

Below is a link to the simulation video on YouTube.

---

Troubleshooting

Cargo downloads are extremely slow or fail with timeouts/resets

• This repo includes .cargo/config.toml to improve reliability on slow/unstable networks.
• If you still see timeouts:
  • try again later or from a different network
  • ensure proxies/VPNs are not interfering with static.crates.io

Build fails on Windows with linker errors

• Use Developer PowerShell for VS 2022.
• If kernel32.lib is missing or a wrong link.exe is used, follow the PowerShell configuration in:
  • Windows 10/11 (MSVC toolchain)

Build fails with libclang / bindgen related errors

Some systems require LLVM/Clang to be installed for bindgen/clang-sys when building native dependencies.

• Windows: install LLVM and ensure libclang is discoverable
• macOS: Xcode Command Line Tools usually provide clang
• Linux: install clang/llvm packages if needed

Start/Goal is “out of reach”

• Ensure:
  • z >= 0
  • |p| is within the workspace shell:
    • [|L1 - L2|, L1 + L2]