Skip to content

GEMINI.md

Latest commit

 

History

History
109 lines (89 loc) · 4.46 KB

GEMINI.md

File metadata and controls

109 lines (89 loc) · 4.46 KB
Raw

Compresso Lab - GEMINI Context

Project Overview

Compresso Lab is an interactive, web-based research and design workbench for data compression algorithms. It allows users to visually construct, test, and analyze compression pipelines.

Key Goals:

  • Provide a hands-on environment for learning about compression.
  • Allow experimentation with chaining different algorithms (transformations + compression).
  • Visualize data at the byte level to understand how algorithms affect entropy and structure.
  • Leverage AI (Google Gemini) to analyze data and suggest optimal compression strategies.

Tech Stack

  • Frontend Framework: React 19
  • Build Tool: Vite
  • Language: TypeScript
  • Styling: Tailwind CSS
  • Visualization: Recharts (Charts), Custom Canvas/SVG (Heatmaps)
  • AI Integration: Google Gemini API (@google/genai)

Building and Running

Prerequisites

  • Node.js (LTS recommended)
  • Google Gemini API Key

Setup

  1. Install Dependencies: 
    npm install
  2. Environment Configuration: Create a .env.local file in the root directory: 
    VITE_GEMINI_API_KEY=your_api_key_here

Commands

  • Development Server: 
    npm run dev
    Runs the app at http://localhost:5173.
  • Build for Production: 
    npm run build
    Outputs to dist/.
  • Preview Production Build: 
    npm run preview

Architecture & Code Structure

Directory Structure

  • src/ (Implied root for source)
    • components/: React UI components (e.g., AlgorithmButton, ByteHeatmap, DataInspector).
    • services/: Core business logic and algorithms.
      • compressionAlgorithms.ts: Implementation of all compression and transformation logic (RLE, LZW, Huffman, etc.).
      • analysisUtils.ts: Entropy calculation and frequency analysis.
      • geminiService.ts: Interface with Google Gemini API.
      • imageUtils.ts, dataUtils.ts: Helpers for data manipulation.
    • App.tsx: Main application controller and layout.
    • types.ts: TypeScript definitions for Pipelines, Steps, and Results.
    • constants.tsx: UI constants, icons, and text content.

Core Concepts

  1. Pipeline: A sequence of PipelineSteps. Data flows through these steps sequentially.
  2. Steps: Each step performs an operation (Algorithm) on the data.
    • Compression: Reduces size (e.g., LZW, Huffman).
    • Transformation: Reorders/modifies data to potentially lower entropy (e.g., BWT, MTF, Delta).
    • Lossy: Discards information (e.g., DCT, Quantization).
  3. Execution Model:
    • services/compressionAlgorithms.ts exports executePipeline.
    • It runs the forward pipeline on input data.
    • It immediately attempts to reverse the pipeline to verify integrity (lossless check).
    • It returns a CompressionResult object containing metrics (Size, Entropy, Ratio) for each step.

Key Features & Algorithms

Supported Algorithms

  • Lossless: RLE, LZW, Huffman, Arithmetic Coding.
  • Transformations: Burrows-Wheeler Transform (BWT), Move-to-Front (MTF), Delta Encoding, XOR, PNG Filter.
  • Lossy: DCT (1D), Scalar Quantization, Sub-sampling.
  • Misc: Base64.

Visualization

  • Byte Heatmap: Visual representation of byte values (0-255) as colors.
  • Frequency Charts: Histogram of byte occurrences.
  • Entropy Analysis: Shannon entropy calculation per step.

AI Features

  • Analysis: Generates textual insights on why a pipeline works (or doesn't).
  • Optimization: Suggests pipeline configurations based on input data characteristics.

Development Conventions

  • State: Centralized state in App.tsx passed down via props. Complex state logic (e.g., pipeline execution) is triggered by useEffect on pipeline changes.
  • Styling: Extensive use of Tailwind CSS utility classes directly in JSX. Dark mode theme (slate-950, slate-900) is the default.
  • Type Safety: Strict TypeScript usage. All algorithms accept and return Uint8Array.
  • Performance: Large datasets are handled cautiously. Some algorithms have safety limits (e.g., BWT max 5kb in demo) to prevent main-thread blocking.

Important Files for Context

  • services/compressionAlgorithms.ts: The "brain" of the application.
  • App.tsx: The "body" connecting UI to logic.
  • types.ts: The "skeleton" defining data structures.