Customizing AR Lighting

  • iPad

Augmented reality (AR) content creators can customize the lighting for AR scenes to adjust the visibility of the entire scene, instead of the individual models. Content creators can also disable the lighting and animation in edit mode so users can view models exactly as they appear in locked mode to prevent confusion. This allows content creators to improve AR content for customers.

There are 4 custom lighting options, which can be configured simultaneously:

  • Ambient
  • Directional
  • Omni
  • Spot

The default lighting is the standard ARKit ambient light. Defining custom lighting automatically disables the standard ARKit lighting.

For example, Sarah Jones launches an AR scene with multiple models. The scene has a directional light which acts like the sun illuminating the entire scene from one direction.

Defining Custom AR Lighting

Content creators can define values for the lighting parameters in the JSON configuration file.

Each lighting option has specific sub-parameters to adjust how the lighting interacts with a scene. The following sub-parameters are available for multiple lighting options:

  • auto_updating_lighting – determines if the scene should use ARKit’s scene lighting calculations to adjust the intensity based on lighting in the real environment
  • color – color of the light in RGB; defaults to 255, 255, 255 (white)
  • direction – direction of the light as an Euler vector with X, Y, and Z coordinates in radians; defaults to -1.57, 0, 0
  • The value -1.57 represents -π/2. The default direction points directly down from the origin.
  • intensity – intensity of the light in lumens; defaults to 1000
  • position – position of the light with respect to the origin; defaults to 0, 0, 0 (origin)
  • temperature – temperature of the light in Kelvin; defaults to 6500

Parameter

Description

Available Sub-parameters

ambient_lighting

An ambient light is a soft light without a source or a direction. It illuminates a scene without casting shadows.

There can only be one ambient light in a scene.
  • auto_updating_lighting
  • enabled
    • true
    • false – Disables all ambient lighting, including the standard ARKit lighting
    • auto (default) – Ignores custom parameters and uses the default standard ARKit ambient lighting
  • intensity

directional_lighting

A directional light is a light source pointing in a specific direction.

There can be multiple directional lights in a scene.
  • auto_updating_lighting
  • color
  • direction
  • intensity
  • temperature

omni_lighting

An omni light is a light source pointing in every direction.

There can be multiple omni lights in a scene.
  • auto_updating_lighting
  • color
  • intensity
  • position
  • temperature

spot_lighting

A spot light is a light source pointing at a target object composed of two concentric cones. The inner cone illuminates the target at maximum brightness. The outer cone partially illuminates the target and defines the maximum area of illumination.

There can be multiple spotlights in a scene.
  • auto_updating_lighting
  • color
  • direction
  • inner_angle – angle of the inner cone in degrees
  • intensity
  • outer_angle – angle of the outer cone in degrees
  • position
  • temperature

Disabling the Edit Mode Animation

Content creators can disable the animation and lighting in edit mode. This ensures models do not float above the plane and only displays lighting defined by the content creator in the JSON configuration file.

To disable the edit mode animation, content creators can define the edit_mode_animation parameter in the JSON configuration file. See Defining AR Scenes for more information.