.. _3diax-reference:

3DIAX API Reference
=============================

Authentise's 3DIAX is designed to make it easier for users to maintain a large database of model data in the cloud. It is also an entryway into Authentise's other services. The specification for the various endpoints are designed to be open so that other providers could create a service that adheres to the same specification and interoperate with any service that works with Authentise.

There are a few concepts involved with the Model service.
This is the service for storing and manipulating models. It's designed to be a location where users can dump any number of models and keep them stored indefinitely. From this service users can also slice and print models.

.. ramldoc:: https://data.authentise.com/model


.. http:post:: /model/

    Create a new model representation. A model is currently composed of a single STL file but this may be expanded in the future. A model resource is owned by the user who uploaded it. A certain amount of processing happens after uploading an STL, as such a callback URL can be provided, which will be called once processing is finished.

    If a valid model is uploaded the system will produce a default snapshot of the model.

    :<json string name: **Required.** The name of the model. This can be any string and should be meaningful to the user.
    :<json obj allowed_transformations: Optional. The transformations that are allowed on this model.
    :<json boolean allowed_transformations.resize: Optional. True if this model is allowed to be resized automatically by other services. Default: False.
    :<json boolean allowed_transformations.rotation: Optional. True if this model is allowed to be rotated automatically by other services. Default: False.
    :<json obj callback: Optional. The URL to call when this model changes states.
    :<json string callback.url: Optional. The URL to request for the callback.
    :<json string callback.method: Optional. The method to use for the request, one of GET, POST or PUT.

    **Example request**

    .. sourcecode:: javascript

        {
            "name"                      : "Authentise's epic logo",
            "allowed_transformations"   : {
                "resize"                : True,
                "rotation"              : True,
            },
            "callback"                  : {
                "method"                : "GET",
                "url"                   : "https://my.domain.net/some/location",
            }
        }

    :>header Location: The URI of the model where information about the model can be requested. Ex: `/model/<uuid>/`
    :>header X-Upload-Location: The URL where the data for the model can be uploaded. Ex: `https://s3.amazonaws.com/authentise-models/?signature=foobar`

    Take note that when you upload your STL file to the X-Upload-Location that you must set the Content-Type header to ``application/octet-stream``, otherwise the service will return 403 and indicate a signature mismatch.

    The callback will be requested on state change, particularly after the model has been uploaded and analyzed. The callback will work according to the :ref:`callback-service`. After analysis the callback will indicate status has changed to either ``error`` or ``processed`` depending on whether or not a valid model file was provided.


.. http:get:: /model/<uuid>/

    Get information about a model.

    **Permissions**:

    * Model owner
    * System Admins
    * Authentise Services

    :>json bool analyses.manifold: A boolean representing if the model is manifold.  If the model is not manifold, there is a higher likelihood that slicing will fail.
    :>json string callback_method: The HTTP method to use when requesting the callback URL. One of GET or POST
    :>json string callback_uri: The URL to request on status change for this model
    :>jsonarr string children: An array of model URIs from which are derived from this model.
    :>json string content: The URL of a link at which a the model can be downloaded.
    :>json datetime created: The date and time the model was created.
    :>json string name: The name of the model.
    :>jsonarr string parents: An array of model URIs from which this model is derived.
    :>json float size.x: The size of the model in the X direction in millimeters
    :>json float size.y: The size of the model in the Y direction in millimeters
    :>json float size.z: The size of the model in the Z direction in millimeters
    :>json string snapshot: The URL of the snapshot resource that was automatically generated for this model
    :>json string status: The current status of the model processing. Can be one of `processing`, `processed`, or `error`.
    :>json float surface_area: The surface area of the model in millimeters
    :>json datetime updated: The datetime of the last time this model was updated
    :>json URL upload-location: If the model has not been uploaded this will contain a URL where the model can be uploaded
    :>json URI uri: The URI of this model
    :>json URI user_uri: The URI of the owner and creator of the model
    :>json float volume: The volume of the model in millimeters



    :>json datetime updated: The date and time the model was last updated.


.. http:get:: /model/

    Get a list of all models the requester has access to based on query filters.

    :query name: a partial name of models to search for.  accepts the wildcard character: "*".
    :query status: a status of models to search for.
    :query created: a creation date to search for models.
    :query updated: an updated date to search for models.

    :query sort: one of the other queryable parameters, such as ``name``, ``status``, ``created`` or ``updated``. accepts ``+`` or ``-`` to indicate order of the sort. Parameters may be strung together, separated by commas. Example: ``+status, +created, -name`` or ``name, created``

    :>jsonarr string models: A list of models which match the query filter and which the caller has permissions. Each item in the list has the same data as :http:get:`/model/<uuid>/`, along with the resource URI.

.. ifconfig:: releaselevel == 'dev'

    .. http:post:: /model/pack/

        API to pack multiple models into one model. Creates a new model resource which is a child of the input models.

        :<json bool auto_place: **Required** Automatically determines the best placement of models if ``True``.
        :<json int bed.x: The size in X of the bed to fit models. Only **Required** if using auto_place.
        :<json int bed.y: The size in Y of the bed to fit models. Only **Required** if using auto_place.

        :<jsonarr string [].model: **Required** The URI of a model to pack.
        :<jsonarr string [].offset.x: The offset in X from the bed center to the center of the model where the model should be placed. Only **Required** if not using auto_place.
        :<jsonarr string [].offset.y: The offset in Y from the bed center to the center of the model where the model should be placed. Only **Required** if not using auto_place.

        :<json string callback.url: The URL to callback to once model processing is finished.
        :<json string callback.method: The HTTP method for the callback to use when calling back.

        :>header Location: The URI of this model where information about the model can be requested. Example: `/model/1234-abcde/`

.. http:post:: /model/<uuid>/transformation/

    API to apply a transformation to a model. Creates a new model resource which is a child of the input model. This endpoint takes in an array of transformations, ordered in the order the transformations should be applied. Each transformation type has a corresponding parameter set that must be included with the type.

    :<jsonarr string transformations.[].type: **Required** The type of operation being applied. Valid types are ``bracket``, ``auto-rotate``, ``rotate``, ``auto-scale``, ``scale``, ``auto-translate`` and ``translate``.

    :<jsonarr object transformations.[].parametersBrackets: A JSON object with the valid transformation parameters for the ``bracket`` type.
    :<jsonarr float transformations.[].parametersBrackets.width: **Required for ``bracket`` type**. The width (X and Y) of the bracket, in mm.
    :<jsonarr float transformations.[].parametersBrackets.gap: **Required for ``bracket`` type**. The distance from the bracket to the model, in mm.
    :<jsonarr float transformations.[].parametersBrackets.thickness: **Required for ``bracket`` type**. The thickness (Z) of the bracket, in mm.

    :<jsonarr object transformations.[].parametersAutoRotate: A JSON object with the valid transformation parameters for the ``auto-rotate`` type.
    :<jsonarr float transformations.[].parametersAutoRotate.build.x: **Required for ``auto-rotate`` type**. The size of the build volume in mm in the X direction.
    :<jsonarr float transformations.[].parametersAutoRotate.build.y: **Required for ``auto-rotate`` type**. The size of the build volume in mm in the Y direction.
    :<jsonarr float transformations.[].parametersAutoRotate.build.z: **Required for ``auto-rotate`` type**. The size of the build volume in mm in the Z direction.

    :<jsonarr object transformations.[].parametersRotate: A JSON object with the valid transformation parameters for the ``rotate`` type. The rotations are applied in a specific order: The X rotation is applied first, then the Y rotation, and finally the Z rotation.
    :<jsonarr float transformations.[].parametersRotate.x: **Required for ``rotate`` type**. The amount of rotation, in degrees, about the X axis. This rotation is applied first.
    :<jsonarr float transformations.[].parametersRotate.y: **Required for ``rotate`` type**. The amount of rotation, in degrees, about the Y axis. This rotation is applied second.
    :<jsonarr float transformations.[].parametersRotate.z: **Required for ``rotate`` type**. The amount of rotation, in degrees, about the Z axis. This rotation is applied last.

    :<jsonarr object transformations.[].parametersAutoScale: A JSON object with the valid transformation parameters for the ``auto-scale`` type.
    :<jsonarr float transformations.[].parametersAutoScale.build.x: **Required for ``auto-scale`` type**. The size of the build volume in mm in the X direction.
    :<jsonarr float transformations.[].parametersAutoScale.build.y: **Required for ``auto-scale`` type**. The size of the build volume in mm in the Y direction.
    :<jsonarr float transformations.[].parametersAutoScale.build.z: **Required for ``auto-scale`` type**. The size of the build volume in mm in the Z direction.

    :<jsonarr object transformations.[].parametersScale: A JSON object with the valid transformation parameters for the ``scale`` type.
    :<jsonarr float transformations.[].parameterScale.x: **Required for ``scale`` type**. The percent scaling in the Z axis.
    :<jsonarr float transformations.[].parameterScale.y: **Required for ``scale`` type**. The percent scaling in the Y axis.
    :<jsonarr float transformations.[].parameterScale.z: **Required for ``scale`` type**. The percent scaling in the Z axis.

    :<jsonarr object transformations.[].parametersTranslate: A JSON object with the valid transformation parameters for the ``translate`` type.
    :<jsonarr float transformations.[].parametersTranslate.x: **Required for ``translate`` type**. The translation in mm in the Z direction from the current location of the model.
    :<jsonarr float transformations.[].parametersTranslate.y: **Required for ``translate`` type**. The translation in mm in the Y direction from the current location of the model.
    :<jsonarr float transformations.[].parametersTranslate.z: **Required for ``translate`` type**. The translation in mm in the Z direction from the current location of the model.

    :<json string callback.url: The URL to callback to once model processing is finished.
    :<json string callback.method: The HTTP method for the callback to use when calling back.

    :>header Location: The URI of this model where information about the model can be requested. Example: `/model/1234-abcde/`

    **Example request**

    .. sourcecode:: javascript

        POST /model/<uuid>/transformation/
        {
            "transformations": [{
                type: “bracket”,
                parametersBrackets: {
                    width: 10mm,
                    grap: 2mm,
                    thickness: 2mm
                }
            },{
                type: “auto-rotate”,
                parametersAutoRotate: {
                    build: {
                        x: 100,
                        y: 160,
                        z: 230
                    }
                }
            },{
                type: “rotate”,
                parametersRotate: {
                    x: 23,
                    y: 10,
                    z: 12
                }
            },{
                type: "auto-scale”,
                parametersAutoScale: {
                    x: 45,
                    y: 0,
                    z: 45
                }
            },{
                type: “scale”,
                parametersScale: {
                    build: {
                        x: 10,
                        y: 10,
                        z: 10
                    }
                }
            },{
                type: “translate”,
                parametersTranslate: {
                    x: 100,
                    y: 20,
                    z: 0
                }
            },{
                type: “translate”
            }],
            "callback": {
                "url": "https://somesite.com/a/callback/url/",
                "method": "GET"
            }
        }

.. http:post:: /model/<uuid>/snapshot/

    Create a snapshot of a given model based on request parameters. This can be a potentially long process, so a URL to check the progress and download the snapshot is given as the response.

    The values for x, y, z and u, v, w are optional. If they are not provided the system will attempt to produce a snapshot that frames the model well. We call this the default snapshot and a snapshot from this position will be produced for every valid model that is uploaded.

    :<json int samples: The number of samples to use in requesting the snapshot. Min 0, Max 5000. Higher numbers will take longer but yield better-looking results.
    :<json int layer: The number of the layer of the model to show. This allows you to visualize the model when partially printed.
    :<json string color: The color in HTML color codes, to use for the material the model is made of. Example: `#AFAA75`
    :<json int height: The height of the image in pixels. Min 0, Max 768.
    :<json int width: The width of the image in pixels. Min 0, Max 1024.
    :<json float x: The position of the camera on the X axis
    :<json float y: The position of the camera on the Y axis
    :<json float z: The position of the camera on the Z axis
    :<json float u: The camera direction vector's X component
    :<json float v: The camera direction vector's Y component
    :<json float w: The camera direction vector's Z component

    :<json string callback.url: The URL to callback to once model processing is finished.
    :<json string callback.method: The HTTP method for the callback to use when calling back.

    :>header Location: The URI of the snapshot where information about the snapshot can be requested. Example: `/model/<uuid>/snapshot/<uuid>/`

.. http:get:: /model/<uuid>/snapshot/<uuid>/

    Get information about the snapshot.

    :>json int samples: The number of samples to use in requesting the snapshot. Min 0, Max 5000. Higher numbers will take longer but yield better-looking results.
    :>json int layer: The number of the layer of the model to show. This allows you to visualize the model when partially printed.
    :>json string color: The color, in HTML color codes, to use for the material the model is made of. Ex: `#AFAA75`
    :>json int height: The height of the image in pixels. Min 0, Max 768.
    :>json int width: The width of the image in pixels. Min 0, Max 1024.
    :>json float x: The position of the camera on the X axis.
    :>json float y: The position of the camera on the Y axis.
    :>json float z: The position of the camera on the Z axis.
    :>json float u: The camera direction vector's X component.
    :>json float v: The camera direction vector's Y component.
    :>json float w: The camera direction vector's Z component.

    :>json string content: The URL of a link at which a the snapshot can be downloaded.