Detailed explanation and code samples

The following steps corresponds to those outlined on the previous page (getting started).

Step 1: Create a geometry file instance

Send an empty POST request with just the file name to the file URI to initialize a file instance. The response will contain the file ID to use in subsquent requests related to this file, the URL to upload the file to and the related fields for authentication when uploading the file. These fields are key value pairs that you will have to use as form-data values of the multipart/form-data request in the next step.

Step 2: Upload the file

At this point you will need to use the URL and the fields from the response to the previous request with your file in a multipart/form-data request. Your file will then be available for processing on our remote filesystem.

Please do not consider the fields keys as static, the keys may vary in future.

Steps 3 and 4: Wait for the file to be processed

Once the file is uploaded to the filesystem, an event is triggered and an async task will start to prepare the file. Your application will need to wait until this process has finished before continuing. This should only take a few seconds.

To know when it is finished you will need to perform a GET request periodically (every 1-2 seconds) to check the status of the file.

Once the status in the response is 'Ok', the layers detected in this file will also be available in the form of a list of items with a name and id.

Did you notice the expand parameter inside the querystring ?
This is a parameter that can be used with every GET request of the API.
Please see the API reference for more information.

Why are we using the /files URI instead of /files/{file_id} ?
When you use the API in your product to upload files to the service, you will most likely upload multiple files simultaneously. Using the /files URI with the ids query parameter allows you, in a single request, to fetch all the layers of all the files you are currently processing.

When using the /files/{file_id} URI, replace file_id with the id obtained in the response to the initial POST request.

Step 5,6,7 and 8: Configure the file layers, scale, unit and tools

Creating a configuration is the most important step in determining the shapes that will be generated from your file.

We recommend that you first create a configuration with all layers defined as 'Cut' type in order to display a png preview of the file. If the image correctly shows the shape as it should be extracted then you can move on to the next step.

If not, perhaps a layer type or a configuration option needs to be changed (See configuration API reference for more information). Create a new configuration with these changes.

When creating a configuration, the process is the same as when uploading a file. The POST request triggers an async task and you then use GET requests to check if the configuration has finished processing or not.

If you try to create a configuration that already exists, the existing one will be returned to you without needing to be re-processed.

Create configuration

Then, fetch it.

When the image representation is correct, you can start generating shapes from this configuration.

Step 9 and 10: Generate shapes

The shapes are the outputs of this service. They are the geometry representations you will able to to use in PowerNest WS or within other sofware and services.

Please note that splines are converted to arcs for compatiblity with CAD/CAM systems.

To generate shapes it is the same process as for files and configurations: a POST request followed by GET requests until the async process has finished.

Then (configuration response includes shapes).

Step 11: (Extra) Shape groups

You have now produced shapes from a file and that could be all you need from this API. There is an extra feature that you may wish to use and that is the "shape groups".

Perhaps you have noticed the deduplicate option available in the configuration request body. This option is set to 'true' by default meaning that the algorithm will identify identical shapes within a file and group them as a single geometry. If you do NOT wish identical shapes to recognised you may set this to 'false'.

The shape groups extends this 'deduplicate' feature to multiple files. After generating a series of shapes from different files, you can submit the shape IDs in a POST request on the /shape-groups URI. This will start an async task which groups shapes with the same geometry and returns the total quantity for each group of shapes.

Wait... Fetch.

Using the nesting result service

Step 1: Upload the PWS job and result files

In order to upload files to our service you must use the attachment endpoint (POST /attachments). Create an attachment by providing the filename of the file you wish to upload. With the url and fields returned in response to the previous request, you do a further POST request to upload the file from a local path.

Do this for both the PWS job json file and the PWS result json file, you will use their attachment IDs to create the nesting result.

Step 2: Create shapes

If you have generated shapes using the service in the past hour then you can skip this step and go straight to step 3.

If not, for each shape associated with a part or imported sheet you will need to upload the .cpf file using the attachment endpoint (POST /attachments). For each attachment, you must create a shape (POST /shapes) simply by providing the attachment ID and the unit system.

Then check that the status of each shape is 'Ok' before proceeding to the next step.

Step 3: Create the nesting result

For the nesting request body, you will now provide the attachment IDs for the PWS job and result json files that you created earlier.

For the parts you will provide a mapping between the ID of the part in the PWS job and the shape ID associated with that part. You may also provide a name for each part which will be used to label it in the nesting result if that option is selected.

If you are using imported sheets, you must provide a mapping between the ID of the sheet in PWS job and the shape ID.

If you are using rectangle sheets, you must provide a mapping between the ID of the sheet in PWS job and the height and length information.

Options

The unit system uses 'metric' by default. The alternative option is 'imperial'.

The option use_origin_layer_names is 'False' by default. If set to 'True', the layer information in the part shapes will be kept in the nesting result.

The option add_part_names is 'False' by default. If set to 'True', the part name provided in the body of the create nesting request will be added as a label to that part in the nesting layout.

The option draw_offcut is 'False' by default. If set to 'True', the offcut of a layout will be drawn as a part in the layout. This part could be used as an imported sheet in a future nesting.

The option remove_sheet_layer is 'False' by default. If set to 'True', then the sheet layer will not be exported in the layout .dxf files.

When you have created the nesting using (POST /nestings), use the returned ID to fetch the nesting and the associated layout files using (GET /nestings/{nesting_id}).

The status of the nesting will be updated to 'Ok' when all layout files have been processed and are available for you to download. Once processed, the layouts listed will contain all the statistical information related to each layout along with the links to donwload the files. The statistics of the nesting result are updated after the layouts have all been processed and represent the overall statistics for the whole nesting result.

A note on statistics

The offcut of a layout is always computed based on a vertical front.

The efficiency of a layout is calculated using the total nested surface and the total useful surface of the sheet. If the layout has an offcut, the total useful surface of the sheet is considered to be the surface of the sheet - the surface of the offcut. The efficiency of an entire nesting result is calculated from the sum of total nested surface and the sum of total useful sheet surface of all layouts.

The number of contours is considered to be the number of stop/starts required for a given part. In the layout object we distinguish two types of contours, internal being any contours for holes within a part and external being the outline of the part. The total number of contours for a given layout can therefore be calculated by summing the nb_ext_contours and nb_int_contours.