---

Web    Live Demo    Video

Web-based XR labs for ALL types of eXperiments

AllEx is a web-based immersive virtual lab platform that allows users to perform various experiments in an XR environment. It is developed as part of the SPARCS Science Hackathon 2024.

---

Table of Contents

1. Features
2. Technology Stack
3. Installation
4. Usage
5. Project Structure
6. Contributing
7. License

---

Features

• Web-based platform for performing interactive experiments.
• Real-time hand tracking and gesture recognition using @vladmandic/human.
• Backend powered by MySQL for managing lab setups, experiment data, and inventory.
• REST API for communication between the frontend and backend.

---

Technology Stack

• Frontend: React (TypeScript)
• Backend: Python and FastAPI for handling server-side logic, with a MySQL database for storing experiments, substances, and lab configurations.
• Interaction: @vladmandic/human for real-time hand detection and gesture recognition
• REST API: For communication between the frontend and backend

---

Installation

Prerequisites

• Python3
• MySQL

Clone the Repository

git clone https://github.com/JJong84/ALLeX.git
cd ALLeX

Install Dependencies

1. Backend (API server)

python3 -m venv venv
source venv/bin/activate
pip install fastapi uvicorn sqlalchemy pymysql

2. Frontend (React App)

cd web
npm install

Database Setup

1. Set up your MySQL server and create a database for the platform.
2. Import the provided SQL dump file (if applicable) or manually create the necessary tables:
   • labs: Contains lab setup details.
   • experiments: Stores details of experiments performed.
   • substances: Stores different substances used in the experiments.
   • lab_inventory: Manages inventory for each lab.

CREATE DATABASE allex;
USE allex;
-- Create the `labs` table
CREATE TABLE labs (
    id INT AUTO_INCREMENT PRIMARY KEY,
    lab_name VARCHAR(255) NOT NULL,
    goal VARCHAR(255) NULL
);

-- Create the `substances` table
CREATE TABLE substances (
    substance_id INT AUTO_INCREMENT PRIMARY KEY,
    substance_name VARCHAR(255) NOT NULL
);

-- Create the `lab_inventory` table
CREATE TABLE lab_inventory (
    entity_id INT AUTO_INCREMENT PRIMARY KEY,
    lab_id INT,
    substance_id INT,
    x INT,
    y INT,
    case_type VARCHAR(255),
    FOREIGN KEY (lab_id) REFERENCES labs(id) ON DELETE CASCADE,
    FOREIGN KEY (substance_id) REFERENCES substances(substance_id) ON DELETE CASCADE
);

-- Create the `experiments` table
CREATE TABLE experiments (
    substance_id1 INT,
    substance_id2 INT,
    color_change VARCHAR(255),
    explosion TINYINT,
    FOREIGN KEY (substance_id1) REFERENCES substances(substance_id) ON DELETE CASCADE,
    FOREIGN KEY (substance_id2) REFERENCES substances(substance_id) ON DELETE CASCADE
);

3. Update your MySQL credentials in the backend's config.py file:

DB_HOST=localhost
DB_USER=root
DB_PASS=yourpassword
DB_NAME=alex

Start the Backend Server

cd server
uvicorn main:app --reload

Start the Frontend

cd web
npm run dev

---

Usage

1. Ensure your webcam is connected, as the platform uses real-time hand tracking and interaction.
2. Open the app in your browser (usually http://localhost:3000 if running locally).
3. Teachers can create virtual labs and set up experiments, while students can join the lab, perform experiments, and interact with the system via hand gestures.
4. The system allows hand detection, substance movement, and experiment simulation in real time.

---

Project Structure

AllEx/
│
├── server/                # Backend (python, fastapi, MySQL)
│   ├── .gitignore
│   ├── .gitkeep
│   ├── config.py
│   ├── crud.py
│   ├── database.py
│   ├── main.py
│   ├── models.py
│   ├── schemas.py
│   └── routers
│       ├── experiments.py
│       ├── inventory.py
│       ├── labs.py
│       ├── substances.py
│       └── __init__.py    
│
├── web/                   # Frontend (React, TypeScript)
│   ├── public/
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── App.tsx         # Main App component
│   │   └── main.tsx        # Entry point for React app
│   ├── vite.config.ts      # Vite configuration
│   └── index.html          # Main HTML template
│
├── README.md               # Project documentation
└── package.json            # Project metadata and dependencies

---

Contributing

We welcome contributions! To get started:

1. Fork the repository.
2. Create a new feature branch.
3. Commit your changes.
4. Open a pull request.

Please follow our coding standards and ensure your code passes all linting and testing requirements.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---