FractalityLab

High-throughput fractal image dataset generator for machine learning

FractalityLab generates labeled fractal image datasets with automatic train/test splits and CSV metadata — ready for ml training, image classification benchmarks, and generative model experiments. Part of the EDUX ML library suite.

Getting Started · Gallery · CLI Reference · Architecture · Contributing

---

Highlights

• 30 fractal generators across 5 categories — escape-time, IFS, L-system curves, strange attractors, and more
• ML-ready output — labeled directories with train/test splits and RFC 4180 CSV metadata
• Virtual Thread parallelism — concurrent image generation with IntStream.parallel() pixel rendering
• Quality control — configurable Gaussian blur, noise injection, and random rotation for data augmentation
• Zero dependencies at runtime (except commons-math3) — pure Java 25, single fat JAR

---

Quickstart

git clone https://github.com/Samyssmile/FractalityLab.git && cd FractalityLab
./gradlew jar
java -jar FractalityLab-1.4.jar --numberPerClass 100 --resolution 256 --quality 80

This generates 100 images per fractal class at 256x256 pixels with 80% quality into dataset/train/ and dataset/test/.

Want only specific fractals? Use --generators:

java -jar FractalityLab-1.4.jar --numberPerClass 200 --resolution 512 --generators mandelbrot,julia,burningship

See CLI Reference for all options.

---

Fractal Gallery

All 30 generators, one example each at 512x512 pixels.

Escape-Time Fractals

Mandelbrot z = z² + c	Julia Fixed complex c-parameter	Burning Ship Absolute-value variant	Tricorn Complex conjugate (Mandelbar)
Multibrot z^d + c (d = 3–6)	Phoenix Memory-based iteration	Celtic |Re(z²)| variant	Buffalo Abs-variant with horns
Perpendicular Cross-term variant	Magnet Type I Rational quadratic map	Magnet Type II Cubic numerator/denominator	Newton Newton's method on z³ - 1
Collatz Complex Collatz conjecture	Lyapunov Logistic map exponent	Buddhabrot Escaping trajectory density

Iterated Function Systems (IFS)

Sierpinski Gasket Triangular subdivision	Sierpinski Carpet Square subdivision	Barnsley Fern 4 affine transforms	Pythagoras Tree Hypotenuse branching
Vicsek Plus-shaped recursion	T-Square Overlapping corner squares	Koch Snowflake Recursive edge spikes	Apollonian Gasket Descartes circle packing

L-System Curves

Dragon Curve 90° turn space-filling

Levy C Curve 45° self-similar

Hilbert Curve Grid space-filling

Gosper Curve Hexagonal flowsnake

Strange Attractors

Clifford sin/cos 4-parameter

De Jong sin/cos attractor

Henon Map 1 - ax² + y, bx

---

Getting Started

Prerequisites

• JDK 25+ (Eclipse Adoptium or any OpenJDK distribution)

Quick Start

# Clone
git clone https://github.com/Samyssmile/FractalityLab.git
cd FractalityLab

# Build
./gradlew build

# Generate 100 images per class at 256x256
./gradlew run --args="--numberPerClass 100 --resolution 256 --quality 80"

Fat JAR

./gradlew jar
java -jar FractalityLab-1.4.jar \
  --numberPerClass 500 --resolution 512 --quality 90 --trainTestRatio 0.80

---

CLI Reference

java -jar FractalityLab.jar [OPTIONS]

Flag	Short	Description	Default
--numberPerClass <n>	-n	Images per fractal class	100
--resolution <n>	-s	Image resolution in pixels (width = height)	256
--quality <0-100>	-q	Image quality (0 = heavily degraded, 100 = pristine)	80
--maxIterations <n>	-i	Base iteration depth for fractal algorithms	18
--trainTestRatio <r>	-r	Fraction of images in the training set (0.0–1.0)	0.8
--output <dir>	-o	Output directory	dataset
--generators <list>	-g	Comma-separated generator labels (see below)	all
--help	-h	Show help and exit	—
--version		Show version and exit	—

Generator Labels

mandelbrot  julia        burningship    tricorn       sierpinski      newton
multibrot   phoenix      magnettypeone  magnettypetwo celtic          buffalo
perpendicular collatz    lyapunov       buddhabrot    sierpinskicarpet barnsleyfern
pythagorastree vicsek   tsquare        kochsnowflake apollonian      dragoncurve
levycurve   hilbertcurve gospercurve    clifford      dejong          henon

Examples

# Generate only escape-time fractals
java -jar FractalityLab.jar --generators mandelbrot,julia,burningship --numberPerClass 200 --resolution 512

# High-resolution dataset with maximum quality
java -jar FractalityLab.jar --numberPerClass 50 --resolution 1024 --quality 100 --maxIterations 200

# Custom output directory with 90/10 train-test split
java -jar FractalityLab.jar --output my-dataset --trainTestRatio 0.90

---

Output Structure

dataset/                        (or custom via --output)
├── train/
│   ├── mandelbrot/
│   │   ├── 0001.png
│   │   ├── 0002.png
│   │   └── ...
│   ├── julia/
│   ├── burningship/
│   ├── ... (one folder per generator)
│   └── images.csv              ← RFC 4180 metadata
└── test/
    ├── (same structure)
    └── images.csv

Each images.csv contains columns for file path and class label — ready for direct ingestion by PyTorch ImageFolder, TensorFlow image_dataset_from_directory, or any CSV-based data loader.

---

Architecture

de.fractalitylab
├── cli/                    CLI parsing, ANSI colors
├── config/                 Immutable Configuration record
├── generators/             FractalGenerator interface + 30 implementations
│   ├── FractalRegistry     Central generator registry
│   ├── FractalMetadata     Generator metadata record
│   └── Complex             Complex number record
├── processing/             QualityProcessor (blur, noise, rotation)
├── data/                   ImageWriter, CSVWriter, DataElement
└── FractalOrchestrator     Virtual Thread orchestration + progress tracking

Design Principles

• Strategy Pattern — each generator implements FractalGenerator with generate(), label(), and metadata()
• Immutable Data — Java records for Configuration, FractalMetadata, Complex, DataElement
• Thread Safety — CopyOnWriteArrayList for result collection, ThreadLocalRandom for randomness, no shared mutable state
• Parallel Rendering — IntStream.parallel() for pixel-level computation, Virtual Threads for image-level I/O

Adding a New Generator

1. Create a class implementing FractalGenerator with generate(), label(), and metadata()
2. Add one line in FractalRegistry.GENERATORS
3. (Optional) Add a test — FractalGeneratorContractTest picks it up automatically

---

Performance

Layer	Strategy	Rationale
Pixel rendering	IntStream.parallel() (ForkJoinPool)	CPU-bound, benefits from work-stealing
Image orchestration	Virtual Threads	I/O-bound (file writes), lightweight concurrency
Quality processing	Batch pixel access	Minimizes BufferedImage lock overhead
Result collection	CopyOnWriteArrayList	Safe concurrent writes, read-once at end

---

Pre-Generated Dataset

A ready-to-use labeled dataset containing 60,000 fractal images across all 30 generator classes with an 80/20 train/test split. Ideal for image classification benchmarks, transfer learning experiments, and quick prototyping without running the generator yourself.

Dataset	Images	Resolution	Download
fractality-2026	60,000	256 x 256	fractality-2026.zip

Generated with:

java -jar FractalityLab-1.4.jar --numberPerClass 2000 --resolution 256 --quality 70

---

Related Projects

• EDUX — Java Machine Learning Library

---

Contributing

Contributions are welcome. Fork the repository, create a feature branch, and submit a pull request.

./gradlew test   # Run tests before submitting

---

_{Built with Java 25 and Virtual Threads}