How to author a job

Adobe Substance 3D Automation Service REST API accepts job specifications as a JSON document.

This JSON document is authored by a user or developer to describe how this service should retrieve your assets, perform manipulations and rendering, and upload results.

This job description is specified as a directed acyclic graph of operations.

Walk-through on how to write a rendering job

In this example, we'll describe how to write a job which requests this service to download a Stager scene, render a camera bookmark and upload the resulting image.

Pre-requisites:

1. A stager scene, available as a pre-signed URL, such as this AWS S3 blob: https://some-bucket.s3.us-east-1.amazonaws.com/some/blob?TOKEN

2. A pre-signed URL to upload the rendered image, such as this Azure Blob: https://some.blob.core.windows.net/container/render.png?TOKEN

Operations

Let's write the operation we want the Substance 3D Automation Service to execute. We look at the API specs and determine the most appropriate operations.

1. Download scene

We'll use the operation https.download to instruct the service on how to retrieve our Stager scene. We gave this specific operation a name, step1-download.

"step1-download": {
  "type": "https.download",
  "parameters": {
    "uri": "https://some-bucket.s3.us-east-1.amazonaws.com/some/blob?TOKEN"
   },
   "output": {
      "type": "scene",
      "extension": ".ssg"
    }
  }
}
CopyCopied to your clipboard
1"step1-download": {
2  "type": "https.download",
3  "parameters": {
4    "uri": "https://some-bucket.s3.us-east-1.amazonaws.com/some/blob?TOKEN"
5   },
6   "output": {
7      "type": "scene",
8      "extension": ".ssg"
9    }
10  }
11}

Whenever we want to refer to the resulting file from this operation, we would use its' identifier step1-download. This is similar to variable assignment in programming languages.

2. Render scene

We'll use the operation scene.render to render the default camera in a Stager scene.

Many operations, like this one, accept a inputs object, which is further typed into scene, image, model or file. Formats accepted for each of these types are described in the OpenAPI spec.

In this instance, we've set .inputs.scene to step1-download. This means the file produced in operation step1-download is used as an input to the step2-render operation.

"step2-render": {
  "type": "scene.render",
  "inputs": {
    "scene": "step1-download"
  },
  "output": {
    "type": "scene",
    "extension": ".ssg"
  }
}
CopyCopied to your clipboard
1"step2-render": {
2  "type": "scene.render",
3  "inputs": {
4    "scene": "step1-download"
5  },
6  "output": {
7    "type": "scene",
8    "extension": ".ssg"
9  }
10}

3. Upload result

For uploading to Azure Blob, we use the operation https.azure.upload. If we were uploading to AWS S3, we'd use a generic https.upload operation.

Since we want to upload the rendering results, and knowing that render output is generated by the step step2-render, we set the inputs section of our upload operation to point to this file.

"step3-upload": {
  "type": "https.azure.upload",
  "parameters": {
    "uri": "https://some.blob.core.windows.net/multi/second.png?TOKEN"
  },
  "inputs": {
    "file": "step2-render"
  }
}
CopyCopied to your clipboard
1"step3-upload": {
2  "type": "https.azure.upload",
3  "parameters": {
4    "uri": "https://some.blob.core.windows.net/multi/second.png?TOKEN"
5  },
6  "inputs": {
7    "file": "step2-render"
8  }
9}

Putting it together

With each of the operations written, we can now combine them into a full job description as follows:

{
  "type": "multi.alpha",
  "spec": {
    "step1-download": {
      "type": "https.download",
      "parameters": {
        "uri": "https://some-bucket.s3.us-east-1.amazonaws.com/some/blob?TOKEN"
      },
      "output": {
        "type": "scene",
        "extension": ".ssg"
      }
    },
    "step2-render": {
      "type": "scene.render",
      "inputs": {
        "scene": "step1-download"
      },
      "output": {
        "type": "image",
        "extension": ".png"
      }      
    },
    "step3-upload": {
      "type": "https.azure.upload",
      "parameters": {
        "uri": "https://some.blob.core.windows.net/multi/second.png?TOKEN"
      },
      "inputs": {
        "file": "step2-render"
      }
    }
  }
}
CopyCopied to your clipboard
1{
2  "type": "multi.alpha",
3  "spec": {
4    "step1-download": {
5      "type": "https.download",
6      "parameters": {
7        "uri": "https://some-bucket.s3.us-east-1.amazonaws.com/some/blob?TOKEN"
8      },
9      "output": {
10        "type": "scene",
11        "extension": ".ssg"
12      }
13    },
14    "step2-render": {
15      "type": "scene.render",
16      "inputs": {
17        "scene": "step1-download"
18      },
19      "output": {
20        "type": "image",
21        "extension": ".png"
22      }      
23    },
24    "step3-upload": {
25      "type": "https.azure.upload",
26      "parameters": {
27        "uri": "https://some.blob.core.windows.net/multi/second.png?TOKEN"
28      },
29      "inputs": {
30        "file": "step2-render"
31      }
32    }
33  }
34}

This job, which will be executed as step1-download -> step2-render -> step3-upload can now be submitted to the Automation Service API. Once it completes, your render results will be available at the blob location you provided.

Conclusion

We hope this walkthrough helped in understanding how to author jobs for Substance 3D Automation Service. Users are provided with the flexibility to construct job descriptios with fairly complex graphs, which can include any supported operation. This allows performing multiple renders, file conversions, imports and manipulations as a single job.

Check our API specifications for 4 examples of jobs of varying complexity.

Last updated 4/18/2023

Was this helpful?

Yes

No