Partner Integrations: ProtoTech Solutions 3DPDF¶

Provider Services¶

First we need to figure out what services are available and find the 3DPDF service. We can do this by hitting the services endpoint.

To do this we need to authenticate. You can use the placeholders in the example curl command. You can also 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 similar to the following:

{
  "resources": [{
    "uri": "https://data.authentise.com/service/09e6129e-cc0b-4634-8492-96e08cc3893a/",
    "name": "ODIN Model Transformation",
    "description": "ODINs Model Transformation",
    "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"
  }]
}

In the response JSON we can see the service that we want to use: 3DPDF converter by Protech Solutions. So let’s take note of the service URI which is: https://data.authentise.com/service/b9ba4ce4-0f49-45d8-ab48-19b44e20614a/.

Creating an Operation¶

To create an operation we need a model. You can see the Tutorial for information on how to upload a model. For this example we will use https://models.authentise.com/model/da38a1fb-bb84-4f3c-aaae-a545f1bd7dff/ as the model URI. We also need the service URI that we got in the previous step.

To create a new operation we hit the operation API endpoint with the following, as an example payload for the POST request:

{
  "service": "https://data.authentise.com/service/b9ba4ce4-0f49-45d8-ab48-19b44e20614a/",
  "inputs": {
    "model": "https://models.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 which is the service URI. The input parameters contain specific parameters to the type of service. For example: A file conversion 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 3DPDF is marked as a file-conversion type, which will require the parameters like the example payload.

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, 3DPDF does not require any parameters. However, 3DIAX requires the parameters object in the payload to create an operation so we include an empty set.

We can include an optional parameter callback for the operation which will be called when the operation is complete. This is useful as it avoids 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 using 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/b9ba4ce4-0f49-45d8-ab48-19b44e20614a/", "inputs": { "model": "https://models.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-transformarion 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 can use: 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"

Using this request a response would look like this:

{
  "uri": "https://data.authentise.com/operation/73d4f855-6691-4ae3-bad7-e125550ad3bf/",
  "service": "https://data.authentise.com/service/b9ba4ce4-0f49-45d8-ab48-19b44e20614a/",
  "inputs": {
    "model": "https://models.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 Prototech.

{
  "uri": "https://data.authentise.com/operation/73d4f855-6691-4ae3-bad7-e125550ad3bf/",
  "service": "https://data.authentise.com/service/b9ba4ce4-0f49-45d8-ab48-19b44e20614a/",
  "inputs": {
    "model": "https://models.authentise.com/model/da38a1fb-bb84-4f3c-aaae-a545f1bd7dff/"
  },
  "status": "error",
  "outputs": {
    "title": "Unable to convert requested model file to 3DPDF",
    "code": "failed conversion"
  },
  "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/b9ba4ce4-0f49-45d8-ab48-19b44e20614a/"}
  "inputs": {"model": "https://models.authentise.com/model/da38a1fb-bb84-4f3c-aaae-a545f1bd7dff/"},
  "status": "complete",
  "outputs": {
    "type": "pdf",
    "content": "https://pts3dpdfbucket.s3.amazonaws.com/da38a1fb-bb84-4f3c-aaae-a545f1bd7dff?AWSAccessKeyId=AKIAJAHHABIBFQYVLGIQ&Expires=1452187869&Signature=ZmeyadUbHR%2BGTf8rX%2BN7kcb3dro%3D"
  },
  "results": "https://models.authentise.com/model/9faa7c75-67ea-4331-82e4-fac56055da06/"
}

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

curl "https://models.authentise.com/model/9faa7c75-67ea-4331-82e4-fac56055da06/" \
  -u "<api_token>:<api_secret>" \
  -H "Content-Type: application/json"

The response from the model endpoint will look like this:

{
  "uri": "https://models.authentise.com/model/9faa7c75-67ea-4331-82e4-fac56055da06/",
  "name": "Authentise Logo",
  "type": "pdf",
  "content": "https://prod-hoth-models.s3.amazonaws.com:443/9faa7c75-67ea-4331-82e4-fac56055da06?Signature=hzjOUZuXSiZp1LBAtKJrJyzXYPA%3D&Expires=1452188134&AWSAccessKeyId=AKIAIXWYOAMWDK2U3WJQ",
  "status": "inoperable"
}

You can see the download URL in the response payload. The status is set to inoperable because 3DIAX is unable to perform model transformations on a PDF. We can make a GET request against that URL to download the new 3DPDF file.

curl https://prod-hoth-models.s3.amazonaws.com:443/9faa7c75-67ea-4331-82e4-fac56055da06?Signature=hzjOUZuXSiZp1LBAtKJrJyzXYPA%3D&Expires=1452188134&AWSAccessKeyId=AKIAIXWYOAMWDK2U3WJQ \
  -o AuthentiseLogo.pdf

Now we can open the transformed model in a PDF viewer that supports 3DPDF’s, like Adobe Acrobat reader, for example:

Note that 3DPDF files do not secure your model. They are a way of including a 3D model inside a PDF file but still includes the model data.

Conclusion¶

Now you have your finished transformation using 3DPDF. Using the information in this tutorial you can learn to use any service that is being provided in 3DIAX. You can read more about ProtoTech Solution’s 3DPDF service here https://prototechsolutions.com/3d-products/3ds-max/3d-pdf-exporter/.