Render 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 provides an optional caching mechanism, but doesn't provide 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.

Enable 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.
  5. Copy the FormaRenderImageOnDemand script from the ImageOnDemand folder.
  6. Add this script to any GameObject in your project.
  7. Select Play.

To provide your FormaRenderImageOnDemand script with a different listening port on the command line, use -forma-render-iod-port 8090.

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.

Use 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?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.

Enable caching for the sample HTTP API in your project

To enable caching for the API in your project:

  1. Go to your project folder and open the FormaRenderSettings.json file.
  2. Add the following lines to your file:
  3. "iodUseCache": true to enable caching
  4. "iodL1CacheCapacityMB": 1024 to determine the cache capacity in megabytes

Use 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?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.

Set up a headless image server

Set up as a Windows service

To set up a headless image server through a Windows service:

  1. Go to the folder that contains the FormaRender executable.
  2. Run the following command: sc.exe create FormaRenderService start=auto binpath="c:\PathToBuild\FormaRender.exe -forma-render-iod -batchMode -logFile "c:\PathToLog\FormaRender.log"
  3. Open your c:\PathToBuild\FormaRenderSettings.json file.
  4. Make sure that "iodWindowsService"= true and "iodWindowsServiceName"= "FormaRenderService".

The Windows service installation depends on two sample scripts:

  • Plugins/RenderServicePlugin.dll
  • Runtime/FormaRenderWindowsServiceAdapter.cs

You must have both files to build your server. FormaRenderWindowsServiceAdapter must be added as a component to your scene.

Set up on hardware

To set up a headless image server on hardware:

  1. Install Microsoft Windows Datacenter 2022.
  2. Install the Nvidia driver.
  3. Set up autologin.
  4. Open ports 8080 and 8081 in the firewall.
  5. In the Task Scheduler, add the following task to run the script whenever a user logs in: c:\PathToBuild\FormaRender.exe -forma-render-iod -batchMode

To test your hardware connection, go to http://<your_ip>:8080/img?w=1920.

Set up on Google Cloud

To set up a headless image server on Google Cloud:

  1. Select a GPU instance with NVIDIA Tesla T4.
  2. Select Microsoft Windows Server 2016.
  3. Enable the Virtual Workstation (NVIDIA GRID).
  4. Install the Nvidia driver.
  5. Set up autologin.
  6. Install Nginx for Windows.
  7. Write a ngix configuration that proxies outside traffic from port 8081 to port 8080, and that maintains 127.0.0.1 as the Host header.
  8. In the Task Scheduler, add the following task to run the script whenever a user logs in: c:\PathToBuild\FormaRender.exe -forma-render-iod -batchMode

To test your hardware connection, go to http://<your_ip>:8080/img?w=1920.

Set up on Linux

Note

Raytracing is not supported on Linux.

To set up a headless image server on Linux:

  1. Select the latest Ubuntu LTS x64 image.
  2. Install GPU proprietary drivers (Nvidia).
  3. Run the application using the following command: sudo xvfb-run --auto-servernum --server-args='-screen 0 640x480x24' FormaRender -batchmode -force-vulkan

HTTP API details

Typical HTTP queries have the http://127.0.0.1:8080/img?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 , or +. When using f=features you must also use the p=product argument for the feature codes to apply correctly)
  • v=view (a valid shot)
  • s=stage
  • d=dome
  • bp=backplate
  • rm=reflectionmap
  • c=camera
  • cw=cameraWaypoint (for multi-location cameras)
  • cpos=cameraPosition (vector3 position values separated by , or +)
  • crot=cameraRotation (vector4 quaternion values separated by , or +)
  • fov=fieldOfView
  • 360=panorama
  • rts=renderTileSize (for performance optimization)
  • hdr=highDynamicRange
  • jpg=jpeg (for jpeg performance optimization)
  • aov=arbitraryOutputVariable (a valid AOV found in the Forma Render UI)
  • pt=pathTracing
  • aaa=X (jittered accumulation followed by the number of samples)
  • ssaa=X (uniform super sampling followed by the number of samples)
  • smaa (can't be used with fxaa)
  • fxaa (can't be used with smaa)
  • dlss=X (applies a deep learning upscale filter to produce X pixels from a single pixel. dlss=2 renders half as many pixels as dlss=1; for example, 1358 x 764 vs 1920 x 1080)
  • jpegQuality=jpegQ (% jpeg compression)
  • webpQuality=webpQ (% webp compression)
  • ft=fileType (hdr, exr, png, jpeg, or webp)
  • rgba (readback uncompressed RGBA channels from the GPU; default is to readback compressed YUV)
  • yuva (readback compressed YUVA channels from GPU; default is to readback compressed YUV)
  • clearCache (force clears the cache if enabled)

Deprecated arguments are:

  • a=accumulation (replaced by aaa)
  • ss=supersampling (replaced by ssaa squared)
Note

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

Note

When you use the sample script FormaRenderImageOnDemand, the aov argument takes a single layer name as argument. However, when you use the script FormaRenderExrOnDemand, you can use multiple layer names to produce a single multipart EXR file.

The syntax is aov=ProductOnly+BackgroundOnly, with layer names separated by +. Custom layer names are also supported. See Produce layer images for details.

HTTP API tips

Balancing image quality and speed

Subpixel Morphological Antialiasing (SMAA) provides the fastest results with the best quality. To use it, you must pass the smaa argument.

To access images with Medium quality, pass the arguments aaa=5 and ssaa=4. Depending on the complexity of the model, this returns a total of 5x4 samples per pixel (20X) at around 100ms of rendering time, ignoring all other times.

Forma Render uses a four stage pipeline. To achieve a higher image throughput, make sure you have four image requests in process at any given time.

For an additional performance boost and to avoid building the Forma Render UI, enable -batchmode on the command line.

Accumulation and quality settings

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

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