Running Replicator Headlessly#

Learning Objectives#

The goal of this tutorial is to show you how to use Replicator headlessly. Headless in this context means the computing device has no monitor or peripherals, such as a keyboard and mouse. In order to do this, we will make mild modifications to the script explained in Core Functions - “Hello World” of Replicator to make it work. It is encouraged to first go through that tutorial to understand the basics of Replicator.

Modifying Hello World Script for running headlessly#

There are two main modifications required to run headlessly. The first one is to add an extra light. When running with a head, by default, the Omniverse Application starts a dome light. When running headlessly, a light needs to be added. For this example, a sphere light is chosen. However, you could choose a different type of light.

sphere_light = rep.create.light(
    light_type="Sphere",
    temperature=rep.distribution.normal(6500, 500),
    intensity=rep.distribution.normal(35000, 5000),
    position=rep.distribution.uniform((-300, -300, -300), (300, 300, 300)),
    scale=rep.distribution.uniform(50, 100),
    count=2
)

The second and most important change is to add rep.orchestrator.run() at the end of the script. As mentioned in the introduction, in the background replicator makes an omnigraph and then you need to tell Omniverse to execute the graph. This will be done by rep.orchestrator.run. Without it, the script will not run the omnigraph and won’t produce an output. The full script below may be copied and pasted. You can store this as a python file anywhere in your computer. For the sake of this example call it test.py .

import omni.replicator.core as rep

with rep.new_layer():

    camera = rep.create.camera(position=(0, 0, 1000))

    sphere_light = rep.create.light(
        light_type="Sphere",
        temperature=rep.distribution.normal(6500, 500),
        intensity=rep.distribution.normal(35000, 5000),
        position=rep.distribution.uniform((-300, -300, -300), (300, 300, 300)),
        scale=rep.distribution.uniform(50, 100),
        count=2
    )

    render_product = rep.create.render_product(camera, (1024, 1024))

    torus = rep.create.torus(semantics=[('class', 'torus')] , position=(0, -200 , 100))

    sphere = rep.create.sphere(semantics=[('class', 'sphere')], position=(0, 100, 100))

    cube = rep.create.cube(semantics=[('class', 'cube')],  position=(100, -200 , 100) )

    with rep.trigger.on_frame(num_frames=10):
        with rep.create.group([torus, sphere, cube]):
            rep.modify.pose(
                position=rep.distribution.uniform((-100, -100, -100), (200, 200, 200)),
                scale=rep.distribution.uniform(0.1, 2))

    # Initialize and attach writer
    writer = rep.WriterRegistry.get("BasicWriter")

    writer.initialize( output_dir="_output", rgb=True,   bounding_box_2d_tight=True)

    writer.attach([render_product])

    rep.orchestrator.run()

Running Replicator script headlessly#

Now you are ready to run the test.py script above. We’ll need the location of the folder Omniverse Code was installed in. Within the Library section of the launcher, select the Code App. Then, click the Code Options menu showing three horizontal lines and select “Settings”. The install path should now be shown. Below is a gif showing how to get to the source.

../_images/Replicator_find_code.gif

From a terminal go to that folder, there you will find that there is omni.code.sh for Linux or omni.code.bat for Windows. To run headless from a terminal you will use the following command:

.\omni.code.bat --no-window --/omni/replicator/script=C:\PATH\TO\test.py

Please note that in Code 2022.3.0 and earlier you will need to use .\omni.code.replicator.bat in the above command line instead.

Note

If you did not modify output_dir, in linux, the data will be in HOME/omni.replicator_out/_output or in the folder your python script is in. If you have any errors due to permissions modify the output folder in the script.

After running that script in a minute or so you will have the images with annotations. Any example run headlessly will have a long initial start up time as it is launching the Omniverse Application in the background. The generation of samples itself should be quick.

Note

Known Issue: Application shutdown may sometimes crash, but integrity of datasets is unaffected.

On this page