Feature/docs benchmarks example

Cargo.toml

@@ -5,7 +5,8 @@ resolver = "2" # this is required to render examples with wgpu
 members = [
     "wfc",
     "wfc-image",
-    "animation-helper",
+    "animation-helper", 
+    "benchmarks",
 ]
 
 [profile.release]

benchmarks/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "benchmarks"
+version = "0.1.0"
+edition = "2021"
+
+[profile.dev]
+opt-level = 3
+
+[dependencies]
+wfc = { path = "../wfc" }
+wfc_image = { path = "../wfc-image" }
+image = { version = "0.24", default-features = false, features = ["png"] }
+coord_2d = "0.3"
+grid_2d = "0.15"
+rand = "0.8"

benchmarks/src/base.rs

@@ -0,0 +1,115 @@
+extern crate test;
+
+use std::num::NonZeroU32;
+
+use grid_2d::Grid;
+use rand::{rngs::StdRng, SeedableRng};
+use test::Bencher;
+use wfc::{
+    overlapping::OverlappingPatterns, Context, Coord, RunBorrow, RunOwn, Size, Wave,
+};
+use wfc_image::WrapXY;
+
+const TEST_GRID_10X10: [[u8; 10]; 10] = [
+    [0, 1, 1, 2, 0, 1, 1, 2, 2, 1],
+    [1, 2, 2, 2, 1, 3, 1, 1, 1, 1],
+    [0, 1, 2, 2, 2, 1, 3, 1, 1, 1],
+    [0, 1, 1, 2, 2, 2, 1, 3, 1, 1],
+    [0, 0, 1, 1, 0, 1, 1, 0, 0, 1],
+    [0, 1, 1, 1, 0, 1, 1, 0, 0, 1],
+    [0, 1, 1, 2, 0, 1, 1, 2, 2, 1],
+    [2, 0, 1, 1, 2, 0, 1, 1, 2, 1],
+    [1, 1, 1, 1, 2, 2, 2, 1, 1, 1],
+    [2, 2, 2, 2, 1, 2, 2, 2, 2, 1],
+];
+
+fn generate_input_grid<const WIDTH: usize, const HEIGHT: usize>(
+    data: &[[u8; WIDTH]; HEIGHT],
+) -> Grid<u8> {
+    let mut input = Grid::<u8>::new_default(Size::new(WIDTH as u32, HEIGHT as u32));
+    for (y, row) in data.iter().enumerate() {
+        for (x, val) in row.iter().enumerate() {
+            let cell = input.get_mut(Coord::new(x as i32, y as i32)).unwrap();
+            *cell = *val;
+        }
+    }
+    input
+}
+
+#[bench]
+fn bench_gen_pattern_3x3_from_10x10(bencher: &mut Bencher) {
+    let input = generate_input_grid(&TEST_GRID_10X10);
+
+    bencher.iter(|| {
+        OverlappingPatterns::new_original_orientation(
+            input.clone(),
+            NonZeroU32::new(3).unwrap(),
+        );
+    })
+}
+
+#[bench]
+fn bench_10x10_pattern_3x3_borrow(bencher: &mut Bencher) {
+    let input = generate_input_grid(&TEST_GRID_10X10);
+
+    let global_stats = OverlappingPatterns::new_original_orientation(
+        input.clone(),
+        NonZeroU32::new(3).unwrap(),
+    )
+    .global_stats();
+
+    bencher.iter(|| {
+        let mut rng = StdRng::seed_from_u64(21371);
+
+        let mut wave = Wave::new(Size::new(10, 10));
+        let mut context = Context::new();
+
+        let mut run =
+            RunBorrow::new_wrap(&mut context, &mut wave, &global_stats, WrapXY, &mut rng);
+
+        run.collapse(&mut rng).unwrap();
+    });
+}
+
+#[bench]
+fn bench_20x20_pattern_3x3_borrow(bencher: &mut Bencher) {
+    let input = generate_input_grid(&TEST_GRID_10X10);
+
+    let global_stats = OverlappingPatterns::new_original_orientation(
+        input.clone(),
+        NonZeroU32::new(3).unwrap(),
+    )
+    .global_stats();
+
+    bencher.iter(|| {
+        let mut rng = StdRng::seed_from_u64(21371);
+
+        let mut wave = Wave::new(Size::new(20, 20));
+        let mut context = Context::new();
+
+        let mut run =
+            RunBorrow::new_wrap(&mut context, &mut wave, &global_stats, WrapXY, &mut rng);
+
+        run.collapse(&mut rng).unwrap();
+    });
+}
+
+#[bench]
+fn bench_10x10_pattern_3x3_own(bencher: &mut Bencher) {
+    let input = generate_input_grid(&TEST_GRID_10X10);
+
+    let global_stats = OverlappingPatterns::new_original_orientation(
+        input.clone(),
+        NonZeroU32::new(3).unwrap(),
+    )
+    .global_stats();
+
+    bencher.iter(|| {
+        let mut rng = StdRng::seed_from_u64(21371);
+
+        let mut run =
+            RunOwn::new_wrap(Size::new(10, 10), &global_stats, WrapXY, &mut rng);
+
+        run.collapse(&mut rng).unwrap();
+    });
+}

benchmarks/src/image.rs

@@ -0,0 +1,112 @@
+extern crate test;
+
+use std::num::NonZeroU32;
+
+use rand::{rngs::StdRng, SeedableRng};
+use test::Bencher;
+use wfc::orientation;
+use wfc::{ForbidNothing, Size};
+use wfc_image::{generate_image_with_rng, retry, ImagePatterns, WrapXY};
+
+const EXAMPLE: &str = "../wfc-image/examples/rooms.png";
+
+#[bench]
+fn bench_gen_pattern_3x3(bencher: &mut Bencher) {
+    let input_image = image::open(EXAMPLE).unwrap();
+    let orientations = &[orientation::Orientation::Original];
+
+    bencher.iter(|| {
+        ImagePatterns::new(&input_image, NonZeroU32::new(3).unwrap(), orientations);
+    })
+}
+
+#[bench]
+fn bench_10x10_pattern_3x3(bencher: &mut Bencher) {
+    let input_image = image::open(EXAMPLE).unwrap();
+    let orientations = &[orientation::Orientation::Original];
+    let output_size = Size::new(10, 10);
+
+    bencher.iter(|| {
+        let mut rng = StdRng::seed_from_u64(2137);
+
+        generate_image_with_rng(
+            &input_image,
+            NonZeroU32::new(3).unwrap(),
+            output_size,
+            orientations,
+            WrapXY,
+            ForbidNothing,
+            retry::NumTimes(0),
+            &mut rng,
+        )
+        .unwrap();
+    })
+}
+
+#[bench]
+fn bench_10x10_pattern_4x4(bencher: &mut Bencher) {
+    let input_image = image::open(EXAMPLE).unwrap();
+    let orientations = &[orientation::Orientation::Original];
+    let output_size = Size::new(10, 10);
+
+    bencher.iter(|| {
+        let mut rng = StdRng::seed_from_u64(21371);
+
+        generate_image_with_rng(
+            &input_image,
+            NonZeroU32::new(4).unwrap(),
+            output_size,
+            orientations,
+            WrapXY,
+            ForbidNothing,
+            retry::NumTimes(0),
+            &mut rng,
+        )
+        .unwrap();
+    })
+}
+
+#[bench]
+fn bench_10x10_pattern_3x3_orientations_all(bencher: &mut Bencher) {
+    let input_image = image::open(EXAMPLE).unwrap();
+    let output_size = Size::new(10, 10);
+
+    bencher.iter(|| {
+        let mut rng = StdRng::seed_from_u64(2137);
+
+        generate_image_with_rng(
+            &input_image,
+            NonZeroU32::new(3).unwrap(),
+            output_size,
+            &orientation::ALL,
+            WrapXY,
+            ForbidNothing,
+            retry::NumTimes(0),
+            &mut rng,
+        )
+        .unwrap();
+    })
+}
+
+#[bench]
+fn bench_20x20_pattern_3x3(bencher: &mut Bencher) {
+    let input_image = image::open(EXAMPLE).unwrap();
+    let orientations = &[orientation::Orientation::Original];
+    let output_size = Size::new(20, 20);
+
+    bencher.iter(|| {
+        let mut rng = StdRng::seed_from_u64(2137);
+
+        generate_image_with_rng(
+            &input_image,
+            NonZeroU32::new(3).unwrap(),
+            output_size,
+            orientations,
+            WrapXY,
+            ForbidNothing,
+            retry::NumTimes(0),
+            &mut rng,
+        )
+        .unwrap();
+    })
+}

benchmarks/src/lib.rs

@@ -0,0 +1,6 @@
+#![feature(test)]
+
+#[cfg(test)]
+mod base;
+#[cfg(test)]
+mod image;

wfc-image/examples/anchor.rs

@@ -60,11 +60,10 @@ impl ForbidPattern for Forbid {
     fn forbid<W: Wrap, R: Rng>(&mut self, fi: &mut ForbidInterface<W>, rng: &mut R) {
         let output_size = fi.wave_size();
         (0..(output_size.width() as i32))
-            .map(|x| Coord::new(x, output_size.height() as i32 - self.offset as i32))
+            .map(|x| Coord::new(x, output_size.height() as i32 - self.offset))
             .chain(
-                (0..(output_size.width() as i32)).map(|y| {
-                    Coord::new(output_size.width() as i32 - self.offset as i32, y)
-                }),
+                (0..(output_size.width() as i32))
+                    .map(|y| Coord::new(output_size.width() as i32 - self.offset, y)),
             )
             .for_each(|coord| {
                 self.pattern_ids.iter().for_each(|&pattern_id| {

wfc-image/src/lib.rs

@@ -190,6 +190,11 @@ impl retry::ImageRetry for retry::ParNumTimes {
     }
 }
 
+/// Generate image with Wave Function Collapse algorithm using provided `rng`
+/// state.
+///
+/// For more detailed documentation see [`generate_image`].
+#[allow(clippy::too_many_arguments)]
 pub fn generate_image_with_rng<W, F, IR, R>(
     image: &DynamicImage,
     pattern_size: NonZeroU32,
@@ -213,6 +218,45 @@ where
     )
 }
 
+/// Generate image with Wave Function Collapse algorithm using random seed.
+///
+/// For generation using fixed [`Rng`] see [`generate_image_with_rng`].
+///
+/// # Arguments
+/// - `image` - input [`DynamicImage`]. Source of [`ImagePatterns`] which will
+/// be used while building the output image.
+/// - `pattern_size` - size of the generated patterns. Smaller size means that
+/// the patterns in output image will be less similar to the input ones.
+/// - `output_size` - [`Size`] of the output image.
+/// - `orientations` - collection of [`Orientation`], signifying which
+/// transformations  can be made on generated *patterns* while building
+/// the output image.
+/// - `wrap` - [`Wrap`] strategy for the *patterns*.
+/// - `forbid` - rules restricting the positioning of the patterns in the output
+/// image.
+/// - `retry` - the retrying strategy upon encountering error during collapse.
+///
+/// # Example
+/// ```
+/// use std::num::NonZeroU32;
+///
+/// use wfc::{Orientation, Size, ForbidNothing};
+/// use wfc_image::{generate_image, retry, ImagePatterns, WrapXY};
+///
+/// let input_image = image::open("../wfc-image/examples/rooms.png").unwrap();
+/// let orientations = &[Orientation::Original];
+/// let output_size = Size::new(10, 10);
+///
+/// generate_image(
+///   &input_image,
+///   NonZeroU32::new(3).unwrap(),
+///   output_size,
+///   orientations,
+///   WrapXY,
+///   ForbidNothing,
+///   retry::NumTimes(10)
+/// ).expect("couldn't generate after 10 retries");
+/// ```
 pub fn generate_image<W, F, IR>(
     image: &DynamicImage,
     pattern_size: NonZeroU32,