Using the shape service

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

Using the layer information returned when performing GET /files, generate a list of settings for each file from which to generate a configuration.

Then, fetch it.

You can download a preview of the shapes that will be produced from the configuration using the 'image_file_url' field. 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.