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.

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.

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

Example request

{
    "name"                      : "Authentise's epic logo",
    "allowed_transformations"   : {
        "resize"                : True,
        "rotation"              : True,
    },
    "callback"                  : {
        "method"                : "GET",
        "url"                   : "https://my.domain.net/some/location",
    }
}
Response Headers:
 
  • Location – The URI of the model where information about the model can be requested. Ex: /model/<uuid>/
  • 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 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.

GET /model/<uuid>/

Get information about a model.

Permissions:

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

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

Query Parameters:
 
  • name – a partial name of models to search for. accepts the wildcard character: “*”.
  • status – a status of models to search for.
  • created – a creation date to search for models.
  • updated – an updated date to search for models.
  • 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
Response JSON Array of Objects:
 
  • models (string) – 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 GET /model/<uuid>/, along with the resource URI.
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.

Request JSON Array of Objects:
 
  • transformations.[].type (string) – Required The type of operation being applied. Valid types are bracket, auto-rotate, rotate, auto-scale, scale, auto-translate and translate.
  • transformations.[].parametersBrackets (object) – A JSON object with the valid transformation parameters for the bracket type.
  • transformations.[].parametersBrackets.width (float) – Required for ``bracket`` type. The width (X and Y) of the bracket, in mm.
  • transformations.[].parametersBrackets.gap (float) – Required for ``bracket`` type. The distance from the bracket to the model, in mm.
  • transformations.[].parametersBrackets.thickness (float) – Required for ``bracket`` type. The thickness (Z) of the bracket, in mm.
  • transformations.[].parametersAutoRotate (object) – A JSON object with the valid transformation parameters for the auto-rotate type.
  • transformations.[].parametersAutoRotate.build.x (float) – Required for ``auto-rotate`` type. The size of the build volume in mm in the X direction.
  • transformations.[].parametersAutoRotate.build.y (float) – Required for ``auto-rotate`` type. The size of the build volume in mm in the Y direction.
  • transformations.[].parametersAutoRotate.build.z (float) – Required for ``auto-rotate`` type. The size of the build volume in mm in the Z direction.
  • transformations.[].parametersRotate (object) – 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.
  • transformations.[].parametersRotate.x (float) – Required for ``rotate`` type. The amount of rotation, in degrees, about the X axis. This rotation is applied first.
  • transformations.[].parametersRotate.y (float) – Required for ``rotate`` type. The amount of rotation, in degrees, about the Y axis. This rotation is applied second.
  • transformations.[].parametersRotate.z (float) – Required for ``rotate`` type. The amount of rotation, in degrees, about the Z axis. This rotation is applied last.
  • transformations.[].parametersAutoScale (object) – A JSON object with the valid transformation parameters for the auto-scale type.
  • transformations.[].parametersAutoScale.build.x (float) – Required for ``auto-scale`` type. The size of the build volume in mm in the X direction.
  • transformations.[].parametersAutoScale.build.y (float) – Required for ``auto-scale`` type. The size of the build volume in mm in the Y direction.
  • transformations.[].parametersAutoScale.build.z (float) – Required for ``auto-scale`` type. The size of the build volume in mm in the Z direction.
  • transformations.[].parametersScale (object) – A JSON object with the valid transformation parameters for the scale type.
  • transformations.[].parameterScale.x (float) – Required for ``scale`` type. The percent scaling in the Z axis.
  • transformations.[].parameterScale.y (float) – Required for ``scale`` type. The percent scaling in the Y axis.
  • transformations.[].parameterScale.z (float) – Required for ``scale`` type. The percent scaling in the Z axis.
  • transformations.[].parametersTranslate (object) – A JSON object with the valid transformation parameters for the translate type.
  • transformations.[].parametersTranslate.x (float) – Required for ``translate`` type. The translation in mm in the Z direction from the current location of the model.
  • transformations.[].parametersTranslate.y (float) – Required for ``translate`` type. The translation in mm in the Y direction from the current location of the model.
  • transformations.[].parametersTranslate.z (float) – Required for ``translate`` type. The translation in mm in the Z direction from the current location of the model.
Request JSON Object:
 
  • callback.url (string) – The URL to callback to once model processing is finished.
  • callback.method (string) – The HTTP method for the callback to use when calling back.
Response Headers:
 
  • Location – The URI of this model where information about the model can be requested. Example: /model/1234-abcde/

Example request

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"
    }
}
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.

Request JSON Object:
 
  • samples (int) – The number of samples to use in requesting the snapshot. Min 0, Max 5000. Higher numbers will take longer but yield better-looking results.
  • layer (int) – The number of the layer of the model to show. This allows you to visualize the model when partially printed.
  • color (string) – The color in HTML color codes, to use for the material the model is made of. Example: #AFAA75
  • height (int) – The height of the image in pixels. Min 0, Max 768.
  • width (int) – The width of the image in pixels. Min 0, Max 1024.
  • x (float) – The position of the camera on the X axis
  • y (float) – The position of the camera on the Y axis
  • z (float) – The position of the camera on the Z axis
  • u (float) – The camera direction vector’s X component
  • v (float) – The camera direction vector’s Y component
  • w (float) – The camera direction vector’s Z component
  • callback.url (string) – The URL to callback to once model processing is finished.
  • callback.method (string) – The HTTP method for the callback to use when calling back.
Response Headers:
 
  • Location – The URI of the snapshot where information about the snapshot can be requested. Example: /model/<uuid>/snapshot/<uuid>/
GET /model/<uuid>/snapshot/<uuid>/

Get information about the snapshot.

Response JSON Object:
 
  • samples (int) – The number of samples to use in requesting the snapshot. Min 0, Max 5000. Higher numbers will take longer but yield better-looking results.
  • layer (int) – The number of the layer of the model to show. This allows you to visualize the model when partially printed.
  • color (string) – The color, in HTML color codes, to use for the material the model is made of. Ex: #AFAA75
  • height (int) – The height of the image in pixels. Min 0, Max 768.
  • width (int) – The width of the image in pixels. Min 0, Max 1024.
  • x (float) – The position of the camera on the X axis.
  • y (float) – The position of the camera on the Y axis.
  • z (float) – The position of the camera on the Z axis.
  • u (float) – The camera direction vector’s X component.
  • v (float) – The camera direction vector’s Y component.
  • w (float) – The camera direction vector’s Z component.
  • content (string) – The URL of a link at which a the snapshot can be downloaded.