Mandelbrot Generator

Professional fractal generator with TypeScript support, interactive web interface, and multiple output formats. Supports Mandelbrot Sets, Julia Sets, and Burning Ship fractals.

📦 Instalacja

Jako pakiet NPM (zalecane)

# Instaluj pakiet globalnie
npm install -g @prachwal/mandelbrot-generator

# Lub dodaj do swojego projektu
npm install @prachwal/mandelbrot-generator

Lokalne uruchomienie

git clone https://github.com/prachwal/mandelbrot-generator.git
cd mandelbrot-generator
npm install

✨ Funkcje

• 🎨 Wieloalgorytmowe generowanie fraktali:
  • 🌀 Mandelbrot Set - Klasyczny zbiór Mandelbrota z konfigurowalnymi parametrami
  • 🌸 Julia Sets - Zbiory Julii z predefiniowanymi presetami (smok, samolot, spirala, etc.)
  • 🔥 Burning Ship - Fraktal "płonący statek" z unikalną formułą abs(z)² + c
• 🔍 Konfigurowalne parametry (rozdzielczość, zakres, iteracje)
• 🌈 Wielokolorowe palety dla wizualizacji
• 💻 Wersja dla Node.js (zapisuje do pliku SVG)
• 🌐 Wersja dla przeglądarki z interaktywnym interfejsem
• ⚡ Optymalizowane obliczenia
• 📚 Pełna dokumentacja TypeScript z JSDoc
• 🏗️ Nowoczesny stack: TypeScript + Vite + Jest
• 📦 Dostępny jako pakiet NPM
• 🔧 Kompletne TypeScript API

🚀 Szybki start

Użyj jako pakiet NPM

# Zainstaluj pakiet
npm install @prachwal/mandelbrot-generator

# Użyj w swoim projekcie
import { generateMandelbrotSVG, defaultConfig } from '@prachwal/mandelbrot-generator';

const svg = generateMandelbrotSVG({
  ...defaultConfig,
  width: 800,
  height: 600,
  colorPalette: 'fire'
});

console.log('Generated SVG:', svg.length, 'characters');

CLI (po instalacji globalnej)

# Instaluj globalnie
npm install -g @prachwal/mandelbrot-generator

# Generuj fractal
mandelbrot-generator --width 1920 --height 1080 --iterations 256

💻 Użycie

NPM Package API

import { 
  generateMandelbrotSVG, 
  saveImageAsSVG,
  defaultConfig,
  interestingPoints,
  type MandelbrotConfig 
} from '@prachwal/mandelbrot-generator';

// Szybkie generowanie Mandelbrota
const svg = generateMandelbrotSVG(defaultConfig);

// Z customową konfiguracją
const config: MandelbrotConfig = {
  width: 1200,
  height: 800,
  maxIterations: 256,
  centerX: -0.7269,
  centerY: 0.1889,
  zoom: 100,
  colorPalette: 'fire'
};

const customSvg = generateMandelbrotSVG(config);

// Zapisz do pliku
const outputPath = saveImageAsSVG(config, 'my-fractal.svg');
console.log(`Saved to: ${outputPath}`);

// Użyj predefiniowanych lokacji
const elephantSvg = generateMandelbrotSVG({
  ...defaultConfig,
  ...interestingPoints.elephant,
  maxIterations: 512
});

Bezpośrednie użycie algorytmów

import { 
  MandelbrotFractal, 
  JuliaFractal, 
  BurningShipFractal,
  fractalEngine 
} from '@prachwal/mandelbrot-generator';

// Użyj konkretnego algorytmu
const mandelbrot = new MandelbrotFractal();
const julia = new JuliaFractal();
const burningShip = new BurningShipFractal();

// Lub użyj FractalEngine do zarządzania algorytmami
const availableAlgorithms = fractalEngine.getAllAlgorithms();
const juliaAlgorithm = fractalEngine.getAlgorithm('julia');

// Generuj z dowolnym algorytmem
const config = julia.defaultConfig;
config.juliaC = JuliaFractal.getPresets().dragon;
const imageData = julia.generateData(config);

Node.js CLI (lokalne uruchomienie)

npm start

Wygeneruje plik mandelbrot.svg w folderze output/.

Uwaga: Wersja Node.js generuje pliki SVG zamiast PNG aby uniknąć problemów z zależnościami systemowymi. SVG oferuje skalowalne grafiki wektorowe idealnie nadające się do wizualizacji fraktali.

Web Interface

Production Test Environment (zalecane)

cd test_web
npm install
npm run serve

Otwórz http://localhost:8080 - czyste środowisko testowe używające biblioteki jako zależności npm.

Development Interface (lokalne uruchomienie)

npm run serve  # uruchamia z głównego folderu

Następnie otwórz http://localhost:8081 w przeglądarce.

Różnice:

• test_web/ - Czyste środowisko używające opublikowanej biblioteki
• web/ - Development interface z mieszanym kodem biblioteki/aplikacji

Dokumentacja

Pełna dokumentacja API jest dostępna w formacie TypeDoc:

# Wygeneruj dokumentację HTML
npm run docs

# Wygeneruj dokumentację Markdown  
npm run docs:update-md

# Uruchom serwer dokumentacji HTML
npm run docs:serve

Dokumentacja obejmuje:

• 📚 API Reference (Markdown) - Dokumentacja w formacie Markdown
• 🌐 API Reference (HTML) - Kompletne API z przykładami
• 📋 Moduły TypeScript - Szczegóły wszystkich modułów
• 🔧 Typy i interfejsy - Definicje typów TypeScript
• ⚡ Funkcje - Szczegółowe opisy funkcji z przykładami

📖 Zobacz dokumentację Markdown | 🌐 Zobacz dokumentację HTML

Testy

# Uruchom wszystkie testy
npm test

# Uruchom testy z pokryciem kodu
npm run test:coverage

# Wygeneruj raport HTML pokrycia
npm run test:coverage-report

Projekt ma 100% pokrycie kodu dla głównego modułu mandelbrot.js.

Konfiguracja

Możesz dostosować parametry generowania z pełnym typowaniem TypeScript:

import { MandelbrotConfig } from './src/types.js';
import { defaultConfig } from './src/config.js';

const config: MandelbrotConfig = {
    ...defaultConfig,
    width: 1920,           // Rozdzielczość X
    height: 1080,          // Rozdzielczość Y
    maxIterations: 256,    // Maksymalne iteracje
    zoom: 100,             // Poziom powiększenia
    centerX: -0.7269,      // Centrum X (rzeczywiste)
    centerY: 0.1889,       // Centrum Y (urojone)
    colorPalette: 'fire'   // Paleta kolorów
};

Dostępne palety kolorów

• rainbow - 🌈 Kolorowa tęcza (domyślna)
• fire - 🔥 Ogień (czerwień, pomarańcz, żółć)
• cool - ❄️ Chłodne (niebieskie, zielone)
• classic - ⚫ Klasyczne (czarno-białe)
• hot - 🌋 Gorące (intensywne czerwienie)
• electric - ⚡ Elektryczne (neonowe)
• ocean - 🌊 Ocean (głębokie niebieskie)
• sunset - 🌅 Zachód słońca (ciepłe kolory)

🧮 Dostępne algorytmy fraktali

🌀 Mandelbrot Set

Klasyczny zbiór Mandelbrota z formułą z_{n+1} = z_n² + c, gdzie z_0 = 0.

import { MandelbrotFractal } from '@prachwal/mandelbrot-generator';

const mandelbrot = new MandelbrotFractal();
const config = mandelbrot.defaultConfig;
const imageData = mandelbrot.generateData(config);

🌸 Julia Sets

Zbiory Julii z formułą z_{n+1} = z_n² + c, gdzie z_0 = point i c jest stałą.

import { JuliaFractal } from '@prachwal/mandelbrot-generator';

const julia = new JuliaFractal();

// Użyj predefiniowanego presetu
const presets = JuliaFractal.getPresets();
const config = {
  ...julia.defaultConfig,
  juliaC: presets.dragon  // { real: -0.7269, imag: 0.1889 }
};

const imageData = julia.generateData(config);

Dostępne presety Julia Sets:

• dragon - Smok Julia (-0.7269, 0.1889)
• airplane - Samolot (-0.75, 0.11)
• spiral - Spirala (-0.4, 0.6)
• dendrite - Dendryt (0, 1)
• rabbit - Królik (-0.123, 0.745)

🔥 Burning Ship

Fraktal "płonący statek" z formułą z_{n+1} = (abs(z.real) + i*abs(z.imag))² + c.

import { BurningShipFractal } from '@prachwal/mandelbrot-generator';

const burningShip = new BurningShipFractal();
const config = {
  ...burningShip.defaultConfig,
  centerX: -0.5,
  centerY: -0.6,
  colorPalette: 'fire'
};

const imageData = burningShip.generateData(config);

Przykłady

Klasyczny widok Mandelbrota

import { generateMandelbrotData } from './src/mandelbrot.js';

const config: MandelbrotConfig = {
    width: 800,
    height: 600,
    maxIterations: 100,
    escapeRadius: 2,
    zoom: 1,
    centerX: -0.5,
    centerY: 0,
    colorPalette: 'rainbow'
};

const imageData = generateMandelbrotData(config);

Julia Sets z predefiniowanymi presetami

import { JuliaFractal } from '@prachwal/mandelbrot-generator';

const julia = new JuliaFractal();
const presets = JuliaFractal.getPresets();

// Smok Julia
const dragonConfig = {
    ...julia.defaultConfig,
    juliaC: presets.dragon,
    maxIterations: 256,
    colorPalette: 'fire'
};

// Samolot Julia
const airplaneConfig = {
    ...julia.defaultConfig,
    juliaC: presets.airplane,
    maxIterations: 512,
    colorPalette: 'cool'
};

const dragonData = julia.generateData(dragonConfig);
const airplaneData = julia.generateData(airplaneConfig);

Burning Ship fractal

import { BurningShipFractal } from '@prachwal/mandelbrot-generator';

const burningShip = new BurningShipFractal();
const config = {
    ...burningShip.defaultConfig,
    width: 1200,
    height: 800,
    centerX: -0.5,
    centerY: -0.6,
    zoom: 2,
    maxIterations: 200,
    colorPalette: 'fire'
};

const imageData = burningShip.generateData(config);

Porównanie wszystkich algorytmów

import { fractalEngine } from '@prachwal/mandelbrot-generator';

const algorithms = fractalEngine.getAllAlgorithms();
const baseConfig = {
    width: 400,
    height: 400,
    maxIterations: 100,
    colorPalette: 'rainbow'
};

// Generuj ten sam obszar różnymi algorytmami
algorithms.forEach(algo => {
    const config = { ...algo.defaultConfig, ...baseConfig };
    const imageData = algo.generateData(config);
    console.log(`Generated ${algo.name} fractal`);
});

Eksploracja interesujących miejsc

import { interestingPoints } from './src/config.js';

// Dolina słoni - słynne miejsce w zbiorze Mandelbrota
const elephantConfig: MandelbrotConfig = {
    ...defaultConfig,
    ...interestingPoints.elephant,
    maxIterations: 256,
    colorPalette: 'fire'
};

// Wzory koników morskich
const seahorseConfig: MandelbrotConfig = {
    ...defaultConfig,
    ...interestingPoints.seahorse,
    maxIterations: 512,
    colorPalette: 'ocean'
};

Wysoka rozdzielczość z optymalizacją

import { generateMandelbrotDataOptimized } from './src/mandelbrot.js';

const hiResConfig: MandelbrotConfig = {
    width: 3840,
    height: 2160,
    maxIterations: 1000,
    zoom: 1000,
    centerX: -0.7269,
    centerY: 0.1889,
    colorPalette: 'electric'
};

// Użyj wersji zoptymalizowanej dla dużych obrazów
const imageData = await generateMandelbrotDataOptimized(hiResConfig, 8);

Struktura projektu

mandelbrot-generator/
├── src/                  # Kod źródłowy TypeScript
│   ├── index.ts          # Główny plik dla Node.js
│   ├── mandelbrot.ts     # Algorytmy Mandelbrota
│   ├── config.ts         # Konfiguracja i ciekawe punkty
│   ├── colors.ts         # Palety kolorów
│   └── types.ts          # Definicje typów TypeScript
├── web/                  # Interfejs webowy
│   ├── docs/             # Dokumentacja TypeDoc
│   ├── index.html        # Strona główna
│   ├── main.js           # Kod JavaScript dla przeglądarki
│   └── style.css         # Stylowanie
├── tests/                # Testy jednostkowe
│   └── mandelbrot.test.ts
├── dist/                 # Skompilowany kod TypeScript
├── coverage/             # Raporty pokrycia testów
├── output/               # Wygenerowane fraktale (SVG)
├── package.json          # Konfiguracja NPM
├── tsconfig.json         # Konfiguracja TypeScript
├── vite.config.js        # Konfiguracja Vite
├── typedoc.json          # Konfiguracja dokumentacji
└── README.md             # Ten plik

Rozwój projektu

Wymagania

• Node.js 18+
• TypeScript 5.2+
• Vite 7.0+

Skrypty deweloperskie

# Budowanie
npm run build              # Kompiluj TypeScript
npm run build:watch        # Kompiluj z obserwowaniem
npm run build:web          # Buduj dla web

# Rozwój
npm run dev                # Serwer dev Vite
npm run dev:watch          # TypeScript + Vite równolegle

# Testowanie  
npm run test               # Uruchom testy
npm run test:watch         # Testy z obserwowaniem
npm run test:coverage      # Pokrycie kodu

# Dokumentacja
npm run docs               # Wygeneruj dokumentację
npm run docs:serve         # Serwuj dokumentację
npm run docs:watch         # Dokumentacja z obserwowaniem

# Inne
npm run clean              # Wyczyść wszystkie pliki build
npm run examples           # Uruchom przykłady
npm run publish:npm        # 🚀 Opublikuj do NPM (jedno polecenie!)

🚀 Publikacja do NPM

Jedno polecenie do publikacji:

npm run publish:npm

To polecenie automatycznie:

1. ✅ Czyści poprzednie buildy (npm run clean)
2. ✅ Kompiluje TypeScript (npm run build)
3. ✅ Uruchamia wszystkie testy (npm test)
4. ✅ Generuje dokumentację (npm run docs)
5. ✅ Publikuje pakiet (npm publish --access public)

Wymagania przed publikacją:

• Zalogowany do NPM: npm login
• Uprawnienia do @prachwal scope
• Wersja w package.json zaktualizowana

Technologie

Ten projekt wykorzystuje nowoczesny stack technologiczny:

Core

• TypeScript 5.2+ - Typowanie statyczne i nowoczesny JavaScript
• Node.js 18+ - Runtime JavaScript po stronie serwera
• ES Modules - Nowoczesny system modułów

Development

• Vite 7.0+ - Szybki bundler i dev server
• Jest 29.7+ - Framework testowy
• c8 - Pokrycie kodu dla Node.js
• Concurrently - Równoległe uruchamianie skryptów

Documentation

• TypeDoc - Generator dokumentacji z TypeScript/JSDoc
• JSDoc - Komentarze dokumentacyjne

Quality

• 100% Test Coverage - Kompletne pokrycie testami
• Strict TypeScript - Ścisłe typowanie
• ESLint Ready - Gotowe do lintingu kodu

API Reference

Główne funkcje

| Funkcja | Opis | Moduł | |---------|------|-------| | generateMandelbrotData() | Generuje dane obrazu fraktala | mandelbrot.ts | | mandelbrotIteration() | Oblicza iteracje dla punktu | mandelbrot.ts | | getColor() | Mapuje iteracje na kolor | colors.ts | | calculateBounds() | Oblicza granice płaszczyzny | config.ts |

Typy TypeScript

| Typ | Opis | Plik | |-----|------|------| | MandelbrotConfig | Konfiguracja generowania | types.ts | | RGBColor | Kolor RGB jako tupla | types.ts | | PaletteType | Typ palety kolorów | types.ts | | FractalBounds | Granice płaszczyzny zespolonej | types.ts |

📖 Pełna dokumentacja API (Markdown) | 🌐 Dokumentacja HTML

📦 NPM Package

Zainstaluj: npm install @prachwal/mandelbrot-generator

• 📋 NPM Registry - Oficjalna strona pakietu
• 📚 API Docs (Markdown) - Dokumentacja w formacie Markdown
• 📊 Bundle Size - Analiza rozmiaru pakietu
• 🔍 Dependencies - Graf zależności
• 📈 Downloads - Statystyki pobrań

Dostępne eksporty

// Główne funkcje generowania (legacy API - tylko Mandelbrot)
import { 
  generateMandelbrotSVG,     // Generuj SVG jako string
  saveImageAsSVG,            // Zapisz SVG do pliku
  generateMandelbrotData,    // Generuj raw data
  mandelbrotIteration        // Oblicz iteracje dla punktu
} from '@prachwal/mandelbrot-generator';

// Nowoczesne algorytmy fraktali (zalecane)
import {
  MandelbrotFractal,         // Klasa algorytmu Mandelbrota
  JuliaFractal,              // Klasa algorytmu Julia Sets
  BurningShipFractal,        // Klasa algorytmu Burning Ship
  fractalEngine              // Engine do zarządzania algorytmami
} from '@prachwal/mandelbrot-generator';

// Konfiguracja i kolory  
import { 
  defaultConfig,             // Domyślna konfiguracja
  interestingPoints,         // Predefiniowane lokacje
  colorPalettes,             // Dostępne palety
  calculateBounds            // Oblicz granice płaszczyzny
} from '@prachwal/mandelbrot-generator';

// Funkcje kolorów
import { 
  getColor,                  // RGB dla iteracji
  rgbToHex,                  // RGB → Hex
  getColorHex                // Hex dla iteracji
} from '@prachwal/mandelbrot-generator';

// Typy TypeScript
import type { 
  MandelbrotConfig,          // Legacy config (używaj FractalConfig)
  FractalConfig,             // Nowa uniwersalna konfiguracja
  PaletteType,               // Typ palety  
  RGBColor,                  // Kolor RGB
  Complex,                   // Liczba zespolona
  FractalResult              // Wynik iteracji fraktala
} from '@prachwal/mandelbrot-generator';

Licencja

MIT License - Zobacz LICENSE dla szczegółów.

Autor

Stworzony przez Prachwal - Generator fraktala Mandelbrota w TypeScript.

⬆️ Na górę | 📖 Dokumentacja | 🧪 Testy | ⚙️ Konfiguracja