✂️ Grid Splitter

A premium, high-performance, fully client-side Instagram grid splitter and puzzle maker.
Effortlessly split panoramas, banners, or square images into perfect multi-post grids with real-time scaling, rotation, custom watermark overlays, and automated sequencers.

Live App Domain: gridsplit.ishanoshada.com
GitHub Repository: Ishanoshada/Grid-Splitter
Developer Profile: Ishan Oshada

---

📖 Table of Contents

1. Key Features
2. How It Works & Instagram Upload Order Logic
3. Watermarks & Branding Overlays Engine
4. Tech Stack
5. Getting Started & Local Setup
6. Core Code Architecture
7. Contributing & License

---

✨ Key Features

🎨 Fully Interactive Canvas Workspace

• Precision Controls: Move, zoom, and rotate base photos natively inside a responsive viewport container.
• Aspect Ratio Intelligence: Supports standard Instagram square (1:1), portrait (4:5), and landscape stories (16:9).
• Fit/Fill Shorthands: Instantly snap photos to cover the entire grid aspect ratio or fit inside while filling background padding.

🖼️ Real-Time Multiple Brand/Watermark Overlays

• Interactive Transforms: Drag to place anywhere, drag corner anchor nodes to scale, drag rotation pin (top node) to orient logos perfectly.
• Visual Layer Stack: Rearrange layers backward/forward, adjust rotation angles, or delete specific overlays on the fly.
• Virtual Coordinate Space: Positions and sizes are stored inside a normalized $1000 \times 1000$ coordinate matrix so watermarks render symmetrically regardless of output export resolutions.

🏁 Automatic Grid Upload Sequencing

• Zero Guesswork: Instagram displays grid elements chronologically from left-to-right, wrapping rows upwards. Grid Splitter automatically overlays sequence numbers (#1, #2, etc.) indicating which photo needs to be posted first.
• Toggleable Slices: Exclude specific tiles of the grid to make custom puzzle patterns where background profiles show through.

⚡ Client-Side Sandbox Security

• 100% Offline-Safe: All image processing, canvas cutting, and asset composition happen strictly in-browser via the HTML5 Canvas API. Your files are never uploaded to a server, guaranteeing ultimate security and zero bandwidth cost.
• Batch ZIP Compilation: Packages sliced high-resolution output tiles instantly in a single compressed ZIP using JSZip.

---

📐 How It Works & Instagram Upload Order Logic

When you view an Instagram profile, the photo posts are structured in a grid of 3 columns. The latest post is placed in the top-left, while the oldest post is pushed to the bottom-right.

To make a contiguous multi-post image (e.g., a $3 \times 3$ grid) look correct, you must upload the segmented tiles in reverse-chronological order:

$$\text{Upload Sequence} = (\text{Total Tiles} - \text{Current Index}) + 1$$

Sequence Matrix Illustration ($3 \times 3$ Grid):

┌───────────────┬───────────────┬───────────────┐
│   Post #9     │   Post #8     │   Post #7     │
│  (Top-Left)   │ (Top-Middle)  │ (Top-Right)   │
├───────────────┼───────────────┼───────────────┤
│   Post #6     │   Post #5     │   Post #4     │
│ (Mid-Left)    │ (Mid-Middle)  │ (Mid-Right)   │
├───────────────┼───────────────┼───────────────┤
│   Post #3     │   Post #2     │   Post #1     │
│ (Bot-Left)    │ (Bot-Middle)  │ (Bot-Right)   │
└───────────────┴───────────────┴───────────────┘

Grid Splitter handles this calculation automatically and highlights Post #1 (Bottom-Right) as "Upload First" and Post #9 (Top-Left) as "Upload Last".

---

💎 Watermarks & Branding Overlays Engine

To avoid loss of image fidelity when dragging and rotating watermarks, the app utilizes a dual-coordinate architecture:

1. Virtual Space (0 - 1000): Overlays store their centers $(x, y)$ and sizes $(w, h)$ in a virtual relative square bounds box.
2. High-Res Canvas Drawing: When generating output slices, coordinates are translated linearly to target high-definition output limits (e.g., $1080\text{px}$ or $2160\text{px}$ per tile):

$$X_{\text{canvas}} = X_{\text{virtual}} \times \left( \frac{\text{Grid Output Width}}{1000} \right)$$

This ensures that watermarks preserve exact pixel ratios, vector sharpness, and relative sizing on $4\text{K}$ high-definition image exports.

---

🛠️ Tech Stack

• Frontend Framework: React 18 + TypeScript (Strict Mode)
• Build Bundle Tool: Vite
• Styles & Responsive Design: Tailwind CSS
• Icons: Lucide React
• Zip Archiving Library: JSZip
• Animation System: Framer Motion

---

🚀 Getting Started & Local Setup

Prerequisites

Make sure you have Node.js (v18+) and npm installed.

1. Clone the repository

git clone https://github.com/Ishanoshada/Grid-Splitter.git
cd Grid-Splitter

2. Install dependencies

npm install

3. Start development server

npm run dev

Open http://localhost:3000 in your browser to experience the app.

4. Build for production

npm run build

The compiled files will be located inside the dist/ folder, ready to be hosted on any static file server (Cloud Run, Vercel, Netlify, or custom servers).

---

📂 Core Code Architecture

The codebase is engineered with high modularity and robust separation of concerns:

├── src/
│   ├── components/
│   │   ├── GridSelector.tsx    # Handles col/row configuration, ratio select, fill/fit shortcuts
│   │   ├── ImageAdjuster.tsx   # Fine-tune base image scaling, rotation, pan offsets
│   │   ├── GridPreview.tsx     # Rich, interactive canvas-like visualizer with overlay drag-nodes
│   │   └── ResultGallery.tsx   # Visual grid display of final output tiles with batch zip downloads
│   ├── utils/
│   │   └── slicer.ts           # Math logic, matrix solvers, image canvas cropping, and export generation
│   ├── types.ts                # Strict TypeScript interface declarations for Grid, Transforms, and Overlays
│   ├── App.tsx                 # Core parent coordinator that orchestrates layout, sidebars, and workflow state
│   └── main.tsx                # Client app mounting entrypoint
├── index.html                  # Core HTML file with preloaded SEO metadata and Google site verifications
└── package.json                # Project dependencies and script compilers

---

🤝 Contributing & Support

Contributions are welcome! If you want to add support for custom grid filters, vector text layers, or layout export variations:

1. Fork the project.
2. Create your Feature Branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the Branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

Made with 💖 by Ishan Oshada. Feel free to star the repo if you find this tool helpful!