Headless Renderer Stage

This stage will handle taking in output viz data (renderer layers) and renders them to camera images. You can take advantage of GPU-assisted rendering if using the Magnum renderer (which is what Qt uses) or you can use software rendering otherwise via the Cairo renderer.

This stage is typically automatically added for you when you use the --video option on your pipeline (and are using the main system). This will take care of adding the headless renderer stage and a video encoding stage (by default, encoding with H264).

You may wish to configure the stage away from the default configuration. If so, you must add the HeadlessRenderer configuration to your config package. See below for more details.


The HeadlessRendererStageConfig structure holds the configuration for this stage. A few options:

  • enabled - If this stage should operate at all.
  • renderer_type - Must be ‘cairo’ or ‘magnum’.
  • layer_allowlist - A list of layers to allow for rendering (all other layers are ignored)
  • layer_blocklist - A list of layers to ignore while rendering (takes priority over allow list).
  • renderer_config - A HeadlessRendererConfig structure.

Both the allow list and block list can accept regexes. If both are empty, all layers are rendered.

The HeadlessRendererConfig structure is made up of:

  • width - Output width of the video.
  • height - Output height of the video.
  • render_frame - Which transform network frame to render from the perspective of.
  • background_color - An RGBA tuple for the desired background color.
  • camera_target - The target camera position. Typically x and y are zero, and z is raised some number of meters.

Note that the camera target and render frame closely control what is focused on in the video.


The stage typically emits frames at 10Hz. There are no futher controls.


No metrics are emitted from this stage, although it does operate in the /headless_renderer namespace by default.