# RSJ 3D Packer

> RSJ 3D Packer computes optimised packing plans for containers and pallets: it
> packs rectangular items of mixed sizes into one or more containers, respects
> weight limits, stacking classes, no-rotation items and dangerous goods rules,
> and returns a JSON solution plus a 3D load view (and GLB export). Available as a
> cloud subscription (30 day free trial), an on-premises server or a stand-alone
> program. Vendor: RSJ Software GmbH, Germering, Germany.

This file documents the product and its HTTP API for agents. All API facts below
come from the published OpenAPI specification and the API sandbox of the running
service.

Product and application: https://3dpacker.rsj.de

## Product facts

- Problem type: 3D bin packing / bin packing with multiple bins. The solver
  produces heuristically optimised solutions for the *static* problem, meaning the
  items may be packed in any order.
- Solver core: a neural network optimised through neuro-evolution.
- Geometry: every item and every container has its own width, height and depth.
  Width/height/depth map to x/y/z.
- Inputs per item: count, width, height, depth, and optionally `weight`,
  `itemClass`, `vertical` (may the item be rotated out of its upright position),
  `riskPoints`, `riskTypes`. An item that must not be rotated is expressed as
  `"vertical": false`.
- Inputs per container: width, height, depth, count, and optionally `weight`
  (maximum load), `allowedRiskPoints` and `itemClass`.
- Stacking classes: an item is only ever placed on items of a lower or equal
  class.
- Every packed item is supported by the item below it; the plan contains no
  floating items.
- Dangerous goods: items carry risk types and risk points, containers carry a
  maximum number of risk points, and `risks` declares pairs of risk types that
  must not be loaded together.
- Result contents: packed items with container index and x/y/z position, fill
  percentage per container, number of containers used, unpacked items with counts,
  a viewer URL and an API sandbox URL.
- Serving budget: the solver works with a 240 second time budget per request.
- Web user interface: browser application with an interactive 3D view of the
  result; the viewer is embeddable in an IFRAME.
- Delivery options: cloud subscription, on-premises server (Windows 10/11 64 Bit
  or Ubuntu Linux 64 Bit, 16 GB RAM, 4 GB hard disk) or stand-alone program.
- Integrations: comprehensive web service API; the cloud version is also
  integrated into Google Sheets through its own add-on.
- Export: the solution can be downloaded as a GLB 3D model.
- Extendability: the algorithm can be adapted for dynamic problems, for example a
  fixed packing order or a required unpacking order.

## Plans and limits

Feature availability by plan. Every plan can be tested free for 30 days, and the
free test exposes the Pro feature set.

| Feature                             | Free Test | Basic | Standard | Pro |
| ----------------------------------- | --------- | ----- | -------- | --- |
| Different item sizes                | yes       | yes   | yes      | yes |
| Different container sizes           | no        | no    | yes      | yes |
| Weight limits                       | no        | no    | yes      | yes |
| Prevent vertical rotation           | no        | no    | yes      | yes |
| Dangerous goods (risk types/points) | no        | no    | no       | yes |
| Monthly price in EUR, excl. VAT     | 0         | 100   | 150      | 200 |
| Yearly price in EUR, excl. VAT      | —         | 1000  | 1500     | 2000 |

Subscriptions are billed through Stripe. The solver time budget of 240 seconds
applies to every request on every plan.

## HTTP API

Base URL: `https://3dpacker.rsj.de`

The API is a JSON REST interface. The same information is published as an
OpenAPI 3.0 document at [openapi.yaml](https://3dpacker.rsj.de/static/openapi.yaml).

### Authentication

1. Log in to obtain an access token:

   ```
   GET /user/{email}?hmac={hmac}
   ```

   The `hmac` is the HMAC-SHA256 hash of the e-mail address and can only be
   computed on the server while the user is logged in, so a stand-alone client
   copies it once. The response contains the user record and a `session` value.

2. Send that session on every call:

   ```
   Authorization: Bearer session-1bc90169-1c83-443e-8ed7-b0328aaf78a5
   ```

   The session is valid for a limited time (about one day), so fetch a fresh one
   instead of storing it. The browser application authenticates with cookies
   instead, which is what the API sandbox relies on.

### POST /solve

Solves a packing problem.

Request body (JSON):

```json
{
  "containers": [
    {
      "width": 48,
      "height": 47,
      "depth": 46,
      "count": 1,
      "weight": 2000,
      "allowedRiskPoints": 1000
    }
  ],
  "items": [
    { "width": 11, "height": 6, "depth": 6, "count": 51 },
    {
      "width": 7,
      "height": 8,
      "depth": 9,
      "count": 53,
      "vertical": false,
      "itemClass": 1,
      "weight": 12
    },
    { "width": 8, "height": 9, "depth": 10, "count": 57, "riskTypes": [1, 2], "riskPoints": 10 }
  ],
  "risks": [{ "type1": 1, "type2": 2 }]
}
```

- `items` and `containers` are required, `risks` is optional.
- `width`, `height`, `depth` are required for items and containers; `count`
  defaults to one when omitted.
- Optional item fields: `weight`, `itemClass`, `vertical`, `riskPoints`,
  `riskTypes`, and an `id` of your choosing.
- Optional container fields: `weight`, `allowedRiskPoints` and `count`.
- `itemClass` and the risk types are integers; `weight`, `riskPoints` and
  `allowedRiskPoints` are numbers.
- Unknown keys in the request objects are ignored, so client metadata may travel
  along; a future field could collide with such a key.

Response body (JSON):

```json
{
  "containers": [
    { "width": 48, "height": 47, "depth": 46, "count": 1, "used": 1, "filled": 76.77, "first": 0 }
  ],
  "items": [
    { "width": 11, "height": 6, "depth": 6, "count": 51, "vertical": true, "remaining": 0 },
    { "width": 8, "height": 9, "depth": 10, "count": 57, "remaining": 17 }
  ],
  "packedItems": [
    { "id": 0, "c": 0, "width": 11, "height": 6, "depth": 6, "x": 0, "y": 0, "z": 0 }
  ],
  "unpackedItems": [
    { "id": 2, "width": 8, "height": 9, "depth": 10, "weight": 0, "itemClass": 0, "count": 17 }
  ],
  "usedContainers": [{ "c": 0, "x": 0, "y": 0, "z": 0, "width": 48, "height": 47, "depth": 46 }],
  "risks": [],
  "viewerUrl": "https://3dpacker.rsj.de/viewer/6f1c...",
  "apiUrl": "https://3dpacker.rsj.de/api/6f1c...",
  "timestamp": "2024-05-01T10:00:00"
}
```

- `packedItems[].c` is the index of the container an item was placed in; `x`, `y`,
  `z` are its position inside that container. For a packed item, `width`,
  `height` and `depth` describe the placed — possibly rotated — item, unlike in
  the request where they describe the item as supplied.
- `items[].remaining` is the number of items of that position that could not be
  packed. `containers[].filled` is the percentage of the container volume in use,
  `containers[].used` the number of containers of that type that were opened, and
  `containers[].first` the index of the first container of that type.
- `viewerUrl` renders the result in the 3D viewer and can be embedded in an
  IFRAME. It is only valid for a limited time, because the server caches the
  request and the response behind it. It requires WebGL.

A known solvable example: `POST /solve` with items
`{"width":11,"height":6,"depth":6,"count":51}`,
`{"width":7,"height":8,"depth":9,"count":53}`,
`{"width":8,"height":9,"depth":10,"count":57}` and
`{"width":9,"height":10,"depth":11,"count":61}` into one container
`{"width":48,"height":47,"depth":46,"count":1}` with `"risks": []` returns a plan
that fills the container to about 77 % and reports the items that did not fit.

### GET /perfect

Returns a randomly generated, guaranteed solvable problem: containers are split
into items at random, so a 100 % solution exists but is usually not found. Use it
to benchmark an integration and to compare fill levels. The response has the same
shape as a solution plus the generated `containers`, `items` and `risks`, so it
can be fed straight back into `POST /solve`.

### POST /response

Converts a stored solution back into a request body, which is useful for
re-planning a load after a small change to the item list.

### Call example

```bash
curl -X POST https://3dpacker.rsj.de/solve \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer session-1bc90169-1c83-443e-8ed7-b0328aaf78a5" \
  --data @problem.json
```

## Links

- [Application](https://3dpacker.rsj.de/): the packing application, where the free test starts
- [API reference](https://3dpacker.rsj.de/3ddocs.html): rendered OpenAPI documentation of every endpoint and field
- [OpenAPI specification](https://3dpacker.rsj.de/static/openapi.yaml): OpenAPI 3.0 document, machine readable
- [API sandbox](https://3dpacker.rsj.de/3dapi.html): live request and response playground with a 3D preview, written in plain JavaScript
- [Sample packing solution](https://3dpacker.rsj.de/viewer/sample): the 3D viewer embedded on the landing page
- [Landing page](https://3dpacker.rsj.de/): product overview with features, delivery options and pricing
- [Company website](https://www.rsj.de): RSJ Software GmbH

## Optional

- [RSJ product page](https://www.rsj.de/www3d.html): the vendor's description of features, delivery options and on-premises requirements
- [Company imprint](https://www.rsj.de/imprint.html) and [privacy policy](https://www.rsj.de/privacy.html)