visualizeBin

Render a 3D visualization of a bin.

The visualizeBin endpoint requires bin dimensions, item dimensions, and item position and returns the HTML to display the 3D interactive bin in your application. Recommended is to first call one of the Metrics endpoints to retrieve all information required for this endpoint.

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/visualizeBin
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/visualizeBin

The Request

The Bin object

Contains the dimensions of the bin that will be plotted.

Mandatory attributes

bin.width numeric

Width of the bin.
Example: 1.2

bin.depth numeric

Depth of the bin.
Example: 0.8

bin.height numeric

Height of the bin.
Example: 1.65

The Item object

Contains the items that will be plotted inside the bin.

Information: An item can either be a cube, or a cylinder. If your item is a cube, the diameter should be omitted. If your item is a cylinder, the width and depth should be omitted.

The request takes an array of item objects as input.

Mandatory attributes

items[].id string

Id to identify this individual item.
Example: ITEM001

items[].width numeric

The width of the item.
Example: 0.20

items[].depth numeric

The depth of the item.
Example: 0.20

items[].height numeric

The height of the item.
Example: 0.20

items[].diameter numeric

The diameter of the item.
Example: 0.20

items[].xCoordinate numeric

X coordinate of the item inside the bin.
Example: 0.10

items[].yCoordinate numeric

Y coordinate of the item inside the bin.
Example: 0.10

items[].zCoordinate numeric

Z coordinate of the item inside the bin.
Example: 0.10

Other attributes

If provided, the item will be rotated accordingly before rendering.
Default: 0

Text that will be displayed when hovering over the item.
The following formatting characters can be used:

<br>
Line break.
<b>
Bold text.
<i>
Cursive text.

Color of the item, takes precedence over figure.itemColorList.
Options: any css named (extended) color
Example: green

Color of the item borders, takes precedence over figure.itemBorderColorList.
Options: any css named (extended) color
Example: blue

The Figure object

Additional parameters to style the figure.

Optional attributes

A comma separated string of CSS named colors. Items will be colored according to the entries in this list.
Options: any css named color.
Default: red,black,blue,green
Example: green,red,black,darkslateblue,sienna

A comma separated string of CSS named colors. The edges of the items will be colored according to the entries in this list.
Options: any css named color.
Default: red,black,blue,green
Example: green,red,black,darkslateblue,sienna

Controls the thickness of the item edges.
Options: Between 0.1 and 10
Default: 2

Controls the opacity of the items, where the value 1 would be a solid, non see-through surface.
Options: Between 0 and 1.
Default: 0.05

If true, items with a userMessage will be highlighted. Items with a userMessage will be colored red, items without userMessage will be colored gray.
Default: false

If false, the figure cannot be dragged by the user.
Default: false

If true, the axes will have the headers indicating the corresponding dimension ("Width", "Depth", and "Height"). If false, the headers for the axes will not be displayed.
Default: true

If true, the axis distance ticks will be displayed.
Default: true

If true, the figure will be plotted on a grid.
Default: true

If true, a small control panel will be added to the figure.
Default: false

A single CSS named color. The z axis of the figure will be colored accordingly, indicating the bottom of the bin.
Default: brown

If true, the cylinder will have horizontal mesh lines. Set to false if you want to decrease the response size.
Default: true

If true, the cylinder will have vertical mesh lines. Set to false if you want to decrease the response size.
Default: false

Determines the granularity of a round shape. This has a big impact on the response size, the more round a circle needs to be, the bigger the response size is.
Between 4 and 20
Default: 10

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.

Determines if the response will be a full HTML page or a single div element.
Options: div, fullPage
Default: div
Example: /api/visualizeBin?htmlLevel=fullPage

Determines in what form the visualization will be shared.

Option Description
html Response will contain HTML tags.
encodedHtml base64 encoded data-URL containing the HTML.
Example: data:text/html;base64,PGRpdj...
json Returns a json representation of the figure. This also requires http header Accept:application/json.

Example: /api/visualizeBin?responseType=encodedHtml

Controls the way that software dependencies are included in the response.
Options: cdn, false
Default: cdn
Example: /api/visualizeBin?htmlLevel=fullPage

Example


{
    "bin": {
        "width": 1.2,
        "depth": 0.8,
        "height": 1.65
    },
    "figure":{
        "itemColorList": "white",
        "itemBorderColorList": "black",
        "itemBorderThickness": 3.5
    },
    "items": [{
            "id": "DTM01",
            "width": 1.2,
            "depth": 0.8,
            "height": 0.6,
            "xCoordinate": 0,
            "yCoordinate": 0,
            "zCoordinate": 0
        },
        {
            "id": "DTM002",
            "width": 0.8,
            "depth": 1.2,
            "height": 0.6,
            "rotationType": 1,
            "xCoordinate": 0,
            "yCoordinate": 0,
            "zCoordinate": 0.6,
            "userMessage": "<b>High Monetary Value</b><br><i>Handle with care</i><br>Monetary Value: $5000"
        },
        {
            "id": "DTM003",
            "width": 0.6,
            "depth": 0.4,
            "height": 0.3,
            "rotationType": 0,
            "xCoordinate": 0,
            "yCoordinate": 0,
            "zCoordinate": 1.2,
            "userMessage": "<b>Double Check Quality</b><br><i>Sourced from new supplier</i>"
        }
    ]
}

The Response

The response body contains the HTML of the bin and can be embedded into a webpage.

Tip: Put the example response into an HTML renderer to see the result.

Example


<div>
    <script type="text/javascript">
        window.PlotlyConfig = {MathJaxConfig: 'local'};
    </script>
    <script src="https://cdn.plot.ly/plotly-2.17.1.min.js"></script>
    <div id="d21e203d-2709-4fe6-b017-88f1ffe327ae" class="plotly-graph-div" style="height:100%; width:100%;"></div>
    <script type="text/javascript">
        window.PLOTLYENV=window.PLOTLYENV || {};                                    if (document.getElementById("d21e203d-2709-4fe6-b017-88f1ffe327ae")) {                    Plotly.newPlot(                        "d21e203d-2709-4fe6-b017-88f1ffe327ae",                        [{"alphahull":0,"color":"red","flatshading":false,"lighting":{"ambient":1},"name":"DTM01","opacity":0.05,"type":"mesh3d","x":[0,1.2,0,0,1.2,0,1.2,1.2],"y":[0,0,0.8,0,0.8,0.8,0,0.8],"z":[0,0,0,0.6,0,0.6,0.6,0.6]},{"line":{"color":"red","width":2},"mode":"lines","type":"scatter3d","x":[0,0,null,0,0,null,0,1.2,null,0,0,null,1.2,1.2,null,0,1.2,null,1.2,1.2,null,1.2,1.2,null,0,0,null,0,1.2,null,1.2,1.2,null,0,1.2,null],"y":[0,0.8,null,0,0.8,null,0,0,null,0,0,null,0,0.8,null,0.8,0.8,null,0,0,null,0.8,0.8,null,0.8,0.8,null,0,0,null,0,0.8,null,0.8,0.8,null],"z":[0,0,null,0.6,0.6,null,0,0,null,0,0.6,null,0,0,null,0,0,null,0,0.6,null,0,0.6,null,0,0.6,null,0.6,0.6,null,0.6,0.6,null,0.6,0.6,null]},{"alphahull":0,"color":"black","flatshading":false,"hovertemplate":"<b>High Monetary Value</b><br><i>Handle with care</i><br>Monetary Value: $5000","lighting":{"ambient":1},"name":"DTM002","opacity":0.05,"type":"mesh3d","x":[0,1.2,0,0,1.2,0,1.2,1.2],"y":[0,0,0.8,0,0.8,0.8,0,0.8],"z":[0.6,0.6,0.6,1.2,0.6,1.2,1.2,1.2]},{"line":{"color":"black","width":2},"mode":"lines","type":"scatter3d","x":[0,0,null,0,0,null,0,1.2,null,0,0,null,1.2,1.2,null,0,1.2,null,1.2,1.2,null,1.2,1.2,null,0,0,null,0,1.2,null,1.2,1.2,null,0,1.2,null],"y":[0,0.8,null,0,0.8,null,0,0,null,0,0,null,0,0.8,null,0.8,0.8,null,0,0,null,0.8,0.8,null,0.8,0.8,null,0,0,null,0,0.8,null,0.8,0.8,null],"z":[0.6,0.6,null,1.2,1.2,null,0.6,0.6,null,0.6,1.2,null,0.6,0.6,null,0.6,0.6,null,0.6,1.2,null,0.6,1.2,null,0.6,1.2,null,1.2,1.2,null,1.2,1.2,null,1.2,1.2,null]},{"alphahull":0,"color":"blue","flatshading":false,"hovertemplate":"<b>Double Check Quality</b><br><i>Sourced from new supplier</i><br>Sourced from supplier XYZ, tel. 0123456","lighting":{"ambient":1},"name":"DTM003","opacity":0.05,"type":"mesh3d","x":[0,0.6,0,0,0.6,0,0.6,0.6],"y":[0,0,0.4,0,0.4,0.4,0,0.4],"z":[1.2,1.2,1.2,1.5,1.2,1.5,1.5,1.5]},{"line":{"color":"blue","width":2},"mode":"lines","type":"scatter3d","x":[0,0,null,0,0,null,0,0.6,null,0,0,null,0.6,0.6,null,0,0.6,null,0.6,0.6,null,0.6,0.6,null,0,0,null,0,0.6,null,0.6,0.6,null,0,0.6,null],"y":[0,0.4,null,0,0.4,null,0,0,null,0,0,null,0,0.4,null,0.4,0.4,null,0,0,null,0.4,0.4,null,0.4,0.4,null,0,0,null,0,0.4,null,0.4,0.4,null],"z":[1.2,1.2,null,1.5,1.5,null,1.2,1.2,null,1.2,1.5,null,1.2,1.2,null,1.2,1.2,null,1.2,1.5,null,1.2,1.5,null,1.2,1.5,null,1.5,1.5,null,1.5,1.5,null,1.5,1.5,null]}],                        {"margin":{"b":0,"l":0,"r":0,"t":0},"scene":{"aspectmode":"data","camera":{"eye":{"x":1.75,"y":1.75,"z":1.75}},"xaxis":{"dtick":0.2,"range":[0,1.2],"title":{"text":"Width"}},"yaxis":{"dtick":0.2,"range":[0,0.8],"title":{"text":"Depth"}},"zaxis":{"backgroundcolor":"brown","dtick":0.2,"range":[0,1.65],"title":{"text":"Height"}}},"showlegend":false,"template":{"data":{"bar":[{"error_x":{"color":"#2a3f5f"},"error_y":{"color":"#2a3f5f"},"marker":{"line":{"color":"#E5ECF6","width":0.5},"pattern":{"fillmode":"overlay","size":10,"solidity":0.2}},"type":"bar"}],"barpolar":[{"marker":{"line":{"color":"#E5ECF6","width":0.5},"pattern":{"fillmode":"overlay","size":10,"solidity":0.2}},"type":"barpolar"}],"carpet":[{"aaxis":{"endlinecolor":"#2a3f5f","gridcolor":"white","linecolor":"white","minorgridcolor":"white","startlinecolor":"#2a3f5f"},"baxis":{"endlinecolor":"#2a3f5f","gridcolor":"white","linecolor":"white","minorgridcolor":"white","startlinecolor":"#2a3f5f"},"type":"carpet"}],"choropleth":[{"colorbar":{"outlinewidth":0,"ticks":""},"type":"choropleth"}],"contour":[{"colorbar":{"outlinewidth":0,"ticks":""},"colorscale":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]],"type":"contour"}],"contourcarpet":[{"colorbar":{"outlinewidth":0,"ticks":""},"type":"contourcarpet"}],"heatmap":[{"colorbar":{"outlinewidth":0,"ticks":""},"colorscale":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]],"type":"heatmap"}],"heatmapgl":[{"colorbar":{"outlinewidth":0,"ticks":""},"colorscale":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]],"type":"heatmapgl"}],"histogram":[{"marker":{"pattern":{"fillmode":"overlay","size":10,"solidity":0.2}},"type":"histogram"}],"histogram2d":[{"colorbar":{"outlinewidth":0,"ticks":""},"colorscale":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]],"type":"histogram2d"}],"histogram2dcontour":[{"colorbar":{"outlinewidth":0,"ticks":""},"colorscale":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]],"type":"histogram2dcontour"}],"mesh3d":[{"colorbar":{"outlinewidth":0,"ticks":""},"type":"mesh3d"}],"parcoords":[{"line":{"colorbar":{"outlinewidth":0,"ticks":""}},"type":"parcoords"}],"pie":[{"automargin":true,"type":"pie"}],"scatter":[{"marker":{"colorbar":{"outlinewidth":0,"ticks":""}},"type":"scatter"}],"scatter3d":[{"line":{"colorbar":{"outlinewidth":0,"ticks":""}},"marker":{"colorbar":{"outlinewidth":0,"ticks":""}},"type":"scatter3d"}],"scattercarpet":[{"marker":{"colorbar":{"outlinewidth":0,"ticks":""}},"type":"scattercarpet"}],"scattergeo":[{"marker":{"colorbar":{"outlinewidth":0,"ticks":""}},"type":"scattergeo"}],"scattergl":[{"marker":{"colorbar":{"outlinewidth":0,"ticks":""}},"type":"scattergl"}],"scattermapbox":[{"marker":{"colorbar":{"outlinewidth":0,"ticks":""}},"type":"scattermapbox"}],"scatterpolar":[{"marker":{"colorbar":{"outlinewidth":0,"ticks":""}},"type":"scatterpolar"}],"scatterpolargl":[{"marker":{"colorbar":{"outlinewidth":0,"ticks":""}},"type":"scatterpolargl"}],"scatterternary":[{"marker":{"colorbar":{"outlinewidth":0,"ticks":""}},"type":"scatterternary"}],"surface":[{"colorbar":{"outlinewidth":0,"ticks":""},"colorscale":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]],"type":"surface"}],"table":[{"cells":{"fill":{"color":"#EBF0F8"},"line":{"color":"white"}},"header":{"fill":{"color":"#C8D4E3"},"line":{"color":"white"}},"type":"table"}]},"layout":{"annotationdefaults":{"arrowcolor":"#2a3f5f","arrowhead":0,"arrowwidth":1},"autotypenumbers":"strict","coloraxis":{"colorbar":{"outlinewidth":0,"ticks":""}},"colorscale":{"diverging":[[0,"#8e0152"],[0.1,"#c51b7d"],[0.2,"#de77ae"],[0.3,"#f1b6da"],[0.4,"#fde0ef"],[0.5,"#f7f7f7"],[0.6,"#e6f5d0"],[0.7,"#b8e186"],[0.8,"#7fbc41"],[0.9,"#4d9221"],[1,"#276419"]],"sequential":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]],"sequentialminus":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]]},"colorway":["#636efa","#EF553B","#00cc96","#ab63fa","#FFA15A","#19d3f3","#FF6692","#B6E880","#FF97FF","#FECB52"],"font":{"color":"#2a3f5f"},"geo":{"bgcolor":"white","lakecolor":"white","landcolor":"#E5ECF6","showlakes":true,"showland":true,"subunitcolor":"white"},"hoverlabel":{"align":"left"},"hovermode":"closest","mapbox":{"style":"light"},"paper_bgcolor":"white","plot_bgcolor":"#E5ECF6","polar":{"angularaxis":{"gridcolor":"white","linecolor":"white","ticks":""},"bgcolor":"#E5ECF6","radialaxis":{"gridcolor":"white","linecolor":"white","ticks":""}},"scene":{"xaxis":{"backgroundcolor":"#E5ECF6","gridcolor":"white","gridwidth":2,"linecolor":"white","showbackground":true,"ticks":"","zerolinecolor":"white"},"yaxis":{"backgroundcolor":"#E5ECF6","gridcolor":"white","gridwidth":2,"linecolor":"white","showbackground":true,"ticks":"","zerolinecolor":"white"},"zaxis":{"backgroundcolor":"#E5ECF6","gridcolor":"white","gridwidth":2,"linecolor":"white","showbackground":true,"ticks":"","zerolinecolor":"white"}},"shapedefaults":{"line":{"color":"#2a3f5f"}},"ternary":{"aaxis":{"gridcolor":"white","linecolor":"white","ticks":""},"baxis":{"gridcolor":"white","linecolor":"white","ticks":""},"bgcolor":"#E5ECF6","caxis":{"gridcolor":"white","linecolor":"white","ticks":""}},"title":{"x":0.05},"xaxis":{"automargin":true,"gridcolor":"white","linecolor":"white","ticks":"","title":{"standoff":15},"zerolinecolor":"white","zerolinewidth":2},"yaxis":{"automargin":true,"gridcolor":"white","linecolor":"white","ticks":"","title":{"standoff":15},"zerolinecolor":"white","zerolinewidth":2}}}},                        {"displaylogo": false, "responsive": true}                    )                };                            
    </script>
</div>