🌲 Acuity — Neural Detail Reconstruction Suite

Acuity is a state-of-the-art web application that leverages Topaz Labs' advanced image upscaling models (via Replicate) to reconstruct and enhance low-resolution images. Designed with a premium, high-contrast, black-and-cream editorial aesthetic, it delivers a stunning cinematic experience for photographers, designers, and creators who need ultra-high-resolution (up to 6K) detail enhancement.

---

✨ Features & Highlights

🎬 Cinematic Landing Page & Interactive Foliage

• Editorial Redesign: Minimalist, high-contrast aesthetic inspired by the Siena Film Foundation. Built using beautiful serif typography (Cormorant Garamond).
• Scroll-Driven Deblur: Background cover shifts smoothly from blurred to crisp as you scroll down, creating a beautiful depth of field reveal.
• LeafVines Particle Physics: Interactive Canvas system that renders floating leaves and vines. Leaves respond dynamically to cursor proximity, deflecting away when hovered and floating back naturally.

🍃 Nature-Breathable Environmental Gallery

• Dynamic Before/After Slider: Users can interactively compare low-resolution previews against upscaled versions of natural scenery:
  • Amazon Rainforest Canopy: Reconstructing intricate leaf venations.
  • Shoreline Waves: Enhancing micro-foam and ocean ripples.
  • Misty Pine Forest: Revealing individual pine needles amidst soft gradients.

🔒 Dual-Tier Resolution Enforcement

Acuity features a solid two-tier monetization and validation architecture:

• Starter Pack ($9 for 30 credits): Unlocks Standard upscaling (2x & 4x) up to 4K resolution with face enhancement.
• Pro Pack ($25 for 100 credits): Unlocks the highest fidelity 6x upscaling (6K resolution) with priority processing and advanced denoising.
• Guardrails: Full end-to-end security checking. The frontend dynamically styles the 6x selector with locks and PRO badges for non-pro accounts, and the server-side API validates requests to block 6x generation attempts for non-pro users with 403 Forbidden responses.

⚡ CORS-Safe Direct Downloads

• Downloads utilize a custom server-side proxy route (/api/download) which pulls the finished asset from CDN and serves it as a direct attachment file, completely bypassing standard browser CORS blockages.

🕶️ 3D Gaussian Splatting Sandbox

• Drone Video-to-3D Reconstruction: Upload drone flights or handheld video scans (MP4/MOV) to simulate photorealistic 3DGS reconstructions (deducts 20 credits).
• Real-time WebGL Splat Renderer: An interactive rendering engine built using @react-three/fiber and @react-three/drei's <Splat /> component to project and depth-sort millions of interactive, color-tinted 3D ellipsoids at 60 FPS.
• Preset Volumetric Explorer: Includes instant sandbox access to multiple outdoor pathways, forests, indoor bedrooms, and high-fidelity product models (ranging from 8MB to 187MB).
• Precise Transformation Control: Real-time canvas control panel offering adjustable scales, translations (X, Y, Z offsets), 3-axis rotation sliders, and toggleable auto-rotation (yaw).
• Stream-Based Loader & Cache: Uses high-performance fetch streams to calculate exact file download percentages, caching results locally as a blob: URL to prevent duplicate network calls.

---

🛠️ Tech Stack & Architecture

• Framework: Next.js 16 (App Router & Turbopack)
• Database & Auth: Firebase (Authentication + Firestore real-time status subscription)
• Payment Processing: Stripe Checkout + Webhook integration
• File Uploads: Uploadthing CDN
• AI Processing: Topaz Labs' Image Upscale on Replicate API
• Styling: Tailwind CSS + Vanilla CSS custom animations

---

🚀 Local Setup & Installation

1. Clone the repository

git clone https://github.com/Luciferjimmy/acuity.git
cd acuity

2. Install dependencies

npm install

3. Setup environment variables

Create a .env.local file in the root of the project and populate the following keys:

# Next.js Public
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Firebase Client Keys
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

# Firebase Admin Service Credentials (Private Key newlines must be parsed \n)
FIREBASE_PROJECT_ID=your_project_id
FIREBASE_CLIENT_EMAIL=your_firebase_admin_email
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkq...your_private_key...\n-----END PRIVATE KEY-----\n"

# Replicate API
REPLICATE_API_TOKEN=r8_your_replicate_token

# Uploadthing Credentials
UPLOADTHING_TOKEN=your_uploadthing_token

# Stripe Billing Keys
STRIPE_SECRET_KEY=sk_test_your_secret_key
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_publishable_key
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_signing_secret

4. Run the development server

npm run dev

Open http://localhost:3000 to view it in your browser.

---

📦 Webhook Testing with Stripe CLI

To test credit updates on your local machine, run the Stripe CLI forwarder:

stripe login
stripe listen --forward-to localhost:3000/api/webhooks/stripe

Copy the webhook signing secret returned by Stripe (starts with whsec_) and save it to your STRIPE_WEBHOOK_SECRET environment variable, then restart your Next.js server.