Max Rects

https://docs.rs/max_rects/1.0.2
Admin
Max Rects is a library for solving 2D bin packing problems. It provides a collection of algorithms...
Tokens:17,017
Snippets:166
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Max Rects Visualization Example in Rust

Source: https://docs.rs/max_rects/1.0.2/max_rects/index.html

Shows how to use the visualizer module to generate an image of the packing solution. Note that the visualization generation call is commented out.

```Rust
extern crate max_rects;
use max_rects::{visualizer, bucket::Bucket, packing_box::PackingBox, max_rects::MaxRects};

fn main() {
    let bins = vec![Bucket::new(200, 200, 0, 0, 1)];
    let boxes = vec![PackingBox::new(50, 50)];
     
    let mut problem = MaxRects::new(boxes, bins);
    let (placed, _, _) = problem.place();
     
    // visualizer::generate_visualization(&placed, &bins);
}
```

--------------------------------

### Generate Visualization of Packed Boxes

Source: https://docs.rs/max_rects/1.0.2/max_rects/visualizer/fn.generate_visualization.html

This example demonstrates how to use the `generate_visualization` function. Ensure that `placed_boxes` and `bins` are populated with actual data before calling the function. The output image will be saved as 'output.png'.

```rust
use max_rects::bucket::Bucket;
use max_rects::packing_box::PackingBox;
use max_rects::visualizer::generate_visualization;

// Assume `placed_boxes` and `bins` are already populated
let placed_boxes: Vec<PackingBox> = Vec::new();  // Your actual placed_boxes vector
let bins: Vec<Bucket> = Vec::new();  // Your actual bins vector

// generate_visualization(&placed_boxes, &bins);
// This will generate an image named 'output.png' visualizing the packed bins and boxes.
```

--------------------------------

### Get Bucket Coordinates

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/bucket.rs.html

Retrieves the left, right, top, and bottom coordinates of a bucket.

```rust
let bucket = Bucket::new(10, 20, 5, 5, 1);
assert_eq!(bucket.get_coords(), (5, 15, 5, 25));
```

--------------------------------

### Get Bucket Corners

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/bucket.rs.html

Returns the (x, y) coordinates of the four corners of a bucket.

```rust
let bucket = Bucket::new(10, 20, 5, 5, 1);
assert_eq!(bucket.get_corners(), [(5, 5), (15, 5), (5, 25), (15, 25)]);
```

--------------------------------

### Get PackingBox Corners

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/packing_box.rs.html

Returns the (x, y) coordinates of the four corners of a placed PackingBox.

```rust
let mut box_item = PackingBox::new(5, 6);
box_item.place(10, 20, 1);
let corners = box_item.get_corners();
assert_eq!(corners, [(10, 20), (15, 20), (10, 26), (15, 26)]);
```

--------------------------------

### Get PackingBox Coordinates

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/packing_box.rs.html

Retrieves the bounding box coordinates (left, right, top, bottom) of a placed PackingBox.

```rust
let mut box_item = PackingBox::new(5, 6);
box_item.place(10, 20, 1);
let coords = box_item.get_coords();
assert_eq!(coords, (10, 15, 20, 26));
```

--------------------------------

### Generic TypeId Implementation

Source: https://docs.rs/max_rects/1.0.2/max_rects/packing_box/struct.PackingBox.html

Provides a way to get the TypeId of a generic type.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
type_id

### Parameters
- `self`: A reference to the instance.

### Returns
The `TypeId` of the instance.
```

--------------------------------

### type_id

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Gets the `TypeId` of `self`. This is a blanket implementation for any type `T` that is 'static and not Sized.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
`type_id`

### Parameters
None

### Returns
`TypeId` - The type identifier of the object.
```

--------------------------------

### Create and Access Bucket Properties

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/bucket.rs.html

Demonstrates how to create a new Bucket instance and retrieve its width, height, origin coordinates, and ID.

```rust
use max_rects::bucket::Bucket;

let bucket = Bucket::new(10, 20, 5, 5, 1);
assert_eq!(bucket.width, 10);
assert_eq!(bucket.height, 20);
assert_eq!(bucket.originx, 5);
assert_eq!(bucket.originy, 5);
assert_eq!(bucket.bucketid, 1);
```

--------------------------------

### Initialize a PackingBox

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/packing_box.rs.html

Shows how to create a new PackingBox with given width and height. Initially, boxes are not placed and have no origin or bucket ID.

```rust
let box_item = PackingBox::new(5, 6);
assert_eq!(box_item.width, 5);
assert_eq!(box_item.height, 6);
assert_eq!(box_item.originx, None);
assert_eq!(box_item.originy, None);
assert_eq!(box_item.bucketid, None);
```

--------------------------------

### Create and Use a PackingBox

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/packing_box.rs.html

Demonstrates creating a new PackingBox, accessing its dimensions, and placing it within a bucket with specific coordinates.

```rust
use max_rects::packing_box::PackingBox;

let mut box_item = PackingBox::new(5, 6);
assert_eq!(box_item.width, 5);
assert_eq!(box_item.height, 6);

box_item.place(10, 20, 1);
assert_eq!(box_item.originx, Some(10));
assert_eq!(box_item.originy, Some(20));
assert_eq!(box_item.bucketid, Some(1));
```

--------------------------------

### deref

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Dereferences the given pointer to get an immutable reference to the object. This is an unsafe function associated with the `Pointable` trait.

```APIDOC
## unsafe fn deref<'a>(ptr: usize) -> &'a T

### Description
Dereferences the given pointer.

### Method
`deref`

### Parameters
- **ptr** (`usize`) - The pointer to dereference.

### Returns
`&'a T` - An immutable reference to the object.
```

--------------------------------

### Basic Max Rects Usage in Rust

Source: https://docs.rs/max_rects/1.0.2/max_rects/index.html

Demonstrates how to initialize and use the MaxRects algorithm for packing boxes into bins. Calculates and prints the packed percentage.

```Rust
extern crate max_rects;
use max_rects::{bucket::Bucket, packing_box::PackingBox, calculate_packed_percentage, max_rects::MaxRects};

fn main() {
    let bins = vec![Bucket::new(200, 200, 0, 0, 1)];
    let boxes = vec![PackingBox::new(50, 50)];

    let mut problem = MaxRects::new(boxes.clone(), bins.clone());
    let (placed, _, _) = problem.place();
       
    let percentage = calculate_packed_percentage(&boxes, &bins);
    println!("Packed percentage: {}%", percentage);
}
```

--------------------------------

### Generic From Implementation

Source: https://docs.rs/max_rects/1.0.2/max_rects/packing_box/struct.PackingBox.html

Allows creating a PackingBox from itself.

```APIDOC
## fn from(t: T) -> T

### Description
Returns the argument unchanged.

### Method
from

### Parameters
- `t`: The value to convert.

### Returns
The unchanged value.
```

--------------------------------

### Bucket::new

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/bucket.rs.html

Creates a new `Bucket` with the specified dimensions and position. This is the constructor for the Bucket struct.

```APIDOC
## Bucket::new

### Description
Creates a new `Bucket` with the specified dimensions and position.

### Parameters
- `width` (i32) - The width of the bucket.
- `height` (i32) - The height of the bucket.
- `originx` (i32) - The X-coordinate of the bucket's origin point.
- `originy` (i32) - The Y-coordinate of the bucket's origin point.
- `bucketid` (i32) - An identifier for the bucket.

### Returns
- `Self` - A new `Bucket` instance.
```

--------------------------------

### deref_mut

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Mutably dereferences the given pointer to get a mutable reference to the object. This is an unsafe function associated with the `Pointable` trait.

```APIDOC
## unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

### Description
Mutably dereferences the given pointer.

### Method
`deref_mut`

### Parameters
- **ptr** (`usize`) - The pointer to mutably dereference.

### Returns
`&'a mut T` - A mutable reference to the object.
```

--------------------------------

### Place a PackingBox

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/packing_box.rs.html

Demonstrates placing an existing PackingBox at specific X and Y coordinates within a given bucket ID.

```rust
let mut box_item = PackingBox::new(5, 6);
box_item.place(10, 20, 1);
assert_eq!(box_item.originx, Some(10));
assert_eq!(box_item.originy, Some(20));
assert_eq!(box_item.bucketid, Some(1));
```

--------------------------------

### Test Bucket Creation

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/bucket.rs.html

Unit test to verify the correct initialization of a Bucket object.

```rust
let bucket = Bucket::new(10, 20, 5, 5, 1);
assert_eq!(bucket.width, 10);
assert_eq!(bucket.height, 20);
assert_eq!(bucket.originx, 5);
assert_eq!(bucket.originy, 5);
assert_eq!(bucket.bucketid, 1);
```

--------------------------------

### Generic ApproxFrom Implementation

Source: https://docs.rs/max_rects/1.0.2/max_rects/packing_box/struct.PackingBox.html

Enables approximate conversion from a source type to PackingBox.

```APIDOC
## fn approx_from(src: Src) -> Result<Src, <Src as ApproxFrom<Src, Scheme>>::Err>

### Description
Convert the given value into an approximately equivalent representation.

### Method
approx_from

### Parameters
- `src`: The source value to convert.

### Returns
A `Result` containing the approximately converted value or an error.
```

--------------------------------

### Generic TryFrom Implementation

Source: https://docs.rs/max_rects/1.0.2/max_rects/packing_box/struct.PackingBox.html

Enables fallible conversion from a source type to PackingBox.

```APIDOC
## fn try_from(src: Src) -> Result<Src, <Src as TryFrom<Src>>::Err>

### Description
Convert the given value into the subject type.

### Method
try_from

### Parameters
- `src`: The source value to convert.

### Returns
A `Result` containing the converted value or an error.
```

--------------------------------

### init

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Initializes a with the given initializer. This is an unsafe function associated with the `Pointable` trait.

```APIDOC
## unsafe fn init(init: <T as Pointable>::Init) -> usize

### Description
Initializes a with the given initializer.

### Method
`init`

### Parameters
- **init** (`<T as Pointable>::Init`) - The initializer for the object.

### Returns
`usize` - The pointer to the initialized object.
```

--------------------------------

### Generic Borrow Implementation

Source: https://docs.rs/max_rects/1.0.2/max_rects/packing_box/struct.PackingBox.html

Allows borrowing of PackingBox instances.

```APIDOC
## fn borrow(&self) -> &T

### Description
Immutably borrows from an owned value.

### Method
borrow

### Parameters
- `self`: A reference to the PackingBox instance.

### Returns
A reference to the borrowed value.
```

--------------------------------

### Generic CloneToUninit Implementation

Source: https://docs.rs/max_rects/1.0.2/max_rects/packing_box/struct.PackingBox.html

Provides an unsafe method for cloning data into uninitialized memory.

```APIDOC
## unsafe fn clone_to_uninit(&self, dest: *mut u8)

### Description
Performs copy-assignment from `self` to `dest`.

### Method
clone_to_uninit

### Parameters
- `self`: A reference to the source PackingBox instance.
- `dest`: A raw pointer to the uninitialized memory destination.
```

--------------------------------

### PackingBox Clone Implementation

Source: https://docs.rs/max_rects/1.0.2/max_rects/packing_box/struct.PackingBox.html

Provides methods for cloning and copying PackingBox instances.

```APIDOC
## fn clone(&self) -> PackingBox

### Description
Returns a duplicate of the value.

### Method
clone

### Parameters
- `self`: A reference to the PackingBox instance.

### Returns
A new PackingBox instance that is a duplicate of the original.
```

```APIDOC
## fn clone_from(&mut self, source: &Self)

### Description
Performs copy-assignment from `source`.

### Method
clone_from

### Parameters
- `self`: A mutable reference to the PackingBox instance to be updated.
- `source`: A reference to the source PackingBox instance to copy from.
```

--------------------------------

### Test Case: Placing Boxes

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/max_rects.rs.html

Verifies the correct placement of boxes within bins using the MaxRects algorithm. Asserts the coordinates of placed boxes and updated bin configurations.

```rust
assert_eq!(placed[0].get_coords(), (0, 5, 14, 20)); //should be placed bottom right
        assert_eq!(placed[1].get_coords(), (5, 9, 16, 20)); //should be placed bottom right

        assert_eq!(updated_bins[0].get_coords(), (0, 10, 0, 14)); // new buckets
        assert_eq!(updated_bins[1].get_coords(), (9, 10, 0, 20)); // new buckets
        assert_eq!(updated_bins[2].get_coords(), (5, 10, 0, 16)); // new buckets
```

--------------------------------

### PackingBox::new

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/packing_box.rs.html

Creates a new PackingBox with the specified width and height. The box is not placed by default.

```APIDOC
## PackingBox::new

### Description
Creates a new `PackingBox` with the specified dimensions. Boxes are not placed until placed by the algorithm.

### Parameters
* **width** (i32) - The width of the box.
* **height** (i32) - The height of the box.

### Returns
A new `PackingBox` instance.
```

--------------------------------

### Generic ConvUtil Implementation

Source: https://docs.rs/max_rects/1.0.2/max_rects/packing_box/struct.PackingBox.html

Offers various conversion utilities for PackingBox.

```APIDOC
## fn approx_as<Dst>(self) -> Result<Dst, Self::Err>

### Description
Approximate the subject to a given type with the default scheme.

### Method
approx_as

### Parameters
- `self`: The PackingBox instance to convert.

### Returns
A `Result` containing the converted value or an error.
```

```APIDOC
## fn approx_as_by<Dst, Scheme>(self) -> Result<Dst, Self::Err>

### Description
Approximate the subject to a given type with a specific scheme.

### Method
approx_as_by

### Parameters
- `self`: The PackingBox instance to convert.
- `Dst`: The destination type.
- `Scheme`: The specific approximation scheme to use.

### Returns
A `Result` containing the converted value or an error.
```

```APIDOC
## fn into_as<Dst>(self) -> Dst

### Description
Convert the subject to a given type.

### Method
into_as

### Parameters
- `self`: The PackingBox instance to convert.
- `Dst`: The destination type.

### Returns
The converted value.
```

```APIDOC
## fn try_as<Dst>(self) -> Result<Dst, Self::Err>

### Description
Attempt to convert the subject to a given type.

### Method
try_as

### Parameters
- `self`: The PackingBox instance to convert.
- `Dst`: The destination type.

### Returns
A `Result` containing the converted value or an error.
```

```APIDOC
## fn value_as<Dst>(self) -> Result<Dst, Self::Err>

### Description
Attempt a value conversion of the subject to a given type.

### Method
value_as

### Parameters
- `self`: The PackingBox instance to convert.
- `Dst`: The destination type.

### Returns
A `Result` containing the converted value or an error.
```

--------------------------------

### Init

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

The type for initializers. This is an associated type of the `Pointable` trait.

```APIDOC
## type Init = T

### Description
The type for initializers.

### Type
`T`
```

--------------------------------

### into

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Calls `U::from(self)`. This is a blanket implementation for `T` where `U` implements `From<T>`.

```APIDOC
## fn into(self) -> U

### Description
Calls `U::from(self)`.

### Method
`into`

### Parameters
- **self** (Self) - The value to convert.

### Returns
`U` - The converted value.
```

--------------------------------

### Generic Pointable Implementation

Source: https://docs.rs/max_rects/1.0.2/max_rects/packing_box/struct.PackingBox.html

Provides low-level pointer manipulation for PackingBox.

```APIDOC
## unsafe fn init(init: <T as Pointable>::Init) -> usize

### Description
Initializes a with the given initializer.

### Method
init

### Parameters
- `init`: The initializer for the type.

### Returns
The pointer to the initialized memory.
```

```APIDOC
## unsafe fn deref<'a>(ptr: usize) -> &'a T

### Description
Dereferences the given pointer.

### Method
deref

### Parameters
- `ptr`: The pointer to dereference.

### Returns
A reference to the value at the pointer.
```

```APIDOC
## unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

### Description
Mutably dereferences the given pointer.

### Method
deref_mut

### Parameters
- `ptr`: The pointer to dereference.

### Returns
A mutable reference to the value at the pointer.
```

```APIDOC
## unsafe fn drop(ptr: usize)

### Description
Drops the object pointed to by the given pointer.

### Method
drop

### Parameters
- `ptr`: The pointer to the object to drop.
```

--------------------------------

### MaxRects Place Method

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/max_rects.rs.html

Attempts to place boxes into bins using the MaxRects algorithm. It iteratively places boxes, divides remaining space, and continues until no more boxes can be placed. Requires `rayon` for parallel iteration.

```rust
extern crate rayon;
use rayon::prelude::*;

use crate::bucket::Bucket;
use crate::packing_box::PackingBox;

// ... (MaxRects struct and new method) ...

pub fn place(&mut self) -> (Vec<PackingBox>, Vec<PackingBox>, Vec<Bucket>) {
    let mut nochange = false;
    let mut placed = vec![];

    while !nochange {
        nochange = true;

        let search_result: Option<(i32, usize, usize)> = self
            .boxes
            .par_iter()
            .enumerate()
            .filter_map(|(i, box_item)| {
                self.bins
                    .iter()
                    .enumerate()
                    .filter_map(|(j, rect)| {
                        if box_item.width <= rect.width && box_item.height <= rect.height {
                            let diff = i32::min(
                                rect.width - box_item.width,
                                rect.height - box_item.height,
                            );
                            Some((diff, i, j))
                        } else {
                            None
                        }
                    })
                    .min_by(|a, b| a.0.partial_cmp(&b.0).unwrap())
            })
            .min_by(|a, b| a.0.partial_cmp(&b.0).unwrap());

        if let Some((_, box_idx, idx)) = search_result {
            nochange = false;
            let mut box_item = self.boxes.remove(box_idx);
            let bin_item = self.bins.remove(idx);

            let adjacent = Bucket {
                width: bin_item.width - box_item.width,
                height: bin_item.height,
                originx: bin_item.originx + box_item.width,
                originy: bin_item.originy,
                bucketid: bin_item.bucketid,
            };

            let above = Bucket {
                width: bin_item.width,
                height: bin_item.height - box_item.height,
                originx: bin_item.originx,
                originy: bin_item.originy,
                bucketid: bin_item.bucketid,
            };

            box_item.place(
                bin_item.originx,
                bin_item.height - box_item.height + bin_item.originy,
                bin_item.bucketid,
            );
            placed.push(box_item.clone());

            if adjacent.area() > 0 {
                self.bins.push(adjacent);
            }

            if above.area() > 0 {
                self.bins.push(above);
            }

            let mut overlaps = vec![false; self.bins.len()];
            let mut new_buckets = Vec::new();

            for (idx, rect) in self.bins.iter().enumerate() {
                if placed.last().unwrap().overlap(rect) {

```

--------------------------------

### MaxRects Placement Method

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Attempts to place packing boxes into bins. This method is iterative and continues until no more boxes can be placed. It returns placed boxes, unplaced boxes, and the updated bins.

```rust
pub fn place(&mut self) -> (Vec<PackingBox>, Vec<PackingBox>, Vec<Bucket>)
```

--------------------------------

### Generic ConvAsUtil Implementations

Source: https://docs.rs/max_rects/1.0.2/max_rects/packing_box/struct.PackingBox.html

Provides utility methods for approximate and direct conversions.

```APIDOC
## fn approx(self) -> Result<Dst, Self::Err>

### Description
Approximate the subject with the default scheme.

### Method
approx

### Parameters
- `self`: The PackingBox instance to approximate.

### Returns
A `Result` containing the approximated value or an error.
```

```APIDOC
## fn approx_by<Scheme>(self) -> Result<Dst, Self::Err>

### Description
Approximate the subject with a specific scheme.

### Method
approx_by

### Parameters
- `self`: The PackingBox instance to approximate.
- `Scheme`: The specific approximation scheme to use.

### Returns
A `Result` containing the approximated value or an error.
```

--------------------------------

### Generic Into Implementation

Source: https://docs.rs/max_rects/1.0.2/max_rects/packing_box/struct.PackingBox.html

Enables conversion from PackingBox to another type that implements From.

```APIDOC
## fn into(self) -> U

### Description
Calls `U::from(self)`.

### Method
into

### Parameters
- `self`: The PackingBox instance to convert.

### Returns
The converted value.
```

--------------------------------

### Generic ApproxInto Implementation

Source: https://docs.rs/max_rects/1.0.2/max_rects/packing_box/struct.PackingBox.html

Enables approximate conversion from PackingBox to a destination type.

```APIDOC
## fn approx_into(self) -> Result<Dst, <Src as ApproxInto<Dst, Scheme>>::Err>

### Description
Convert the subject into an approximately equivalent representation.

### Method
approx_into

### Parameters
- `self`: The PackingBox instance to convert.

### Returns
A `Result` containing the approximately converted value or an error.
```

--------------------------------

### from

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Returns the argument unchanged. This is a blanket implementation for `T` where `T` implements `From<T>`.

```APIDOC
## fn from(t: T) -> T

### Description
Returns the argument unchanged.

### Method
`from`

### Parameters
- **t** (T) - The value to return.

### Returns
`T` - The input value `t`.
```

--------------------------------

### generate_visualization

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/visualizer.rs.html

Generates a visualization of placed boxes within bins and saves the result as an image. It draws bins side by side and colorizes each placed box within them.

```APIDOC
## generate_visualization

### Description
Generates a visualization of placed boxes within bins and saves the result as an image. Bins are rendered side by side with a buffer space between them, and each box within a bin is colorized with a unique color.

### Method Signature
`pub fn generate_visualization(placed_boxes: &[PackingBox], bins: &Vec<Bucket>)`

### Parameters
- `placed_boxes`: A reference to a slice of `PackingBox` objects representing the boxes that have been placed.
- `bins`: A reference to a vector of `Bucket` objects representing the bins.

### Panics
This function will panic if it fails to save the generated image to the file system.

### Examples
```rust
use max_rects::bucket::Bucket;
use max_rects::packing_box::PackingBox;
use max_rects::visualizer::generate_visualization;

// Assume `placed_boxes` and `bins` are already populated
let placed_boxes: Vec<PackingBox> = Vec::new();  // Your actual placed_boxes vector
let bins: Vec<Bucket> = Vec::new();  // Your actual bins vector

// generate_visualization(&placed_boxes, &bins);
// This will generate an image named 'output.png' visualizing the packed bins and boxes.
```
```

--------------------------------

### MaxRects Visualizer Function Implementation

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/visualizer.rs.html

This is the core implementation of the `generate_visualization` function. It calculates image dimensions, iterates through bins and placed boxes, assigns random colors to boxes, and draws them onto an image buffer before saving it as 'output.png'. It uses the `image` and `imageproc` crates for image manipulation.

```rust
extern crate image;
use image::{ImageBuffer, Rgb};
use imageproc::drawing::draw_filled_rect_mut;
use imageproc::rect::Rect;

use crate::bucket::Bucket;
use crate::packing_box::PackingBox;

pub fn generate_visualization(placed_boxes: &[PackingBox], bins: &Vec<Bucket>) {
    const BUFFER: i32 = 10; // Define a buffer of 10 pixels between bins

    // Find the max bin width and height for standardizing the visualization
    let max_bin_width = bins.iter().map(|bin| bin.width).max().unwrap_or(0);
    let max_bin_height = bins.iter().map(|bin| bin.height).max().unwrap_or(0);

    // Calculate the entire width of the image, considering the buffer between bins
    let width = bins.len() as i32 * (max_bin_width + BUFFER) - BUFFER; // subtract BUFFER to remove the last unnecessary buffer.
    let height = max_bin_height;

    let mut img = ImageBuffer::<Rgb<u8>, Vec<u8>>::new(width as u32, height as u32);

    for (i, bin) in bins.iter().enumerate() {
        // Draw the bin with a gray color
        draw_filled_rect_mut(
            &mut img,
            Rect::at(i as i32 * (max_bin_width + BUFFER), 0)
                .of_size(bin.width as u32, bin.height as u32),
            Rgb([200, 200, 200]),
        );

        for box_item in placed_boxes
            .iter()
            .filter(|&b| b.bucketid == Some(bin.bucketid))
        {
            let (box_x1, box_x2, box_y1, box_y2) = box_item.get_coords();
            let x_offset = i as i32 * (max_bin_width + BUFFER);
            let color = Rgb([
                rand::random::<u8>(),
                rand::random::<u8>(),
                rand::random::<u8>(),
            ]); // random color for each box

            // Draw the box with a darker color
            draw_filled_rect_mut(
                &mut img,
                Rect::at(box_x1 + x_offset, box_y1)
                    .of_size((box_x2 - box_x1) as u32, (box_y2 - box_y1) as u32),
                color,
            );
        }
    }

    img.save::<&str>("output.png").unwrap();
}
```

--------------------------------

### try_as

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Attempts to convert the subject to a given type `Dst`. This requires the subject to implement `TryInto<Dst>`.

```APIDOC
## fn try_as<Dst>(self) -> Result<Dst, Self::Err>

### Description
Attempt to convert the subject to a given type.

### Method
`try_as`

### Parameters
- **self** (Self) - The subject value to attempt conversion on.
- **Dst** (Type) - The target type for conversion.

### Returns
`Result<Dst, Self::Err>` - A result containing the converted value or an error.
```

--------------------------------

### approx_from

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Converts a source value into an approximately equivalent representation using a specified scheme. This is implemented for `Src` where `Scheme` implements `ApproxScheme`.

```APIDOC
## fn approx_from(src: Src) -> Result<Src, <Src as ApproxFrom<Src, Scheme>>::Err>

### Description
Convert the given value into an approximately equivalent representation.

### Method
`approx_from`

### Parameters
- **src** (Src) - The source value to convert.

### Returns
`Result<Src, <Src as ApproxFrom<Src, Scheme>>::Err>` - A result containing the approximately converted value or an error.
```

--------------------------------

### value_as

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Attempts a value conversion of the subject to a given type `Dst`. This requires the subject to implement `ValueInto<Dst>`.

```APIDOC
## fn value_as<Dst>(self) -> Result<Dst, Self::Err>

### Description
Attempt a value conversion of the subject to a given type.

### Method
`value_as`

### Parameters
- **self** (Self) - The subject value to attempt conversion on.
- **Dst** (Type) - The target type for conversion.

### Returns
`Result<Dst, Self::Err>` - A result containing the converted value or an error.
```

--------------------------------

### TryInto<Dst> for Src

Source: https://docs.rs/max_rects/1.0.2/max_rects/bucket/struct.Bucket.html

Provides a `try_into` method for converting a source type `Src` into a destination type `Dst` if `Dst` implements `TryFrom<Src>`.

```APIDOC
## impl<Src, Dst> TryInto<Dst> for Src
where Dst: TryFrom<Src>

### Error Type
#### type Err = <Dst as TryFrom<Src>>::Err
The error type produced by a failed conversion.

### Method
#### fn try_into(self) -> Result<Dst, <Src as TryInto<Dst>>::Err>
Convert the subject into the destination type.
```

--------------------------------

### value_from

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Converts a source value into an exactly equivalent representation. This is implemented for `Src` where `Src` implements `ValueFrom<Src>`.

```APIDOC
## fn value_from(src: Src) -> Result<Src, <Src as ValueFrom<Src>>::Err>

### Description
Convert the given value into an exactly equivalent representation.

### Method
`value_from`

### Parameters
- **src** (Src) - The source value to convert.

### Returns
`Result<Src, <Src as ValueFrom<Src>>::Err>` - A result containing the converted value or an error.
```

--------------------------------

### generate_visualization

Source: https://docs.rs/max_rects/1.0.2/max_rects/visualizer/fn.generate_visualization.html

Generates a visualization of placed boxes within bins and saves the result as an image. Bins are rendered side by side with a buffer space between them, and each box within a bin is colorized with a unique color.

```APIDOC
## Function generate_visualization

### Description
Generates a visualization of placed boxes within bins and saves the result as an image. This function constructs an image where each bin and each placed box within the bins are drawn as rectangles. Bins are rendered side by side with a buffer space between them, and each box within a bin is colorized with a unique color.

### Signature
```rust
pub fn generate_visualization(placed_boxes: &[PackingBox], bins: &Vec<Bucket>)
```

### Arguments
* `placed_boxes`: A reference to a slice of `PackingBox` objects representing the boxes that have been placed.
* `bins`: A reference to a vector of `Bucket` objects representing the bins.

### Panics
This function will panic if it fails to save the generated image to the file system.

### Examples
```rust
use max_rects::bucket::Bucket;
use max_rects::packing_box::PackingBox;
use max_rects::visualizer::generate_visualization;

// Assume `placed_boxes` and `bins` are already populated
let placed_boxes: Vec<PackingBox> = Vec::new();  // Your actual placed_boxes vector
let bins: Vec<Bucket> = Vec::new();  // Your actual bins vector

// generate_visualization(&placed_boxes, &bins);
// This will generate an image named 'output.png' visualizing the packed bins and boxes.
```
```

--------------------------------

### into_as

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Converts the subject to a given type `Dst`. This requires the subject to implement `Into<Dst>`.

```APIDOC
## fn into_as<Dst>(self) -> Dst

### Description
Convert the subject to a given type.

### Method
`into_as`

### Parameters
- **self** (Self) - The subject value to convert.
- **Dst** (Type) - The target type for conversion.

### Returns
`Dst` - The converted value.
```

--------------------------------

### Bucket Struct

Source: https://docs.rs/max_rects/1.0.2/max_rects/bucket/struct.Bucket.html

Represents a container with a defined width and height, positioned at a specific point in a 2D space.

```APIDOC
## Struct Bucket

Represents a container with a defined width and height, positioned at a specific point in a 2D space.

### Fields
- `width`: i32 - The width of the bucket.
- `height`: i32 - The height of the bucket.
- `originx`: i32 - The X-coordinate of the bucket’s origin point.
- `originy`: i32 - The Y-coordinate of the bucket’s origin point.
- `bucketid`: i32 - An identifier for the bucket.
```

--------------------------------

### Generic BorrowMut Implementation

Source: https://docs.rs/max_rects/1.0.2/max_rects/packing_box/struct.PackingBox.html

Allows mutable borrowing of PackingBox instances.

```APIDOC
## fn borrow_mut(&mut self) -> &mut T

### Description
Mutably borrows from an owned value.

### Method
borrow_mut

### Parameters
- `self`: A mutable reference to the PackingBox instance.

### Returns
A mutable reference to the borrowed value.
```

--------------------------------

### TryInto<U> for T

Source: https://docs.rs/max_rects/1.0.2/max_rects/bucket/struct.Bucket.html

A generic implementation of `TryInto` for type `T` to `U`, contingent on `U` implementing `TryFrom<T>`.

```APIDOC
## impl<T, U> TryInto<U> for T
where U: TryFrom<T>

### Error Type
#### type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.

### Method
#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
Performs the conversion.
```

--------------------------------

### MaxRects Initialization Test

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/max_rects.rs.html

Tests the basic initialization of the MaxRects struct with a list of boxes and bins. Verifies that the number of boxes and bins is correctly set.

```rust
    #[test]
    fn test_new() {
        let boxes = vec![PackingBox::new(5, 6)];
        let bins = vec![Bucket::new(10, 20, 0, 0, 1)];
        let max_rects = MaxRects::new(boxes, bins);

        assert_eq!(max_rects.boxes.len(), 1);
        assert_eq!(max_rects.bins.len(), 1);
    }
```

--------------------------------

### Add max_rects to Cargo.toml

Source: https://docs.rs/max_rects/1.0.2/index.html

Include this line in your Cargo.toml file to add the max_rects crate as a dependency.

```toml
[dependencies]
max_rects = "1.0.2"
```

--------------------------------

### Test Case: Packed Percentage with No Bins

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/lib.rs.html

Tests the calculate_packed_percentage function when no bins are provided, expecting a result of 0.0.

```rust
#[test]
fn test_packed_percentage_no_bins() {
    let placed_boxes = vec![PackingBox::new(5, 5), PackingBox::new(10, 10)];
    let bins = vec![];
    let percentage = calculate_packed_percentage(&placed_boxes, &bins);
    assert_eq!(percentage, 0.0);
}

```

--------------------------------

### try_into

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Converts the subject into the destination type. This is implemented for `Src` where `Dst` implements `TryFrom<Src>`.

```APIDOC
## fn try_into(self) -> Result<Dst, <Src as TryInto<Dst>>::Err>

### Description
Convert the subject into the destination type.

### Method
`try_into`

### Parameters
- **self** (Src) - The subject value to convert.

### Returns
`Result<Dst, <Src as TryInto<Dst>>::Err>` - A result containing the converted value or an error.
```

--------------------------------

### MaxRects::place

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/max_rects.rs.html

Attempts to place the boxes into the bins using the MaxRects algorithm, optimizing for minimal wasted space.

```APIDOC
## MaxRects::place

### Description
Attempts to place the boxes into the bins. This method iteratively places boxes into bins where they fit, dividing the remaining bin space into potentially smaller bins as boxes are placed. The process continues until no more boxes can be placed.

### Returns
A tuple of three vectors:
- A vector of `PackingBox` objects representing the placed boxes.
- A vector of `PackingBox` objects representing the remaining unplaced boxes.
- A vector of `Bucket` objects representing the updated bins after all possible placements have been made.
```

--------------------------------

### MaxRects::place

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Attempts to place the boxes into the bins, iteratively fitting them and updating bin space.

```APIDOC
## MaxRects::place

### Description
Attempts to place the boxes into the bins. This method iteratively places boxes into bins where they fit, dividing the remaining bin space into potentially smaller bins as boxes are placed. The process continues until no more boxes can be placed.

### Returns
A tuple of three vectors:
* A vector of `PackingBox` objects representing the placed boxes.
* A vector of `PackingBox` objects representing the remaining unplaced boxes.
* A vector of `Bucket` objects representing the updated bins after all possible placements have been made.
```

--------------------------------

### Generic ToOwned Implementation

Source: https://docs.rs/max_rects/1.0.2/max_rects/packing_box/struct.PackingBox.html

Provides methods for creating owned versions of PackingBox.

```APIDOC
## fn to_owned(&self) -> T

### Description
Creates owned data from borrowed data, usually by cloning.

### Method
to_owned

### Parameters
- `self`: A reference to the PackingBox instance.

### Returns
An owned version of the PackingBox instance.
```

```APIDOC
## fn clone_into(&self, target: &mut T)

### Description
Uses borrowed data to replace owned data, usually by cloning.

### Method
clone_into

### Parameters
- `self`: A reference to the source PackingBox instance.
- `target`: A mutable reference to the target owned PackingBox instance.
```

--------------------------------

### approx

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Approximates the subject with the default scheme. This requires the subject to implement `ApproxInto<Dst>`.

```APIDOC
## fn approx(self) -> Result<Dst, Self::Err>

### Description
Approximate the subject with the default scheme.

### Method
`approx`

### Parameters
- **self** (Self) - The subject value to approximate.

### Returns
`Result<Dst, Self::Err>` - A result containing the approximated value or an error.
```

--------------------------------

### Test Case: Packed Percentage Half Filled

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/lib.rs.html

Tests the calculate_packed_percentage function when bins are half-filled, expecting a result of 25.0.

```rust
#[test]
fn test_packed_percentage_half_filled() {
    let placed_boxes = vec![PackingBox::new(5, 5)];
    let bins = vec![Bucket::new(10, 10, 0, 0, 1)];
    let percentage = calculate_packed_percentage(&placed_boxes, &bins);
    assert_eq!(percentage, 25.0);
}

```

--------------------------------

### Splitting and Filtering Bins in MaxRects

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/max_rects.rs.html

This code demonstrates the logic for splitting existing bins when a new rectangle is placed and then filtering out bins that are fully contained within others. It's used after a box has been placed and may result in the creation of new, smaller bins.

```rust
                        // split!
                        let left = Bucket::new(
                            placed.last().unwrap().originx.unwrap() - rect.originx,
                            rect.height,
                            rect.originx,
                            rect.originy,
                            rect.bucketid,
                        );
                        let above = Bucket::new(
                            rect.width,
                            placed.last().unwrap().originy.unwrap() - rect.originy,
                            rect.originx,
                            rect.originy,
                            rect.bucketid,
                        );
                        let right = Bucket::new(
                            rect.get_coords().1 - placed.last().unwrap().get_coords().1,
                            rect.height,
                            placed.last().unwrap().get_coords().1,
                            rect.originy,
                            rect.bucketid,
                        );
                        let below = Bucket::new(
                            rect.width,
                            rect.get_coords().3 - placed.last().unwrap().get_coords().3,
                            rect.originx,
                            placed.last().unwrap().get_coords().3,
                            rect.bucketid,
                        );

                        for new_bucket in [left, above, right, below] {
                            if new_bucket.area() > 0 {
                                new_buckets.push(new_bucket);
                                overlaps.push(false);
                            }
                        }
                    }
                }

                self.bins.extend(new_buckets);
                let filtered_bins: Vec<Bucket> = self
                    .bins
                    .iter()
                    .zip(&overlaps)
                    .filter_map(|(item, &keep)| if !keep { Some(item) } else { None })
                    .cloned()
                    .collect();

                self.bins = filtered_bins;
                let mut overlaps = vec![false; self.bins.len()];

                for (i, bin1) in self.bins.iter().enumerate() {
                    for (j, bin2) in self.bins.iter().enumerate() {
                        if i != j && bin1.contains(bin2) {
                            overlaps[j] = true;
                        }
                    }
                }

                let new_bins: Vec<Bucket> = self
                    .bins
                    .clone()
                    .into_iter()
                    .enumerate()
                    .filter(|(idx, _)| !overlaps[*idx])
                    .map(|(_, bin)| bin)
                    .collect();

                self.bins = new_bins;
            }
        }

        (placed, self.boxes.clone(), self.bins.clone())
    }
}
```

--------------------------------

### calculate_packed_percentage Function Signature

Source: https://docs.rs/max_rects/1.0.2/max_rects/fn.calculate_packed_percentage.html

This is the function signature for `calculate_packed_percentage`. It takes slices of `PackingBox` and `Bucket` as input and returns a `f32` representing the packed percentage.

```rust
pub fn calculate_packed_percentage(
    placed_boxes: &[PackingBox],
    bins: &[Bucket],
) -> f32
```

--------------------------------

### approx_by

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Approximates the subject with a specific scheme. This requires the subject to implement `ApproxInto<Dst, Scheme>` where `Scheme` implements `ApproxScheme`.

```APIDOC
## fn approx_by<Scheme>(self) -> Result<Dst, Self::Err>

### Description
Approximate the subject with a specific scheme.

### Method
`approx_by`

### Parameters
- **self** (Self) - The subject value to approximate.
- **Scheme** (ApproxScheme) - The scheme to use for approximation.

### Returns
`Result<Dst, Self::Err>` - A result containing the approximated value or an error.
```

--------------------------------

### TryInto<Dst> for Src (Dst: TryFrom<Src>)

Source: https://docs.rs/max_rects/1.0.2/max_rects/packing_box/struct.PackingBox.html

Implementation of the TryInto trait for generic type Src, allowing conversion into type Dst where Dst implements TryFrom<Src>.

```APIDOC
## impl<Src, Dst> TryInto<Dst> for Src
where Dst: TryFrom<Src>

### Associated Types
#### type Err = <Dst as TryFrom<Src>>::Err

### Methods
#### fn try_into(self) -> Result<Dst, <Src as TryInto<Dst>>::Err>
```

--------------------------------

### PackingBox Debug Implementation

Source: https://docs.rs/max_rects/1.0.2/max_rects/packing_box/struct.PackingBox.html

Allows the PackingBox struct to be formatted for debugging purposes.

```APIDOC
## fn fmt(&self, f: &mut Formatter<'_>) -> Result

### Description
Formats the value using the given formatter.

### Method
fmt

### Parameters
- `self`: A reference to the PackingBox instance.
- `f`: A mutable reference to the formatter.
```

--------------------------------

### MaxRects Constructor

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Constructs a new MaxRects instance with initial boxes and bins. Use this to set up the packing problem.

```rust
pub fn new(boxes: Vec<PackingBox>, bins: Vec<Bucket>) -> Self
```

--------------------------------

### try_from

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Converts a source value into the subject type. This is implemented for `Src` where `Src` implements `Into<T>`.

```APIDOC
## fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

### Description
Performs the conversion.

### Method
`try_from`

### Parameters
- **value** (U) - The value to convert.

### Returns
`Result<T, <T as TryFrom<U>>::Error>` - A result containing the converted value or an error.
```

--------------------------------

### ValueInto<Dst> for Src

Source: https://docs.rs/max_rects/1.0.2/max_rects/bucket/struct.Bucket.html

Provides a `value_into` method for converting a source type `Src` into a destination type `Dst`, provided `Dst` implements `ValueFrom<Src>`.

```APIDOC
## impl<Src, Dst> ValueInto<Dst> for Src
where Dst: ValueFrom<Src>

### Error Type
#### type Err = <Dst as ValueFrom<Src>>::Err
The error type produced by a failed conversion.

### Method
#### fn value_into(self) -> Result<Dst, <Src as ValueInto<Dst>>::Err>
Convert the subject into an exactly equivalent representation.
```

--------------------------------

### approx_as

Source: https://docs.rs/max_rects/1.0.2/max_rects/max_rects/struct.MaxRects.html

Approximates the subject to a given type `Dst` with the default scheme. This requires the subject to implement `ApproxInto<Dst>`.

```APIDOC
## fn approx_as<Dst>(self) -> Result<Dst, Self::Err>

### Description
Approximate the subject to a given type with the default scheme.

### Method
`approx_as`

### Parameters
- **self** (Self) - The subject value to approximate.
- **Dst** (Type) - The target type for approximation.

### Returns
`Result<Dst, Self::Err>` - A result containing the approximated value or an error.
```

--------------------------------

### Calculate Packed Percentage Function

Source: https://docs.rs/max_rects/1.0.2/src/max_rects/lib.rs.html

Calculates the percentage of area packed within bins based on the total area of placed boxes and the total area of the bins. Handles division by zero.

```rust
use bucket::Bucket;
use packing_box::PackingBox;

pub fn calculate_packed_percentage(placed_boxes: &[PackingBox], bins: &[Bucket]) -> f32 {
    // Summing up the area of all bins
    let total_bin_area: i32 = bins.iter().map(|bin| bin.width * bin.height).sum();

    // Summing up the area of all placed boxes
    let total_placed_box_area: i32 = placed_boxes
        .iter()
        .map(|box_item| box_item.width * box_item.height)
        .sum();

    // Checking for zero to prevent division by zero
    if total_bin_area == 0 {
        return 0.0;
    }

    // Calculating the percentage
    (total_placed_box_area as f32 / total_bin_area as f32) * 100.0
}

```

--------------------------------

### calculate_packed_percentage

Source: https://docs.rs/max_rects/1.0.2/max_rects/fn.calculate_packed_percentage.html

Calculates the percentage of packed space given a list of placed boxes and bins.

```APIDOC
## calculate_packed_percentage

### Description
Calculates the percentage of space that has been packed within the bins.

### Signature
```rust
pub fn calculate_packed_percentage(placed_boxes: &[PackingBox], bins: &[Bucket]) -> f32
```

### Parameters
* `placed_boxes` - A slice of `PackingBox` representing the boxes that have been placed.
* `bins` - A slice of `Bucket` representing the bins available for packing.
```
Tokens:
Raw