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:

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