Rendering with image on-demand (preview)

You can use Forma Render's HTTP API to request images of your products and environments and to integrate Forma Render shots into other on-demand solutions.

You can find default settings and sample scripts in your Samples folder.

Note

Forma Render does not provide caching, provisioning, scheduling, billing, or monetization.

The image on-demand API is an experimental feature. You can send feedback about your experience to your Unity support contact.

Enabling the sample HTTP API in your project

To enable the API in your project:

  1. In your project, select Unity Package Manager > Forma Render.
  2. Expand the Samples section.
  3. Install the sample scripts.
  4. Go to Samples > Forma Render > {version} > Sample Scripts > Runtime > ImageOnDemand.
  5. Copy the FormaRenderImageOnDemand script from the ImageOnDemand folder.
  6. Add this script to any GameObject in your project.
  7. Select Play.
Note

A second sample script FormaImageOnDemand gives you complete control over the image on-demand pipeline. This script is fully customizable and uses only the open source code from Forma, but it does not support custom views, domes, AOVs, and reflection maps.

Using the sample HTTP API

Important

You cannot use spaces in HTTP API arguments. You must replace any spaces in your arguments with %20.

To use the API, access a web browser and go to http://127.0.0.1:8080/img?job=w=1920,h=1080. The browser returns the default view of your product as a .jpg image that is 1920 pixels wide and 1080 pixels tall.

Using views as shot templates

A view argument is an existing, valid shot metadata (.json) in your Forma Render Shot folder.

To use post-processing and dome settings from the HTTP API, your query must refer to a valid view argument with the same post-processing and dome settings.

To use views as shot templates:

  1. Take a shot in Forma Render with the post-processing and dome settings you want.
  2. Rename your shot. For example, my_awesome_shot.
  3. With the HTTP API, request an image in the format http://127.0.0.1:8080/img?job=w=1920,p=Aviera,view=my_awesome_shot,features=CarPaint_Aqua+EXT_Rear_Spoiler_Down, with the new shot name as the view argument.
  4. Replace any spaces in your view argument with %20.

HTTP API details

Typical HTTP queries have the http://127.0.0.1:8080/img?job=w=1920,p=Aviera,features=CarPaint_Aqua+EXT_Rear_Spoiler_Down format.

Each argument is separated by , and each key and value is separated by =.

Available arguments are:

  • w=width (px)
  • h=height (px)
  • p=product (required when using the f:features argument)
  • f=features (Forma feature codes separated by +)
  • v=view (a valid shot)
  • s=stage
  • d=dome
  • bp=backplate
  • rm=reflectionmap
  • c=camera
  • a=accumulation (jittered accumulation values)
  • ss=supersampling (for a uniform grid)
  • cw=cameraWaypoint (for multi-location cameras)
  • cpos=cameraPosition (vector3 position values separated by +)
  • crot=cameraRotation (vector4 quaternion values separated by +)
  • fov=fieldOfView
  • 360=panorama
  • rts=renderTileSize (for performance optimization)
  • hdr=highDynamicRange
  • aov=arbitraryOutputVariable (a valid AOV found in the Forma Render UI)
  • pt=pathTracing
Note

The arguments cameraPosition and cameraRotation cannot be used individually. You must use both or neither.

HTTP API tips

Balancing image quality and speed

By default, the API uses Subpixel Morphological Antialiasing (SMAA). This provides the fastest results with the best quality, and is equivalent to passing the arguments accumulation=1 and supersampling=1.

To access images with Medium quality in Forma Render, pass the arguments accumulation=5 and supersampling=2. Depending on the complexity of the model, this returns a total of 5x4 samples per pixel (20X) at around 100ms.

Accumulation and Quality settings

The API inherits the settings from the Forma Render Settings menu, which you can access to change the Accumulation and Quality settings. You can provide your settings via a .json file.

By default, Forma Render stores settings in your My Documents > Render Studio folder. To override this default location, change the projectFolder value in the RenderStudioSettings.json file at the root of your project.