API

Public API of spyrrow

class spyrrow.Item(id, shape, demand, allowed_orientations)

An Item represents any closed 2D shape by its outer boundary.

Spyrrow doesn’t support hole(s) inside the shape as of yet. Therefore no Item can be nested inside another.

Parameters:

  • id (str) – The Item identifier Needs to be unique accross all Items of a StripPackingInstance

  • shape (Sequence[tuple[float,float]]) – An ordered Sequence of (x,y) defining the shape boundary. The shape is represented as a polygon formed by this list of points. The origin point can be included twice as the finishing point. If not, [last point, first point] is infered to be the last straight line of the shape.

  • demand (int) – The quantity of identical Items to be placed inside the strip. Should be strictly positive.

  • allowed_orientations (Sequence[float]|None) – Sequence of angles in degrees allowed. An empty Sequence is equivalent to [0.]. A None value means that the item is free to rotate The algorithmn is only very weakly sensible to the length of the Sequence given.

class spyrrow.StripPackingInstance(name, strip_height, items)

An Instance of a Strip Packing Problem.

Parameters:

  • name (str) – The name of the instance. Required by the underlying sparrow library. An empty string ‘’ can be used, if the user doesn’t have a use for this name.

  • strip_height (float) – the fixed height of the strip. The unit should be compatible with the Item

  • items – The Items which defines the instances. All Items should be defined with the same scale ( same length unit).

solve(config)

The method to solve the instance.

Parameters:

config (StripPackingConfig) – The configuration object to control how the instance is solved.

Returns:

a StripPackingSolution

to_json_str()

Return a string of the JSON representation of the object

Returns:

str

class spyrrow.StripPackingConfig(early_termination=True, quadtree_depth=4, min_items_separation=None, total_computation_time=600, exploration_time=None, compression_time=None, num_workers=None, seed=None)

Initializes a configuration object for the strip packing algorithm.

Either total_computation_time, or both exploration_time and

compression_time, must be provided. Providing all three or only one of the latter two raises an error.

If total_computation_time is provided, 80% of it is allocated to exploration and 20% to compression. If seed is not provided, a random seed will be generated.

Parameters:

  • early_termination (bool, optional) – Whether to allow early termination of the algorithm. Defaults to True.

  • quadtree_depth (int, optional) – Maximum depth of the quadtree used by the collision detection engine jagua-rs. Must be positive, common values are 3,4,5. Defaults to 4.

  • min_items_separation (Optional[float], optional) – Minimum required distance between packed items. Defaults to None.

  • total_computation_time (Optional[int], optional) – Total time budget in seconds. Used if exploration_time and compression_time are not provided. Defaults to 600.

  • exploration_time (Optional[int], optional) – Time in seconds allocated to exploration. Defaults to None.

  • compression_time (Optional[int], optional) – Time in seconds allocated to compression. Defaults to None.

  • num_workers (Optional[int], optional) – Number of threads used by the collision detection engine during exploration. When set to None, detect the number of logical CPU cores on the execution plateform. Defaults to None.

  • seed (Optional[int], optional) – Optional random seed to give reproductibility. If None, a random seed is generated. Defaults to None.

Raises:

ValueError – If the combination of time arguments is invalid.

class spyrrow.StripPackingSolution

An object representing the solution to a given StripPackingInstance.

Can not be directly instanciated. Result from StripPackingInstance.solve.

width

the width of the strip found to contains all Items. In the same unit as input.

Type:

float

placed_items

a list of all PlacedItems, describing how Items are placed in the solution

Type:

list[PlacedItem]

density

the fraction of the final strip used by items.

Type:

float

class spyrrow.PlacedItem

An object representing where a copy of an Item was placed inside the strip.

id

The Item identifier referencing the items of the StripPackingInstance

Type:

str

rotation

The rotation angle in degrees, assuming that the original Item was defined with 0° as its rotation angle. Use the origin (0.0,0.0) as the rotation point.

Type:

float

translation

the translation vector in the X-Y axis. To apply after the rotation

Type:

tuple[float,float]