szafir-utils

/**

• @fileoverview README dla biblioteki szafir-utils */

🎨 Szafir Utils

Biblioteka narzędzi i komponentów dla aplikacji Vite + Preact z zaawansowanymi funkcjami generowania fraktali.

📦 Instalacja

npm install szafir-utils

🚀 Szybki start

Generator fraktala Mandelbrot (JavaScript/TypeScript)

import {
  generateMandelbrot,
  DEFAULT_MANDELBROT_CONFIG,
} from "szafir-utils/fractals";

// Wygeneruj fraktal
const config = {
  ...DEFAULT_MANDELBROT_CONFIG,
  width: 800,
  height: 600,
  maxIterations: 100,
};

const result = generateMandelbrot(config, (progress) => {
  console.log(`Postęp: ${Math.round(progress * 100)}%`);
});

console.log(`Wygenerowano w ${result.generationTime}ms`);
console.log(`Punktów w zbiorze: ${result.stats.pointsInSet}`);

Komponenty Preact

import { MandelbrotViewer } from "szafir-utils/components";

function App() {
  return (
    <div>
      <h1>Fraktal Mandelbrot</h1>
      <MandelbrotViewer
        width={800}
        height={600}
        maxIterations={200}
        showControls={true}
        onGenerated={(result) => {
          console.log("Fraktal wygenerowany!", result);
        }}
      />
    </div>
  );
}

🔧 API

Fractals Module

generateMandelbrot(config, onProgress?)

Generuje fraktal Mandelbrot z zadaną konfiguracją.

Parametry:

• config: FractalConfig - konfiguracja fraktala
• onProgress?: (progress: number) => void - callback postępu (0-1)

Zwraca: FractalResult

generateJulia(config, onProgress?)

Generuje fraktal Julia.

Parametry:

• config: JuliaConfig - konfiguracja z parametrem juliaC
• onProgress?: (progress: number) => void - callback postępu

Zwraca: FractalResult

renderToCanvas(result, canvas, options?)

Renderuje wynik fraktala na HTML Canvas.

Parametry:

• result: FractalResult - wynik generacji fraktala
• canvas: HTMLCanvasElement - element canvas
• options?: RenderOptions - opcje renderowania

Complex Numbers Operations

import { complex, add, multiply, square, modulus } from "szafir-utils/fractals";

const c1 = complex(3, 4); // 3 + 4i
const c2 = complex(1, 2); // 1 + 2i

const sum = add(c1, c2); // 4 + 6i
const product = multiply(c1, c2); // -5 + 10i
const squared = square(c1); // -7 + 24i
const magnitude = modulus(c1); // 5

Components Module

<MandelbrotViewer>

Zaawansowany komponent do wyświetlania fraktala Mandelbrot z kontrolkami.

Props:

• width?: number - szerokość (domyślnie 800)
• height?: number - wysokość (domyślnie 600)
• maxIterations?: number - maksymalne iteracje (domyślnie 100)
• showControls?: boolean - pokazuj kontrolki (domyślnie true)
• onGenerated?: (result) => void - callback po generacji
• onProgress?: (progress) => void - callback postępu

<JuliaViewer>

Komponent do wyświetlania fraktali Julia z predefiniowanymi presetami.

Props:

• width?: number
• height?: number
• maxIterations?: number
• juliaC?: ComplexNumber - parametr C
• showControls?: boolean

<FractalCanvas>

Uniwersalny komponent canvas do wyświetlania fraktali.

🎨 Palety kolorów

import { COLOR_PALETTES, renderToCanvas } from "szafir-utils/fractals";

const renderOptions = {
  colorPalette: COLOR_PALETTES.FIRE, // CLASSIC, FIRE, OCEAN, RAINBOW, PURPLE, MONOCHROME
  colorMode: "smooth", // 'iterations', 'smooth', 'binary'
  brightness: 1.2,
  contrast: 1.0,
};

renderToCanvas(fractalResult, canvas, renderOptions);

🔬 Presety Julia

import { JULIA_PRESETS, generateJulia } from "szafir-utils/fractals";

// Użyj predefiniowanego presetu
const config = {
  width: 800,
  height: 600,
  maxIterations: 100,
  juliaC: JULIA_PRESETS.DRAGON, // DRAGON, SPIRAL, TREE, SYMMETRIC, DENDRITE, CLASSIC
};

const result = generateJulia(config);

⚡ Optymalizacja

Fragmenty (chunks) dla dużych fraktali

import { generateMandelbrotChunk } from "szafir-utils/fractals";

const config = { width: 1920, height: 1080, maxIterations: 500 };

// Generuj w fragmentach dla lepszej wydajności
const chunks = [];
const chunkHeight = 100;

for (let y = 0; y < config.height; y += chunkHeight) {
  const endY = Math.min(y + chunkHeight, config.height);
  const chunk = generateMandelbrotChunk(config, y, endY);
  chunks.push(chunk);
}

Web Workers (planowane)

// Przyszłe API - generacja w Web Worker
const result = await generateMandelbrotAsync(config);

🧪 Przykłady użycia

Interaktywny eksplorator Mandelbrot

import { useState } from "preact/hooks";
import { MandelbrotViewer } from "szafir-utils/components";

function FractalExplorer() {
  const [iterations, setIterations] = useState(100);

  return (
    <div>
      <div>
        <label>Iteracje: {iterations}</label>
        <input
          type="range"
          min="10"
          max="1000"
          value={iterations}
          onChange={(e) => setIterations(parseInt(e.target.value))}
        />
      </div>

      <MandelbrotViewer
        width={1024}
        height={768}
        maxIterations={iterations}
        showControls={true}
        onProgress={(progress) => {
          document.title = `Generowanie... ${Math.round(progress * 100)}%`;
        }}
        onGenerated={(result) => {
          document.title = `Fraktal - ${result.generationTime.toFixed(0)}ms`;
        }}
      />
    </div>
  );
}

Export do obrazu

import { generateMandelbrot, toImageDataUrl } from "szafir-utils/fractals";

const result = generateMandelbrot({
  width: 1920,
  height: 1080,
  maxIterations: 500,
  minReal: -2.5,
  maxReal: 1.0,
  minImaginary: -1.25,
  maxImaginary: 1.25,
});

// Export jako Data URL
const imageUrl = toImageDataUrl(result, {
  colorPalette: ["#000000", "#ff0000", "#ffff00", "#ffffff"],
  colorMode: "smooth",
  brightness: 1.3,
});

// Użyj w img lub pobierz
const link = document.createElement("a");
link.download = "mandelbrot.png";
link.href = imageUrl;
link.click();

📊 TypeScript

Pełne wsparcie TypeScript z dokładnymi definicjami typów:

import type {
  FractalConfig,
  FractalResult,
  ComplexNumber,
  RenderOptions,
} from "szafir-utils/fractals";

const config: FractalConfig = {
  width: 800,
  height: 600,
  maxIterations: 100,
  minReal: -2.0,
  maxReal: 2.0,
  minImaginary: -2.0,
  maxImaginary: 2.0,
  escapeRadius: 4.0,
};

🤝 Współpraca

git clone https://github.com/szafir-team/szafir-utils.git
cd szafir-utils
npm install
npm run dev     # development build
npm run build   # production build
npm run test    # run tests

📄 Licencja

MIT © Szafir Team

🔗 Linki

• GitHub Repository
• NPM Package
• Documentation
• Examples