ChimeraX docs icon

Command: lighting

lightingpreset ]  options

lighting model  spec   model-options

The lighting command controls global lighting parameters, through individual options and in convenient preset combinations. Related per-model settings can be adjusted with the lighting model command. The material command sets material properties for light reflection and whether mesh surfaces and transparent objects cast shadows. See also: preset, graphics, Graphics icons, automatic styling

Given without arguments, lighting reports the current settings in the Log. Colors are reported as red, green, and blue components in the range 0-100 (percentages). automatic styling

There are two directional lights, key and fill, plus ambient lighting. The key light is often the dominant source and can cast shadows; the first set of intensity, direction, and color values reported in the Log refer to this light. The fill light serves as a secondary directional source to improve the visibility of regions that would otherwise be dark. Regardless of whether shadows are on, the directional lights cause “shading,” where the brightness of an object varies based on the angle between the light direction and the surface normal. The key light also produces directionally dependent specular highlights. The ambient lighting is an approximation to omnidirectional illumination. Shadows cast from multiple uniformly distributed directions can produce ambient shadowing, or “ambient occlusion.”

The preset can be:

The detailed settings within a preset can be listed in the Log by applying the preset and then using the lighting command without arguments. Although there is a preset named default, different settings may be applied by automatic styling based on the size of the first atomic model opened at a time.

The Graphics icon   toggles key-light shadows, and if the key light is off, adjusts key-light intensity from 0 to 0.5 to show the shadows.


Parameters that are not specified retain their current values. Below, settings in the simple preset are indicated with bold.

direction  xk,yk,zk
Set key-light direction. Any length vector can be specified; only the direction is used. In simple lighting, the direction is 1,-1,-1. This is from the upper left front to the lower right back in the screen coordinate system (see moveWithCamera),
intensity  Ik
Set key-light intensity (1.0 in simple lighting).
color  color-spec
Set key-light color (white in simple lighting).
fillDirection  xf,yf,zf
Set fill-light direction (approx. -0.2,-0.2,-0.959 in simple lighting).
fillIntensity  If
Set fill-light intensity (0.5 in simple lighting).
fillColor  color-spec
Set fill-light color (white in simple lighting).
ambientIntensity  Ia
Set ambient-light intensity (0.4 in simple lighting).
ambientColor  color-spec
Set ambient-light color (white in simple lighting).
depthCue  true | false
Whether to use depth-cueing, front-to-back shading of the scene (true in simple lighting). See also per-model settings.
depthCueColor  color-spec
Set depth-cueing color (black in simple lighting). Any transparency in the color will be ignored.
depthCueStart  start
depthCueEnd  end
Set the position of the depth-cueing ramp. Depth-cueing shading increases linearly from start to end, each expressed as a position relative to the front (0.0) and back (1.0) global clipping planes (0.5 to 1.0 in simple lighting). See also: clip
shadows  true | false
Whether the key light should cast shadows (false in simple lighting). This will only have a visible effect when the key light is on (intensity > 0). See also per-model settings.
qualityOfShadows  coarse | normal | fine | finer | Mk
Set the quality of directional (key-light) shadows. These shadows are rendered with a two-dimensional texture or “depth map.” A small map gives pixelated shadow edges. The integer map size Mk can be specified directly or via one of the quality settings:
depthBias  bk
Set the bias distance for directional shadows, used to avoid a surface shadowing itself due to rounding errors (0.005 of the scene diameter in simple lighting).
multiShadow  N
How many directions should be used to generate ambient shadows (0 in simple lighting, meaning no ambient shadows; maximum 1024). See also per-model settings.
msMapSize  Ma
Set the size of the depth map for rendering ambient shadows (integer-valued, 1024 in simple lighting).
msDepthBias  ba
Set the bias distance for ambient shadows, used to avoid a surface shadowing itself due to rounding errors (0.01 of the scene diameter in simple lighting). A larger bias is needed for ambient shadows than for directional shadows because a smaller depth map is typically used.
moveWithCamera  true | false
Whether directional lighting should be pinned to the camera viewpoint (screen coordinate system, default) or to the scene coordinate system.

Per-Model Lighting Options

Usage: lighting model  spec  [ depthCue  true | false ] [ directional  true | false ] [ shadows  true | false ] [ multiShadow  true | false ]

The lighting model command allows turning off a setting for an individual model or models when that setting is globally enabled. If the setting is globally disabled, the per-model settings will not be evident.

depthCue  true | false
Whether depth-cueing should apply to the specified model(s) when depth-cueing is enabled globally.
directional  true | false
Model(s) for which this setting is false will appear as flat, without any directional shading, highlights, or shadows. They will also be unaffected by changes in ambient lighting, but depth-cueing may still apply.
shadows  true | false
Whether the key light should cast shadows on the specified model(s). This will only have a visible effect when the key light is on (intensity > 0) and shadows are enabled globally.
multiShadow  true | false
Whether ambient shadowing should be shown on the specified model(s) when ambient shadowing is enabled globally (number of directions N > 0).

UCSF Resource for Biocomputing, Visualization, and Informatics / August 2020