Chaos Game Fractal Generator

A simple command-line application written in Rust for generating fractals using the 'Chaos Game' algorithm.

Table of Contents

• Algorithm Description
• Gallery
• Installation and Usage
  • Basic Example
  • Command-Line Arguments
• Development Setup
  • Adding Custom Rules
• License

Algorithm Description

This application generates fractals using the following simple, iterative algorithm:

1. Define the $n$ vertices of a regular polygon
2. Choose a random initial point within the polygon
3. Select one of the polygon's vertices at random
4. Move the current point a specific ratio, $r$, of the distance towards the chosen vertex
5. Repeat steps 3 and 4 for some large number of iterations, plotting each new point

By adjusting the number of vertices, the distance ratio, and optionally adding additional restrictions to the choice of vertices, a huge variety of intricate fractal patterns can be generated. More details on the algorithm can be found here.

Gallery

Below are some example fractals generated with this application.

Fractal	Parameters	Image
Sierpiński Triangle	$n=3$, $r=0.5$
Rainbow Hex Fractal	$n=6$, $r=0.5$
Spirals Fractal	$n=5$, $r=0.5$, Rule: Cannot pick the same vertex twice in a row.
Star Fractal	$n=5$, $r=0.5$, Rule: If a vertex is picked twice in a row, the next pick cannot be a direct neighbour of it.

Installation and Usage

To use the application, you can simply install it using Cargo:

cargo install chaos-game

You can then run it from the command line, providing arguments to customise the generated fractal.

Basic Example

This basic example generates the Sierpiński triangle, one of the most well-known fractals produced by the Chaos Game.

chaos-game -n 3 -r 0.5 -o sierpinski.png

Command-Line Arguments

You can see all available options by running the application with the --help flag.

Development Setup

To set up the project for development and add your own custom rules, follow these steps:

1. Clone the repository

   git clone https://github.com/benjaminrall/chaos-game.git
   cd chaos-game
   

2. Run the application:

   You can build and run the project directly with Cargo. Using the --release flag is recommended for performance.

   cargo run --release -- -n 6 -c -o example.png
   

Adding Custom Rules

The application is designed to be easily extensible with custom rules for generating more complex fractals. Rules consist of a function acting on some history of previous points and a proposed new point, and must return a boolean indicating whether the new point is valid.

To create your own rule, follow these steps:

1. Create a file for your new rule:

   Create a new file in the chaos-game/src/rules/ directory (e.g., my_rule.rs)

2. Write your rule function:

   Inside the new file, write a function that takes the history of previous points and a proposed new point, and returns whether the point is valid. Decorate it with the #[rule] attribute, giving it a unique name and specifying how much history it needs.

   // chaos-game/src/rules/my_rule.rs
   use std::collections::VecDeque;
   use chaos_game_macros::rule;
   use crate::types::Vertex;
   
   // An example rule that doesn't allow the same vertex to be selected twice in a row
   #[rule("my-rule", history = 1)]
   fn no_repeats(previous_points: &VecDeque<&Vertex>, new_point: &Vertex) -> bool {
     if previous_points.len() == 0 {
       return true;
     }
     previous_points[0].index != new_point.index
   }
   

3. Add your rule to the rules module:

   Inside chaos-game/src/rules/mod.rs, define your rule as a module by its filename (e.g. mod my_rule;)

4. Use your new rule:

   After completing this setup, the rule will be automatically registered and available to use from the command line:

   cargo run --release -- -n 5 -c --rule my-rule
   

License

This project is licensed under the MIT License. See the LICENSE file for details.