Integrations: Model Healing

3DIAX allows companies to provide tools that can be used by user. The provider can also determine how to share their tool. This tutorial will show the process of using a model-healing service to improve a model’s print-ability.

Services Providers:

First we need to figure out what services are available and find a service that provides the function we need. We can list the available services by requesting a GET on the services endpoint.

To do this we need to authenticate. You can use the placeholders in the example curl command. In this example we’ve used an API token and secret, but you could also authenticate with your 3DIAX credentials.

You can reference the Client Authentication on how to authenticate to the 3DIAX API.

curl "https://data.authentise.com/service/" \
  -u "<api_token>:<api_secret>" \
  -H "Content-Type: application/json"

This endpoint will return data similar to the following:

{
  "resources": [{
    "uri": "https://data.authentise.com/service/5e2abb98-c46a-4770-a4ca-b0e11193d10e/",
    "name": "Onshape File Translation",
    "description": "Uses Onshape to translate a model file into an STL.",
    "type": "file-conversion"
  }, {
    "uri": "https://data.authentise.com/service/b9ba4ce4-0f49-45d8-ab48-19b44e20614a/",
    "name": "3DPDF Converter",
    "description": "A 3DPDF service developed by Prototech Solutions to convert OBJ or STL to 3DPDF.",
    "type": "file-conversion"
  }, {
    "uri": "https://data.authentise.com/service/0dc91cb6-b0ba-42f3-a60e-cae78f7c88fb/",
    "name": "Materialise Model Healing",
    "description": "Materialise API for print preparation and model healing"
    "type": "model-healing"
  }]
}

We have integrated Materialise and one of their tools provides a service for repiaring STL files. For this tutorial we will use the Materialise model-healing service to repair a model file in preparation for printing.

In order to use the Onshape data we will need the URI. So let’s take note of the service URI which is: https://integrations.authentise.com/service/0dc91cb6-b0ba-42f3-a60e-cae78f7c88fb/

Uploading a model

To create an operation we need a model. You can see the Tutorial for information on how to upload a model. For our example we’ll use a file with a definite problem. Here you can see

../_images/logo-damaged.png

You can create the model with the following POST request:

curl "https://data.authentise.com/model/" \
  -X POST \
  -u "<api_token>:<api_secret>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Authentise logo" }'
  -v

This request will return a header, Location, that includes the URI of the created model. In our example we’ll use the URI https://data.authentise.com/model/da38a1fb-bb84-4f3c-aaae-a545f1bd7dff/. We use the X-Upload-Location header to upload the content of the model through a PUT request. Be sure to include the Content-Type header with the value application/octet-stream. After the data is uploaded we can do the work of sending the file for model healing

Creating an Operation

Model healing operations are performed by requesting an operation through a third party. The third party is Materialise for this operation.

To create a new operation we send a POST request to the /operation/ API endpoint with the following example payload:

{
  "service": "https://data.authentise.com/service/0dc91cb6-b0ba-42f3-a60e-cae78f7c88fb/",
  "inputs": {
    "model" : "https://data.authentise.com/model/da38a1fb-bb84-4f3c-aaae-a545f1bd7dff/"
  },
  "parameters": {

  },
  "callback": {
    "method": "POST",
    "url": "https://example.com/operation/complete/"
  }
}

Looking at the example payload you can see the service parameter contains the service URI. The input parameters contain specific parameters to the type of service. For example: A model healing service requires a model parameter in the inputs which tells it what model to use for the operation. Another type of service might require different parameters in the inputs to complete the operation. Currently Materialise is marked as a model-healing type, which will require the parameters like the example payload shown.

You might have noticed a parameters object in the payload. This is custom parameters that the service requires. The provider will sometimes need custom configuration settings to complete the operation. For now, Materialise does not require any parameters. However, 3DIAX requires the parameters object in the payload to create an operation so we include an empty set indicating we are supply no additional parameters.

We can include an optional parameter callback for the operation which will be called when the operation is complete. This is useful to avoid having to poll the operation resource to check its status. In this case we should expect a POST to the https://example.com/operation/complete/ URL once the operation is complete. You can read more about callbacks in Callback Service.

Now that we have our payload we can create an operation. We do that by sending a POST request on the operation API with the payload from the above example:

curl "https://data.authentise.com/operation/" \
  -X POST \
  -u "<api_token>:<api_secret>" \
  -H "Content-Type: application/json" \
  -d '{ "service": "https://data.authentise.com/service/0dc91cb6-b0ba-42f3-a60e-cae78f7c88fb/", "inputs": { "model" : "https://data.authentise.com/model/da38a1fb-bb84-4f3c-aaae-a545f1bd7dff/" }, "parameters": {}}' \
  -v

3DIAX will check to make sure the user has access to perform the operation using the specified service. It will also check to make sure the user has access to the model for the model-healing type service.

A successful response status code will return a 204. In the response there will be a Location header. This is the URI for the newly created operation. For this example we got a Location header of: https://data.authentise.com/operation/73d4f855-6691-4ae3-bad7-e125550ad3bf/.

Getting the status of an Operation

Once we know the operation’s URI we can get the current status and any other information about the operation by making a GET request to the operation’s URI. An example CURL request for this is:

curl "https://data.authentise.com/operation/73d4f855-6691-4ae3-bad7-e125550ad3bf/" \
  -u "<api_token>:<api_secret>" \
  -H "Content-Type: application/json"

The response to this request looks like this:

{
  "uri": "https://data.authentise.com/operation/73d4f855-6691-4ae3-bad7-e125550ad3bf/",
  "service": "https://data.authentise.com/service/0dc91cb6-b0ba-42f3-a60e-cae78f7c88fb/",
  "inputs": {
    "model": "https://data.authentise.com/model/da38a1fb-bb84-4f3c-aaae-a545f1bd7dff/"
  },
  "status": "processing",
  "outputs": null,
  "results": null
}

If you look at the status in the response JSON we can see that the operation is still processing.

We can try this same call again until we get a complete or failure status. If the operation fails the outputs object might contain helpful information about why it failed from the provider’s service. Here is an example error status from Onshape.

{
  "uri": "https://data.authentise.com/operation/73d4f855-6691-4ae3-bad7-e125550ad3bf/",
  "service": "https://data.authentise.com/service/0dc91cb6-b0ba-42f3-a60e-cae78f7c88fb/",
  "inputs": {
    "model": "https://data.authentise.com/model/da38a1fb-bb84-4f3c-aaae-a545f1bd7dff/"
  },
  "status": "error",
  "outputs": {
    "title": "Unable to repair the model",
    "code": "failed healing"
  },
  "results": null
}

A complete status will include a results object in the response. This will include the results of the completed operation.

{
  "uri": "https://data.authentise.com/operation/bc53d17e-dad6-4bc5-af4e-b6f9806a1fac/",
  "service": "https://data.authentise.com/service/0dc91cb6-b0ba-42f3-a60e-cae78f7c88fb/",
  "inputs": {"model": "https://data.authentise.com/model/da38a1fb-bb84-4f3c-aaae-a545f1bd7dff/"},
  "status": "complete",
  "outputs": {
    "type": "stl",
    "content": "https://data.authentise.com/model/e9e809bf-0b6c-45ad-a33c-35dc1a2a1951"
  },
  "results": "https://data.authentise.com/model/e9e809bf-0b6c-45ad-a33c-35dc1a2a1951"
}

Depending on the service type, the contents of results will be different. For our model-healing type, it contains a URI for the new model that was created after the healing was complete. We can use that to get a download link to the actual model file by making a GET request against the model URI.

curl "https://data.authentise.com/model/e9e809bf-0b6c-45ad-a33c-35dc1a2a1951" \
  -u "<api_token>:<api_secret>" \
  -H "Content-Type: application/json"

The response from the model endpoint will look like this:

{
  "uri": "https://data.authentise.com/model/e9e809bf-0b6c-45ad-a33c-35dc1a2a1951" \
  "name": "Authentise Logo",
  "type": "stl",
  "content": "https://woodhouse.authentise.com/content/5d71ec23-96a8-4b1a-9f35-0cef9fc1ad7a/?method=GET&signature=Imh0dHBzOi8vd29vZGhvdXNlLmF1dGhlbnRpc2UuY29tL2NvbnRlbnQvNWQ3MWVjMjMtOTZhOC00YjFhLTlmMzUtMGNlZjlmYzFhZDdhLz9tZXRob2Q9R0VUIg.Cw0B9w.85TzzFg2jrKa8w5eqK3bJCciTxg",
  "status": "processed"
}

You can see the download URL in the response payload. The status is set to processed because 3DIAX has fully downloaded and processed the file. We can make a GET request against that URL to download the new STL model file that was created from our input.

curl https://woodhouse.authentise.com/content/5d71ec23-96a8-4b1a-9f35-0cef9fc1ad7a/?method=GET&signature=Imh0dHBzOi8vd29vZGhvdXNlLmF1dGhlbnRpc2UuY29tL2NvbnRlbnQvNWQ3MWVjMjMtOTZhOC00YjFhLTlmMzUtMGNlZjlmYzFhZDdhLz9tZXRob2Q9R0VUIg.Cw0B9w.85TzzFg2jrKa8w5eqK3bJCciTxg \
  -o AuthentiseLogo.pdf

Now we can open the healed model in your choice of software:

../_images/logo-repaired.png

Conclusion

This example showed how to use 3DIAX to heal a damaged model to prepare it for printing