circlePackMetrics

Pack circular items in a two dimensional bin.

This endpoint is specialized in packing circular-shaped items inside either a circular, or rectangular bin. This endpoint works with two-dimensional data. The circlePackMetrics endpoint requires bin size and item information as input and provides detailed information about how many bins are needed to pack all the items. It provides detailed information per item in each bin, such as the coordinates of the item.

Just getting started?

Take a look at our quick start page.

Not sure which endpoint to use?

Take a look at our features for more information.

Establishing Connection

Connectivity
Base url
https://www.packing-optimizer.com
Path
/api/circlePack/metrics
Method
POST

All API requests must be made over HTTPS.

Headers
Authorization
Basic-Auth
Content-Type
application/json

Your credentials can be retrieved (and reset) from your account settings.

curl --user username:password -d @input.json -H "Content-Type: application/json" https://www.packing-optimizer.com/api/circlePack/metrics

The Request

The Bin object

Information about the bin that will be used for packing.

Information: A bin can either be a circle, or a rectangle. If your bin is a rectangle, the diameter should be omitted. If your bin is a circle, the width and depth should be omitted.

Mandatory attributes

bin.type string

Type of bin used for packing.
Example: pallet

bin.width numeric

Width of the bin.
Example: 1.2

bin.depth numeric

Depth of the bin.
Example: 0.8

bin.diameter numeric

The diameter of the bin.
Example: 0.2

bin.maxWeight numeric

Max weight that a single bin can carry.
Example: 1500

Other attributes

Allows you to enforce that the heaviest items will be packed first. Diameter will generally result in a faster response and a higher space utilization.
Options: weight, diameter
Default: diameter

The pattern that will be used to place items onto the bin.
Options: spiral, bottomUp, insideOut
Default: bottomUp

The Item object

Information about the items that have to be packed.

The request takes an array of item objects as input.

Mandatory attributes

items[].id string

Id to identify this individual item.
Example: ITEM001

items[].diameter numeric

The diameter of the item.
Example: 0.20

items[].weight numeric

The weight of the item.
Example: 10

Other attributes

A margin that must be between this item and another item. This can be used if items are not allowed to be too tightly packed.
Example: 0.05

Items with the same consolidation key will be separated from the other items and grouped in their own bin(s). Items with different consolidation key values will never be grouped in the same bin. Items with no key will group together by default.
Default: none
Example: customerX

Query String Options

Parameters which provide some control over the data being transmitted in the response, such as specifying the quantity or format of the data.

If false, the individual bins will not be included in the response and only header information will be transmitted.
Options: true or false
Default: true
Example: /api/circlePack/metrics?includeBins=false

If false, the individual item information per bin will not be included in the response.
Options: true or false
Default: true
Example: /api/circlePack/metrics?includeItems=false

Sets the decimal precision of the response body.
Default: 3
Example: /api/circlePack/metrics?responsePrecision=5

Example


{
    "bin": {
        "type": "sheet"
        "maxWeight": 1500
        "diameter": 3
        "packingPattern": "bottomUp"
    },
    "items": [
        {
            "id": "circleXL1"
            "weight": 10
            "diameter": 0.9
        },
        {
            "id": "circleXL2"
            "weight": 10
            "diameter": 0.9
        },
        {
            "id": "circleM1"
            "weight": 10
            "diameter": 0.4
            "margin": 0.1
        },
        {
            "id": "circleM2"
            "weight": 10
            "diameter": 0.4
            "margin": 0.1
        },
        {
            "id": "circleM3"
            "weight": 10
            "diameter": 0.4
            "margin": 0.1
        },
        {
            "id": "circleM4"
            "weight": 10
            "diameter": 0.4
            "margin": 0.1
        },
        {
            "id": "circleS1"
            "weight": 10
            "diameter": 0.2
        },
        {
            "id": "circleS2"
            "weight": 10
            "diameter": 0.2
        },
        {
            "id": "circleS3"
            "weight": 10
            "diameter": 0.2
        }
    ]
}

The Response

The response layout

The packing response body follows a certain hierarchy, this hierarchy can be categorized in 3 sections.

Header information
These details reason across all the bins that have been packed.
Bin information
These details are about a particular bin that has been packed.
Item information
These are details about a particular item. Items are nested inside bins.

Header

Contains header information about the complete packing request.

requiredNrOfBins numeric

The total number of bins it requires to pack all items.

totalSurfaceAreaUtil numeric

The total surface area utilization in percentage points.

totalWeightUtil numeric

The total weight utilization in percentage points

packedBins array

Contains the bins that have been packed.

unfittedItems array

Array of items that did not fit. Items in this array have the same attributes as items where packed successfully.

PackedBins

Contains information about each bin that has been packed.

packedBins[].id numeric

Incrementing counter starting from 1. Generated by Packing Optimizer.

packedBins[].type string

The type of bin as provided by the caller in the request body.

packedBins[].width numeric

The maximum width of the bin as provided by the caller in the request body.

packedBins[].depth numeric

The maximum depth of the bin as provided by the caller in the request body.

packedBins[].diameter numeric

The diameter of the bin as provided by the caller in the request body.

packedBins[].surfaceArea numeric

The maximum surface area of the bin.

packedBins[].coveredSurfaceArea numeric

Total surface area of the items packed in the bin.

packedBins[].surfaceAreaUtil numeric

coveredSurfaceArea expressed in percentage points relative to the surfaceArea attribute.

packedBins[].maxWeight numeric

The maximum weight of the bin as provided by the caller in the request body.

packedBins[].actualWeight numeric

Total weight of the items packed in the bin.

packedBins[].actualWeightUtil numeric

actualWeight expressed in percentage points relative to the maxWeight attribute.

packedBins[].nrOfItems numeric

The total number of items packed inside the bin.

packedBins[].fittedItems array

Contains the items inside the bin.

FittedItems

Contains information about each item that has been packed in the bin.

packedBins[].fittedItems[].id numeric

Item identifier as provided by the caller in the request body.

packedBins[].fittedItems[].consolidationKey string

Item consolidation key used during packing.

packedBins[].fittedItems[].xCoordinate numeric

X coordinate of the item inside the bin.

packedBins[].fittedItems[].yCoordinate numeric

Y coordinate of the item inside the bin.

packedBins[].fittedItems[].margin numeric

The margin that was taken into account while placing the item.

Example


{
    "packedBins": [
        {
            "actualWeight": 90
            "actualWeightUtil": 6
            "coveredSurfaceArea": 1.869248
            "diameter": 3
            "fittedItems": [
                {
                    "diameter": 0.9
                    "id": "circleXL2"
                    "margin": 0
                    "surfaceArea": 0.6361725
                    "weight": 10
                    "xCoordinate": 1.5
                    "yCoordinate": 0.45
                },
                {
                    "diameter": 0.9
                    "id": "circleXL1"
                    "margin": 0
                    "surfaceArea": 0.6361725
                    "weight": 10
                    "xCoordinate": 2.308915
                    "yCoordinate": 0.844534
                },
                {
                    "diameter": 0.4
                    "id": "circleM4"
                    "margin": 0.1
                    "surfaceArea": 0.1256637
                    "weight": 10
                    "xCoordinate": 1.630236
                    "yCoordinate": 1.188606
                },
                {
                    "diameter": 0.4
                    "id": "circleM3"
                    "margin": 0.1
                    "surfaceArea": 0.1256637
                    "weight": 10
                    "xCoordinate": 1.136393
                    "yCoordinate": 1.105965
                },
                {
                    "diameter": 0.4
                    "id": "circleM2"
                    "margin": 0.1
                    "surfaceArea": 0.1256637
                    "weight": 10
                    "xCoordinate": 0.8046121
                    "yCoordinate": 0.7309549
                },
                {
                    "diameter": 0.4
                    "id": "circleM1"
                    "margin": 0.1
                    "surfaceArea": 0.1256637
                    "weight": 10
                    "xCoordinate": 2.695193
                    "yCoordinate": 1.48741
                },
                {
                    "diameter": 0.2
                    "id": "circleS3"
                    "margin": 0
                    "surfaceArea": 0.03141593
                    "weight": 10
                    "xCoordinate": 1.985621
                    "yCoordinate": 0.1917906
                },
                {
                    "diameter": 0.2
                    "id": "circleS2"
                    "margin": 0
                    "surfaceArea": 0.03141593
                    "weight": 10
                    "xCoordinate": 0.9583557
                    "yCoordinate": 0.3544935
                },
                {
                    "diameter": 0.2
                    "id": "circleS1"
                    "margin": 0
                    "surfaceArea": 0.03141593
                    "weight": 10
                    "xCoordinate": 2.822384
                    "yCoordinate": 1.041636
                }
            ]
            "id": 1
            "maxWeight": 1500
            "nrOfItems": 9
            "surfaceArea": 7.068583
            "surfaceAreaUtil": 26.44444
            "type": "sheet"
        }
    ],
    "requiredNrOfBins": 1
    "totalSurfaceAreaUtil": 26.44444
    "totalWeightUtil": 6
}