Image on-demand (preview)

Forma Render includes an HTTP API that your application can use to request images of your products and environments. The API lets you integrate shots from Forma Render into any other image on-demand solution.

For convenience, you can find default settings and a sample script in the Samples folder for this package.

Note

Forma Render does not currently provide caching, provisioning, or scheduling, billing, or monetization. The Image on-demand API is an experimental feature. Please send feedback about your experience to your Unity support contact.

Enable the sample HTTP API in your project

  1. Within your project, from the Unity Package Manager, select the Forma Render package, expand the Samples section from the right panel, and install the sample scripts.
  2. In your project assets you should now find Samples > Forma Render > {version} > Sample Scripts > RenderOnDemand; this folder contains one script called RenderOnDemandHttpService.
  3. Add this script to any GameObject in your project.
  4. Press Play.

Use the sample HTTP API

Important

You cannot use spaces in arguments for the HTTP API. Since camera and stage names often contain spaces, you must replace any spaces in the argument with %20. Submitting arguments with spaces will cause your arguments to fail in most browsers.

To use the API, follow these steps:

  1. Make sure Forma Render is enabled and enter Play mode. You should see an overlay of performance statistics for the HTTP service with all values at 0 (until an image query is made).
  2. From a web browser on your machine, navigate to the address http://127.0.0.1/img?job=w=1920,h=1080.
  3. The browser returns the default view of your product as a .jpg image that is 1920 pixels wide and 1080 pixels high.

HTTP API details

Typical HTTP queries have this format:http://127.0.0.1/img?job=w=1920,p=Aviera,features=CarPaint_Aqua+EXT_Rear_Spoiler_Down Each argument is separated by , and each key and value separated by =. Available arguments are:

  • w=width (px)
  • h=height (px)
  • p=product (required when using the features argument)
  • f=features (Forma feature codes '+' separated, product argument is required)
  • v=view (a valid shot)
  • s=stage
  • c=camera
  • a=accumulation (jittered)
  • ss=supersampling (uniform grid)
  • cw=cameraWaypoint (for multi-location cameras)
  • cpos=cameraPosition (position '+' separated)
  • crot=cameraRotation (quaternion '+' separated)
  • 360=panorama
  • rts=renderTileSize (performance opt)

Use views as shot templates

You can use all post-processing and dome settings from the HTTP API as long as your query refers to a valid view that contains those settings. A view is an existing valid shot metadata (.json) in the Forma Render Shots document folder.

  1. Take a shot in Forma Render as you normally would with the desired dome and post-processing.
  2. Rename it to a memorable name, such as my_awesome_shot.
  3. Using the HTTP API, request an image in the format http://127.0.0.1/img?job=w=1920,p=Aviera,view=my_awesome_shot,features=CarPaint_Aqua+EXT_Rear_Spoiler_Down which passes my_awesome_shot as the view argument.
  4. Make sure you replace any spaces in your view name with %20 when making the API request.

HTTP API tips

Balancing image quality and speed

By default, the API uses Subpixel Morphological Antialiasing (SMAA), which gives the fastest result with good quality. Equivalent to passing accumulation=1 and ss=1.

To access images with the Medium level of quality in Forma Render, provide the accumulation=5 and supersampling=2 arguments. This returns a total of 5 x 4 samples per pixel (20X) at around 100ms (depending on the complexity of the model).

Accumulation and Quality settings

The API uses your settings from the Forma Render Settings menus. You can also control accumulation and quality settings from the Settings menus. All settings can be provided via .json files.

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