Search for content

Bin packing

In this tutorial you will learn how to implement a loading space optimization app. Using the app, it will allow you to specify bins and items. Then, after optimizing, it displays the result of the loaded bins. The aim of the code examples in the tutorial is to illustrate the use of the PTV Developer Loading Space Optimization API

Try it! Download from GitHub


  • Basic JavaScript knowledge.
  • Basic knowledge of JavaScript asynchronous programming using Promises.
  • Helpful: Basic knowledge of jQuery. A page like the W3 Schools jQuery tutorial is sufficient.

How to use this tutorial

This tutorial illustrates step by step how to implement a viewer for bin packing with the PTV Developer Loading Space Optimization API with JavaScript.

Getting started

  • Request an API key:
    • Register and login at
    • Activate PTV Developer
    • Create your API key
  • Download an editor such as Visual Studio Code or Atom which work with HTML and JavaScript.
  • You can find more details of requests and responses in the reference manual.
  • Download the package from GitHub and get the loadViewer.js and convertResponsePackedBins.js files. Copy the LoadViewer folder which contains the implementation of the viewer using the library three.js.

Create a HTML page and prepare the controls

Create a new HTML file called index.html, prepare all the div layers and finally define all needed scripts.

    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Loading Space Optimization</title>
    <link rel="stylesheet" href="style.css" />
    <script src=""></script>
          <div class="viewport">
              <div class="wrapper">
                  <h1>Loading Space Optimization</h1>
                  <a href="">by PTV Group</a>

                  <div class="entry-settings">

                  <div class="entry-settings">

                  <div class="entry-settings">
                      <select id="focus">
                          <option value="BUILD_LAYERS" selected>BUILD_LAYERS</option>
                          <option value="REDUCE_LOADING_METERS">REDUCE_LOADING_METERS</option>

                  <div class="group space-between">
                    <button id="btn-start-optimization" disabled>Optimize your items</button>
                    <button id="clear-data">Clear all data</button>

              <div id="binViewer"></div>

              <div id="optimization-results">
                  <div id="bin-switcher" class="group">
                    <button id="previous-bin"><</button>
                    <div class="bin-info">
                      <label id="bin-index">-</label>
                      <label id="bin-id">-</label>
                    <button id="next-bin">></button>
                  <div class="key-value"><span>Number of items</span><span id="total-items-count">-</span></div>
                  <div class="key-value"><span>Travel items volume</span><span id="total-items-volume">-</span></div>
                  <div class="key-value"><span>Travel items weight</span><span id="total-items-weight">-</span></div>
                  <div class="key-value"><span>Used weight capacity</span><span id="used-weight-capacity">-</span></div>
                  <div class="key-value"><span>Used volume capacity</span><span id="used-volume-capacity">-</span></div>
                  <div class="key-value"><span>Loading meters</span><span id="loading-meters">-</span></div>

                <div id="kpis">
                  <h3>Optimization results</h3>
                  <div class="key-value"><span>Used</span><span id="used-bins">-</span></div>
                  <div class="key-value"><span>Unused</span><span id="unused-bins">-</span></div>
                  <div class="key-value"><span>Packed</span><span id="packed-items">-</span></div>
                  <div class="key-value"><span>Unpacked</span><span id="unpacked-items">-</span></div>

          <!-- load viewer functions -->
          <script src="LoadViewer/three.min.js" charset="utf-8"></script>
          <script src="LoadViewer/threex.domevents.js" charset="utf-8"></script>
          <script src="LoadViewer/OrbitControls.js" charset="utf-8"></script>
          <script src="LoadViewer/packwidget.js" charset="utf-8"></script>
          <script src="LoadViewer/packWidgetUtils.js" charset="utf-8"></script>
          <script src="LoadViewer/mapping.js" charset="utf-8"></script>
          <script src="./convertResponsePackedBins.js"></script>
          <script src="./loadViewer.js"></script>

          <script src="general-helper-functions.js"></script>
          <script src="loading-space-optimization.js"></script>

Please note that div layer with the id="binViewer" is the base layer for the viewer.

Create the JavaScript code

Create a new JavaScript file named loading-space-optimization.js.

Initialization and main functions

The first step is to add the code below and replace the string "YOUR_API_KEY" with your PTV Developer API key if this has not already been done.

const api_key = "YOUR_API_KEY";

const APIEndpoints = {
    StartBinPacking: "",
    GetStatus: (binpackingId) => `${binpackingId}`,
    GetPackedBins: (binpackingId) => `${binpackingId}`

// Always add the API key to request headers
const applyAPIKey = (configuration) => ({
    headers: {
       "apiKey": api_key,
       ...configuration ? { ...configuration.headers } : {}

 * This object represents the application state
const appState = {
    bins: [],
    items: [],
    optimizedResult: {request: undefined, response: undefined},
    selectedBinIndex: 0

 * Applications entry point, triggered by "window.onload" event
const initializeApplication = () => {
    getElement("btn-start-optimization").addEventListener("click", optimize);

    getElement("previous-bin").addEventListener("click", () => switchSelectedBin(-1));
    getElement("next-bin").addEventListener("click", () => switchSelectedBin(1));

    window.addEventListener('beforeunload', (e) => { e.preventDefault(); e.returnValue = ''; });

window.onload = initializeApplication;


Implement the optimization process

Main optimize function

In the javascript file, the optimize function is added. It is responsible to the whole optimization process.

const optimize = async () => {
    let requestBody = {
        items: appState.items,
        bins: appState.bins

    let focusCtrl = getElement("focus");
    let focus = focusCtrl.options[focusCtrl.selectedIndex].value;

    const startSuccessful = await startOptimization(focus, requestBody);
    if (!startSuccessful) return;

    const interval = setInterval( async () => {
        const progress = await getOptimizationProgress(;
        if (!progress) return clearInterval(interval);

        if (progress.status === "SUCCEEDED" || progress.status === "FAILED") {
            const optimizedResult = await getOptimizedResult(;
            if (!optimizedResult) return;

            appState.optimizedResult.request = requestBody;
            appState.optimizedResult.response = optimizedResult;

            handleResponse($("#binViewer"), appState.optimizedResult.request, appState.optimizedResult.response);
            showElement("optimization-results", "flex");
    }, 500);

The first lines of the function create the request body and get the query parameters.
The startOptimization will start the optimization using as an async process. Then, we use setInterval to watch over the optimization process until it finishes using getOptimizationProgress
When the optimization is finished, the function getOptimizedResult returns the result.
Finally the viewer is initialized using the request and the response. Moreover the binDetails and KPIs layers are updated.

Start the optimization process

Implement the startOptimization function. The function returns the id of the optimization process.

const startOptimization = (focus, requestBody) =>
        APIEndpoints.StartBinPacking + '?focus=' + focus,
            method: "POST",
            headers: {
                "Content-Type": "application/json"
            body: JSON.stringify(requestBody)
    ).then(response => response.ok ? response.json() : logError(response));

Watch the optimization process

Implement the getOptimizationProcess function. The function returns the status of the optimization process.

const getOptimizationProgress = (id) =>
).then(response => response.ok ? response.json() : logError(response));

Get the result

Implement the getOptimizedResult function.

const getOptimizedResult = (id) =>
).then(response => response.ok ? response.json() : logError(response));


Control the viewer

Initialize the viewer

To initialize the viewer, you need to pass the request and the response.
The main entry point is the handleResponse function, which is responsible to decode the response and initialize the viewer.
Then to switch between the result bins, you can call the changeBinView. In our app, the function is implemented by the following function.

const switchSelectedBin = (step) => {
    const { selectedBinIndex } = appState;
    const usedBins = appState.optimizedResult.response.packedBins.length;

    let newIndex = selectedBinIndex + step;
    if (newIndex < 0) newIndex = usedBins - 1;
    if (newIndex > usedBins - 1) newIndex = 0;

    appState.selectedBinIndex = newIndex;


Fill the result layers

Show the bin details

const populateBinDetails = () => {
    const response = appState.optimizedResult.response;
    const selectedBin = response.packedBins[appState.selectedBinIndex];

    getElement("bin-index"           ).innerText = 'index: ' + appState.selectedBinIndex;
    getElement("bin-id"              ).innerText = selectedBin ? selectedBin.binId : '-';
    getElement("total-items-count"   ).innerText = selectedBin ? selectedBin.packedItems.length : '-';
    getElement("total-items-volume"  ).innerText = selectedBin ? (selectedBin.totalItemsVolume / 100 / 100 / 100).toFixed(3) + ' \u33A5' : '-';
    getElement("total-items-weight"  ).innerText = selectedBin ? selectedBin.totalItemsWeight/1000 + ' kg' : "-";
    getElement("used-weight-capacity").innerText = selectedBin ? selectedBin.usedWeightCapacity.toFixed(2) + ' %' : "-";
    getElement("used-volume-capacity").innerText = selectedBin ? selectedBin.usedVolumeCapacity.toFixed(2) + ' %' : "-";
    getElement("loading-meters"      ).innerText = selectedBin ? selectedBin.loadingMeters.toFixed(2) + ' m' : "-";

Show the global KPIs

const populateKPIs = () => {
    const { request, response } = appState.optimizedResult;

    const totalAvailableBins = request.bins.reduce((sum, bin) => sum + bin.numberOfInstances, 0);
    const totalAvailableItems = request.items.reduce((sum, item) => sum + item.numberOfInstances, 0);

    const totalUsedBins = response.packedBins.length;
    const totalUnpackedItems = response.itemsNotPacked.reduce((sum, item) => sum + item.numberOfInstances, 0);

    getElement("used-bins").innerText = totalUsedBins;
    getElement("unused-bins").innerText = totalAvailableBins - totalUsedBins;
    getElement("packed-items").innerText = totalAvailableItems - totalUnpackedItems;
    getElement("unpacked-items").innerText = totalUnpackedItems;