frost_patterns/README.md

# Frost Patterns
#### Making Diffusion Limited Aggregation look nice

![a result of the DLA algorithm where a cell is a light blue square and empty space is very dark blue, blurred slightly, with the unblurred result overlaid on top in purple](https://cqql.site/assets/articles/frost_patterns/gallery_5.png)

I learned about an algorithm called [Diffusion-Limited Aggregation](https://en.wikipedia.org/wiki/Diffusion-limited_aggregation) from [this youtube video](https://www.youtube.com/watch?v=gsJHzBTPG0Y) about procedural landscape generation for games. It happens on an empty grid with one cell in the middle. Let's call that cell the shape for now. Then, in each step of the algorithm, a new cell is spawned in a random location and does a random walk until it touches the side of the shape, after which it stays there and becomes a part of the shape.

I wrote more about how I made it on my website in the [Frost Patterns](https://cqql.site/articles/frost_patterns.html) article.

## This repository

This is the code I wrote for generating those images. It builds into a binary that can be used to generate an image with any initialization parameters. The result can either be saved to a file, or written to stdout to pipe into other programs.

### Usage

Here's how to use it:
```
Usage: frost_patterns [OPTIONS] --width <grid width> --height <grid height> --num-particles <number of particles> --scale <image scale> --palette <123456-abcdef-000000>

Options:
      --width <grid width>
          The width of the grid on which particles will be placed
      --height <grid height>
          The height of the grid on which particles will be placed
      --num-particles <number of particles>
          The number of particles to place on the grid
      --scale <image scale>
          How much scaled up should the image be, i.e. the image width will be the grid width multiplied by the grid height
      --seed <randomness seed>
          Optional randomness seed for the generator - providing the same seed will generate the same result. Leave empty for a random value
      --palette <123456-abcdef-000000>
          Shorthand notation of the color palette to use. Three RGB values in hex, where the first is the background color, the second is the blurry shape color, and the third is the sharp overlaid shape color
      --filename <FILENAME>
          Filename to save the image as. If not provided, a descriptive filename will be generated. Can't be used together with -i
      --cell-placement-strategy <CELL_PLACEMENT_STRATEGY>
          [default: anywhere] [possible values: anywhere, corners]
  -v
          Verbose - prints the progress of generating the image and the filename it has been saved to. Can't be used together with -i
  -i
          Output PNG bytes to stdout. Can't be used together with -v or --filename
  -h, --help
          Print help
```

Cell placement strategy determines where the new cells will be placed before they start their random walk.
- `anywhere` - place the new cell anywhere there's an empty space but not right next to the shape.
- `corners` - place the new cell in any randomly picked corner of the grid that isn't occupied by the shape yet. If all corners are occupied, it falls back to `anywhere`.

Keeping a `--seed` value set will generate the same shape every time that seed is used, given the same grid size, number of particles, and cell placement strategy are used.

#### Example

Generate on a 100 by 100 grid, walk 2000 particles on it (so the shape will be made up of 2000 cells). Scale the grid by 5 to generate the final image (500 by 500 pixels). Use #e5f9e0 for the background color, #a3f7b5 for the gradient under the shape, and #40c9a2 for the shape. Print the progress of generating the image (`-v`).
```
./target/release/frost_patterns --width 100 --height 100 --num-particles 2000 --scale 5 --palette e5f9e0-a3f7b5-40c9a2 -v
```

### Building

To build the project, run:
```sh
cargo build --release
```
and the executable binary will be in `target/release/frost_patterns`.

### Attribution

Feel free to use and modify this software. I would appreciate if you could attribute me if you do (most preferrably by using my website [https://cqql.site](cqql.site)) and let me know, I'll be curious! But I don't require attribution. I do not consent for the software, images generated by it, or any derivative work of them, to be used for commercial purposes without my written permission. You can contact me by email at cqql.0@proton.me. I will be very open to talk, the only reason I'm going non-commercial is because I want to prevent someone from making a no-effort dropshipping business selling posters of my generative art projects.

The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.