.. _3diax-integrations-file-conversion: Integrations: File Conversions ================================================== 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 `file-conversion` service to convert various 3D model file formats to other formats. Service Providers -------------------------------------------------- See Serice Providers listing in ref:`_3diax-model-healing` @Far TODO: make a link here Creating an Operation -------------------------------------------------- File Conversions are performed by requesting an operation through a third party. To create a new operation we send a ``POST`` request to the ``/operation/`` API endpoint with the following example payload: .. sourcecode:: json { "service": "https://data.authentise.com/service/5e2abb98-c46a-4770-a4ca-b0e11193d10e/", "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 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 the File Converter is marked as a ``file-conversion`` 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, the File Converter 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 :ref:`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: .. sourcecode:: shell curl "https://data.authentise.com/operation/" \ -X POST \ -u ":" \ -H "Content-Type: application/json" \ -d '{ "service": "https://data.authentise.com/service/5e2abb98-c46a-4770-a4ca-b0e11193d10e/", "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 ``file-conversion`` 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: .. sourcecode:: shell curl "https://data.authentise.com/operation/73d4f855-6691-4ae3-bad7-e125550ad3bf/" \ -u ":" \ -H "Content-Type: application/json" The response to this request looks like this: .. sourcecode:: json { "uri": "https://data.authentise.com/operation/73d4f855-6691-4ae3-bad7-e125550ad3bf/", "service": "https://data.authentise.com/service/5e2abb98-c46a-4770-a4ca-b0e11193d10e/", "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 the File Converter. .. sourcecode:: json { "uri": "https://data.authentise.com/operation/73d4f855-6691-4ae3-bad7-e125550ad3bf/", "service": "https://data.authentise.com/service/5e2abb98-c46a-4770-a4ca-b0e11193d10e/", "inputs": { "model": "https://data.authentise.com/model/da38a1fb-bb84-4f3c-aaae-a545f1bd7dff/" }, "status": "error", "outputs": { "title": "Unable to convert requested model file - the file contains invalid data", "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. .. sourcecode:: json { "uri": "https://data.authentise.com/operation/bc53d17e-dad6-4bc5-af4e-b6f9806a1fac/", "service": "https://data.authentise.com/service/5e2abb98-c46a-4770-a4ca-b0e11193d10e/", "inputs": {"model": "https://data.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://data.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 conversion 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. .. sourcecode:: shell curl "https://data.authentise.com/model/9faa7c75-67ea-4331-82e4-fac56055da06/" \ -u ":" \ -H "Content-Type: application/json" The response from the model endpoint will look like this: .. sourcecode:: json { "uri": "https://data.authentise.com/model/9faa7c75-67ea-4331-82e4-fac56055da06/", "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. .. sourcecode:: shell 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 converted model in your choice of software: .. image:: images/logo-default-render.png :scale: 25 % :align: center :alt: Authentise Logo Conclusion ---------- This example showed how to use 3DIAX to convert from one model file format to another, in this case