🔮 HARRY POTTER CHARACTER GALAXY 🌌

⚡ AI-Powered Natural Language Processing & 3D Interactive Spatial Vector Map

---

📖 Project Overview

Harry Potter Character Galaxy is a high-fidelity, interactive 3D WebGL visualization platform that maps the semantic and emotional relationships of characters in the Harry Potter universe.

By analyzing thousands of dialogue lines from the complete script corpus of the wizarding world using Advanced Natural Language Processing (NLP), the platform positions characters in a 3D vector space where physical proximity represents speech similarity, vocabulary patterns, and emotional traits.

🌟 "Words are, in my not-so-humble opinion, our most inexhaustible source of magic. Capable of both inflicting injury, and remedying it." — Albus Dumbledore

---

🚀 Magical Features

🧙‍♂️ 1. The AI Sorting Hat & 3D Projector

• Dialogue Vectorization: Paste your own dialogues, lines, or speech traits. The NLP backend uses character-level N-gram TF-IDF vectorization to convert your speech patterns into mathematical coordinates.
• Hogwarts House Sorting: Computes real-time cosine similarity against average House speech centroids, yielding a percentage-based House affinity distribution.
• 3D Node Projection: Reruns a transductive t-SNE algorithm to project your custom node (labeled "YOU") directly into the 3D starfield, establishing connections to closest matches.
• Storage Persistence: Uses localStorage to save your custom avatar node, keeping it alive in the galaxy even across browser page reloads!

⚔️ 2. Turn-Based Wand Duel Mini-Game

• Playable Duel Arena: Swap between stats analysis and turn-based wand dueling modes inside the modal.
• Wand Combats: Play as your selected wizard and cast spells with unique base damage, hit rates, and special traits.
• AI Duelist Intel: The opponent wizard responds with counter-spells dynamically calculated based on their core house personality traits.
• Web Audio Sound Effects: Retro-style synthesized wave chimes and pitch sweeps custom-built for spell casts:
  • 🔴 Expelliarmus (Sine wave exponential pitch bend)
  • 🟡 Stupefy (Bandpassed white-noise burst + triangle frequency drop)
  • 🔵 Protego (Feedback swell for shielding)
  • 🟢 Avada Kedavra (Descending sawtooth wave with low-pass filters)

📡 3. 3D Neural Constellations & Holographic HUD

• Dynamic Grid Cage: Structured holographic grid planes (XZ floor projection, back XY, and left YZ boundaries) representing latent dimension limits.
• Interactive Node Telemetry: Selecting or hovering nodes highlights vertical dashed projection lines and pulses circular floor targeting rings.
• Data Transmission Pulses: Glowing data packets move along neural constellations when character similarity exceeds the optimized threshold (0.38).

---

📜 The Magical Spellbook

Here are the spells available in the Wand Duel Arena:

Spell Symbol	Action Name	Base Damage	Success Rate	Special Effect	Sound Signature
🔴	Expelliarmus	12 - 18	88%	Disarm target, low damage	High-frequency pitch bend
🟡	Stupefy	22 - 35	68%	Medium damage stun	Noise burst + frequency drop
🔵	Protego	0	100%	Absorbs 80% of next attack	High-pass sine wave swell
🟢	Avada Kedavra	60	30%	Extreme damage (Dark wizards only)	Descending low-pass sawtooth

---

📂 System Architecture

graph TD
    A[Dialogue Scripts CSV] --> B[NLP Text Preprocessing]
    B --> C[TF-IDF N-gram Feature Extraction]
    C --> D[Cosine Similarity Calculation]
    D --> E[t-SNE Dimensionality Reduction]
    E --> F[3D Coordinate Mapping X, Y, Z]
    F --> G[React Three Fiber Canvas]
    G --> H[Interactive Space Grid & Projector HUD]

Loading

---

🛠️ Technology Stack

• Frontend: React (Vite), React Three Fiber, Three.js, @react-three/drei (3D billboard lines), Framer Motion, React Icons.
• Styling: Tailwind CSS v4, custom glassmorphism effects, radial background stars.
• Backend: FastAPI (Python), Uvicorn.
• NLP Pipeline: Scikit-Learn (TF-IDF Vectorizer, MinMaxScaler), NumPy, Pandas, TextBlob.

---

📥 Installation & Local Setup

1. Clone the Repository

git clone https://github.com/khushalkks/Harry_Porter.git
cd Harry_Porter

2. Run Backend (FastAPI API Server)

cd backend
python -m venv venv

# Activate Virtual Environment:
# On Windows PowerShell:
.\venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

pip install -r requirements.txt
python -m uvicorn app.main:app --reload

The API server will launch at http://localhost:8000.

3. Run Frontend (React Vite Server)

cd ../frontend
npm install
npm run dev

Open http://localhost:5173 in your browser.

---

📖 NLP Vector Space Methodology

1. Dialogue Accumulation: Dialogues are consolidated, cleaned, and lower-cased, striping punctuation.
2. N-gram Vectorizer: Extracts character-level lexical patterns (ngram_range=(2, 4)) into a 500-dimensional matrix, preserving speech characteristics.
3. Similarity Analysis: Cosine Distance matrices verify relationship strengths.
4. Coordinate Manifold: t-SNE projection maps the high-dimensional vectors into three physical coordinates (x, y, z) scaled dynamically inside grid boundaries.

---

Developed with ⚡ and Magic for the Wizarding World.