🌐 Visit ARGUS-AI

"Teaching an AI robot arm where to move—instead of solving hard math equations."

---

1. What is Argus AI? (Beginner Friendly)

Imagine you have a robotic arm with 2 main segments (links $L_1$ and $L_2$) connected by 2 joints ($\theta_1$ at the shoulder, $\theta_2$ at the elbow):

• Your Goal: You want the tip of the robot hand to touch a specific spot on a screen, coordinates $(X, Y)$.
• The Question: At what angles should the shoulder ($\theta_1$) and elbow ($\theta_2$) rotate so the hand reaches $(X, Y)$?

Argus AI trains smart Machine Learning models (like XGBoost) to instantly predict the exact joint angles $(\theta_1, \theta_2)$ for any target coordinate $(X, Y)$ and arm lengths $(L_1, L_2)$ in a fraction of a millisecond!

---

💡 2. Core Robotics Concepts Explained Simply

📐 Concept A: Forward Kinematics (FK) — "The Easy Direction"

If you already know the joint angles ($\theta_1, \theta_2$), calculating where the hand $(X, Y)$ lands is simple trigonometry:

$$X = L_1 \cos(\theta_1) + L_2 \cos(\theta_1 + \theta_2)$$ $$Y = L_1 \sin(\theta_1) + L_2 \sin(\theta_1 + \theta_2)$$

This is a 1-to-1 formula. Input angles $\to$ Output position.

---

🔄 Concept B: Inverse Kinematics (IK) — "The Hard Direction"

In real life, you don't care about joint angles first—you care about where you want the robot hand to go $(X, Y)$. Working backwards from $(X, Y)$ to find $(\theta_1, \theta_2)$ is called Inverse Kinematics.

Traditional robotics solves complex square-root and arc-tangent equations (atan2). In Argus AI, we let a Machine Learning model learn this relationship directly from data!

---

⚠️ Concept C: The "Elbow-Up vs. Elbow-Down" Problem

Think about reaching for a doorknob with your arm. You can reach the exact same knob in two different ways:

1. With your elbow pointing Up ↗️
2. With your elbow pointing Down ↘️

Why is this dangerous for AI?
If you give a Machine Learning model a dataset containing BOTH "Elbow-Up" and "Elbow-Down" solutions for the same spot, the AI will try to average them. The average of Elbow-Up and Elbow-Down is a straight arm pointing into thin air!
The Solution: We strictly enforce Elbow-Down ($\theta_2 \ge 0$) during data generation so the AI gets 1 clean, unambiguous target every time.

---

🏗 3. Project Architecture

The repository is built as a clean, production-grade modular system:

📁 Project Structure Breakdown:

• src/kinematics/ 🧮
  The mathematical source of truth. Contains Forward Kinematics equations used to verify AI predictions.
• src/dataset/ 🎲
  Synthesizes thousands of random robot configurations $(X, Y, L_1, L_2 \to \theta_1, \theta_2)$ while strictly enforcing elbow-down rules.
• src/preprocessing/ ⚙️
  Normalizes and scales input data so the ML models train efficiently.
• src/training/ 🧠
  Trains multi-output regressors (XGBoost, Random Forest, Decision Trees, Extra Trees).
• src/evaluation/ 📊
  Takes the predicted angles $(\theta_1, \theta_2)$, runs them back through Forward Kinematics, and calculates the exact Cartesian distance error in millimeters.
• api/index.py & server.py 🌐
  Exposes a REST API (POST /predict) for single-step joint angle predictions.
• webapp/ 💻
  A modern Vite + React 2D/3D web interface that renders the animated robot arm in real time.

---

🚀 4. Quick Start Guide (Run It Locally)

Want to try it on your computer? Follow these 3 simple steps:

Step 1: Clone & Install

git clone https://github.com/dev-hari-haran/ARGUS-AI.git
cd ARGUS-AI

# Create virtual environment
python -m venv .venv

# Activate environment (Windows)
.venv\Scripts\activate
# Activate environment (Linux/macOS)
source .venv/bin/activate

pip install -r requirements.txt

Step 2: Start the Python Backend Server

python server.py

Step 3: Start the Web App Frontend

Open a second terminal window:

cd webapp
npm install
npm run dev

Open http://localhost:5173 in your browser to interact with the robot arm!

---

🌐 5. Online Live Deployment

You don't even need to install anything locally to see it work!
The full project is hosted live on Vercel:

👉 Launch Argus AI Web App

---

⚙️ 6. Custom Configuration

You can change robot parameters without modifying python code in configs/robot.yaml:

link_lengths:
  l1: [0.5, 2.0]  # Minimum and maximum length for Link 1
  l2: [0.5, 2.0]  # Minimum and maximum length for Link 2
joint_limits:
  q1: [-3.14159, 3.14159]  # Shoulder rotation limits (-180° to 180°)
  q2: [0.0, 3.14159]       # Elbow rotation limits (0° to 180° - Elbow Down)

---

📜 7. License

Distributed under the MIT License. See LICENSE for details.
Created by Hariharan R (2026).

---

💖 A Personal Note

"Every line of code in Argus AI was written with curiosity, passion, and a dream to bridge the gap between abstract mathematics and physical motion. What started as simple joint equations grew into an intelligent system that learns, predicts, and brings a virtual robotic arm to life.

To everyone exploring this repository: never stop building, never stop learning, and may your code always reach its destination with millimeter accuracy."

With passion and gratitude,
Hariharan R ✨
Developer of ARGUS-AI (2026)