Partner Integrations: Spark on 3DIAX

3DIAX is designed to work with 3rd party services. Lately we have been working on adding support for ` Autodesk Spark <https://spark.autodesk.com/>`_. If you are not familiar with the work that Autodesk is doing on Spark it may be worth looking in to.

One of the services that Spark provides is model healing. This tutorial will show you how to use 3DIAX to get Spark to heal your models before you (or someone else) print them.

Creating a User

First you will need to be sure that you have a user with 3DIAX. You can create one at https://app.authentise.com/#/registration. Let’s assume your username is test@authentise.com and your password is opensesame. We will start by getting you logged in:

POST https://users.authentise.com/sessions/
Content-Type: application/json
{
    "username"  : "test@authentise.com",
    "password"  : "opensesame",
}

Set-Cookie: session=abc-123

Our login succeeded and we were given a session. You could alternatively use an API token/key pair to authenticate your requests, but this is easy for now. Just make sure that your programming language of choice persists the cookie data between requests and includes it.

Listing Available Services

Next we need to locate the Spark Model Healing service in the catalog of services. We can get the current catalog with this request:

GET https://integrations.authentise.com/service/?filter[type]=model-healing
Content-Type: application/json
{
    "resources" : [{
        ...,
    },{
        "description"   : "The Spark platform model healing service",
        "group_uri"     : "https://users.authentise.com/groups/54372fd4-312e-4a5f-b92f-6fa34afe8410/",
        "name"          : "Spark Model Healing",
        "service_url"   : "https://gigan.authentise.com/spark/model-healing/",
        "type"          : "model-healing",
        "uri"           : "https://integrations.authentise.com/service/f23fc23e-4ef7-4c06-bf76-7930e00dbc22/",
    }, ...]
}

This requests all services whose type is model-healing (like Spark’s). Here we get the service URI which we can use to make requests to use the service. How do we make those requests? We will get to that in a moment. First, we need to upload a model. For full details you can check out the 3DIAX Tutorial. For now, here is a couple steps to get you going.

Uploading a Model

In order to heal a model we will need to get it uploaded to 3DIAX. We do that in two parts - creating a model resource and then uploading the data for the resource.

POST https://models.authentise.com/model/
Content-Type: application/json

{
  "name": "Broken squirtle",
}

Location: https://models.authentise.com/model/abc-123/
X-Upload-Location: https://dev-hoth-models.s3.amazonaws.com:443/3f6d9729-aa44-4019-9129-b6fc215ad87d?Signature=0U%2...

This tells 3DIAX that we need to create a model named ‘Broken squirtle’. 3DIAX will respond with the standard Location header, which will be the URI of the new model resource. It will also respond with a X-Upload-Location. This is a URL where I will need to send my model file. That can be done with a PUT request. The body of the request should be the file. Because the service supports both ASCII and binary STL files you must include a Content-Type header that contains application/octet-stream.

Here is the model I am going to upload:

../_images/broken-squirtle.png

Cute, isn’t it? Now I just PUT that data...

PUT https://dev-hoth-models.s3.amazonaws.com:443/3f6d9729-aa44-4019-9129-b6fc215ad87d?Signature=0U%2...
Content-Type: application/octet-stream

model data goes here

Alright, that model will now get ingested. I can check the status by performing a GET request against my model resource at https://models.authentise.com/model/abc-123/. I don’t actually have to wait for anything - I can start off the model healing process immediately and 3DIAX will make sure the job gets done as quickly as it can. So how do I start the operation?

Initiating the healing operation

Spark, like any 3rd-party integration with 3DIAX, goes through the integrations service. We just need to tell it what we want. Tasks that get sent to 3rd parties from 3DIAX are call ‘operations’ and are controlled with operation resources. Let’s create one:

POST https://integrations.authentise.com/operation/
Content-Type: application/json
{
    "service"   : "https://integrations.authentise.com/service/f23fc23e-4ef7-4c06-bf76-7930e00dbc22/",
    "inputs"    : {
        "model" : "https://models.authentise.com/model/abc-123/",
    },
    "parameters": {
        "all"   : true
    },
    "callback": {
        "url"       : "http://myservice.com/healing_complete?model=squirtle",
        "method"    : "POST",
    }
}
Location: https://integrations.authentise.com/operation/aaa-bbb/

We have now created an operation. The response to our request will contain a Location header that contains the URI of the operation that we created.

We specified the service by passing in the uri we got from the services catalog that matched the Spark Model Healing Service we wanted to use. Because this is a model-healing service, it requires a single input - the model that will be healed. We provided the URI of the model that we created earlier for our Broken Squirtle model.

The next parameter that we supplied, parameters, only has meaning for Spark, not for 3DIAX. 3DIAX will pass through any parameters inside parameters to the 3rd-party service. In this case there is only one parameter that Spark understands for this operation: whether it should repair all defects it finds or just the first one. We will repair them all for this tutorial.

The final parameter, callback, tells 3DIAX where to send a request when this operation has status updates. This parameter is optional - we could just rely on polling to get information about the progress of the operation. However, it is much better to streamline our operations by supplying a publicly-addressable URL that 3DIAX can request. 3DIAX will do so for any status updates - task progress, errors, and completion. What updates are sent are up to Spark. A 3rd party may have many frequent status updates or none. The only gauranteed updates are for errors or for completion.

Getting updates

In the case of Spark, we only get completion and error callbacks. When a callback request is made it would look like this:

POST http://myservice.com/healing_complete?model=squirtle
Content-Type: application/json
{
    "status"    : "complete",
    "uri"       : "https://integrations.authentise.com/operation/aaa-bbb/"
}

As you can see, on status updates the callback will contain the value of the status and the URI of the operation that had the update. You can then GET the operation to find out any additional information including the result of the model healing task. You can also poll the operation URI for status instead of relying on callbacks. Either way, an operation resource looks like this:

GET https://integrations.authentise.com/operation/aaa-bbb/
Content-Type: application/json
{
    "status"    : "complete",
    "result"    : "https://models.authentise.com/model/xxx-yyy/",
    "service"   : "https://integrations.authentise.com/service/f23fc23e-4ef7-4c06-bf76-7930e00dbc22/",
    "inputs"    : {
        "model" : "https://models.authentise.com/model/abc-123/",
    },
    "outputs"   : {
        "content"   : "https://prod-gigan-results.s3.amazonaws.com/111-222-333/",
    },
    "parameters": {
        "all"   : true
    },
    "results"   : "https://models.authntise.com/model/xxx-yyy/",
    "callback": {
        "url"       : "http://myservice.com/healing_complete?model=squirtle",
        "method"    : "POST",
    }
}

Getting results

The operation resource contains all the parameters that we provided on creation, but now also includes a status field and a result field. When the operation is completed, the status field will be set to complete. Also upon completion the result will contain the URI for a new model resource that was created in 3DIAX and contains the model in its healed form. We can go ahead and get the information on that model...

GET https://models.authentise.com/model/xxx-yyy/
Content-Type: application/json
{
    "content"   :  "https://dev-hoth-models.s3.amazonaws.com:443/f15830fc-c1bb-4d00-ac4f-f43d70119581?Signature=a3Df...",
    ...
}

I have left out the rest of the resource as it is not too interesting. The important part is the content. This is where you can download the contents of the repaired model file. You can also use this resource directly with other 3DIAX services including snapshots, repositioning, slicing, scaling, and streaming to your printer.

So, how did the repair work out? You be the judge.

../_images/repaired-squirtle.png

Looks like it worked out just great! Spark was able to identify the various polygons missing at different locations and introduce them to make the model manifold. Nice work Spark! Of course, if it had not worked out you could always switch to any one of our other service providers. This gives you the freedom to choose any service that works best for your use case without having to learn or implement their API.

We hope you enjoy using 3DIAX and the growing list of partners providing services. Now go make something!