Pallet pattern JSON file format

Pallet pattern files are simple text files in JSON format. You can use any text editor to open and edit the files.

After editing a file manually, make sure the file is a syntactically correct JSON file. Several free tools are available online, e.g. jsonformatter.org where you can easily verify your file before uploading to the robot.

Each product type requires its own pallet pattern definition file. This file includes all product-specific information that the robot needs for palletizing:

product data
layer types
layers
zones

Project overview

This section of the pattern file includes base data about the product itself, such as

the dimensions (width, length, height) of the pallet, mm:
height of the empty pallet (see palletHeight), mm:
the dimensions (width, length, height) of one box of product, mm:
the weight of one box, g:
the label position on the box (labelOrientation):
- 0: label in front
- -90: label on the left side
- 90: label on the right side
- 180: label on the back side
- null or missing value: label not defined
the maximum number of boxes the robot can pick at once (maxGrip)
- 1: single pick
- 2: double pick
- 3: triple pick
- … (up to 8-pick) or
automatic calculation of the maximum number of boxes in multi-grip (maxGripAuto)
a unique name, a description, and a timestamp,
and some additional metadata for the graphical pattern editor.

It is important that the product dimensions are as accurate as possible to achieve the best possible result.

{
    "name": "test",
    "description": "my first pattern",
    "dateModified": "2020-04-29T07:03:20.288Z",
    "dimensions": {
        "height": 1048,
        "length": 1200,
        "width": 800,
        "palletHeight": 145
    },
    "productDimensions": {
        "width": 365,
        "height": 262,
        "length": 377,
        "weight": 5000
    },
    "maxGrip": 1,
    "maxGripAuto": true,
    "labelOrientation": 0,

Layer types

Layer types define possible layouts of individual layers. Depending on the desired stacking method, the pallet can be built by using the same layer type repeatedly (column stack) or alternating two or more different layouts (flipped, rotated, etc.) in order to create interlocking between the layers for increased stability.

{
    [...]
    "layerTypes": [
        {
            "name": "normal",
            "pattern": [
                {
                    "x": 588.5,
                    "y": 217,
                    "r": [90, 270]
                },
                {
                    "x": 211.5,
                    "y": 217,
                    "r": [90, 270],
                    "g": [0],
                    "f": 1
                },
                [...]
            ],
            "altPattern": [
                {
                    "x": 588.5,
                    "y": 217,
                    "r": [90, 270]
                },
                [...]
            ],
            "approach": "inverse"
        },
        {
            "name": "rotated",
            "pattern": [
                {
                    [...]

Box position

Each box has a specific position (the "x" and "y" values) relative to the pallet corner. The edges of the pallet define a Cartesian coordinate-system with the origo in the lower left corner. By default, positions are defined in millimeters.

Note: The layer type is a 2-dimensional logical model of the layout, thus only the x and y coordinates are defined. The z-coordinate will be calculated from the product height and the actual layer being palletized. The [x, y, z] values point to the center point at the top of the box on the pallet.

Box rotation

Each product has at least one allowed rotation (the "r" values) on the pallet, which can be 0, 90, 180, or 270 degrees, or the combinations of [0, 180] and [90, 270] respectively.

Box order

Boxes are palletized in the same order as they are defined in the pattern file. All positions of one layer are completed before the robot continues on the next layer. The only exception is the use of zones.

Enforced single/multi-grip

By default, the robot will try to palletize two or more adjacent boxes in one turn, in order to maximize throughput. The number of boxes that the robot can pick at once is limited by the maxGrip parameter in the pattern file as well as the installed product sensors on the production line and the size of the gripper.

In order to force the robot to pick less than the maximum possible number of boxes, the separator flag (the "f" value) can be used. The separator flag will instruct the robot to stop looking for more boxes. An “f”-value set to 1 means that the robot will check to see if it can pick the current box with the next box in the pattern. If the “f”-value is set to 0, then the robot will not try to pick the current box with the next box.

The following outtake of a pattern file shows how it is possible to force the robot to complete a double-pick followed by a single-pick for the three first boxes in a pattern where the robot can pick three boxes at once.

"maxGrip": 3 
[...]
"pattern": [
                {
                    "x": 690,
                    "y": 165,
                    "r": [0, 180],
                    "f": 1
                },
                {
                    "x": 690,
                    "y": 455,
                    "r": [0, 180],
                    "f": 0
                },
                { 
                    "x": 690,
                    "y": 745,
                    "r": [0, 180],
                    "f": 0
                },
                [...]
            ],
[...]

Gripper rotation at the conveyor

By default, the robot will choose the best gripper position when picking up the box(es) from the conveyor. The possible options are specified by the gripper optimization settings in the URCap (4-ways, 2-ways, or none).

For specific box positions however, it is possible to enforce a gripper position (the "g" values) or limit the possible gripper positions the robot can choose from. Any combinations of the following values are allowed: 0, 90, 180, and 270, where 0 corresponds to the configured pickup position in the URCap, other values are angles, counterclockwise when seen from above.

Left and right pallet layout

Each layout can be defined separately for the left and right pallet position. Even if the left and right pallets look identical, the order of the boxes can be different.

The default layout (the "pattern" structure) defines the layout for the right pallet. The alternative layout (the "altPattern" structure) defines the layout for the left pallet. By default - if no alternative layout is defined - the robot will generate a mirrored layout for the left pallet, in order to make a symmetric setup.

Inverse approach

For each layer type it is possible to define how the robot should approach the target position (the "approach" value corresponds to the right, and the "altApproach" to the left pallet layout). The approach direction should depend on the box order - palletizing from the furthest side of the pallet and in ("normal") or starting at the nearest side and continuing further out ("inverse"). In special circumstances - especially when the mounting base is wide - the inverse box order and approach produces a better result with less or no collision situations.

Shim paper

Shim papers are considered as special layers without actual products. The shim paper layer has its own height, usually 2-3 mm. The number of shim paper layers is not limited.

The shim paper layer type is marked with the "class": "separator" field and must not contain the "pattern" and "altPattern" structures.

Layers

The "layers" structure defines the actual layout of the final pallet. Each layer is built according to one of the layer types as described above.

Note: The first element in the layer list is the first layer on the empty pallet. The last element in the list is the topmost layer.

Zones

Normally the robot completes a layer before starting the next layer. However, the pallet can be split into different regions (the "zones" and the optional "altZones" structure) which override the regular layer completion rules. In general, a zone cannot be started until the previous zone is finished.

Zones can divide the pallet along the X, Y, and Z-axis. For example, it is possible to complete all layers of the furthest (outer) half of the pallet before proceeding to the nearest (inner) half.

The URCap allows inserting extra program code before starting and after completing a zone, in order to communicate with any optional external hardware or software or perform custom operation when a specific part of the pallet is started and/or completed.

Each zone definition can contain a position transformation hint (the "posData" array) which may be used by the Pally URCap to control a lifting column. The posData value is optional, and the program will not control the lifting column unless the value is explicitly defined.

Conditions

Zones are defined by using relational operators "<", "<=", ">", ">=" on the x, y, and z axis in the Cartesian coordinate-system defined by the pallet edges with the origo in the lower left corner of the pallet. If multiple conditions are used, they have to be enclosed in an array:

Note: Zones are evaluated in the order they are defined. If two or more zones are overlapping, the program will choose the first one that matches the condition criteria. This might cause some zones to never be activated.

Position transformations

Each zone can define a position transformation hint, which may be used by the Pally URCap to control a lifting column and/or a base slider. Before the robot starts palletizing the specified zone, the external hardware is controlled by the Pally program to put the robot into the desired mounting position.

The "posData" value has the following format: [x, y, z] in the robot base coordinate system (in millimeters). The default position is [0, 0, 0].

Location of the zone definitions

For compatibility reasons it is possible to define the zones in 3 different locations, which are loaded in the following order:

the "zones" and "altZones" structures included in the pattern file (recommended),
a separate file called pattern.zones.json - for a pattern file called pattern.json
a default file called zones.json
automatically generated by the Pally URCap for each product (only when a supported lifting column is installed and configured properly)