Image Mode
Image mode needs to be enabled on your account before it is accessible. Please contact your ZeroLight account manager to have it enabled.
Background
Image mode is useful for high traffic use-cases, such as product configurators, where some amount of interactivity can be sacrificed and in order to serve more users that with one-to-one video streams.
Image mode is not fundamentally different to Video mode, the core integration is the same and if state is already being robustly handled then there will be nothing/little to do in your application to support Image mode.
The main thing to consider in Image mode is that a user is not able to interact with the application directly through mouse and keyboard input in the stream Window as they are in Video mode. Instead in Image mode all control over OmniStream must be done through interactions on the webpage and passed through to OmniStream as state. OmniStream manages the sending of the state of a running application, the rendering of an image to reflect that state and serving that image back to the webpage through a CDN without any more integration on the application side.
It's also worth considering that in Image mode the one-to-one connection between a user and the running application is broken. In Image mode an application might be serving requests from many users simultaneously, so ensuring each state request is absolute and not relative is of utmost importance.
Cameras
Usually the biggest different between Video mode and Image mode is how camera interactions are handled. In Video mode it's usual to have fully interactive an/or animated cameras to give the user the most interactive and engaging experience. In Image mode cameras need to be moved or switched between based on information passed through in the state JSON. Exactly how you implement cameras in Image mode will depend on your application and is worth some thought.
Typically there are two types of camera used in Image mode - static cameras and "animated" cameras. The first are fairly simple, a camera placed at a fixed position that can be switched to when requested. The second is a bit more complex.
An animated camera is one where there are sequence of camera shots wanting to be displayed in sequence, often by clicking and dragging on the integrating web page. This might be to orbit around an object in a loop or to move up and down within some defined limits.
Within your application there are two main ways to implement an animated camera. You could set up a series of static cameras with names or tags which are switched to when requested from the web front-end e.g.
{"camera":"mainOrbit1"}
{"camera":"mainOrbit2"}
{"camera":"mainOrbit3"}
etc.
The other way is to implement a single camera that is then moved to the relevant position based on information passed from the web front-end. One way to accomplish this would be to parent the camera to a dummy object and then rotate this dummy object based on the parameters passed in the state JSON. Is a more complex path was wanted (e.g. an orbit with some height variation) then an animated path could be used and the point along the path set based on what was passed.
{"camera": "mainOrbit", "orbit":{ "requestedStep":3, "totalSteps": 16}}
In this example the web front-end is requesting a camera 1/16th of the way round the object (22.5 degrees). In the application code this can be processed and set the camera to represent this. It also allows the number of steps to be changed to say 32 to offer a smoother orbit, or reduced to 8 to reduce the bandwidth needed, without needing any application changes.
Caching
Imaged generated in Image mode are served directly to the user so they receive the image as quickly as possible. At the same time as this happens the image is stored in a CDN, indexed by a hash that combines the state that the image represents and the resolution of the image. This means that is the same state and resolution is requested again the image does not have to be re-rendered, and can be served near instantly from the CDN.
When deploying a new version of your application you can optionally choose to clear the cache. This should be done if your application contains visual changes to existing states - otherwise users requesting states that would be served from the image cache will receive out of date images. If the new version of the application does not include visual changes, or any includes additional states (if you've added new colour options, but not changed any existing colour options for example) then you can choose to not clear the cache.
Pre-caching
If you're planning on running a pre-cache we recommend contacting your ZeroLight Account Manager as your account might require a quota increase to allow a large number of simultaneous instances.
Before launching a customer facing experience it might be desirable to have some images pre-generated. This means the first user to request a specific image will have the image retrieved from the cache rather than waiting for it to be generated. We call this process "pre-caching".
The complexity of the experience will dictate whether a complete pre-cache of every possible image will be viable or whether a section of the most requested or "happy path" images makes more sense. If the number of images in the experience is in the tens of thousands or lower, then a complete pre-cache will almost certainly be viable. If it's millions, then generating a selection of the most likely requested images probably makes the most sense.
When doing a pre-cache there are a number of things worth considering. First is how the images will be requested. We recommend building the ability to request images in batches into the main site you'll be using for the experience. You can use the existing site code, but rather than waiting for a user to navigate the UI, programmatically go through the options, not waiting for the image to be returned before submitting the next one. We have found this approach is preferable to building a dedicate pre-caching tool as there can be subtle state or resolution mismatches between what the pre-cache tool has requested and what the final site requests.
It's also important to track progress through the pre-cache, to make resuming a pre-cache smoother. If the pre-cache is being orchestrated from a single machine, a simple way to do this is through local storage.
The order the images are requested in is also an important consideration as it affects how much time it takes (and therefore how many credits are needed) to complete a precache. It is preferable to batch together images with smaller changes together, for example if the project is a vehicle configurator with two cars, it would make sense to request all the images for one car and then all the images for the second car. The car switch is likely to be the slowest operation, so doing it frequently when generating images will significantly increase the time required to generate the images.
OmniStream supports of maximum queue length of 500 images. To get the most effective use for the instances running for the pre-cache it is best to keep this queue fed. We recommend submitting images in batches of 250, so upon starting a pre-cache operation submit two batches of 250 images. Then upon the first 250 images completing, submit the next batch of 250 images. This should mean the queue length never drops below 250, and the instances are never left idle.
Next Steps
Once your application is set up to properly manage state for Image mode then you can integrate Image mode into your webpage.