Introduction

After sending a nesting order to the service, different views of the result can be retrieved. The full view return all the data computed by the service. A statistical view allows to perform quotation. And finally, a png image of the result can be fetched to get a preview of the result.

Full Result - Production

This is the main request to retrieve the full nesting result data after optimization.

This is usually reserved for production purpose. For quotation or material consumption evaluation, the Partial Result and Images should be used instead as it is charged with a lower price.

The request is as follow:

GET https://api.nesting.almacam.com/result/{order_id}/full
Authorization: Bearer ...

In case of success (HTTP code 200), the result can be retrieved in the body in the JSON format.

A nesting result object has the following attributes:

Attribute Value Description
message string, required a human readable status of the result
nestings array, required the nestings results are described there

A nesting contains the following attributes:

Attribute Value Description
sheet int, required the user-provided id of the sheet
nested_parts array, required the nested_parts contained in that nesting
quantity int, required the multiplicity of this nesting
length float, required the length until the straight vertical offcut
height float the height, similarly to the length

Warning, the height is only available as an indicative value and is not part of the optimization target.

And a nested-part:

Attribute Value Description
id int, required the user provided id of the part
angle float, required the orientation of the nested part
flip boolean, required true if the part is symmetrized along the x axis
position array(float), required the carthesian coordinates [x, y] of the nested part

The flip, if any, is applied after the rotation. The coordinate (0, 0) of the input description of the geometry is the reference point for all the transformations (rotation and translation). When in doubt, the simplest way is to apply the rotation, then the flip (if any), then the translation and voila.

The json-schema describing the result datastructure can be found here: result_schema.js.

Example:

Content-Type: application/json

{
    "message": "successfully completed",
    "nestings": [
        {
            "sheet": 1,
            "nested_parts": [
                {
                    "id": 1,
                    "position": [0.0, 0.0],
                    "angle": 0.0,
                    "flip": false
                }
            ],
            "quantity": 1,
            "length": 1.0,
            "height": 1.0
        }
    ]
}

Partial Result - Quote

Retrieve the overview of a nesting result. The data returned is similar to the one returned by the /full URI, but without the actual positions of the nested parts.

This allows to use the service for quotation purpose or material consumption evaluation. Indeed, the /full URI is charged with a much higher price than the /stats one, while its content is not necessary for this purpose.

The request is as follow:

GET https://api.nesting.almacam.com/result/{order_id}/stats
Authorization: Bearer ...

In case of success (HTTP code 200), the result can be retrieved in the body in the JSON format.

A nesting result object has the following attributes:

Attribute Value Description
message string, required a human readable status of the result
nestings array, required the nestings are described there

A nesting contains the following attributes:

Attribute Value Description
sheet int, required the user-provided id of the sheet
nested_parts array, required the nested_parts contained in that nesting
quantity int, required the multiplicity of this nesting
length float, required the length until the straight vertical offcut
height float the height, similarly to the length

Warning, the height is only available as an indicative value and is not part of the optimization target.

And a nested-part contains only an id:

Attribute Value Description
id int, required the user-provided id of the part

Example:

Content-Type: application/json

{
    "message": "successfully completed",
    "nestings": [
        {
            "sheet": 1,
            "nested_parts": [
                {
                    "id": 1,
                }
            ],
            "quantity": 3,
            "length": 1.0,
            "height": 1.0
        }
    ]
}

Image of Nesting Results

The request is as follow, with index the position of the nesting in the result (see Full Result or Partial Result)

GET https://api.nesting.almacam.com/result/{order_id}/image/{index}
Authorization: Bearer ...

In case of success (HTTP code 200), the image is returned:

Content-Type: image/png

Example: Example

Responses

202

Content-Type: application/json

{
    "message": "This nesting order is still computing"
}

400 - See Error 400 for details

Content-Type: application/json

{
    "message":"An error occured",
    "errors":[
        {
            "message":"Outline description is self intersecting",
            "parts":[
                1
            ],
            "error_code":-979
        }
    ]
}

401

Content-Type: application/json

{
    "message": "Incorrect authentication"
}

404

Content-Type: application/json

{
    "message": "This nesting order does not exist"
}

Error 400

In cases of error 400, the returned data contains the following attributes:

Attribute Value Description
message string, required a human readable status
errors array, optional the list of specific errors found, if relevant

Each error contains the following attributes:

Attribute Value Description
error_code int, required an error code for this specific error
message string, required a human readable message describing the error
path array, optional the path where the error was found in the sent json, if relevant
parts array, optional the array of parts IDs where the error was found, if relevant
sheets array, optional the array of sheets IDs where the error was found, if relevant

The json-schema describing the error 400 datastructure can be found here: error_schema.js.

Note: path contains the components used to access a specific location of the JSON data. For instance, in the following example, the orientation array of the first part is empty:

Content-Type: application/json

{
    "parts":
    [
        {
            "geometry": [[0, 0], [1, 0], [1, 1], [0, 1]],
            "instances":
            [
                {
                    "orientations": [],
                    "id": 1
                }
        [...]
}

gives:

Content-Type: application/json

{
    "message":"An error occured",
    "errors":[
        {
            "path":["parts", 0, "instances", 0, "orientations"],
            "message":"[] is too short",
            "error_code":-3000
        }
    ]
}

Error code list:

Error_code Description
-3000 Json schema is not valid.
-4000 Unexpected error.
-5000 Json parse error.
-6000 Maximum number of parts instances reached.
-7000 Duplicated parts ids in instances json block.
-8000 Duplicated sheets ids in intances json block.
-1000 Unexpected error.
-996 Invalid geometry
-994 Invalid sheet
-989 Invalid Orientation: We must have min_angle <= max_angle AND min_angle, max_angle in [0, 360 [
-981 Hole is not compatible with shape description
-979 Geometry description is self intersecting
-973 Bad user param
-971 Invalid contour