HelloDam / jagua-rs

A fast and fearless Collision Detection Engine for 2D irregular Cutting and Packing problems

Jagua-rs

A fast and fearless Collision Detection Engine for 2D irregular Cutting and Packing problems

Preamble

2D irregular cutting and packing (C&P) problems are a class of combinatorial optimization problems that involve placing irregular shaped items into containers in an efficient way. This class of problems contain two distinct challenges:

• Optimization: deciding which items to place in which configuration in order to optimize some objective function.
• Geometric: determining the feasibility of a placement. Does the item fit in the container? Does it not collide with other items?

Previously, those tackling these problems have had to address both challenges simultaneously, requiring two distinct sets of expertise and lots of research & development effort.

This project aims to decouple the two challenges by providing a Collision Detection Engine (CDE) that deals with the geometric aspects of 2D irregular C&P problems. The CDE's main responsibility is determining if an item can be placed at a certain location without causing any collisions (infeasibility). The CDE embedded in jagua-rs is able to resolve millions of these collision queries every second.

jagua-rs enables you to confidently focus on the combinatorial aspects of the optimization challenge at hand, without worrying about the underlying geometry.

We also provide a reference implementation of a basic optimization algorithm built on top of jagua-rs in the lbf crate.

jagua-rs 🐆

jagua-rs incorporates all components required to create an easily manipulable internal representation of 2D irregular C&P problems. It also boasts a powerful Collision Detection Engine (CDE) which determines whether an item can fit at a specific position without causing any collisions.

Design Goals

• Performant:
  • Focus on maximum performance, both in terms of query resolution and update speed
  • Able to resolve millions of collision queries per second
  • Integrated preprocessor to simplify polygons
• Robust:
  • Designed to mimic the exact results of a naive trigonometric approach
  • Special care is taken to handle edge cases caused by floating-point arithmetic
  • Written in pure Rust 🦀
• Adaptable:
  • Define custom C&P problem variants by creating new Instance and accompanying Problem implementations
  • Add extra constraints by creating new Hazards and HazardFilters
    • Hazards: consolidation of all spatial constraints into a single model
    • HazardFilters: excluding specific Hazards from consideration on a per-query basis
• Currently supports:
  • Bin- & strip-packing problems
  • Irregular shaped items & bins
  • Continuous rotation & translation (double precision)
  • Holes and quality zones in the bin

lbf ↙️

The lbf crate contains a reference implementation of an optimization algorithm built on top of jagua-rs. It is a simple left-bottom-fill heuristic, which places the items one-by-one in the bin, each time at the left-bottom most position.

The code is thoroughly documented and should provide a good starting point for anyone interested building their own optimization algorithm on top of jagua-rs.

How to run LBF

Make sure Rust and Cargo are installed and up to date.

General usage:

cd lbf
cargo run --release -- \
  -i <input file> \
  -c <config file (optional)> \
  -s <solution folder> \
  -l <log level (optional)>

Concrete example:

cd lbf
cargo run --release -- \
  -i ../assets/swim.json \
  -c ../assets/config_lbf.json \
  -s ../solutions

Input

The assets folder contains a set of input files from the academic literature that were converted to the same JSON structure.

The files are also available in Oscar Oliveira's OR-Datasets repository.

Solution

At the end of the optimization, the solution is written to the specified folder. Two types of files are written in the solution folder:

JSON

The solution JSON is similar to the input JSON, but with the addition of the Solution key at the top level. It contains all information required to recreate the solution, including the containers used, how the items are placed inside and some additional statistics.

SVG

A visual representation of every layout is created as an SVG file. By default, just the container and the items placed inside it are drawn. Optionally the quadtree, hazard proximity grid or fail-fast surrogates can be drawn on top. A custom theme can also be defined.

This can all be configured in the config file. See docs for all available options.

Some examples of layout SVGs created by lbf:

Note: Unfortunately, the SVG standard does not support strokes drawn purely inside (or outside) of polygons. Items might therefore sometimes falsely appear to be (very slightly) colliding in the SVG visualizations.

Config JSON

Configuration of jagua-rs and lbf heuristic is done through a JSON file. An example config file is provided here. If no config file is provided, the default configuration is used.

The configuration file is a JSON file with the following structure:

{
  "cde_config": { //Configuration of the collision detection engine
    "quadtree_depth": 5, //Maximum depth of the quadtree is 5
    "hpg_n_cells": 2000, //The hazard proximity grid contains 2000 cells
    "item_surrogate_config": {
      "pole_coverage_goal": 0.9, //The surrogate will stop generating poles when 90% of the item is covered
      "max_poles": 10, //The surrogate will at most generate 10 poles
      "n_ff_poles": 2, //Two poles will be used for fail-fast collision detection
      "n_ff_piers": 0 //Zero piers will be used for fail-fast collision detection
    }
  },
  "poly_simpl_tolerance": 0.001, //Polygons will be simplified until at most a 0.1% deviation in area from the original
  "prng_seed": 0, //Seed for the pseudo-random number generator. If undefined the outcome will be non-deterministic
  "n_samples": 5000, //5000 placement samples will be queried per item per layout
  "ls_frac": 0.2 //Of those 5000, 80% will be sampled at uniformly at random, 20% will be local search samples
}

See docs for a detailed description of all available options.

Important note

Due to lbf being a one-pass constructive heuristic, the final solution quality is very chaotic.
Meaning that tiny changes in the operation of the algorithm (sorting of the items, configuration, prng seed...) will lead to solutions with drastically different quality.
Seemingly superior configurations (such as increased n_samples), for example, can result in worse solutions and vice versa.
Omitting prng_seed in the config file disables deterministic behavior and will demonstrate this variation in solution quality.

This heuristic should only serve as a reference implementation of how to use jagua-rs and not as a optimization algorithm for any real-world use case.

Documentation

Documentation of this repo is written with rustdoc and is the most recent version is automatically deployed and hosted on GitHub Pages:

• jagua-rs docs: https://jeroengar.github.io/jagua-rs-docs/jagua_rs/
• lbf docs: https://jeroengar.github.io/jagua-rs-docs/lbf/

Alternatively, you can compile and view the docs of older versions locally by using: cargo doc --open.

Testing

The jagua-rs codebase contains a suite of assertion checks which verify the correctness of the engine. These debug_asserts are enabled by default in debug and test builds but are omitted in release builds to maximize performance.

Additionally, lbf contains some basic integration tests to validate the correctness of the engine on a macro level. It basically runs the heuristic on a set of input files with multiple configurations with assertions enabled.

The scope of these tests needs to be expanded in the future.

Development

Contributions to jagua-rs are more than welcome! To submit code contributions, fork the repository, commit your changes, and submit a pull request.

License

This project is licensed under Mozilla Public License 2.0 - see the LICENSE file for details.

Acknowledgements

This project began development at KU Leuven and was funded by Research Foundation - Flanders (FWO) (grant number: 1S71222N).